States
======

States hold the quantum data. Perceval introduces a formalism to represent all kinds of quantum states.

Basic State
-----------

Basic states describe Fock states of :math:`n` photons over :math:`m` modes where photons can be annotated. If none is
annotated, then all photons in the state are indistinguishable. It is represented by ``|n_1,n_2,...,n_m>`` notation
where ``n_k`` is the number of photons in mode *k*.

Technichally, the :code:`BasicState` initializer is implemented as a factory able to return any of the following types:

* :code:`FockState`: A light-weight object only containing photon positions in mode (e.g. :code:`|1,0,1>`). Can be used to
  represent detections. It is an alias of exqalibur :ref:`FockState`.
* :code:`NoisyFockState`: A collection of indistinguishable photon groups, that are totally distinguishable. The
  distinguishability index is an integer and is referred to as the `noise tag` (e.g. :code:`|{0},{1},{0}{2}>` contains three
  groups of indistinguishable photons tagged 0, 1 and 2). It is an alias of exqalibur :ref:`NoisyFockState`.
* :code:`AnnotatedBasicState`: Replace the previous :code:`FockState` by allowing rich annotations, having one or more
  string types, each having a complex number for value. This enables to accurately encode physical parameters and
  play with partial distinguishability (e.g. :code:`|{P:H,lambda:0.625},{P:V,lambda:0.618}>`). Please note that apart from
  polarisation, `Perceval` does not provide a generic algorithm to separate rich annotated states, and the user would
  have to write one. It is an alias of exqalibur :ref:`AnnotatedFockState` (see also: :code:`exqalibur.Annotation`).

Simple code example with indistinguishable photons:

>>> import perceval as pcvl
>>>
>>> # Create a two-mode FockState with no photon in the 1st mode, and 1 photon in the 2nd mode.
>>> bs = pcvl.BasicState("|0,1>")
>>> print(bs)                          # Prints out the created Fock state
|0,1>
>>> bs.n                               # Displays the number of photons of the created Fock state
1
>>> bs.m                               # Displays the number of modes of the created Fock state
2
>>> bs[0]                              # Displays the number of photons in the first mode of the created Fock state ( note that the counter of the number of modes    starts at 0 and ends at m-1 for an m-mode Fock state)
0
>>> print(pcvl.BasicState([0,1])*pcvl.BasicState([2,3]))  # Tensors the |0,1> and |2,3> Fock states, and prints out the result (the Fock state |0,1,2,3>)
|0,1,2,3>

State Vector
------------

:code:`StateVector` represents a pure state. It is a (complex) linear combination of any of the :code:`FockState` types
to represent state superposition.

It is an alias of exqalibur :ref:`StateVector` class.

Basic State Samples
-------------------

The class :code:`BSSamples` is a container that collects chronologically ordered sampled states.
It is, for instance, the object generated by a sampling method, such as ``samples`` command.

It is an alias of exqalibur :ref:`BSSamples` class and only stores perfect :code:`FockState`.

Basic State Count
-----------------

The class :code:`BSCount` is also a container but it only counts the states without keeping in track their order.
The ``sample_count`` command return this data type.

It is an alias of exqalibur :ref:`BSCount` class and only stores perfect :code:`FockState`.

Basic State Distribution
------------------------

The class :code:`BSDistribution` represents a probability distribution of measured states.
It maps states with their associated probability.
It is the type of object returned by a ``probs`` command.

It is an alias of exqalibur :ref:`BSDistribution` class and only stores perfect :code:`FockState`.

State Vector Distribution
-------------------------

:code:`SVDistribution` is a recipe for constructing a mixed state using ``BasicState`` and/or
``StateVector`` as components.

For example, The following ``SVDistribution``

+-------------------------------------+------------------+
| ``state``                           | ``probability``  |
+=====================================+==================+
| ``|0,1>``                           |     ``1/2``      |
+-------------------------------------+------------------+
| ``1/sqrt(2)*|1,0>+1/sqrt(2)*|0,1>`` |     ``1/4``      |
+-------------------------------------+------------------+
| ``|1,0>``                           |     ``1/4``      |
+-------------------------------------+------------------+

results in the mixed state
:math:`\frac{1}{2}\ket{0,1}\bra{0,1} + \frac{1}{4}(\frac{1}{\sqrt{2}}\ket{1,0} + \frac{1}{\sqrt{2}}\ket{0,1})(\frac{1}{\sqrt{2}}\bra{1,0} + \frac{1}{\sqrt{2}}\bra{0,1}) + \frac{1}{4}\ket{1,0}\bra{1,0}`

It is an alias of exqalibur :ref:`SVDistribution` class.

.. WARNING::
    ``BSDistribution``, ``SVDistribution`` and ``BSCount`` are NOT ordered data structures and must NOT be indexed with integers.

States generators
-----------------

.. autofunction:: perceval.utils.states.allstate_iterator

.. autofunction:: perceval.utils.states.max_photon_state_iterator