# Sampling algorithms¶

Module name: thewalrus.samples

This submodule provides access to algorithms to sample from the hafnian or the torontonian of Gaussian quantum states.

## Hafnian sampling¶

 generate_hafnian_sample(cov[, mean, hbar, …]) Returns a single sample from the Hafnian of a Gaussian state. hafnian_sample_state(cov, samples[, mean, …]) Returns samples from the Hafnian of a Gaussian state. hafnian_sample_graph(A, n_mean[, samples, …]) Returns samples from the Gaussian state specified by the adjacency matrix $$A$$ and with total mean photon number $$n_{mean}$$ hafnian_sample_classical_state(cov, samples) Returns samples from a Gaussian state that has a positive $$P$$ function. hafnian_sample_graph_rank_one(G, n_mean[, …]) Returns samples from a rank one adjacency matrix bm{A} = bm{G} bm{G}^T where $$\bm{G}$$ is a row vector.

## Torontonian sampling¶

 generate_torontonian_sample(cov[, mu, hbar, …]) Returns a single sample from the Hafnian of a Gaussian state. torontonian_sample_state(cov, samples[, mu, …]) Returns samples from the Torontonian of a Gaussian state torontonian_sample_graph(A, n_mean[, …]) Returns samples from the Torontonian of a Gaussian state specified by the adjacency matrix $$A$$ and with total mean photon number $$n_{mean}$$ torontonian_sample_classical_state(cov, samples) Returns threshold samples from a Gaussian state that has a positive P function. threshold_detection_prob(mu, cov, det_pattern) Threshold detection probabilities for Gaussian states.

## Brute force sampling¶

 photon_number_sampler(probabilities, num_samples) Given a photon-number probability mass function(PMF) it returns samples according to said PMF.

## Code details¶

generate_hafnian_sample(cov, mean=None, hbar=2, cutoff=6, max_photons=30, approx=False, approx_samples=100000.0)[source]

Returns a single sample from the Hafnian of a Gaussian state.

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• mean (array) – a $$2N$$ np.float64 vector of means representing the Gaussian state.

• hbar (float) – (default 2) the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• cutoff (int) – the Fock basis truncation.

• max_photons (int) – specifies the maximum number of photons that can be counted.

• approx (bool) – if True, the approximate hafnian algorithm is used. Note that this can only be used for real, non-negative matrices.

• approx_samples – the number of samples used to approximate the hafnian if approx=True.

Returns

a photon number sample from the Gaussian states.

Return type

np.array[int]

generate_torontonian_sample(cov, mu=None, hbar=2, max_photons=30)[source]

Returns a single sample from the Hafnian of a Gaussian state.

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• mu (array) – a $$2N$$ np.float64 displacement vector representing an $$N$$ mode quantum state. This can be obtained via the smeanxp method of the Gaussian backend of Strawberry Fields.

• hbar (float) – (default 2) the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• max_photons (int) – specifies the maximum number of clicks that can be counted.

Returns

a threshold sample from the Gaussian state.

Return type

np.array[int]

hafnian_sample_classical_state(cov, samples, mean=None, hbar=2, atol=1e-08, cutoff=None)[source]

Returns samples from a Gaussian state that has a positive $$P$$ function.

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• samples (int) – number of samples to generate

• mean (array) – vector of means of the gaussian state

• hbar (float) – the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• sigdigits (integer) – precision to check that the covariance matrix is a true covariance matrix of a gaussian state.

Returns

photon number samples from the Gaussian state with covariance cov and vector means mean.

Return type

np.array[int]

hafnian_sample_graph(A, n_mean, samples=1, cutoff=5, max_photons=30, approx=False, approx_samples=100000.0, parallel=False)[source]

Returns samples from the Gaussian state specified by the adjacency matrix $$A$$ and with total mean photon number $$n_{mean}$$

Parameters
• A (array) – a $$N\times N$$ np.float64 (symmetric) adjacency matrix matrix

• n_mean (float) – mean photon number of the Gaussian state

• samples (int) – the number of samples to return.

• cutoff (int) – the Fock basis truncation.

• max_photons (int) – specifies the maximum number of photons that can be counted.

• approx (bool) – if True, the approximate hafnian algorithm is used. Note that this can only be used for real, non-negative matrices.

• approx_samples – the number of samples used to approximate the hafnian if approx=True.

• parallel (bool) – if True, uses dask for parallelization of samples

Returns

photon number samples from the Gaussian state

Return type

np.array[int]

hafnian_sample_graph_rank_one(G, n_mean, samples=1)[source]

Returns samples from a rank one adjacency matrix bm{A} = bm{G} bm{G}^T where $$\bm{G}$$ is a row vector.

Parameters
• G (array) – factorization of the rank-one matrix A = G @ G.T.

• nmean (float) – Total mean photon number.

• samples (int) – the number of samples to return.

Returns

(array): samples.

hafnian_sample_state(cov, samples, mean=None, hbar=2, cutoff=5, max_photons=30, approx=False, approx_samples=100000.0, parallel=False)[source]

Returns samples from the Hafnian of a Gaussian state.

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• samples (int) – the number of samples to return.

• mean (array) – a $$2N$$ np.float64 vector of means representing the Gaussian state.

• hbar (float) – (default 2) the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• cutoff (int) – the Fock basis truncation.

• max_photons (int) – specifies the maximum number of photons that can be counted.

• approx (bool) – if True, the hafnian_approx() function is used to approximate the hafnian. Note that this can only be used for real, non-negative matrices.

• approx_samples – the number of samples used to approximate the hafnian if approx=True.

• parallel (bool) – if True, uses dask for parallelization of samples

Returns

photon number samples from the Gaussian state

Return type

np.array[int]

photon_number_sampler(probabilities, num_samples, out_of_bounds=False)[source]

Given a photon-number probability mass function(PMF) it returns samples according to said PMF.

Parameters
• probabilities (array) – probability tensor of the modes, has shape [cutoff]*num_modes

• num_samples (int) – number of samples requested

• out_of_bounds (boolean) – if False the probability distribution is renormalized. If not False, the value of out_of_bounds is used as a placeholder for samples where more than the cutoff of probabilities are detected.

Returns

Samples, with shape [num_sample, num_modes]

Return type

(array)

threshold_detection_prob(mu, cov, det_pattern, hbar=2, atol=1e-10, rtol=1e-10)[source]

Threshold detection probabilities for Gaussian states. Formula from Jake Bulmer, Nicolas Quesada and Stefano Paesani. When state is displaced, threshold_detection_prob_displacement is called. Otherwise, tor is called.

Parameters
• mu (1d array) – means of xp Gaussian Wigner function

• cov (2d array) – : xp Wigner covariance matrix

• det_pattern (1d array) – array of {0,1} to describe the threshold detection outcome

• hbar (float) – the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• rtol (float) – the relative tolerance parameter used in np.allclose

• atol (float) – the absolute tolerance parameter used in np.allclose

Returns

probability of detection pattern

Return type

np.float64

torontonian_sample_classical_state(cov, samples, mean=None, hbar=2, atol=1e-08)[source]

Returns threshold samples from a Gaussian state that has a positive P function.

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• samples (int) – number of samples to generate

• mean (array) – vector of means of the Gaussian state

• hbar (float) – the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• sigdigits (integer) – precision to check that the covariance matrix is a true covariance matrix of a gaussian state.

Returns

threshold samples from the Gaussian state with covariance cov and vector means mean.

Return type

np.array[int]

torontonian_sample_graph(A, n_mean, samples=1, max_photons=30, parallel=False)[source]

Returns samples from the Torontonian of a Gaussian state specified by the adjacency matrix $$A$$ and with total mean photon number $$n_{mean}$$

Parameters
• A (array) – a $$N\times N$$ np.float64 (symmetric) adjacency matrix matrix

• n_mean (float) – mean photon number of the Gaussian state

• samples (int) – the number of samples to return.

• max_photons (int) – specifies the maximum number of photons that can be counted.

• parallel (bool) – if True, uses dask for parallelization of samples

Returns

photon number samples from the Torontonian of the Gaussian state

Return type

np.array[int]

torontonian_sample_state(cov, samples, mu=None, hbar=2, max_photons=30, parallel=False)[source]

Returns samples from the Torontonian of a Gaussian state

Parameters
• cov (array) – a $$2N\times 2N$$ np.float64 covariance matrix representing an $$N$$ mode quantum state. This can be obtained via the scovmavxp method of the Gaussian backend of Strawberry Fields.

• samples (int) – number of samples to generate

• mu (array) – a $$2N$$ np.float64 displacement vector representing an $$N$$ mode quantum state. This can be obtained via the smeanxp method of the Gaussian backend of Strawberry Fields.

• hbar (float) – (default 2) the value of $$\hbar$$ in the commutation relation $$[\x,\p]=i\hbar$$.

• max_photons (int) – specifies the maximum number of clicks that can be counted.

• parallel (bool) – if True, uses dask for parallelization of samples

Returns

threshold samples from the Gaussian state.

Return type

np.array[int]