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 direct photon occupation number measurement, or a Husimi Q function as a result of a displace-and-measure technique [1]. Different sources of noise can be applied to the image data for the latter at customizable levels.

Individual States

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(dim: int, alpha: float, N=None) → Qobj

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

Parameters:

• dim (int) – Hilbert space dimensionality.

• alpha (float) – Coherent state parameter.

Returns:

Density matrix for a cat state.

Return type:

Qobj

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

Generates a cat state (superposition of coherent states).

Parameters:

• dim (int) – Hilbert space dimensionality.

• alpha (float) – Coherent state parameter.

Returns:

Cat state.

Return type:

Qobj

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

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

Parameters:

• dim (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(dim: int, n1_range: list[int, int], n2_range: list[int, int], delta: float, mu: int, N=None) → Qobj

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

Parameters:

• dim (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.num_dm(state: str, dim=None, state_index=None, N=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’.

• dim (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, dim: int = None, state_index: int = None, N=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’.

• dim (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], 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]

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.

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.2, Gaussian_conv_ntherm: float = 2.0, affine_theta: float = 20.0, affine_x: float = 0.1, affine_y: float = 0.1, additive_Gaussian_stddev: float = 0.001, pepper_p: float = 0.01, salt_p: float = 0.0, latent_dim=None, mixed_state_noise_noise_level=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.2.

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

• 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.001.

• 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

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.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, 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.

• 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.gaussian_convolution(Q_function: ndarray, variance: float) → ndarray

Convolves a Q-function image with a Gaussian kernel.

Parameters:

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

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

Returns:

Q-function image after convolution.

Return type:

np.ndarray

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

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

Parameters:

• density_matrix (np.ndarray) – 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.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