qsttoolkit.data Subpackage

This subpackage contains functions and classes for generating QuTiP representations of specific optical quantum states. These states can be produced individually, in batches of specified size with randomized state parameters, or in specific preset datasets, intended to be standard datasets for modelling. States can be produced as pure states, or with some mixing applied to the density matrix. Measurement data is generated for a variety of quantum optics measurement regimes using positive operator valued measures (POVMs) and multinomial sampling to simulate finite measurement shots. Different sources of noise can be applied to the measurement data at customizable levels.

Individual States

qsttoolkit.data.states.bell_dm(state: str = '00') → Qobj

Generates a density matrix for a given Bell state.

Parameters:

state (str) – Type of Bell state to generate. Must be one of ‘00’, ‘01’, ‘10’, or ‘11’.

Returns:

Density matrix for the Bell state.

Return type:

Qobj

qsttoolkit.data.states.binomial_dm(dim: int, S: int, N: int, mu: int, Nc=None) → Qobj

Generates a density matrix for a binomial superposition of Fock states.

Parameters:

• dim (int) – Hilbert space dimensionality.

• S (int) – Coherent state parameter.

• N (int) – Number of excitations.

• mu (int) – Logical encoding parameter.

Returns:

Density matrix for a binomial state in the Nc-dimensional Hilbert space.

Return type:

Qobj

qsttoolkit.data.states.binomial_state(dim: int, S: int, N: int, mu: int, Nc=None) → Qobj

Generates a binomial superposition of Fock states.

Parameters:

• dim (int) – Hilbert space dimensionality.

• S (int) – Coherent state parameter.

• N (int) – Number of excitations.

• mu (int) – Logical encoding parameter.

Returns:

Binomial state in the Nc-dimensional Hilbert space.

Return type:

Qobj

qsttoolkit.data.states.cat_dm(N: int, alpha: float, positive: bool = True, dim=None) → Qobj

Generates a density matrix for a cat state (superposition of coherent states).

Parameters:

• N (int) – Hilbert space dimensionality.

• alpha (float) – Coherent state parameter.

• positive (bool) – If True, generates a positive cat state (superposition of coherent states with the same phase). If False, generates a negative cat state (superposition of coherent states with opposite phases).

Returns:

Density matrix for a cat state.

Return type:

Qobj

qsttoolkit.data.states.cat_state(N: int, alpha: float, positive: bool = True, dim=None) → Qobj

Generates a cat state (superposition of coherent states).

Parameters:

• N (int) – Hilbert space dimensionality.

• alpha (float) – Coherent state parameter.

• positive (bool) – If True, generates a positive cat state (superposition of coherent states with the same phase). If False, generates a negative cat state (superposition of coherent states with opposite phases).

Returns:

Cat state.

Return type:

Qobj

qsttoolkit.data.states.ghz_dm(N: int) → Qobj

Generates a density matrix for an N-qubit Greenberger-Horne-Zeilinger (GHZ) state.

Parameters:

N (int) – Number of qubits.

Returns:

Density matrix for the GHZ state.

Return type:

Qobj

qsttoolkit.data.states.gkp_dm(N: int, n1_range: list[int, int], n2_range: list[int, int], delta: float, mu: int, dim=None) → Qobj

Generates a density matrix for a Gottesman-Kitaev-Preskill (GKP) state.

Parameters:

• N (int) – Hilbert space dimensionality.

• n1_range (list) – Grid parameter 1.

• n2_range (int) – Grid parameter 2.

• delta (float) – Real normalisation parameter.

• mu (int) – Logical encoding parameter.

Returns:

Density matrix for a GKP state.

Return type:

Qobj

qsttoolkit.data.states.gkp_state(N: int, n1_range: list[int, int], n2_range: list[int, int], delta: float, mu: int, dim=None) → Qobj

Generates a Gottesman-Kitaev-Preskill (GKP) state.

Parameters:

• N (int) – Hilbert space dimensionality.

• n1_range (list) – Grid parameter 1.

• n2_range (int) – Grid parameter 2.

• delta (float) – Real normalisation parameter.

• mu (int) – Logical encoding parameter.

Returns:

GKP state.

Return type:

Qobj

qsttoolkit.data.states.hadamard_dm(N: int) → Qobj

Generates a density matrix for the N-qubit Hadamard state |Φ_H⟩ = (|0⟩ + |1⟩)/√2 ⊗ … ⊗ (|0⟩ + |1⟩)/√2, equivalent to applying a Hadamard gate to every qubit in |0⟩^⊗N.

Parameters:

N (int) – Number of qubits.

Returns:

Density matrix for the Hadamard state.

Return type:

Qobj

qsttoolkit.data.states.hadamard_state(N: int) → Qobj

Generates an N-qubit Hadamard state |Φ_H⟩ = (|0⟩ + |1⟩)/√2 ⊗ … ⊗ (|0⟩ + |1⟩)/√2, equivalent to applying a Hadamard gate to every qubit in |0⟩^⊗N.

Parameters:

N (int) – Number of qubits.

Returns:

Hadamard state.

Return type:

Qobj

qsttoolkit.data.states.num_dm(state: str, N=None, state_index=None, dim=None) → Qobj

Generates a density matrix for a ‘num state’ (specific superposition of Fock states numerically optimized for quantum error correction).

Parameters:

• state (str) – Type of ‘num state’ to generate. Must be one of ‘17’, ‘M’, ‘P’, ‘P2’, or ‘M2’.

• N (int) – Hilbert space dimensionality. If None, the dimension of the state vector will be used.

• state_index (int) – Index of the state to generate. If None, a random state will be generated.

Returns:

Density matrix for a ‘num state’.

Return type:

Qobj

qsttoolkit.data.states.num_state(state: str, N: int = None, state_index: int = None, dim=None) → Qobj

Generates a ‘num state’ (specific superposition of Fock states numerically optimized for quantum error correction).

Parameters:

• state (str) – Type of num state to generate. Must be one of ‘17’, ‘M’, ‘P’, ‘P2’, or ‘M2’.

• N (int) – Hilbert space dimensionality. If None, the dimension of the state vector will be used.

• state_index (int) – Index of the state to generate. If None, a random state will be generated.

Returns:

‘Num state’.

Return type:

Qobj

State Batches

class qsttoolkit.data.state_batches.BinomialStates(n_states: int, dim: int, S_range: list[int, int], mu_range: list[int, int], N=None)

Bases: States

A class to produce batches of binomial states with randomized parameters within a given range.

n_states

Number of binomial states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

S_range

Range of the S parameter.

Type:

list[int, int]

mu_range

Range of the logical encoding parameter mu.

Type:

list[int, int]

init_states()

Generates the binomial states with the given parameters.

class qsttoolkit.data.state_batches.CatStates(n_states: int, dim: int, alpha_magnitude_range: list[float, float], type: str = 'positive', N=None)

Bases: States

A class to produce batches of cat states with randomized parameters within a given range.

n_states

Number of cat states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

alpha_magnitude_range

Range of magnitudes for the coherent state parameter alpha.

Type:

list[float, float]

type

Type of cat state to generate. Must be one of ‘positive’, ‘negative’, or ‘mix’.

Type:

str

init_states()

Generates the cat states with the given parameters.

class qsttoolkit.data.state_batches.CoherentStates(n_states: int, dim: int, alpha_magnitude_range: list[float, float], N=None)

Bases: States

A class to produce batches of coherent states with randomized parameters within a given range.

n_states

Number of coherent states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

alpha_magnitude_range

Range of magnitudes for the phase space position parameter alpha.

Type:

list[float, float]

init_states()

Generates the coherent states with the given parameters.

class qsttoolkit.data.state_batches.FockStates(n_states: int, dim: int, n_range: list[int, int], N=None)

Bases: States

A class to produce batches of Fock states with randomized parameters within a given range.

n_states

Number of Fock states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

n_range

Range of photon numbers n.

Type:

list[int, int]

init_states()

Generates the Fock states with the given parameters.

class qsttoolkit.data.state_batches.GKPStates(n_states: int, dim: int, n1_range: list[int, int], n2_range: list[int, int], delta_range: list[float, float], mu_range: list[int, int], N=None)

Bases: States

A class to produce batches of Gottesman-Kitaev-Preskill (GKP) states with randomized parameters within a given range.

n_states

Number of GKP states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

n1_range

Range of grid parameter 1.

Type:

list[int, int]

n2_range

Range of grid parameter 2.

Type:

list[int, int]

delta_range

Range of the real normalisation parameter delta.

Type:

list[float, float]

mu_range

Range of the logical encoding parameter mu.

Type:

list[int, int]

init_states()

Generates the GKP states with the given parameters.

class qsttoolkit.data.state_batches.NumStates(n_states: int, dim: int, types: list[str], N=None)

Bases: States

A class to produce batches of specific bosonic code states numerically optimized for quantum error correction.

n_states

Number of num states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

types

Types of num states to generate. Must be one of ‘17’, ‘M’, ‘P’, ‘P2’, or ‘M2’.

Type:

list[str]

init_states()

Generates the num states with the given parameters.

class qsttoolkit.data.state_batches.RandomStates(n_states: int, dim: int, N=None)

Bases: States

A class to produce random states using QuTiP’s rand_dm function.

n_states

Number of random states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

density_matrices()

Overrides the parent method .density_matrices() as random states are initialized as density matrices.

init_states()

Generates the random states with the given parameters

class qsttoolkit.data.state_batches.States(n_states: int, dim: int)

Bases: object

Skeleton class for a set of quantum states, with methods for computing various representations and measurement functions.

n_states

Number of states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

density_matrices() → list[Qobj]

Returns the density matrices.

Returns:

Density matrices of the states.

Return type:

list[Qobj]

gen_Q(xgrid: ndarray, pgrid: ndarray) → list[ndarray]

Generates the Husimi Q function images for the states.

Parameters:

• xgrid (np.ndarray) – Grid for the real part of the coherent state parameter.

• pgrid (np.ndarray) – Grid for the imaginary part of the coherent state parameter.

Returns:

Husimi Q function images for the states.

Return type:

list[np.ndarray]

normalise()

Deprecated alias for the normalize method.

normalize()

Normalizes the states within the self.states attribute.

class qsttoolkit.data.state_batches.ThermalStates(n_states: int, dim: int, nbar_range: list[float, float], N=None)

Bases: States

A class to produce batches of thermal states with randomized parameters within a given range.

n_states

Number of thermal states to generate.

Type:

int

dim

Hilbert space dimensionality.

Type:

int

nbar_range

Range of mean photon numbers nbar.

Type:

list[float, float]

density_matrices()

Overrides the parent method .density_matrices() as thermal states are initialized as density matrices.

init_states()

Generates the thermal states with the given parameters.

Measurement

qsttoolkit.data.measurement.Husimi_Q_measurement_operators(dim: int, xgrid: ndarray, pgrid: ndarray) → ndarray

Deprecated alias for heterodyne_measurement_operators.

qsttoolkit.data.measurement.displacement_parity_measurement_operators(N: int, xgrid: ndarray = None, pgrid: ndarray = None, alpha_grid: ndarray = None, numpy: bool = True) → ndarray

Computes the measurement operators for displacement parity measurement.

Parameters:

• N (int) – Hilbert space dimensionality.

• xgrid (np.ndarray) – Phase space X quadrature grid.

• pgrid (np.ndarray) – Phase space P quadrature grid.

• alpha_grid (np.ndarray) – Complex amplitude grid. If provided, xgrid and pgrid are ignored.

• numpy (bool) – If True, returns the result as a NumPy array. Defaults to True.

Returns:

Measurement operators.

Return type:

np.ndarray

qsttoolkit.data.measurement.heterodyne_measurement_operators(N: int, xgrid: ndarray = None, pgrid: ndarray = None, alpha_grid: ndarray = None, numpy: bool = True) → ndarray

Computes the measurement operators for heterodyne detection of an optical quantum state across a grid of phase space displacements.

Parameters:

• N (int) – Hilbert space dimensionality.

• xgrid (np.ndarray) – Phase space X quadrature grid.

• pgrid (np.ndarray) – Phase space P quadrature grid.

• alpha_grid (np.ndarray) – Complex amplitude grid. If provided, xgrid and pgrid are ignored.

• numpy (bool) – If True, returns the result as a NumPy array. Defaults to True.

Returns:

Measurement operators.

Return type:

np.ndarray

qsttoolkit.data.measurement.homodyne_measurement_operators(N: int, alpha_grid: ndarray, numpy: bool = True) → ndarray

Computes the measurement operators for homodyne detection of an optical quantum state across a grid of phase space displacements defined by qgrid.

Parameters:

• N (int) – Hilbert space dimensionality.

• alpha_grid (np.ndarray) – Complex amplitude grid.

• numpy (bool) – If True, returns the result as a NumPy array. Defaults to True.

Returns:

Measurement operators.

Return type:

np.ndarray

qsttoolkit.data.measurement.measure_shots(probabilities: ndarray, num_shots: int) → ndarray

Simulates a finite number of measurements of a quantum state from a normalized probability distribution.

Parameters:

• probabilities (np.ndarray) – Probabilities of the measurement outcomes.

• num_shots (int) – Number of shots to simulate.

Returns:

Noisy probabilities after applying shot noise.

Return type:

np.ndarray

qsttoolkit.data.measurement.measurement_operators(N: int, measurement_type: str, numpy: bool = True, dim=None, **kwargs) → ndarray

Computes the measurement operators for the specified measurement type.

Parameters:

• N (int) – Hilbert space dimensionality.

• measurement_type (str) – Type of measurement to be performed. Must be one of ‘heterodyne’, ‘homodyne’, ‘displacement_parity’, or ‘photon_number’.

• numpy (bool) – If True, returns the result as a NumPy array. Defaults to True.

• **kwargs (dict) – Additional keyword arguments required for specific measurement types.

Returns:

Measurement operators.

Return type:

np.ndarray

qsttoolkit.data.measurement.photon_number_measurement_operators(N: int, numpy: bool = True, dim=None) → ndarray

Computes the measurement operators for photon occupation number measurement.

Parameters:

• N (int) – Hilbert space dimensionality.

• numpy (bool) – If True, returns the result as a NumPy array. Defaults to True.

Returns:

Measurement operators.

Return type:

np.ndarray

Noise

qsttoolkit.data.noise.additive_gaussian_noise(image: ndarray, mean: float, std: float) → ndarray

Adds Gaussian noise to the image by sampling from a Gaussian distribution with the given mean and standard deviation. This type of noise arises from finite measurements and discrete binning of continuous data.

Parameters:

• image (np.ndarray) – Image to which noise will be added.

• mean (float) – Mean of the Gaussian distribution.

• std (float) – Standard deviation of the Gaussian distribution.

Returns:

Image with Gaussian noise added.

Return type:

np.ndarray

qsttoolkit.data.noise.affine_transformation(image: ndarray, theta: float, x: float, y: float) → ndarray

Applies a random affine transformation to an image using TensorFlow’s apply_affine_transform function.

Parameters:

• image (np.ndarray) – Image to be transformed.

• theta (float) – Maximum rotation angle in degrees.

• x (float) – Maximum translation in the x direction.

• y (float) – Maximum translation in the y direction.

Returns:

Transformed image.

Return type:

np.ndarray

qsttoolkit.data.noise.amplification_noise(Q_function: ndarray, ntherm: float = None, variance=None) → ndarray

Simulates additional bosonic modes from photon detection using linear amplifiers. This is done by convolving the Q-function measurement image with a Gaussian kernel.

Parameters:

• Q_function (np.ndarray) – Q-function image to be convolved.

• ntherm (float) – Variance of the Gaussian kernel.

Returns:

Q-function image after convolution.

Return type:

np.ndarray

qsttoolkit.data.noise.apply_measurement_noise(image: ndarray, affine_theta: float, affine_x: float, affine_y: float, additive_Gaussian_stddev: float, pepper_p: float, salt_p: float = 0.0, amplification_ntherm: float = 0.0, salt_and_pepper_prob=None) → ndarray

Applies all types of measurement noise to the image, using the given parameters.

Parameters:

• image (np.ndarray) – Image to which noise will be added.

• affine_theta (float) – Maximum rotation angle in degrees.

• affine_x (float) – Maximum translation in the x direction.

• affine_y (float) – Maximum translation in the y direction.

• amplification_ntherm (float) – Variance of the Gaussian kernel used for amplification noise.

• additive_Gaussian_stddev (float) – Standard deviation of the Gaussian distribution from which additive noise is sampled.

• salt_p (float) – Proportion of pixels to set to 1. Defaults to 0.

• pepper_p (float) – Proportion of pixels to set to 0.

Returns:

Image with all types of noise added.

Return type:

np.ndarray

qsttoolkit.data.noise.dark_count_noise(measurement_operators: list, dark_count_p: float, n_thermal=0.1) → list

Simulates dark counts by adding a thermal state to a list of measurement operators.

Parameters:

• measurement_operators (list of Qobj of Qobj) – List of measurement operators to which noise will be added.

• dark_count_p (float) – Probability of dark counts.

• n_thermal (float) – Average number of thermal photons. Defaults to 0.1.

Returns:

List of measurement operators that simulate dark counts.

Return type:

list

qsttoolkit.data.noise.displacement_error_noise(alpha_grid: ndarray, amp_std: float) → ndarray

Simulates displacement error noise by adding a Gaussian noise to the amplitude of the complex amplitude alpha.

Parameters:

• alpha_grid (np.ndarray) – Phase space grid of complex amplitudes.

• amp_std (float) – Standard deviation of the Gaussian noise in amplitude.

Returns:

Phase space grid with displacement error noise added.

Return type:

np.ndarray

qsttoolkit.data.noise.gaussian_convolution(Q_function: ndarray, variance: float) → ndarray

Deprecated alias for amplification_noise.

qsttoolkit.data.noise.mixed_state_noise(rho: Qobj, noise_level: float = 0.1, density_matrix=None) → ndarray

Adds noise to a density matrix by mixing it with a random density matrix.

Parameters:

• rho (Qobj) – Density matrix to which noise will be added.

• noise_level (float) – Proportion of noise to add to the density matrix. Must be between 0 and 1. Defaults to 0.1.

Returns:

Density matrix with noise added.

Return type:

np.ndarray

qsttoolkit.data.noise.mode_mismatch_noise(alpha_grid: ndarray, mu: float) → ndarray

Simulates mode mismatch noise by scaling the amplitude of the complex amplitude alpha.

Parameters:

• alpha_grid (np.ndarray) – Phase space grid of complex amplitudes.

• mu (float) – Scaling factor for the amplitude.

Returns:

Phase space grid with mode mismatch noise applied.

Return type:

np.ndarray

qsttoolkit.data.noise.phase_error_noise(alpha_grid: ndarray, sigma_rad: float) → ndarray

Simulates phase error noise by adding a Gaussian noise to the phase of the complex amplitude alpha.

Parameters:

• alpha_grid (np.ndarray) – Phase space grid of complex amplitudes.

• sigma_rad (float) – Standard deviation of the Gaussian noise in radians.

Returns:

Phase space grid with phase error noise added.

Return type:

np.ndarray

qsttoolkit.data.noise.photon_loss_noise(rho: Qobj, resonator_frequency: float, loss_rate: float, tau: float, nsteps: int = None, nstep_increase_factor: float = 2.0, verbose: bool = False) → ndarray

Simulates photon loss in the resonator by evolving the density matrix using the Lindbladian master equation.

Parameters:

• rho (Qobj) – Density matrix to which noise will be added.

• resonator_frequency (float) – Frequency of the resonator.

• loss_rate (float) – Rate of photon loss.

• tau (float) – Time duration of the evolution.

• nsteps (int, optional) – Number of steps for the evolution. If None, it will be estimated based on the resonator frequency and loss rate.

• nstep_increase_factor (float, optional) – Factor by which to increase the number of steps if the evolution fails. Defaults to 2.0.

• verbose (bool, optional) – If True, prints additional information during the evolution. Defaults to False.

Returns:

Density matrix after photon loss noise has been applied.

Return type:

np.ndarray

qsttoolkit.data.noise.salt_and_pepper_noise(image: ndarray, pepper_p: float, salt_p: float = 0.0, prob=None) → ndarray

Adds salt-and-pepper noise to the image - set a proportion of pixels to 0.

Parameters:

• image (np.ndarray) – Image to which noise will be added.

• pepper_p (float) – Proportion of pixels to set to 0.

• salt_p (float) – Proportion of pixels to set to 1. Defaults to 0.0.

Returns:

Image with salt-and-pepper noise added.

Return type:

np.ndarray

Datasets

qsttoolkit.data.datasets.optical_state_dataset(dim: int, data_dim: int = None, state_numbers: list = [1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000], mixed_state_noise_level: float = 0.1, affine_theta: float = 20.0, affine_x: float = 0.1, affine_y: float = 0.1, additive_Gaussian_stddev: float = 0.01, amplification_ntherm: float = 1.0, pepper_p: float = 0.01, salt_p: float = 0.0, latent_dim=None, mixed_state_noise_noise_level=None, Gaussian_conv_ntherm=None) → DataFrame

Generates a standardized dataset of optical quantum states with added noise for training machine learning quantum state discrimination and tomography models.

Parameters:

• dim (int) – Dimensionality of the Hilbert space.

• data_dim (int) – Number of points in the X and P grids for the Q-function.

• state_numbers (list[int]) – List of 8 integers specifying the number of states to generate for each state type in the dataset. order is [Fock, Coherent, Thermal, Num, Binomial, Cat, GKP, Random]. Defalts to [1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000].

• mixed_state_noise_level (float) – Random state coefficient for the mixed state noise. Defaults to 0.1.

• affine_theta (float) – Maximum rotation angle in degrees. Defaults to 20.0.

• affine_x (float) – Maximum translation in the x direction. Defaults to 0.1.

• affine_y (float) – Maximum translation in the y direction. Defaults to 0.1.

• additive_Gaussian_stddev (float) – Standard deviation of the Gaussian distribution from which additive noise is sampled. Defaults to 0.01.

• amplification_ntherm (float) – Mean photon number, equal to the variance of the Gaussian convolution kernel. Defaults to 1.0.

• salt_p (float) – Proportion of pixels to set to 1. Defaults to 0.0.

• pepper_p (float) – Proportion of pixels to set to 0. Defaults to 0.01.

Returns:

DataFrame containing the labels, density matrices, Husimi Q functions, and state parameters of the states.

Return type:

pd.DataFrame