Preparations¶

The built-in preparation instructions in Piquasso. Preparation instructions should be placed at the beginning of the Piquasso program.

class Vacuum¶

Prepare the system in a vacuum state.

Example usage:

with pq.Program() as program:
    pq.Q() | pq.Vacuum()
    ...

Note

This operation can only be used for all modes and is only practical to be used at the beginning of a program declaration.

class Mean(mean: ndarray)¶

Set the first canonical moment of the state.

Example usage:

with pq.Program() as program:
    pq.Q() | pq.Mean(
        mean=np.array(...)
    )
    ...

Can only be applied to the following states: GaussianState.

Note

The mean vector is dependent on \(\hbar\), but the value of \(\hbar\) is specified later when executed by a simulator. The parameter mean should be specified keeping in mind that it will automatically be scaled with \(\hbar\) during execution.

Parameters:: mean (numpy.ndarray) – The vector of the first canonical moments in xpxp-ordering.

class Covariance(cov: ndarray)¶

Sets the covariance matrix of the state.

Example usage:

with pq.Program() as program:
    pq.Q() | pq.Covariance(
        cov=np.array(...)
    )
    ...

Can only be applied to the following states: GaussianState.

Note

The covariance matrix is dependent on \(\hbar\), but the value of \(\hbar\) is specified later when executed by a simulator. The parameter cov should be specified keeping in mind that it will automatically be scaled with \(\hbar\) during execution.

Parameters:: cov (numpy.ndarray) – The covariance matrix in xpxp-ordering.

class Thermal(mean_photon_numbers: Iterable[float])¶

Prepares a thermal state.

Example usage:

with pq.Program() as program:
    pq.Q(0, 1) | pq.Thermal([0.5, 1.5])
    ...

The thermal state is defined by

\[\rho = \sum_{\vec{n} = 0}^\infty \frac{\overline{n}^{\vec{n}}}{(1 + \overline{n})^{\vec{n} + 1}} | \vec{n} \rangle \langle \vec{n} |,\]

where \(\overline{n} \in \mathbb{R}^d\) is the vector of mean photon numbers. The power on vectors is defined as

\[\vec{a}^{\vec{b}} = \prod_{i=1}^d a_i^{b_i}.\]

In terms of Gaussian states, the mean vector and covariance matrix is

\[\begin{split}\mu &= 0_{2d} \\ \sigma &= \hbar ( 2 \operatorname{diag}(\operatorname{repeat} (\overline{n}, 2)) + I_{2d \times 2d} ).\end{split}\]

Can only be applied to the following states: GaussianState.

Parameters:: mean_photon_numbers (Iterable[float]) – The sequence of mean photon numbers.
Raises:: InvalidParameter – If the mean photon numbers are not positive real numbers.

class NumberState(occupation_numbers: Iterable[int], coefficient: complex = 1.0)¶

State preparation with Fock basis vectors.

Example usage:

with pq.Program() as program:
    pq.Q() | (
        0.3 * pq.NumberState([2, 1, 0, 3])
        + 0.2 * pq.NumberState([1, 1, 2, 3])
        ...
    )
    ...

Can only be applied to the following states: PureFockState and PassiveState.

Parameters:

occupation_numbers (Iterable[int]) – The occupation numbers.
coefficient (complex, optional) – The coefficient of the occupation number. Defaults to \(1.0\).

Raises:

InvalidState – If the specified occupation numbers are not all natural numbers.

class DistinguishableNumberState(occupation_numbers: Iterable[int], particle_overlap: float | ndarray = 0.0)¶

State preparation with labelled photons in spatial number states.

The occupation numbers specify the spatial input modes. The optional particle_overlap specifies the internal-state Gram matrix of the labelled photons.

Example usage with uniform partial distinguishability:

with pq.Program() as program:
    pq.Q() | pq.DistinguishableNumberState(
        [2, 1, 0, 3],
        particle_overlap=0.8,
    )
    ...

Example usage with a full particle-overlap matrix:

G = np.array(
    [
        [1.0, 0.8, 0.7],
        [0.8, 1.0, 0.6],
        [0.7, 0.6, 1.0],
    ],
    dtype=complex,
)

with pq.Program() as program:
    pq.Q() | pq.DistinguishableNumberState(
        [1, 1, 1, 0],
        particle_overlap=G,
    )
    ...

The photon ordering is induced by the occupation numbers in increasing mode order. For example, occupation_numbers=[2, 0, 1] corresponds to labelled photon input modes [0, 0, 2]. Therefore, a full overlap matrix G must satisfy G[i, j] = <phi_i | phi_j> with respect to this ordering.

A scalar particle_overlap=lambda means real uniform amplitude overlap,

\[G_{ii} = 1, \qquad G_{ij} = \lambda \quad i \neq j.\]

A matrix particle_overlap=G must be a normalized positive semidefinite Gram matrix,

\[G = G^\dagger, \qquad G \succeq 0, \qquad G_{ii}=1.\]

Complex-valued overlaps should be specified using the full Gram matrix form, so that Hermiticity is explicit.

The scalar uniform-overlap algorithms are typically faster than the general Gram-matrix algorithms.

Can only be applied to the following states: PassiveState.

Parameters:

occupation_numbers (Iterable[int]) – The spatial occupation numbers.
particle_overlap (Union[float, np.ndarray]) –
Either a scalar uniform amplitude overlap or an n x n particle-overlap Gram matrix, where n = sum(occupation_numbers).

A scalar value means uniform pairwise overlap between every pair of labelled photons.

A matrix value means particle_overlap[i, j] is the internal-state overlap of photons i and j in the ordering induced by occupation_numbers.

Raises:

InvalidState – If the occupation numbers are invalid, or if the particle overlap is not a valid scalar overlap or Gram matrix.

class FockStateVector(fock_amplitude_map: Dict[Tuple[int, ...], complex], coefficient: complex = 1.0)¶

State preparation with Fock basis vectors.

Example usage:

with pq.Program() as program:
    pq.Q() | pq.FockStateVector(
        {
            (2, 1, 0, 3): 0.3,
            (1, 1, 2, 3): 0.2,
            ...
        }
    )
    ...

Can only be applied to the following states: PureFockState and PassiveState.

Parameters:

fock_amplitude_map (Dict[Tuple[int, ...], complex]) – The Fock amplitude map.
coefficient (complex, optional) – The coefficient of the occupation number. Defaults to \(1.0\).

Raises:

InvalidState – If the specified occupation numbers are not all natural numbers.

class StateVector(occupation_numbers: Iterable[int] | None = None, fock_amplitude_map: Dict[Tuple[int, ...], complex] | None = None, coefficient: complex = 1.0)¶

State preparation with Fock basis vectors.

Example usage:

with pq.Program() as program:
    pq.Q() | pq.StateVector([2, 1, 0, 3])
    ...

Can only be applied to the following states: PureFockState.

Deprecated since version 8.0.0: Use NumberState or FockStateVector instead.

Parameters:

occupation_numbers (Iterable[int], optional) – The occupation numbers.
fock_amplitude_map (Dict[Tuple[int, ...], complex], optional) – A mapping of occupation numbers to their corresponding amplitudes.
coefficient (complex, optional) – The coefficient of the occupation number. Defaults to \(1.0\).

Raises:

InvalidParameter – If neither occupation_numbers nor fock_amplitude_map is provided.
InvalidParameter – If both occupation_numbers and fock_amplitude_map are provided.
InvalidState – If the specified occupation numbers are not all natural numbers.
InvalidState – If the keys in fock_amplitude_map are not all natural numbers.

class DensityMatrix(ket: Iterable[int], bra: Iterable[int], coefficient: complex = 1.0)¶

State preparation with density matrix elements.

Example usage:

with pq.Program() as program:
    pq.Q() | (
        0.2 * pq.DensityMatrix(ket=(1, 0, 1), bra=(2, 1, 0))
        + 0.3 * pq.DensityMatrix(ket=(2, 0, 1), bra=(0, 1, 1))
        ...
    )
    ...

Note

This only creates one matrix element.

Can only be applied to the following states: FockState.

Parameters:

bra (Iterable[int]) – The bra vector.
ket (Iterable[int]) – The ket vector.
coefficient (complex, optional) – The coefficient of the operator defined by the “bra” and “ket” vectors. Defaults to \(1.0\).

Raises:

InvalidState – If the specified “bra” or “ket” vectors are not all natural numbers.

class Create¶

Create a particle on a mode.

This instruction essentially applies a creation operator on the specified mode, then normalizes the state.

Example usage:

with pq.Program() as program:
    pq.Q(1) | pq.Create()
    pq.Q(2) | pq.Create()
    ...

Can only be applied to the following states: FockState, PureFockState.

class Annihilate¶

Annihilate a particle on a mode.

This instruction essentially applies an annihilation operator on the specified mode, then normalizes the state.

Example usage:

with pq.Program() as program:
    ...
    pq.Q(0) | pq.Annihilate()
    ...

Can only be applied to the following states: FockState, PureFockState.