more doc

README.md

@@ -22,13 +22,16 @@ Basically:
 
 - you can install `QPtomographer` via `pip`.
 
+[tomographer_py_inst]: https://tomographer.github.io/tomographer/get-started/#python-version
+
 
 Here are quick-and-easy steps for some common setups:
 
 ### Ubuntu/Linux
 
 Download & compile [SCS ≥ 2.0](https://github.com/cvxgrp/scs):
 
+    > sudo apt-get install liblapack-dev
     > cd $HOME/Downloads
     > curl -L https://github.com/cvxgrp/scs/archive/v2.0.2.tar.gz -o scs-2.0.2.tar.gz
     > tar xvfz scs-2.0.2.tar.gz && cd scs-2.0.2
@@ -37,19 +40,18 @@ Download & compile [SCS ≥ 2.0](https://github.com/cvxgrp/scs):
 Download & compile `tomographer ≥ 5.4` and other prerequisites:
 
     # If you are using *pip* (or if you're not sure):
-    > pip install numpy pybind11 qutip
+    > pip install numpy scipy pybind11 qutip
     > pip install tomographer
 
     # If you are using *anacoda/conda*:
-    > conda install numpy gcc libgcc
+    > conda install numpy scipy gcc libgcc
     > conda install -c conda-forge pybind11 qutip
     > pip install tomographer
 
 Install `QPtomographer` via `pip`:
 
     > SCS_ROOT=$HOME/Downloads/scs-2.0.2 pip install QPtomographer
 
-
 ### Apple Mac OS X
 
 Download & compile [SCS ≥ 2.0](https://github.com/cvxgrp/scs):
@@ -74,11 +76,9 @@ Install `QPtomographer` via `pip`:
 
     > SCS_ROOT=$HOME/Downloads/scs-2.0.2 pip install QPtomographer
 
+### Alternatively, you can build and install `QPtomographer` from source
 
-
-## Alternatively, you can build and install `QPtomographer` from source
-
-You should only have to run
+After installing all the prerequisites, you should only have to run
 
     > SCS_ROOT=$HOME/Downloads/scs python setup.py install
 
@@ -93,7 +93,38 @@ the C++ flags set for `tomographer` itself, and uses those same flags. Thus, if
 you use the same compiler).
 
 
+## Getting started with examples
+
+The `examples/` folder contains examples using `QPtomographer`.
+
+The examples are provided as [jupyter notebooks][jpynb] (`*.ipynb` files).
+Jupyter is a convenient environment, inspired by Mathematica and powered by
+Python, for running code interactively.
+
+To run an example, first [install jupyter locally][jpyinst].  Then, in a
+terminal, enter the current `examples/` directory in `QPtomographer` and launch
+jupyter:
+
+    > cd QPtomographer/examples
+    > jupyter notebook
+
+This should open your browser with a jupyter session. Click on the directory
+corresponding to the example you wish to run, and then open the corresponding
+notebook file (`run.ipynb` file).
+
+[jpynb]: https://jupyter.org/
+[jpyinst]: http://jupyter.readthedocs.io/en/latest/install.html
+
+
+## Full documentation and API reference
+
+Full documentation of what `QPtomographer` does, how to call the code, and
+everything you always wanted to know about `QPtomographer` but didn't dare to
+ask, can be found at:
+
+https://QPtomographer.readthedocs.org/latest/
+
 
-# License
+## License
 
 `QPtomographer` is released under the MIT License (see `LICENSE.txt`).

cxx/pyfigofmerit.cxx

@@ -77,7 +77,8 @@ tpy::RealScalar figofmerit_avg_entgl_fidelity2(
   tomographer_assert(dim_X * dim_Y == dim_XY) ;
 
   if (dim_X != dim_Y) {
-    throw py::value_error("average entanglement fidelity to identity channel: input and output dimensions must be equal.");
+    throw py::value_error("average entanglement fidelity to identity channel: "
+                          "input and output dimensions must be equal.");
   }
 
   return entanglement_fidelity(E_XY, dim_X);
@@ -102,7 +103,8 @@ scs_float figofmerit_worst_entgl_fidelity2(
   tomographer_assert(dim_X * dim_Y == dim_XY) ;
 
   if (dim_X != dim_Y) {
-    throw py::value_error("worst-case entanglement fidelity to identity channel: input and output dimensions must be equal.");
+    throw py::value_error("worst-case entanglement fidelity to identity channel: "
+                          "input and output dimensions must be equal.");
   }
 
   scs_float epsilon = opt.attr("get")("epsilon"_s, 1e-6).cast<scs_float>();

doc/QPtomographer.figofmerit.rst

@@ -17,23 +17,57 @@ average entanglement fidelity as well as the worst-case entanglement fidelity
    is deduced from the size of `Delta_XY`).
 
    The Hermiticity-preserving map :math:`\Delta_{X\to Y}(\cdot)` is specified in
-   the argument `Delta_XY` as a complex NumPy array, via the Choi matrix, which
-   is of dimension :math:`d_X d_Y \times d_X d_Y`.
+   the argument `Delta_XY` as a complex NumPy array, via the Choi matrix, of
+   dimension :math:`d_X d_Y \times d_X d_Y`, as specified in
+   :ref:`conventions-channels-states`.
 
    The semidefinite problem is solved using `SCS` via QPtomographer's C++
    wrappers.  This function is in fact a wrapper to the same C++ subroutine code
    that computes the diamond norm when calling
    :py:func:`QPtomographer.channelspace.run()` or
    :py:func:`QPtomographer.bistates.run()`.
 
+   The argument `epsilon` specifies the precision to which the SDP
+   characterizing the diamond norm is solved.
+
 
 .. py:function:: avg_entgl_fidelity2(E_XY, dim_X)
 
-    Doc here......
+   Compute the average entanglement fidelity (squared) of the process specified
+   by `E_XY` to the identity process.  See :ref:`figures-of-merit` for details.
+   Specify the dimension of the input system :math:`X` in the argument `dim_X`
+   (the dimension of the output system is deduced from the size of `Delta_XY`).
+
+   The completely positive, trace-preserving map :math:`\mathcal{E}_{X\to
+   Y}(\cdot)` is specified in the argument `E_XY` as a complex NumPy array, via
+   the Choi matrix, of dimension :math:`d_X d_Y \times d_X d_Y`, as specified in
+   :ref:`conventions-channels-states`.
+
+   The average entanglement fidelity is calculated by direct computation, via
+   the same C++ code that computes the average entanglement fidelity when
+   calling :py:func:`QPtomographer.channelspace.run()` or
+   :py:func:`QPtomographer.bistates.run()`.
 
 
 .. py:function:: worst_entgl_fidelity2(E_XY, dim_X, [epsilon=1e-6])
 
-    Doc here......
+   Compute the worst-case entanglement fidelity (squared) of the process
+   specified by `E_XY` to the identity process.  See :ref:`figures-of-merit` for
+   details.  Specify the dimension of the input system :math:`X` in the argument
+   `dim_X` (the dimension of the output system is deduced from the size of
+   `Delta_XY`).
+
+   The completely positive, trace-preserving map :math:`\mathcal{E}_{X\to
+   Y}(\cdot)` is specified in the argument `E_XY` as a complex NumPy array, via
+   the Choi matrix, of dimension :math:`d_X d_Y \times d_X d_Y`, as specified in
+   :ref:`conventions-channels-states`.
+
+   The semidefinite problem is solved using `SCS` via QPtomographer's C++
+   wrappers.  This function is in fact a wrapper to the same C++ subroutine code
+   that computes the worst-case entanglement fidelity when calling
+   :py:func:`QPtomographer.channelspace.run()` or
+   :py:func:`QPtomographer.bistates.run()`.
 
+   The argument `epsilon` specifies the precision to which the SDP
+   characterizing the worst-case entanglement fidelity is solved.
 

doc/QPtomographer.util.rst

@@ -1,6 +1,6 @@
 
-`QPtomographer.util` module
-===========================
+Some utilities: `QPtomographer.util`
+====================================
 
 .. automodule:: QPtomographer.util
     :members:

doc/api_conventions.rst

@@ -50,3 +50,6 @@ onto a state :math:`\sigma` is computed as
 
 where :math:`\sigma_X^T` is the partial transpose of :math:`\sigma_X` during
 which the system :math:`X` is relabled as :math:`R`.
+
+The unnormalized Choi matrix can be represented as a NumPy :py:class:`array
+<numpy.ndarray>` or as a :py:class:`qutip.Qobj` in the same way as states.