Observables¶

Pauli Operators¶

class qucumber.observables.SigmaZ(absolute=False)[source]¶

Bases: qucumber.observables.ObservableBase

The $\sigma_z$ observable.

Computes the average magnetization in the Z direction of a spin chain.

Parameters: absolute (bool) – Specifies whether to estimate the absolute magnetization.

apply(nn_state, samples)[source]¶

Computes the average magnetization along Z of each sample given a batch of samples.

Assumes that the computational basis that the NeuralState was trained on was the Z basis.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of samples to calculate the observable on. Must be using the $\sigma_i = 0, 1$ convention.

property name¶: The name of the Observable.

sample(nn_state, k, num_samples=1, initial_state=None, overwrite=False)[source]¶

Draws samples of the observable using the given NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
k (int) – The number of Gibbs Steps to perform before drawing a sample.
num_samples (int) – The number of samples to draw.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_samples will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

The samples drawn through this observable.

Return type

torch.Tensor

statistics(nn_state, num_samples, num_chains=0, burn_in=1000, steps=1, initial_state=None, overwrite=False)[source]¶

Estimates the expected value, variance, and the standard error of the observable over the distribution defined by the NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
num_samples (int) – The number of samples to draw. The actual number of samples drawn may be slightly higher if num_samples % num_chains != 0.
num_chains (int) – The number of Markov chains to run in parallel; if 0 or greater than num_samples, will use a number of chains equal to num_samples. This is not recommended in the case where a num_samples is large, as this may use up all the available memory. Ignored if initial_state is provided.
burn_in (int) – The number of Gibbs Steps to perform before recording any samples.
steps (int) – The number of Gibbs Steps to take between each sample.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_chains will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

statistics_from_samples(nn_state, samples)[source]¶

Estimates the expected value, variance, and the standard error of the observable using the given samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

property symbol¶: The algebraic symbol representing the Observable.

class qucumber.observables.SigmaX(absolute=False)[source]¶

Bases: qucumber.observables.ObservableBase

The $\sigma_x$ observable

Computes the average magnetization in the X direction of a spin chain.

Parameters: absolute (bool) – Specifies whether to estimate the absolute magnetization.

apply(nn_state, samples)[source]¶

Computes the average magnetization along X of each sample in the given batch of samples.

Assumes that the computational basis that the NeuralState was trained on was the Z basis.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of samples to calculate the observable on. Must be using the $\sigma_i = 0, 1$ convention.

property name¶: The name of the Observable.

sample(nn_state, k, num_samples=1, initial_state=None, overwrite=False)[source]¶

Draws samples of the observable using the given NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
k (int) – The number of Gibbs Steps to perform before drawing a sample.
num_samples (int) – The number of samples to draw.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_samples will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

The samples drawn through this observable.

Return type

torch.Tensor

statistics(nn_state, num_samples, num_chains=0, burn_in=1000, steps=1, initial_state=None, overwrite=False)[source]¶

Estimates the expected value, variance, and the standard error of the observable over the distribution defined by the NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
num_samples (int) – The number of samples to draw. The actual number of samples drawn may be slightly higher if num_samples % num_chains != 0.
num_chains (int) – The number of Markov chains to run in parallel; if 0 or greater than num_samples, will use a number of chains equal to num_samples. This is not recommended in the case where a num_samples is large, as this may use up all the available memory. Ignored if initial_state is provided.
burn_in (int) – The number of Gibbs Steps to perform before recording any samples.
steps (int) – The number of Gibbs Steps to take between each sample.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_chains will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

statistics_from_samples(nn_state, samples)[source]¶

Estimates the expected value, variance, and the standard error of the observable using the given samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

property symbol¶: The algebraic symbol representing the Observable.

class qucumber.observables.SigmaY(absolute=False)[source]¶

Bases: qucumber.observables.ObservableBase

The $\sigma_y$ observable

Computes the average magnetization in the Y direction of a spin chain.

Parameters: absolute (bool) – Specifies whether to estimate the absolute magnetization.

apply(nn_state, samples)[source]¶

Computes the average magnetization along Y of each sample in the given batch of samples.

Assumes that the computational basis that the NeuralState was trained on was the Z basis.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of samples to calculate the observable on. Must be using the $\sigma_i = 0, 1$ convention.

property name¶: The name of the Observable.

sample(nn_state, k, num_samples=1, initial_state=None, overwrite=False)[source]¶

Draws samples of the observable using the given NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
k (int) – The number of Gibbs Steps to perform before drawing a sample.
num_samples (int) – The number of samples to draw.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_samples will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

The samples drawn through this observable.

Return type

torch.Tensor

statistics(nn_state, num_samples, num_chains=0, burn_in=1000, steps=1, initial_state=None, overwrite=False)[source]¶

Estimates the expected value, variance, and the standard error of the observable over the distribution defined by the NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
num_samples (int) – The number of samples to draw. The actual number of samples drawn may be slightly higher if num_samples % num_chains != 0.
num_chains (int) – The number of Markov chains to run in parallel; if 0 or greater than num_samples, will use a number of chains equal to num_samples. This is not recommended in the case where a num_samples is large, as this may use up all the available memory. Ignored if initial_state is provided.
burn_in (int) – The number of Gibbs Steps to perform before recording any samples.
steps (int) – The number of Gibbs Steps to take between each sample.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_chains will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

statistics_from_samples(nn_state, samples)[source]¶

Estimates the expected value, variance, and the standard error of the observable using the given samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

property symbol¶: The algebraic symbol representing the Observable.

Neighbour Interactions¶

class qucumber.observables.NeighbourInteraction(periodic_bcs=False, c=1)[source]¶

Bases: qucumber.observables.ObservableBase

The $\sigma^z_i \sigma^z_{i+c}$ observable

Computes the $c^\text{th}$ nearest neighbour interaction for a spin chain with either open or periodic boundary conditions.

Parameters

periodic_bcs (bool) – Specifies whether the system has periodic boundary conditions.
c (int) – Interaction distance.

apply(nn_state, samples)[source]¶

Computes the energy of this neighbour interaction for each sample given a batch of samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of samples to calculate the observable on. Must be using the $\sigma_i = 0, 1$ convention.

property name¶: The name of the Observable.

sample(nn_state, k, num_samples=1, initial_state=None, overwrite=False)[source]¶

Draws samples of the observable using the given NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
k (int) – The number of Gibbs Steps to perform before drawing a sample.
num_samples (int) – The number of samples to draw.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_samples will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

The samples drawn through this observable.

Return type

torch.Tensor

statistics(nn_state, num_samples, num_chains=0, burn_in=1000, steps=1, initial_state=None, overwrite=False)[source]¶

Estimates the expected value, variance, and the standard error of the observable over the distribution defined by the NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
num_samples (int) – The number of samples to draw. The actual number of samples drawn may be slightly higher if num_samples % num_chains != 0.
num_chains (int) – The number of Markov chains to run in parallel; if 0 or greater than num_samples, will use a number of chains equal to num_samples. This is not recommended in the case where a num_samples is large, as this may use up all the available memory. Ignored if initial_state is provided.
burn_in (int) – The number of Gibbs Steps to perform before recording any samples.
steps (int) – The number of Gibbs Steps to take between each sample.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_chains will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

statistics_from_samples(nn_state, samples)[source]¶

Estimates the expected value, variance, and the standard error of the observable using the given samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

property symbol¶: The algebraic symbol representing the Observable.

Abstract Observable¶

Note

This is an Abstract Base Class, it is not meant to be used directly. The following API reference is mostly for developers.

class qucumber.observables.ObservableBase[source]¶

Bases: abc.ABC

Base class for observables.

abstract apply(nn_state, samples)[source]¶

Computes the value of the local-estimator of the observable $O$ , for a batch of samples $\lbrace \sigma \rbrace$ :

$\mathcal{O}(\sigma) &= \sum_{\sigma'} \frac{\rho(\sigma', \sigma)}{\rho(\sigma, \sigma)} O(\sigma, \sigma') = \sum_{\sigma'} \frac{\psi(\sigma')}{\psi(\sigma)} O(\sigma, \sigma')$

This function must not perform any averaging for statistical purposes, as the proper analysis is delegated to the specialized statistics and statistics_from_samples methods.

Must be implemented by any subclasses. Refer to the tutorial on Observables to see an example.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

The value of the observable of each given basis state.

Return type

torch.Tensor

property name¶: The name of the Observable.

sample(nn_state, k, num_samples=1, initial_state=None, overwrite=False)[source]¶

Draws samples of the observable using the given NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
k (int) – The number of Gibbs Steps to perform before drawing a sample.
num_samples (int) – The number of samples to draw.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_samples will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

The samples drawn through this observable.

Return type

torch.Tensor

statistics(nn_state, num_samples, num_chains=0, burn_in=1000, steps=1, initial_state=None, overwrite=False)[source]¶

Estimates the expected value, variance, and the standard error of the observable over the distribution defined by the NeuralState.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState to draw samples from.
num_samples (int) – The number of samples to draw. The actual number of samples drawn may be slightly higher if num_samples % num_chains != 0.
num_chains (int) – The number of Markov chains to run in parallel; if 0 or greater than num_samples, will use a number of chains equal to num_samples. This is not recommended in the case where a num_samples is large, as this may use up all the available memory. Ignored if initial_state is provided.
burn_in (int) – The number of Gibbs Steps to perform before recording any samples.
steps (int) – The number of Gibbs Steps to take between each sample.
initial_state (torch.Tensor) – The initial state of the Markov Chain. If given, num_chains will be ignored.
overwrite (bool) – Whether to overwrite the initial_state tensor, if provided, with the updated state of the Markov chain.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

statistics_from_samples(nn_state, samples)[source]¶

Estimates the expected value, variance, and the standard error of the observable using the given samples.

Parameters

nn_state (qucumber.nn_states.NeuralStateBase) – The NeuralState that drew the samples.
samples (torch.Tensor) – A batch of sample states to calculate the observable on.

Returns

A dictionary containing the (estimated) expected value (key: “mean”), variance (key: “variance”), and standard error (key: “std_error”) of the observable. Also outputs the total number of drawn samples (key: “num_samples”).

Return type

dict(str, float)

property symbol¶: The algebraic symbol representing the Observable.