Updated more of the language for the Coherent channel tools.

Added update and git installation instructions to the readme.

Author: JBurniston

ChannelModules/ChannelConstructionTools/Coherent.m

@@ -4,9 +4,23 @@
     % optical modes. We then write coherent states across them as
     % |vec(alpha)> := |alpha_1>|alpha_2> ... |alpha_n>. For this class, we
     % store coherent states by extracting the column vector vec(alpha) in
-    % C^n. Furthermore, any operator, M, that transforms mode annihilation
-    % operators as vec(b) = M*vec(a), then M transforms coherent states as
-    % |vec(beta)>_vec(b) = |M*vec(alpha)>_vec(a).
+    % C^n.
+    % 
+    % A linear optics system characterized by matrix M in C^{m x n} with
+    % ||M||_infinity <= 1 acts as the quantum channel:
+    %
+    % Phi_{M,A->B}(|vec(alpha)><vec(beta)|_A) = <vec(beta)|vec(alpha)>
+    % / (<M vec(beta)|M vec(alpha)>) * |M vec(alpha)><M vec(beta)|_B
+    %
+    % When M is an isometry, one can think of the transformation as a
+    % replacement of mode creation operators vec(a^dagger) via
+    % vec(b^dagger) = M vec(a^dagger) or equivalently
+    % M^dagger*vec(b^dagger) = vec(a^dagger).
+    %
+    % Note the special case:
+    % 
+    % Phi_{M,A->B}(|vec(alpha)><vec(alpha)|_A) =
+    % |M*vec(alpha)><M*vec(alpha)|_A)
     %
     % See Also: Rotations Qudit
     methods (Static)
@@ -96,12 +110,11 @@
 
         function transMat = beamSplitter(transmittance)
             % A function that constructs the unitary transition matrix on
-            % coherent states/annihilation operators when a beam splitter
-            % is applied to a two mode state (one on each input side of the
-            % beam splitter). The outputs are organized so that a
-            % transmittance of 1 results in the identity matrix.
-            % Furthermore, no global or relative phase shifts are applied
-            % to the output modes.
+            % coherent states when a beam splitter is applied to a two mode
+            % state (one on each input side of the beam splitter). The
+            % outputs are organized so that a transmittance of 1 results in
+            % the identity matrix. Furthermore, no global or relative phase
+            % shifts are applied to the output modes.
             %
             % * transmittance: proportion of the intensity that is
             %   transmitted through the beam splitter without being
@@ -117,13 +130,12 @@
 
         function transMat = singleInputBeamSplitter(transmittance)
             % A function that constructs the isometry transition matrix on
-            % a coherent state/annihilation operator when a beam splitter
-            % is applied to a single input mode. This is useful for passive
-            % detector schemes like in BB84 where the signal must be split
-            % randomly into multiple detector setups. The outputs are
-            % ordered as transmitted portion then reflected portion.
-            % Furthermore, no global or relative phase shifts are applied
-            % to the output modes.
+            % a coherent state when a beam splitter is applied to a single
+            % input mode. This is useful for passive detector schemes like
+            % in BB84 where the signal must be split randomly into multiple
+            % detector setups. The outputs are ordered as transmitted
+            % portion then reflected portion. Furthermore, no global or
+            % relative phase shifts are applied to the output modes.
             %
             % * transmittance: proportion of the intensity that is
             %   transmitted through the beam splitter without being
@@ -136,13 +148,13 @@
 
         function transMat = singleInputMultiBeamSpliter(probDist)
             % A function that constructs the isometry transition matrix on
-            % a coherent state/annihilation operator when that splits the
-            % input across multiple output modes based on fractions of the
-            % intensity. This is useful for passive detector schemes like
-            % six-state where the signal must be split randomly into
-            % multiple detector setups. The outputs are ordered the same as
-            % the probability distribution. No global or relative phase
-            % shifts are applied to the output modes.
+            % a coherent state  when that splits the input across multiple
+            % output modes based on fractions of the intensity. This is
+            % useful for passive detector schemes like six-state where the
+            % signal must be split randomly into multiple detector setups.
+            % The outputs are ordered the same as the probability
+            % distribution. No global or relative phase shifts are applied
+            % to the output modes.
             % 
             % * probDist: probability distribtion to distribute the beam
             %   into fractions of the orgininal intensity.
@@ -190,10 +202,10 @@
             % Computes the inner product between two sets of coherent
             % states. <coherentStatesA|coherentStatesB>.
             %
-            % * coherentStatesA: nd array of complex coherent state
+            % * coherentStatesA: An nd array of complex coherent state
             %   amplitudes. Takes the complex conjugate for the
             %   inner product.
-            % * coherentStatesB: nd array of complex coherent state
+            % * coherentStatesB: An nd array of complex coherent state
             %   amplitudes. Must be the same size as coherentStatesA.
             % Name-value arguments
             % * combineModes(true): When true, each individual
@@ -223,9 +235,9 @@
             % coherentInnerProduct(coherentStatesA,coherentStatesB)...
             % ).^2).
             %
-            % * coherentStatesA: nd array of complex coherent state
+            % * coherentStatesA: An nd array of complex coherent state
             %   amplitudes.
-            % * coherentStatesB: nd array of complex coherent state
+            % * coherentStatesB: An nd array of complex coherent state
             %   amplitudes. Must be the same size as coherentStatesA.
             % Name-value arguments
             % * combineModes (true): When true, each individual
@@ -250,10 +262,10 @@
             % coherent states. The Fock states recieve the complex
             % conjugate. <fockStates|coherentStates>.
             %
-            % * fockStates: nd array of non-negative integers that
+            % * fockStates: An nd array of non-negative integers that
             %   represent the number of photons in each mode. Takes the
             %   complex conjugate for the inner product.
-            % * coherentStates: nd array of complex coherent state
+            % * coherentStates: An nd array of complex coherent state
             %   amplitudes. Must be the same size as fockStates.
             % Name-value arguments
             % * combineModes (true): When true, each individual inner
@@ -280,9 +292,9 @@
             % tolerance, the result should be the same as
             % abs(fockCoherentInnerProduct(fockStates,coherentStates)).^2
             %
-            % * fockStates: nd array of non-negative integers that
+            % * fockStates: An nd array of non-negative integers that
             %   represent the number of photons in each mode.
-            % * coherentStates: nd array of complex coherent state
+            % * coherentStates: An nd array of complex coherent state
             %   amplitudes. Must be the same size as fockStates.
             % Name-value arguments
             % * combineModes (true): When true, each individual probability
@@ -309,12 +321,12 @@
             % given an input coherent state and dark count rate.
             %
             % Inputs:
-            % * coherentState: nd array of complex coherent state
+            % * coherentState: An nd array of complex coherent state
             %   amplitudes.
-            % * darkCountRate (0): nd array that represents the probability
-            %   that a no click event is transformed into a click event.
-            %   The darkCountRate must have a compatible size for element
-            %   wise operations with coherentState.
+            % * darkCountRate (0): An nd array that represents the
+            %   probability that a no click event is transformed into a
+            %   click event. The darkCountRate must have a compatible size
+            %   for element wise operations with coherentState.
             %
             % see also mustBeCompatibleSizes
             arguments
@@ -351,11 +363,11 @@
             % example, [0.25;0.1] is mapped to [0.675;0.225;0.075;0.025].
             %
             % Inputs:
-            % * probDetectorsClick: nd array of click probabilities for
+            % * probDetectorsClick: An nd array of click probabilities for
             %   threshold detectors.
             %
             % Outputs: 
-            % * probDetectorsClickPatterns: nd array with the same size
+            % * probDetectorsClickPatterns: An nd array with the same size
             %   except 2^n columns where n was the previous number of
             %   columns. 
             arguments

README.md

@@ -1,3 +1,5 @@
+[![DOI](https://zenodo.org/badge/402256220.svg)](https://doi.org/10.5281/zenodo.14262568)
+
 # OpenQKDSecurity Version 2.0
 
 OpenQKDSecurity is a software package based in MATLAB that allows users to calculate key rates for quantum key distribution (QKD) protocols using the [Winick et al. framework](https://quantum-journal.org/papers/q-2018-07-26-77/) ([arXiv](https://arxiv.org/abs/1710.05511)). It is extensible, allowing for user-defined protocols to be implemented, and modular, allowing for users to change specific aspects of a protocol. Our software can be used to interface with experimental data, demonstrate the theoretical scalability of protocols in various conditions, and optimize parameters to maximize key rate. Its modular structure helps break down the colossal task of calculating key rates into small areas that require only domain specific knowledge. Therefore, no single person must be an expect in all areas.
@@ -45,7 +47,10 @@ Our software has the following dependencies for its default settings:
 
 Please refer to the documentation of each of these software packages for installation instructions.
 
-To install the openQKDSecurity package, download the repository on GitHub as a zip file and unzip to a preferred directory. This can be done on the main page of the repository by pressing the green “Code” button at the top of the page and then selecting "Download ZIP".
+To install the openQKDSecurity package, download the repository on GitHub as a zip file and unzip to a preferred directory. This can be done on the main page of the repository by pressing the green “Code” button at the top of the page and then selecting "Download ZIP". Alternatively, you can clone the reposity using git with
+```
+git clone https://github.com/Optical-Quantum-Communication-Theory/openQKDsecurity
+```
 
 Next, ensure that our software and the above dependencies are on your MATLAB path.To place a folder on your path, navigate to it in MATLAB, then right-click and select "Add to Path\textgreater Selected folder and Subfolders". Make sure you do this for OpenQKDSecurity, QETLAB and CVX. We also recommend you run "cvx_setup" to check if CVX is properly configured and which solvers are available.
 
@@ -54,6 +59,16 @@ Before you close MATLAB, go to "Home\>Environment\>Set Path" and click "save" at
 > [!IMPORTANT]
 > We strongly encourage you to run "testInstall.m" at this point to check for basic installation issues.
 
+
+## Updating
+
+- If you cloned the repository, fetch and pull changes to your local copy. Next, remove OpenQKDSecurity and all subfolders from your path, then add OpenQKDSecurity and all subfolder back to your path.
+
+- If you downloaded the repository as a zip file, back up any local files you added. Next, remove OpenQKDSecurity and all subfolders from your path, then delete the folder. Unzip the new version and add OpenQKDSecurity and all subfolder back to your path.
+
+Once again, we recommend you run "testInstall.m" to check for basic installation issues.
+
+
 ## Current Status
 Currently in this version of the software, we provide the following example protocols:
 * Qubit BB84 with no loss, where Alice is 4-dimensional
@@ -68,6 +83,58 @@ We also provide two math solver modules:
 
 In the future, we plan to add more protocols. We also welcome custom-defined protocols and solver modules.
 
+## Citing
+
+If you use Open QKD Security in research, please cite our software and write in your document something like
+```
+To calculate the key rate for protocol "X" we used the Open QKD Security package[#].
+```
+
+Here is a bibtex entry you can use:
+```bib
+@software{burniston_2024_14262569,
+  author       = {Burniston, John and
+                  Wang, Wenyuan and
+                  Kamin, Lars and
+                  Lin, Jie and
+                  Coles, Patrick and
+                  Metodiev, Eric and
+                  George, Ian and
+                  Li, Nicky Kai Hong and
+                  Fang, Kun and
+                  Chemtov, Max and
+                  Zhang, Yanbao and
+                  Böhm, Christopher and
+                  Winick, Adam and
+                  van Himbeeck, Thomas and
+                  Johnstun, Scott and
+                  Nahar, Shlok and
+                  Tupkary, Devashish and
+                  Pan, Shihong and
+                  Wang, Zhiyao and
+                  Corrigan, Aodhan and
+                  Kanitschar, Florian and
+                  Gracie, Laura and
+                  Gu, Shouzhen and
+                  Mathur, Natansh and
+                  Upadhyaya, Twesh and
+                  Lutkenhaus, Norbert},
+  title        = {Open {QKD} {S}ecurity: {V}ersion 2.0.2},
+  month        = dec,
+  year         = 2024,
+  publisher    = {Zenodo},
+  version      = {v2.0.2},
+  doi          = {10.5281/zenodo.14262569},
+  url          = {https://doi.org/10.5281/zenodo.14262569}
+  swhid        = {swh:1:dir:ce63165f716a15a425fbadc208e27934cc66be10
+                   ;origin=https://doi.org/10.5281/zenodo.14262568;vi
+                   sit=swh:1:snp:ea6ece4519d009abf5ae6b7c084f97ba9d3f
+                   14c2;anchor=swh:1:rel:54e7860c1d1e613f2e7a075653d1
+                   2fa44f1226fa;path=/
+                  },
+}
+```
+
 ## Contributing