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=12, max_photons=8)[source]

Returns a single sample from the Hafnian of a Gaussian state. Code contributed by Jake F.F. Bulmer based on arXiv:2108.01622.

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.

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, fanout=10, cutoff=1)[source]

Returns a single sample from the Hafnian of a Gaussian state. Code contributed by Jake F.F. Bulmer based on arXiv:2108.01622.

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

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

  • 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, fanout=10, cutoff=1, 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, fanout=10, cutoff=1, 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]