README
======

1) For installation of the library, follow the instructions in the file 'INSTALL'.

2) A detailed description of the library can be found in the manuscript accompanying this code.

3) Within MATLAB or Octave, type

        help some_command

    to learn more about the function with the name 'some_command'.

4) Running the examples. Within MATLAB or Octave, either type

        cd path_to_libcreme/examples/eofIsotropic
        example_eofIsotropic

    or
        
        cd path_to_libcreme/examples/tangleGHZW
        example_tangleGHZW

    to run either one of the two examples, where 'path_to_libcreme' is the full path to the
    directory containing this README file.



List of files with short descriptions
-------------------------------------

INSTALL                                            Installation instructions for compiling the C/C++ extensions and using the library
LICENSE                                            GNU General Public License Version 3
README                                             This file

examples/                                          Directory containing examples/demonstrations

    eofIsotropic/                                  Example 1: Entanglement of formation of 'isotropic states'

        example_eofIsotropic.m                     Main script to run the example

        eofIsotropic.m                             Entanglement of formation of an 'isotropic' density matrix (according to theory)

        example_eofIsotropic_output.txt            Output produced when running the example

        example_eofIsotropic_chi.txt               Data file
        example_eofIsotropic_U0i.txt               Data file
        example_eofIsotropic_U0r.txt               Data file


    tangleGHZW/                                    Example 2: Tangle of GHZ/W mixtures

        example_tangleGHZW.m                       Main script to run the example

        tangleGHZW.m                               Tangle of GHZ/W mixture (according to theory)

        example_tangleGHZW_output.txt              Output produced when running the example

        example_tangleGHZW_X0.dat                  Data file

lib/                                               The library libCreme

    entanglementMeasures/                          Directory containing various entanglement measures

        eof2x2.m                                   Entanglement of formation for 2 qubits (according to theory)

        convexSum.m                                Convex sum parameterized by a Stiefel matrix
        entropyOfEntanglement.m                    Entropy of entanglement
        meyer_wallach.m                            Meyer-Wallach measure
        tangle.m                                   Tangle

        grad_convexSum.m                           Gradient of convex sum
        grad_entropyOfEntanglement.m               Gradient of entropy of entanglement
        grad_meyer_wallach.m                       Gradient of Meyer-Wallach measure
        grad_tangle.m                              Gradient of Tangle
    
    extensions/                                    C/C++ extensions for otherwise slow functions

        octave/                                    Extensions for Octave (C++)

            buildUnitary.cc                        Build a complex Stiefel matrix from a parameterization vector
            grad_buildUnitary.cc                   Gradient of the above function

            pTrace.cc                              Partial trace over any subsystems of arbitrary (finite) dimensions
        
        matlab/                                    Extensions for Matlab (C)

            buildUnitary.c                         Same as buildUnitary.cc above
            grad_buildUnitary.c                    Same as grad_buildUnitary.cc above

            pTrace.c                               Same as pTrace.cc above

            compile.m                              Matlab script to compile the extension functions. See INSTALL

    optimization/                                  Directory containing optimization algorithms

        cg_min.m                                   Conjugate-gradient method
        bfgs_min.m                                 BFGS quasi-Newton method

        minimize1d_exp.m                           Minimization along a geodesic on the Stiefel manifold
        minimize1d_lin.m                           Minimization along a line in Euclidean space

        get_termination_criteria.m                 Helper function to check and handle termination criteria for the optimization algorithms


    util/                                          Utilities

        randDensityMatrix.m                        Random density matrix
        randState.m                                Random pure quantum state
        randUnitaryMatrix.m                        Random Stiefel matrix

        decomposeUnitary.m                         Get angles parameterizing a Stiefel matrix
        dimSt.m                                    Dimension of Stiefel manifold
        densityEig.m                               Get eigendecomposition of a density matrix in the form required by many functions within the library
        psDecomposition.m                          Get pure-state decomposition parameterized by a Stiefel matrix

        createConvexFunctions.m                    Create convex-sum function handles for use with cg_min
        createEHFunctions.m                        Create convex-sum function handles for use with bfgs_min

        grad_eh_adapt.m                            Adapter function to calculate the gradient of a convex sum parameterized by Stiefel matrix angles

        buildUnitary_script.m                      Equivalent script file to extension files buildUnitary.c(c)
        grad_buildUnitary_script.m                 Equivalent script file to extension files grad_buildUnitary.c(c)
        pTrace_script.m                            Equivalent script file to extension files pTrace.c(c)

        completeGramSchmidt.m                      Helper function for numerical stability used within cg_min

        buildUnitary.m                             'help' comment C/C++ extension; not executable
        grad_buildUnitary.m                        'help' comment C/C++ extension; not executable
        pTrace.m                                   'help' comment C/C++ extension; not executable
