States¶

`BargmannEigenstate`	The Bargmann eigenstate.
`Coherent`	The coherent state in Bargmann representation.
`DM`	Base class for density matrices.
`DisplacedSqueezed`	The displaced squeezed state in Bargmann representation.
`GaussianDM`	The N-mode mixed state described by a Gaussian gate that acts on a given thermal state.
`GaussianKet`	The N-mode pure state described by a Gaussian gate that acts on Vacuum.
`Ket`	Base class for all Hilbert space vectors.
`Number`	The number state in Fock representation.
`QuadratureEigenstate`	The Quadrature eigenstate in Bargmann representation.
`Sauron`	The n-th Sauron state is an approximation of the n-th Fock states using a ring of n+1 coherent states.
`SqueezedVacuum`	The squeezed vacuum state in Bargmann representation.
`State`	Base class for all states.
`Thermal`	The thermal state in Bargmann representation.
`TwoModeSqueezedVacuum`	The two-mode squeezed vacuum state.
`Vacuum`	The N-mode vacuum state in Bargmann representation.

Inheritance Diagram¶

BargmannEigenstate¶

class mrmustard.lab.states.BargmannEigenstate(mode, alpha=0j, name=None)[source]¶

Bases: Ket

The Bargmann eigenstate.

>>> from mrmustard.lab import BargmannEigenstate
>>> state = BargmannEigenstate(mode=1, alpha=0.1 + 0.5j)
>>> assert state.modes == (1,)

Parameters:

mode (int | tuple[int]) – The mode of the Bargmann eigenstate.
alpha (complex | Sequence[complex] | Parameter) – The displacement of the state (i.e., the eigen-value).
name (str | None) – A name for the state. If not provided, the class name will be used.

Note

The only difference with Coherent(mode, alpha) is in its c parameter (and hence, does not have unit norm).

Details and Conventions

Its (A,b,c) triple is given by

\[A = 0 , b = \alpha, c = 1.\]

Coherent¶

class mrmustard.lab.states.Coherent(mode, alpha=0j, name=None)[source]¶

Bases: Ket

The coherent state in Bargmann representation.

>>> from mrmustard.lab import Coherent, Vacuum, Dgate
>>> state = Coherent(mode=0, alpha=0.3 + 0.2j)
>>> assert state == Vacuum(0) >> Dgate(0, alpha=0.3 + 0.2j)

Parameters:

mode (int | tuple[int]) – The mode of the coherent state.
alpha (complex | Sequence[complex] | Parameter) – The alpha displacement of the coherent state.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A Ket object representing a coherent state.

Details and Conventions

For any \(\bar{\alpha} = \bar{x} + i\bar{y}\) of length \(N\), the \(N\)-mode coherent state displaced \(N\)-mode vacuum state is defined by

\[V = \frac{\hbar}{2}I_N \text{and } r = \sqrt{2\hbar}[\text{Re}(\bar{\alpha}), \text{Im}(\bar{\alpha})].\]

Its (A,b,c) triple is given by

\[A = O_{N\text{x}N}\text{, }b=\bar{\alpha}\text{, and }c=\text{exp}\big(-|\bar{\alpha}^2|/2\big).\]

Note that vector of means in phase space for a coherent state with parameters x,y is np.sqrt(2)*x, np.sqrt(2)*y (with units settings.HBAR=1).

DM¶

class mrmustard.lab.states.DM(ansatz_factory=None, wires=None, name=None)[source]¶

Bases: State

Base class for density matrices.

Parameters:

ansatz_factory (AnsatzFactory | None)
wires (Wires | None)
name (str | None)

property is_positive: bool¶

Whether this DM corresponds to a positive operator.

>>> from mrmustard.lab import GaussianDM
>>> assert GaussianDM.random([0]).is_positive

Raises:

NotImplementedError – If the state is mixed.
NotImplementedError – If the state has derived variables.
NotImplementedError – If the state has an ArrayAnsatz.

property is_physical: bool¶

Whether this DM is a physical density operator.

>>> from mrmustard.lab import GaussianDM
>>> assert GaussianDM.random([0]).is_physical

property probability: float¶: Probability (trace) of this DM, using the batch dimension of the Ansatz as a convex combination of states.

property purity: float¶

Computes the purity (\(tr(rho^2)\)) of this DM.

>>> from mrmustard import math
>>> from mrmustard.lab import DM, Vacuum
>>> assert math.allclose(Vacuum([0]).dm().purity, 1.0)

classmethod from_bargmann(modes, triple, name=None, lin_sup=False)[source]¶

Initializes a state of type cls from an (A, b, c) triple parametrizing the Ansatz in Bargmann representation.

>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> from mrmustard.physics.triples import coherent_state_Abc
>>> from mrmustard.lab.states.ket import Ket
>>> modes = (0,)
>>> triple = coherent_state_Abc(alpha=0.1)
>>> coh = Ket.from_bargmann(modes, triple)
>>> assert coh.modes == modes
>>> assert coh.ansatz == PolyExpAnsatz(*triple)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
name (str | None) – The name of this state.
lin_sup (bool) – Whether to include linear superposition axes in the batch dimensions.

Returns:

A State.

Raises:

ValueError – If the A or b have a shape that is inconsistent with the number of modes.

Return type:

DM

classmethod from_fock(modes, array, name=None, batch_dims=0)[source]¶

Initializes a state of type cls from an array parametrizing the state in Fock representation.

>>> from mrmustard.physics.ansatz import ArrayAnsatz
>>> from mrmustard.lab import Coherent, Ket
>>> array = Coherent(mode=0, alpha=0.1).to_fock().ansatz.array
>>> coh = Ket.from_fock((0,), array, batch_dims=0)
>>> assert coh.modes == (0,)
>>> assert coh.ansatz == ArrayAnsatz(array, batch_dims=0)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
array (ComplexTensor) – The Fock array.
name (str | None) – The name of this state.
batch_dims (int) – The number of batch dimensions in the given array.

Returns:

A State.

Raises:

ValueError – If the given array has a shape that is inconsistent with the number of modes.

Return type:

DM

classmethod from_ansatz(modes, ansatz=None, name=None)[source]¶

Initializes a state of type cls given modes and an ansatz.

>>> from mrmustard import math
>>> from mrmustard.lab import Ket
>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> A = math.astensor([[0,.5], [.5,0]])
>>> b = math.astensor([2-1j,2+1j])
>>> c = 1
>>> psi = Ket.from_ansatz([0,1], PolyExpAnsatz(A,b,c))
>>> assert isinstance(psi, Ket)

Parameters:

modes (Collection[int]) – The modes of this state.
ansatz (PolyExpAnsatz | ArrayAnsatz | None) – The ansatz of this state.
name (str | None) – The name of this state.

Returns:

A state.

Return type:

DM

classmethod from_phase_space(modes, triple, name=None, atol_purity=None)[source]¶

Initializes a density matrix from the covariance matrix, vector of means and a coefficient, which parametrize the s-parametrized phase space function \(coeff * exp(-1/2(x-means)^T cov^{-1} (x-means))\).h:coeff * exp((x-means)^T cov^{-1} (x-means)).

>>> from mrmustard import math
>>> from mrmustard.lab import DM, Vacuum
>>> rho = DM.from_phase_space([0], (math.eye(2)/2, [0,0], 1))
>>> assert rho == Vacuum([0]).dm()

Parameters:

modes (Collection[int]) – The modes of this states.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (cov, means, coeff) triple.
name (str | None) – The name of this state.
atol_purity (float | None) – Unused argument.

Returns:

A DM object from its phase space representation.

Return type:

DM

Details and Conventions

The Wigner function is considered as \(coeff * exp(-1/2(x-means)^T cov^{-1} (x-means))\).h:coeff * exp((x-means)^T cov^{-1} (x-means)).

classmethod from_quadrature(modes, triple, phi=0.0, name=None)[source]¶

Initializes a state from a triple (A,b,c) that parametrizes the wavefunction as c * exp(0.5 z^T A z + b^T z) in the quadrature representation.

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
phi (float) – The angle of the quadrature. 0 corresponds to the x quadrature (default).
name (str | None) – The name of this state.

Returns:

A state of type cls.

Raises:

ValueError – If the given triple has shapes that are inconsistent with the number of modes.

Return type:

DM

dm()[source]¶

The DM object obtained from this DM.

>>> from mrmustard.lab import Vacuum, DM
>>> assert isinstance(Vacuum([0]).dm(), DM)

Returns:: A DM.
Return type:: DM

expectation(operator)[source]¶

The expectation value of an operator with respect to this DM.

Given the operator O, this function returns \(Tr\big(\rho O)\), where \(\rho\) is the density matrix of this state.

The operator is expected to be a component with ket-like wires (i.e., output wires on the ket side), density matrix-like wires (output wires on both ket and bra sides), or unitary-like wires (input and output wires on the ket side).

>>> from mrmustard import math
>>> from mrmustard.lab import Rgate, GaussianDM
>>> beta = 1
>>> symplectic = math.eye(2)
>>> rho = GaussianDM([0], beta, symplectic)
>>> answer = (1-math.exp(-beta))/(1+math.exp(-beta))
>>> assert math.allclose(rho.expectation(Rgate(0, np.pi)), answer)

Parameters:

operator (CircuitComponent) – A ket-like, density-matrix like, or unitary-like circuit component.

Returns:

Expectation value either as a complex number or a batch of complex numbers.

Raises:

ValueError – If the operator is not a ket-like, density-matrix like, or unitary-like component.
ValueError – If the operator is defined over a set of modes that is not a subset of the modes of this state.
ValueError – If the modes in common between the operator and the state are not a subset of the modes of the operator.

Return type:

Scalar

fidelity(other)[source]¶

The fidelity between this DM and another ket or DM. If the other state is a Ket, fidelity is computed as the squared overlap, consistent with the pure state’s fidelity. If the other state is a DM and the representation is Fock, the fidelity is computed as in Richard Jozsa (1994) Fidelity for Mixed Quantum States, Journal of Modern Optics, 41:12, 2315-2323, DOI: 10.1080/09500349414552171 Otherwise, the fidelity is computed as the Gaussian fidelity as in arXiv:2102.05748 <https://arxiv.org/pdf/2102.05748.pdf> (square definition).

Parameters:

other (State) – The other state.

Returns:

The fidelity between this DM and the other state (Ket or DM).

Raises:

NotImplementedError – If the state is batched.
ValueError – If the states have different modes.

Return type:

Scalar

fock_array(shape=None, standard_order=False)[source]¶

Returns an array representation of this component in the Fock basis with the given shape.

The standard_order boolean argument lets one choose the standard convention for the index ordering of the density matrix. For a single mode, if standard_order=True the returned 2D array \(rho_{ij}\) has a first index corresponding to the “left” (ket) side of the matrix and the second index to the “right” (bra) side. Otherwise, MrMustard’s convention is that the bra index comes before the ket index. In other words, for a single mode, the array returned by fock_array with standard_order=False (false by default) is the transpose of the standard density matrix. For multiple modes, the same applies to each pair of indices of each mode.

>>> from mrmustard import math
>>> from mrmustard.lab import Vacuum, DM
>>> assert math.allclose(Vacuum([0]).dm().fock_array(), math.astensor([[1]]))

Parameters:

shape (int | Sequence[int] | None) – The shape of the returned representation. If shape is given as an int, it is broadcasted to all the dimensions. If not given, it is generated via auto_shape.
standard_order (bool) – The ordering of the wires. If standard_order = False, then the conventional ordering of bra-ket is chosen. However, if one wants to get the actual matrix representation in the standard conventions of linear algebra, then standard_order=True must be chosen.

Returns:

The Fock representation of this component.

Return type:

array

Raises:

ValueError – If the shape is not valid for the component.

Note

The standard_order boolean argument lets one choose the standard convention for the index ordering of the density matrix. For a single mode, if standard_order=True the returned 2D array \(rho_{ij}\) has a first index corresponding to the “left” (ket) side of the matrix and the second index to the “right” (bra) side. Otherwise, MrMustard’s convention is that the bra index comes before the ket index. In other words, for a single mode, the array returned by fock_array with standard_order=False (false by default) is the transpose of the standard density matrix. For multiple modes, the same applies to each pair of indices of each mode.

formal_stellar_decomposition(core_modes)[source]¶

Computes the formal stellar decomposition for the DM.

>>> from mrmustard.lab import GaussianDM, Vacuum
>>> rho = GaussianDM.random([0,1])
>>> core, phi = rho.formal_stellar_decomposition([0])
>>> assert (core >> Vacuum(1).dual).normalize() == Vacuum(0).dm()
>>> assert rho == core >> phi
>>> assert (core >> Vacuum(1).dual).normalize() == Vacuum(0).dm()

Parameters:: core_modes (Collection[int]) – The set of modes defining core variables.
Returns:: The core state (DM) and the Gaussian Map performing the stellar decomposition (not necessarily CPTP).
Return type:: tuple[DM, Map]

Note

This method pulls out the map phi from the given state on the given modes, so that the remaining state is a core state. Formally, we have .. math:

\rho = (\phi\otimes\mathcal I) \rho_{\mathrm{core}}

where the map \(phi\) acts on the given core_modes only. Core states have favorable properties in the Fock representation e.g., being sparse.

physical_stellar_decomposition(core_modes)[source]¶

Applies the physical stellar decomposition.

When the number of core modes equals exactly half of the total modes (and n_modes is even), returns a Ket core and Channel. Otherwise, returns a DM core and Channel.

>>> from mrmustard.lab import GaussianDM, Vacuum
>>> rho = GaussianDM.random([0, 1])
>>> core, phi = rho.physical_stellar_decomposition([0])
>>> assert rho == core >> phi
>>> assert (core >> Vacuum(1).dual).normalize() == Vacuum(0)

Parameters:: core_modes (Collection[int]) – The core modes defining the core variables.
Returns:: The core state (DM or Ket depending on the number of core modes) and the channel acting on the core modes.
Raises:: ValueError – If the rank condition is not satisfied (when core modes < half).
Return type:: tuple[State, Channel]

DisplacedSqueezed¶

class mrmustard.lab.states.DisplacedSqueezed(mode, alpha=0j, r=0.0, phi=0.0, name=None)[source]¶

Bases: Ket

The displaced squeezed state in Bargmann representation.

>>> from mrmustard.lab import DisplacedSqueezed, Vacuum, Sgate, Dgate
>>> state = DisplacedSqueezed(mode=0, alpha=1, r=0.2, phi=0.3)
>>> assert state == Vacuum(0) >> Sgate(0, r=0.2, phi=0.3) >> Dgate(0, alpha=1)

Parameters:

mode (int | tuple[int]) – The mode of the displaced squeezed state.
alpha (complex | Sequence[complex] | Parameter) – The complex displacement.
r (float | Sequence[float] | Parameter) – The squeezing magnitude.
phi (float | Sequence[float] | Parameter) – The squeezing angle.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A Ket.

GaussianDM¶

class mrmustard.lab.states.GaussianDM(modes, beta, symplectic, name=None)[source]¶

Bases: DM

The N-mode mixed state described by a Gaussian gate that acts on a given thermal state. This corresponds to the Williamson form. It is equivalent to the construction Thermal(beta) >> Ggate(symplectic).

>>> from mrmustard.lab import GaussianDM, DM
>>> rho = GaussianDM.random(modes=0)
>>> assert isinstance(rho, DM)

Parameters:

modes (int | tuple[int, ...]) – The modes over which the state is defined.
beta (float | Sequence[float] | Parameter) – the set of temperatures determining the thermal states. If only a float is provided for a multi-mode state, the same temperature is considered across all modes.
symplectic (RealMatrix | Parameter) – The symplectic representation of the unitary that acts on a vacuum to produce the desired state.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A GaussianDM.

Details and Conventions

For a given Gaussian unitary U (that is determined by its symplectic representation), and a set of temperatures, produces the state

\[\rho = U (\bigotimes_i \rho_t(\beta_i))\]

where rho_t are thermal states with temperatures determined by beta.

classmethod random(modes, max_r=1.0, min_beta=0.2, max_beta=1.0, max_disp=None, seed=None, name=None)[source]¶

Returns a random GaussianDM, optionally displaced.

Constructed as Thermal(beta) >> Ggate(symplectic), for a random beta and a random symplectic. If a specific beta is required, use the construction Thermal(beta) >> Ggate.random() where beta is the desired inverse temperature. To obtain random Gaussian density matrices from the induced trace measure, use the construction GaussianKet.random().get_modes() with appropriate modes.

When max_disp is given, each mode is displaced by a random complex amplitude sampled uniformly from the disk of radius max_disp.

Parameters:

modes (int | tuple[int, ...]) – The modes of the GaussianDM.
max_r (float) – Maximum squeezing parameter for the Gaussian unitary. Default is 1.0.
min_beta (float) – Minimum inverse temperature that will be sampled. Default is 0.5.
max_beta (float) – Maximum inverse temperature that will be sampled. Default is 1.0.
max_disp (float | None) – Maximum displacement amplitude. Each mode gets an independent displacement sampled uniformly from the disk |alpha| <= max_disp. If None, no displacement is applied.
seed (int | None) – The random seed. If None, the global seed is used.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

The random state (GaussianDM if no displacement, DM otherwise).

Raises:

ValueError – if modes is an empty tuple.

Return type:

DM

get_modes(modes)[source]¶

Keep the given modes and trace out the rest.

Parameters:: modes (int | Sequence[int]) – The modes to keep.
Returns:: A new GaussianDM with the modes indexed by modes.
Return type:: GaussianDM

GaussianKet¶

class mrmustard.lab.states.GaussianKet(modes, symplectic, name=None)[source]¶

Bases: Ket

The N-mode pure state described by a Gaussian gate that acts on Vacuum.

>>> from mrmustard.lab import GaussianKet, Ket
>>> psi = GaussianKet.random(modes=0)
>>> assert isinstance(psi, Ket)

Parameters:

modes (int | tuple[int, ...]) – The modes over which the state is defined.
symplectic (RealMatrix | Parameter) – The symplectic representation of the unitary that acts on
state. (vacuum to produce the desired)
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A GaussianKet.

Details and Conventions

For a given Gaussian unitary U (that is determined by its symplectic representation), produces the state

\[|\psi\rangle = U |0\rangle\]

classmethod random(modes, max_r=1.0, max_disp=None, seed=None, name=None)[source]¶

Returns a random GaussianKet, optionally displaced.

When max_disp is given, each mode is displaced by a random complex amplitude sampled uniformly from the disk of radius max_disp.

Parameters:

modes (int | tuple[int, ...]) – The modes of the GaussianKet.
max_r (float) – Maximum squeezing parameter over which we make random choices.
max_disp (float | None) – Maximum displacement amplitude. Each mode gets an independent displacement sampled uniformly from the disk |alpha| <= max_disp. If None, no displacement is applied.
seed (int | None) – The random seed. If None, the global seed is used.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

The random state (GaussianKet if no displacement, Ket otherwise).

Raises:

ValueError – if modes is an empty tuple.

Return type:

Ket

get_modes(modes)[source]¶

Keep the given modes and trace out the rest. Returns a density matrix.

Parameters:: modes (int | Sequence[int]) – The modes to keep.
Returns:: A new GaussianKet with the modes indexed by modes.
Return type:: GaussianKet

Ket¶

class mrmustard.lab.states.Ket(ansatz_factory=None, wires=None, name=None)[source]¶

Bases: State

Base class for all Hilbert space vectors.

Parameters:

ansatz_factory (AnsatzFactory | None)
wires (Wires | None)
name (str | None)

property is_physical: bool¶

Whether the ket object is a physical one.

>>> from mrmustard.lab import GaussianKet
>>> psi = GaussianKet.random([0])
>>> assert psi.is_physical

Returns:

A boolean variable.

Raises:

NotImplementedError – If the state is in a linear superposition.
NotImplementedError – If the state has derived variables.
NotImplementedError – If the state has an ArrayAnsatz.

property probability: float¶

Probability of this Ket (L2 norm squared).

>>> from mrmustard import math
>>> from mrmustard.lab import GaussianKet
>>> psi = GaussianKet.random([0])
>>> assert math.allclose(psi.probability, 1.0)

Returns:: The probability of this Ket.

property purity: float¶

The purity of the state.

>>> from mrmustard.lab import GaussianKet
>>> assert GaussianKet.random([0]).purity == 1.0

Returns:: The purity of this Ket (always 1.0).

classmethod from_bargmann(modes, triple, name=None, lin_sup=False)[source]¶

Initializes a state of type cls from an (A, b, c) triple parametrizing the Ansatz in Bargmann representation.

>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> from mrmustard.physics.triples import coherent_state_Abc
>>> from mrmustard.lab.states.ket import Ket
>>> modes = (0,)
>>> triple = coherent_state_Abc(alpha=0.1)
>>> coh = Ket.from_bargmann(modes, triple)
>>> assert coh.modes == modes
>>> assert coh.ansatz == PolyExpAnsatz(*triple)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
name (str | None) – The name of this state.
lin_sup (bool) – Whether to include linear superposition axes in the batch dimensions.

Returns:

A State.

Raises:

ValueError – If the A or b have a shape that is inconsistent with the number of modes.

Return type:

Ket

classmethod from_fock(modes, array, name=None, batch_dims=0)[source]¶

Initializes a state of type cls from an array parametrizing the state in Fock representation.

>>> from mrmustard.physics.ansatz import ArrayAnsatz
>>> from mrmustard.lab import Coherent, Ket
>>> array = Coherent(mode=0, alpha=0.1).to_fock().ansatz.array
>>> coh = Ket.from_fock((0,), array, batch_dims=0)
>>> assert coh.modes == (0,)
>>> assert coh.ansatz == ArrayAnsatz(array, batch_dims=0)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
array (ComplexTensor) – The Fock array.
name (str | None) – The name of this state.
batch_dims (int) – The number of batch dimensions in the given array.

Returns:

A State.

Raises:

ValueError – If the given array has a shape that is inconsistent with the number of modes.

Return type:

Ket

classmethod from_ansatz(modes, ansatz=None, name=None)[source]¶

Initializes a state of type cls given modes and an ansatz.

>>> from mrmustard import math
>>> from mrmustard.lab import Ket
>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> A = math.astensor([[0,.5], [.5,0]])
>>> b = math.astensor([2-1j,2+1j])
>>> c = 1
>>> psi = Ket.from_ansatz([0,1], PolyExpAnsatz(A,b,c))
>>> assert isinstance(psi, Ket)

Parameters:

modes (Collection[int]) – The modes of this state.
ansatz (PolyExpAnsatz | ArrayAnsatz | None) – The ansatz of this state.
name (str | None) – The name of this state.

Returns:

A state.

Return type:

Ket

classmethod from_phase_space(modes, triple, name=None, atol_purity=None)[source]¶

Initializes a state from the covariance matrix and the vector of means of a state in phase space.

>>> from mrmustard import math
>>> from mrmustard.lab import Ket, Vacuum
>>> assert Ket.from_phase_space([0], (math.eye(2)/2, [0,0], 1)) == Vacuum([0])

Note

If the given covariance matrix and vector of means are consistent with a pure state, a Ket is returned. Otherwise, a DM is returned. One can skip this check by setting atol_purity to None (atol_purity defaults to None).

Parameters:

modes (Collection[int]) – The modes of this states.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – A covariance matrix, vector of means, and constant multiple triple.
name (str | None) – The name of this state.
atol_purity (float | None) – If atol_purity is given, the purity of the state is computed, and an error is raised if its value is smaller than 1-atol_purity or larger than 1+atol_purity. If None, this check is skipped.

Returns:

A State.

Raises:

ValueError – If the given cov and means have shapes that are inconsistent with the number of modes.
ValueError – If atol_purity is not None and the purity of the returned state is smaller than 1-atol_purity or larger than 1+atol_purity.

Return type:

Ket

classmethod from_quadrature(modes, triple, phi=0.0, name=None)[source]¶

Initializes a state from a triple (A,b,c) that parametrizes the wavefunction as c * exp(0.5 z^T A z + b^T z) in the quadrature representation.

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
phi (float) – The angle of the quadrature. 0 corresponds to the x quadrature (default).
name (str | None) – The name of this state.

Returns:

A state of type cls.

Raises:

ValueError – If the given triple has shapes that are inconsistent with the number of modes.

Return type:

Ket

dm()[source]¶

The DM object obtained from this Ket.

>>> from mrmustard.lab import Vacuum, DM
>>> assert isinstance(Vacuum([0]).dm(), DM)

Returns:: A DM.
Return type:: DM

expectation(operator)[source]¶

The expectation value of an operator calculated with respect to this Ket.

>>> from mrmustard import math
>>> from mrmustard.lab import Number, Rgate
>>> psi = Number(0, 1)
>>> theta = 0.123
>>> answer = math.exp(1j*theta)
>>> assert math.allclose(psi.expectation(Rgate(0, theta)), answer)

Parameters:

operator (CircuitComponent) – A ket-like, density-matrix like, or unitary-like circuit component.

Returns:

Expectation value as a complex number.

Raises:

ValueError – If the operator is not a ket-like, density-matrix like, or unitary-like component.
ValueError – If the operator is defined over a set of modes that is not a subset of the modes of this state.
ValueError – If the modes in common between the operator and the state are not a subset of the modes of the operator.

Return type:

Scalar

Note

Given the operator O, this function returns \(Tr\big(|\psi\rangle\langle\psi| O)\), where \(|\psi\rangle\) is the vector representing this state.

The operator is expected to be a component with ket-like wires (i.e., output wires on the ket side), density matrix-like wires (output wires on both ket and bra sides), or unitary-like wires (input and output wires on the ket side).

fidelity(other)[source]¶

The fidelity between this ket and another state.

Details and Conventions

\[F(|\psi\rangle, \phi\rangle) = |\langle \psi, \phi \rangle|^2\]

Parameters:: other (State) – The other state.
Returns:: The fidelity between this ket and the other state.
Raises:: ValueError – If the states have different modes.
Return type:: Scalar

formal_stellar_decomposition(core_modes)[source]¶

Applies the formal stellar decomposition.

>>> from mrmustard.lab import GaussianKet
>>> psi = GaussianKet.random([0,1])
>>> core, t = psi.formal_stellar_decomposition([0])
>>> A_core = core.ansatz.A
>>> assert A_core[0,0] == 0

Parameters:: core_modes (Collection[int]) – The set of modes defining core variables.
Returns:: The core state (Ket) and the Gaussian Operation performing the stellar decomposition.
Return type:: tuple[Ket, Operation]

Note

This method pulls out the unitary U from the given state on the given modes, so that the remaining state is a core state. Formally, we have .. math:

\psi = (T\otimes\mathbb I) S_{\mathrm{core}}

where the operator \(T\) acts on the given core_modes only. Core states have favorable properties in the Fock representation e.g., being sparse.

physical_stellar_decomposition(core_modes)[source]¶

Applies the physical stellar decomposition.

>>> from mrmustard import math
>>> from mrmustard.lab import GaussianKet
>>> psi = GaussianKet.random([0,1])
>>> core, U = psi.physical_stellar_decomposition([0])
>>> assert psi == core >> U
>>> A_c = core.ansatz.A
>>> assert math.allclose(A_c[0,0], 0)

Parameters:: core_modes (Collection[int]) – The set of modes defining core variables.
Returns:: The core state (Ket) and the Gaussian unitary performing the stellar decomposition.
Return type:: tuple[Ket, Unitary]

Note

This method pulls out the unitary U from the given state on the given modes, so that the remaining state is a core state. Formally, we have

\[\psi = (U\otimes\mathbb I) \psi_{\mathrm{core}}\]

where the unitary U acts on the given core_modes only. Core states have favorable properties in the Fock representation e.g., being sparse.

stellar_roots(max_degree=None)[source]¶

Compute the stellar roots of this single-mode ket.

The stellar roots are the zeros of the Bargmann polynomial

\[F(z) = \sum_n c_n z^n / \sqrt{n!}\]

built from the Fock amplitudes \(c_{n}\) of this state.

For states already in Fock representation the amplitudes are used directly. For Bargmann states whose c tensor is scalar (i.e. pure Gaussian states with no polynomial part) there are no finite roots and an empty array is returned. For Bargmann states with a non-scalar c the state is converted to Fock using the polynomial degree (or the explicit max_degree if provided, clamped to the true polynomial degree to avoid spurious roots from the Gaussian envelope). The polynomial degree is sum(n_i - 1) where n_i are the dimensions of the derived-variable part of c.

Parameters:: max_degree (int | None) – Maximum polynomial degree for computing the roots. For PolyExpAnsatz states this is clamped to the true polynomial degree. If None, the degree is inferred from the ansatz.
Returns:: Complex 1D array of stellar roots (empty for Gaussian states).
Raises:: ValueError – If the state has more than one mode or is batched.
Return type:: ndarray

plot_stellar_roots(max_degree=None, *, ax=None, max_limit=10.0)[source]¶

Plot the stellar roots of this single-mode ket.

Each root is plotted in the complex plane and colored by its phase angle via the HSV colormap.

Parameters:

max_degree (int | None) – Maximum polynomial degree for computing the roots. If None, the degree is inferred from the ansatz.
ax (Axes | None) – Optional matplotlib Axes to draw on. When provided the roots are drawn on the existing axes (no new figure is created and plt.show() is not called). Useful with the ipympl backend for flicker-free interactive updates.
max_limit (float) – Maximum absolute value for each axis.

Returns:

The matplotlib Axes instance used for the plot.

Raises:

ValueError – If the state has more than one mode or is batched.

Return type:

Axes

Number¶

class mrmustard.lab.states.Number(mode, n, cutoff=None, name=None)[source]¶

Bases: Ket

The number state in Fock representation.

>>> from mrmustard.lab import Number
>>> from mrmustard.physics.ansatz import ArrayAnsatz
>>> state = Number(mode=0, n=10)
>>> assert isinstance(state.ansatz, ArrayAnsatz)

Parameters:

mode (int | tuple[int]) – The mode of the number state.
n (int | Sequence[int]) – The (batchable) number of photons.
cutoff (int | None) – The photon cutoff. If cutoff is None, it defaults to math.max(n).
name (str | None) – A name for the state. If not provided, the class name will be used.

Details and Conventions

For any \(\bar{n} = (n_1,\:\ldots,\:n_N)\), the \(N\)-mode number state is defined by

\[\ket{\bar{n}} = \ket{n_1}\otimes\ldots\otimes\ket{n_N}\:,\]

where \(\ket{n_j}\) is the eigenstate of the number operator on mode j with eigenvalue \(n_j\).

QuadratureEigenstate¶

class mrmustard.lab.states.QuadratureEigenstate(mode, x=0.0, phi=0.0, name=None)[source]¶

Bases: Ket

The Quadrature eigenstate in Bargmann representation.

>>> from mrmustard.lab import QuadratureEigenstate
>>> state = QuadratureEigenstate(1, x = 1, phi = 0)
>>> assert state.modes == (1,)

Parameters:

mode (int | tuple[int]) – The mode of the quadrature eigenstate.
x (float | Sequence[float] | Parameter) – The displacement of the state.
phi (float | Sequence[float] | Parameter) – The angle of the state with 0 being a position eigenstate and pi/2 being the momentum eigenstate.
name (str | None) – A name for the state. If not provided, the class name will be used.

Details and Conventions

Its (A,b,c) triple is given by

\[A = -I_{N}\exp(i2\phi)\text{, }b = I_Nx\exp(i\phi)\sqrt{2/\hbar}\text{, and }c = 1/(\pi\hbar)^{-1/4}\exp(-\abs{x}^2/(2\hbar)).\]

property L2_norm¶: The L2 norm of this quadrature eigenstate.

Sauron¶

class mrmustard.lab.states.Sauron(mode, n, epsilon=0.1, name=None)[source]¶

Bases: Ket

The n-th Sauron state is an approximation of the n-th Fock states using a ring of n+1 coherent states.

>>> from mrmustard.lab import Sauron
>>> psi = Sauron(0, 1)
>>> assert psi.modes == (0,)

Parameters:

mode (int | tuple[int]) – The mode of the Sauron state.
n (int) – The Fock state that is approximated.
epsilon (float) – The radius of the ring of coherent states, default is 0.1.
name (str | None) – A name for the state. If not provided, the class name will be used.

Note

The reference to the Lord of the Rings comes from the approximation becoming perfect in the limit for the radius of the ring going to zero where vacuum (= darkness) is. The formula for the Sauron state as a superposition of coherent states on a ring is given in https://arxiv.org/abs/2305.17099:

\[|\text{Sauron}(n)\rangle = \frac{1}{\mathcal{N}}\sum_{k=0}^{n} e^{i 2\pi k/(n+1)} |\epsilon e^{2\pi k/(n+1)}\rangle_c,\]

SqueezedVacuum¶

class mrmustard.lab.states.SqueezedVacuum(mode, r=0.0, phi=0.0, name=None)[source]¶

Bases: Ket

The squeezed vacuum state in Bargmann representation.

>>> from mrmustard.lab import SqueezedVacuum, Vacuum, Sgate
>>> state = SqueezedVacuum(mode=0, r=0.3, phi=0.2)
>>> assert state == Vacuum(0) >> Sgate(0, r=0.3, phi=0.2)

Parameters:

mode (int | tuple[int]) – The mode of the squeezed vacuum state.
r (float | Sequence[float] | Parameter) – The squeezing magnitude.
phi (float | Sequence[float] | Parameter) – The squeezing angle.
name (str | None) – A name for the state. If not provided, the class name will be used.

State¶

class mrmustard.lab.states.State(ansatz_factory=None, wires=None, name=None)[source]¶

Bases: CircuitComponent

Base class for all states.

Parameters:

ansatz_factory (AnsatzFactory | None)
wires (Wires | None)
name (str | None)

property is_pure¶: Whether this state is pure.

property is_separable¶

Check if a multi-mode quantum state is separable based on the von Neumann entropy.

Returns:: Whether the state is separable.
Raises:: NotImplementedError – If the state is a linear superposition.

property L2_norm: float¶

The L2 norm squared of a Ket, or the Hilbert-Schmidt norm of a DM.

>>> from mrmustard import math
>>> from mrmustard.lab import GaussianKet
>>> state = GaussianKet.random([0])
>>> assert math.allclose(state.L2_norm, 1.0)

abstract property probability: float¶: Returns \(\langle\psi|\psi\rangle\) for Ket states \(|\psi\rangle\) and \(\text{Tr}(\rho)\) for DM states \(\rho\).

abstract property purity: float¶: The purity of this state.

property wigner¶

Returns the Wigner function of this state in phase space as an Ansatz.

>>> import numpy as np
>>> from mrmustard.lab import GaussianKet
>>> state = GaussianKet.random([0])
>>> x = np.linspace(-5, 5, 100)
>>> assert np.all(state.wigner(x,0).real >= 0)

classmethod from_bargmann(modes, triple, name=None, lin_sup=False)[source]¶

Initializes a state of type cls from an (A, b, c) triple parametrizing the Ansatz in Bargmann representation.

>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> from mrmustard.physics.triples import coherent_state_Abc
>>> from mrmustard.lab.states.ket import Ket
>>> modes = (0,)
>>> triple = coherent_state_Abc(alpha=0.1)
>>> coh = Ket.from_bargmann(modes, triple)
>>> assert coh.modes == modes
>>> assert coh.ansatz == PolyExpAnsatz(*triple)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
name (str | None) – The name of this state.
lin_sup (bool) – Whether to include linear superposition axes in the batch dimensions.

Returns:

A State.

Raises:

ValueError – If the A or b have a shape that is inconsistent with the number of modes.

Return type:

Self

classmethod from_fock(modes, array, name=None, batch_dims=0)[source]¶

Initializes a state of type cls from an array parametrizing the state in Fock representation.

>>> from mrmustard.physics.ansatz import ArrayAnsatz
>>> from mrmustard.lab import Coherent, Ket
>>> array = Coherent(mode=0, alpha=0.1).to_fock().ansatz.array
>>> coh = Ket.from_fock((0,), array, batch_dims=0)
>>> assert coh.modes == (0,)
>>> assert coh.ansatz == ArrayAnsatz(array, batch_dims=0)
>>> assert isinstance(coh, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
array (ComplexTensor) – The Fock array.
name (str | None) – The name of this state.
batch_dims (int) – The number of batch dimensions in the given array.

Returns:

A State.

Raises:

ValueError – If the given array has a shape that is inconsistent with the number of modes.

Return type:

Self

abstract classmethod from_ansatz(modes, ansatz=None, name=None)[source]¶

Initializes a state of type cls given modes and an ansatz.

>>> from mrmustard import math
>>> from mrmustard.lab import Ket
>>> from mrmustard.physics.ansatz import PolyExpAnsatz
>>> A = math.astensor([[0,.5], [.5,0]])
>>> b = math.astensor([2-1j,2+1j])
>>> c = 1
>>> psi = Ket.from_ansatz([0,1], PolyExpAnsatz(A,b,c))
>>> assert isinstance(psi, Ket)

Parameters:

modes (Sequence[int]) – The modes of this state.
ansatz (PolyExpAnsatz | ArrayAnsatz | None) – The ansatz of this state.
name (str | None) – The name of this state.

Returns:

A state.

Return type:

Self

abstract classmethod from_phase_space(modes, triple, name=None, atol_purity=None)[source]¶

Initializes a state from the covariance matrix and the vector of means of a state in phase space.

>>> from mrmustard import math
>>> from mrmustard.lab import Ket, Vacuum
>>> assert Ket.from_phase_space([0], (math.eye(2)/2, [0,0], 1)) == Vacuum([0])

Note

If the given covariance matrix and vector of means are consistent with a pure state, a Ket is returned. Otherwise, a DM is returned. One can skip this check by setting atol_purity to None (atol_purity defaults to None).

Parameters:

modes (Sequence[int]) – The modes of this states.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – A covariance matrix, vector of means, and constant multiple triple.
name (str | None) – The name of this state.
atol_purity (float | None) – If atol_purity is given, the purity of the state is computed, and an error is raised if its value is smaller than 1-atol_purity or larger than 1+atol_purity. If None, this check is skipped.

Returns:

A State.

Raises:

ValueError – If the given cov and means have shapes that are inconsistent with the number of modes.
ValueError – If atol_purity is not None and the purity of the returned state is smaller than 1-atol_purity or larger than 1+atol_purity.

Return type:

Self

classmethod from_quadrature(modes, triple, phi=0.0, name=None)[source]¶

Initializes a state from a triple (A,b,c) that parametrizes the wavefunction as c * exp(0.5 z^T A z + b^T z) in the quadrature representation.

Parameters:

modes (Sequence[int]) – The modes of this state.
triple (tuple[mrmustard.utils.typing.Matrix, mrmustard.utils.typing.Vector, mrmustard.utils.typing.Scalar]) – The (A, b, c) triple.
phi (float) – The angle of the quadrature. 0 corresponds to the x quadrature (default).
name (str | None) – The name of this state.

Returns:

A state of type cls.

Raises:

ValueError – If the given triple has shapes that are inconsistent with the number of modes.

Return type:

Self

auto_shape(max_prob=None, max_shape=None, min_shape=None, respect_manual_shape=True)[source]¶

Generates an estimate for the Fock shape. If the state is in Fock the core shape is used. If in Bargmann, the shape is computed as the shape that captures at least settings.AUTOSHAPE_PROBABILITY of the probability mass of each single-mode marginal (default 99.9%) so long as the state has no derived variables and is unbatched. Otherwise, defaults to settings.DEFAULT_FOCK_SIZE. If respect_manual_shape is True, the non-None values in self.manual_shape are used to override the shape.

>>> from mrmustard import math
>>> from mrmustard.lab import Vacuum
>>> assert math.allclose(Vacuum([0]).fock_array(), 1)

Note

If jitted, the shape will default to settings.DEFAULT_FOCK_SIZE.

Parameters:

max_prob – The maximum probability mass to capture in the shape. Default is settings.AUTOSHAPE_PROBABILITY.
max_shape – The maximum shape cutoff. Default is settings.AUTOSHAPE_MAX.
min_shape – The minimum shape cutoff. Default is settings.AUTOSHAPE_MIN.
respect_manual_shape – Whether to respect the non-None values in manual_shape. Default is True.

Returns:

The Fock shape of this component.

Return type:

tuple[int, …]

fock_distribution(cutoff)[source]¶

Returns the Fock distribution of the state up to some cutoff.

Parameters:: cutoff (int) – The photon cutoff (maximum photon number).
Returns:: The Fock distribution including states from \(|0\rangle\) to \(|\text{cutoff}\rangle\).
Return type:: ComplexTensor

get_modes(modes)[source]¶

Reduced density matrix obtained by tracing out all the modes except those in modes. Note that the result is returned with modes in increasing order.

Parameters:: modes (int | Sequence[int]) – The modes to keep.
Returns:: A State object with the remaining modes.
Raises:: ValueError – If the modes to keep are not a subset of the modes of the state.
Return type:: State

wormhole_1mode(pnr_outcomes, output_cutoff, leftover_mode)[source]¶

Compute conditional single-mode states given PNR measurements.

Uses the wormhole algorithm to efficiently compute the conditional state of one “leftover” mode given photon number resolving (PNR) measurements on all other modes. This is much more efficient than computing the full Fock tensor and slicing for high photon counts.

Supports both single and batched states. For batched states, the computation is parallelized across batch elements for improved performance.

Parameters:

pnr_outcomes (tuple[int, ...] | list[tuple[int, ...]]) – Either a single tuple or a list of tuples specifying photon counts for the measured modes. Each tuple has length n_modes - 1, with photon counts in mode order (excluding the leftover mode).
output_cutoff (int) – Maximum photon number for the output state.
leftover_mode (int) – The mode to keep unmeasured. Must be one of this state’s modes.

Returns:

Dict mapping PNR tuples to State objects (same type as self). For batched input states, the returned states will also be batched.

Raises:

ValueError – If this state has fewer than 2 modes.
ValueError – If leftover_mode is not one of this state’s modes.
ValueError – If pnr_outcomes tuples have wrong length.

Return type:

dict[tuple[int, …], State]

Example

>>> import numpy as np
>>> from mrmustard.lab import GaussianKet
>>> ket = GaussianKet.random([0, 1], seed=42)
>>> pnr = (2,)
>>> cutoff = 5
>>> results = ket.wormhole_1mode(pnr, output_cutoff=cutoff, leftover_mode=0)
>>> cond_ket = results[pnr]
>>> cond_ket.fock_array().shape
(6,)

Note

The wormhole algorithm is particularly efficient for high photon counts where computing the full Fock tensor would be prohibitively expensive. Memory scaling depends on state type: O(2^M × cutoff) for Ket, O(4^M × cutoff²) for DM, where M is the number of measured modes.

abstract formal_stellar_decomposition(core_modes)[source]¶

Applies the formal stellar decomposition.

Parameters:: core_modes (Sequence[int]) – The set of modes defining core variables.
Returns:: A tuple containing the core state and the Gaussian transformation performing the stellar decomposition.
Return type:: tuple[State, Transformation]

normalize()[source]¶

Returns a rescaled version of the state such that its probability is 1.

Return type:: State

phase_space(s)[source]¶

Returns the phase space parametrization of a state, consisting in a covariance matrix, a vector of means and a scaling coefficient. When a state is a linear superposition of Gaussians, each of cov, means, coeff are arranged in a batch.

Phase space representations are labelled by an s parameter (float) which modifies the exponent of \(D_s(\gamma) = e^{\frac{s}{2}|\gamma|^2}D(\gamma)\), which is the operator basis used to expand phase space density matrices.

The s parameter typically takes the values of -1, 0, 1 to indicate Glauber/Wigner/Husimi functions.

Parameters:: s (float) – The phase space parameter
Returns:: The covariance matrix, the mean vector and the coefficient of the state in s-parametrized phase space.
Return type:: tuple

abstract physical_stellar_decomposition(core_modes)[source]¶

Applies the physical stellar decomposition.

Parameters:: core_modes (Sequence[int]) – The set of modes defining core variables.
Returns:: A tuple containing the core state and the Gaussian transformation performing the stellar decomposition.
Return type:: tuple[State, Transformation]

quadrature_distribution(*quad, phi=0.0)[source]¶

The (discretized) quadrature distribution of the State.

Parameters:

quad (RealVector) – the discretized quadrature axis over which the distribution is computed.
phi (float) – The quadrature angle. 0 corresponds to the x quadrature, pi/2 to the p quadrature.

Returns:

The quadrature distribution.

Return type:

ComplexTensor

visualize_2d(xbounds=(-6, 6), pbounds=(-6, 6), resolution=200, colorscale='RdBu', return_fig=False, min_shape=50)[source]¶

2D visualization of the Wigner function of this state.

Plots the Wigner function on a heatmap, alongside the probability distributions on the two quadrature axis.

>>> from mrmustard.lab import Coherent
>>> state = Coherent(0, alpha=1) / 2**0.5 + Coherent(0, alpha=-1) / 2**0.5
>>> # state.visualize_2d()

Parameters:

xbounds (tuple[int, int]) – The range of the x axis.
pbounds (tuple[int, int]) – The range of the p axis.
resolution (int) – The number of bins on each axes.
colorscale (str) – A colorscale. Must be one of Plotly's built-in continuous color scales.
return_fig (bool) – Whether to return the Plotly figure.
min_shape (int) – The minimum fock shape to use for the Wigner function plot.

Returns:

A Plotly figure representing the state in 2D.

Raises:

ValueError – If this state is a multi-mode state.

Return type:

Figure | None

visualize_2d_with_arrows(arrows, xbounds=(-6, 6), pbounds=(-6, 6), resolution=200, colorscale='RdBu', return_fig=False, min_shape=50)[source]¶

Plot the state Wigner function and q/p marginals along with arrows from the origin of the Wigner function.

Useful for, e.g., visualizing the stabilizer arguments of a GKP state.

Parameters:

arrows (ndarray) – 1D numpy array of complex numbers representing arrow end-points.
xbounds (tuple[int, int]) – The range of the x axis.
pbounds (tuple[int, int]) – The range of the p axis.
resolution (int) – The number of bins on each axes.
colorscale (str) – A colorscale. Must be one of Plotly’s built-in continuous color scales.
return_fig (bool) – Whether to return the Plotly figure.
min_shape (int) – The minimum fock shape to use for the Wigner function plot.

Returns:

A Plotly figure.

Return type:

Figure | None

visualize_3d(xbounds=(-6, 6), pbounds=(-6, 6), resolution=200, colorscale='RdBu', return_fig=False, min_shape=50)[source]¶

3D visualization of the Wigner function of this state on a surface plot.

Parameters:

xbounds (tuple[int, int]) – The range of the x axis.
pbounds (tuple[int, int]) – The range of the p axis.
resolution (int) – The number of bins on each axes.
colorscale (str) – A colorscale. Must be one of Plotly's built-in continuous color scales.
return_fig (bool) – Whether to return the Plotly figure.
min_shape (int) – The minimum fock shape to use for the Wigner function plot.

Returns:

A Plotly figure representing the state in 3D.

Raises:

ValueError – If this state is a multi-mode state.

Return type:

Figure | None

visualize_dm(cutoff=None, return_fig=False)[source]¶

Plots the absolute value \(abs(\rho)\) of the density matrix \(\rho\) of this state on a heatmap.

Parameters:

cutoff (int | None) – The desired cutoff. Defaults to the value of auto_shape.
return_fig (bool) – Whether to return the Plotly figure.

Returns:

A Plotly figure representing absolute value of the density matrix of this state.

Raises:

ValueError – If this state is a multi-mode state.

Return type:

Figure | None

Thermal¶

class mrmustard.lab.states.Thermal(mode, nbar=0.0, name=None)[source]¶

Bases: DM

The thermal state in Bargmann representation.

>>> from mrmustard.lab import Thermal
>>> state = Thermal(1, nbar=3)
>>> assert state.modes == (1,)

Parameters:

mode (int | tuple[int]) – The mode of the thermal state.
nbar (float | Sequence[float] | Parameter) – The expected number of photons.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A DM type object that represents the thermal state.

TwoModeSqueezedVacuum¶

class mrmustard.lab.states.TwoModeSqueezedVacuum(modes, r=0.0, phi=0.0, name=None)[source]¶

Bases: Ket

The two-mode squeezed vacuum state.

>>> from mrmustard.lab import TwoModeSqueezedVacuum, S2gate, Vacuum
>>> state = TwoModeSqueezedVacuum(modes=(0, 1), r=0.3, phi=0.2)
>>> assert state == Vacuum((0,1)) >> S2gate((0, 1), r=0.3, phi=0.2)

Parameters:

modes (tuple[int, int]) – The modes of the two-mode squeezed vacuum state.
r (float | Sequence[float] | Parameter) – The squeezing magnitude.
phi (float | Sequence[float] | Parameter) – The squeezing angle.
name (str | None) – A name for the state. If not provided, the class name will be used.

Returns:

A Ket type object that represents the two-mode squeezed vacuum state.

Vacuum¶

class mrmustard.lab.states.Vacuum(modes, name=None)[source]¶

Bases: Ket

The N-mode vacuum state in Bargmann representation.

>>> from mrmustard.lab import Vacuum
>>> state = Vacuum((1, 2))
>>> assert state.modes == (1, 2)

Parameters:

modes (int | tuple[int, ...]) – A tuple of modes.
name (str | None) – A name for the state. If not provided, the class name will be used.

Details and Conventions

The \(N\)-mode vacuum state is defined by

\[V = \frac{\hbar}{2}I_N \text{and } r = \bar{0}_N.\]

Its (A,b,c) triple is given by

\[A = O_{N\text{x}N}\text{, }b = O_N\text{, and }c = 1.\]

get_modes(modes)[source]¶

Reduced density matrix obtained by tracing out all the modes except those in modes. Note that the result is returned with modes in increasing order.

Parameters:: modes (int | Collection[int]) – The modes to keep.
Returns:: A State object with the remaining modes.
Raises:: ValueError – If the modes to keep are not a subset of the modes of the state.
Return type:: Vacuum

code/lab/states

Download Python script

Download Notebook

View on GitHub

States¶

Inheritance Diagram¶

BargmannEigenstate¶

Details and Conventions

Coherent¶

Details and Conventions

DM¶

Details and Conventions

DisplacedSqueezed¶

GaussianDM¶

Details and Conventions

GaussianKet¶

Details and Conventions

Ket¶

Details and Conventions

Number¶

Details and Conventions

QuadratureEigenstate¶

Details and Conventions

Sauron¶

SqueezedVacuum¶

State¶

Thermal¶

TwoModeSqueezedVacuum¶

Vacuum¶

Details and Conventions

Contents