Quantum States

Positive WaveFunction

class qucumber.nn_states.PositiveWaveFunction(num_visible, num_hidden=None, gpu=True, module=None)[source]

Bases: qucumber.nn_states.WaveFunctionBase

Class capable of learning wavefunctions with no phase.

Parameters
  • num_visible (int) – The number of visible units, ie. the size of the system being learned.

  • num_hidden (int) – The number of hidden units in the internal RBM. Defaults to the number of visible units.

  • gpu (bool) – Whether to perform computations on the default GPU.

  • module (qucumber.rbm.BinaryRBM) – An instance of a BinaryRBM module to use for density estimation. Will be copied to the default GPU if gpu=True (if it isn’t already there). If None, will initialize a BinaryRBM from scratch.

amplitude(v)[source]

Compute the (unnormalized) amplitude of a given vector/matrix of visible states.

\text{amplitude}(\bm{\sigma})=|\psi_{\bm{\lambda}}(\bm{\sigma})|=
e^{-\mathcal{E}_{\bm{\lambda}}(\bm{\sigma})/2}

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Matrix/vector containing the amplitudes of v

Return type

torch.Tensor

static autoload(location, gpu=True)[source]

Initializes a NeuralState from the parameters in the given location.

Parameters
  • location (str or file) – The location to load the model parameters from.

  • gpu (bool) – Whether the returned model should be on the GPU.

Returns

A new NeuralState initialized from the given parameters. The returned NeuralState will be of whichever type this function was called on. An error may be thrown if the loaded parameters correspond to a different type of NeuralState than the caller.

compute_batch_gradients(k, samples_batch, neg_batch, *args, **kwargs)[source]

Compute the gradients of a batch of the training data (samples_batch).

Parameters
  • k (int) – Number of contrastive divergence steps in training.

  • samples_batch (torch.Tensor) – Batch of the input samples.

  • neg_batch (torch.Tensor) – Batch of the input samples for computing the negative phase.

  • *args – Ignored.

  • **kwargs – Ignored.

Returns

A single-element list containing the gradients calculated with a Gibbs sampled negative phase update

Return type

list[torch.Tensor]

compute_exact_gradients(samples_batch, space, bases_batch=None)[source]

Computes the gradients of the parameters, using exact sampling for the negative phase update instead of Gibbs sampling

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • space (torch.Tensor) – A rank 2 tensor of the entire visible space.

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with an exact negative phase update

Return type

list[torch.Tensor]

compute_exact_grads(samples_batch, space, *args, **kwargs)[source]

Computes the gradients of the parameters, using exact sampling for the negative phase update instead of Gibbs sampling

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • space (torch.Tensor) – A rank 2 tensor of the entire visible space.

  • *args – Ignored.

  • **kwargs – Ignored.

Returns

A single-element list containing the gradients calculated with an exact negative phase update

Return type

list[torch.Tensor]

compute_normalization(space)[source]

Alias for normalization

property device

The device that the model is on.

fit(data, epochs=100, pos_batch_size=100, neg_batch_size=None, k=1, lr=0.001, progbar=False, starting_epoch=1, time=False, callbacks=None, optimizer=torch.optim.SGD, optimizer_args=None, scheduler=None, scheduler_args=None, **kwargs)[source]

Train the NeuralState.

Parameters
  • data (numpy.ndarray) – The training samples

  • epochs (int) – The number of full training passes through the dataset. Technically, this specifies the index of the last training epoch, which is relevant if starting_epoch is being set.

  • pos_batch_size (int) – The size of batches for the positive phase taken from the data.

  • neg_batch_size (int) – The size of batches for the negative phase taken from the data. Defaults to pos_batch_size.

  • k (int) – The number of contrastive divergence steps.

  • lr (float) – Learning rate

  • input_bases (numpy.ndarray) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction or DensityMatrix.

  • progbar (bool or str) – Whether or not to display a progress bar. If “notebook” is passed, will use a Jupyter notebook compatible progress bar.

  • starting_epoch (int) – The epoch to start from. Useful if continuing training from a previous state.

  • callbacks (list[qucumber.callbacks.CallbackBase]) – Callbacks to run while training.

  • optimizer (torch.optim.Optimizer) – The constructor of a torch optimizer.

  • scheduler – The constructor of a torch scheduler

  • optimizer_args (dict) – Arguments to pass to the optimizer

  • scheduler_args (dict) – Arguments to pass to the scheduler

  • **kwargs – Ignored; exists for backwards compatibility.

generate_hilbert_space(size=None, device=None)[source]

Generates Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space. Defaults to the number of visible units.

  • device – The device to create the Hilbert space matrix on. Defaults to the device this model is on.

Returns

A tensor with all the basis states of the Hilbert space.

Return type

torch.Tensor

gradient(v, *args, **kwargs)[source]

Compute the gradient of the effective energy for a batch of states.

\nabla_{\bm{\lambda}}\mathcal{E}_{\bm{\lambda}}(\bm{\sigma})

Parameters
  • v (torch.Tensor) – visible states \bm{\sigma}

  • *args – Ignored.

  • **kwargs – Ignored.

Returns

A two-element list containing the gradients of the effective energy. The second element will always be zero.

Return type

list[torch.Tensor]

importance_sampling_denominator(v)[source]

Compute the denominator of the weight of an arbitrary sample, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters

v (torch.Tensor) – A batch containing the samples \bm{\sigma}

Returns

A complex tensor containing the denominator of the weights with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_numerator(vp, v)[source]

Compute the numerator of the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma'}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters
Returns

A complex tensor containing the numerator of the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_weight(vp, v)[source]

Compute the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this ratio is:

\frac{\rho(\bm{\sigma'}, \bm{\sigma})}{\rho(\bm{\sigma}, \bm{\sigma})}

While in the pure case:

\frac{\psi(\bm{\sigma'})}{\psi(\bm{\sigma})}

Parameters
Returns

A complex tensor containing the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

load(location)[source]

Loads the NeuralState parameters from the given location ignoring any metadata stored in the file. Overwrites the NeuralState’s parameters.

Note

The NeuralState object on which this function is called must have the same parameter shapes as the one who’s parameters are being loaded.

Parameters

location (str or file) – The location to load the NeuralState parameters from.

property max_size

Maximum size of the Hilbert space for full enumeration

property networks

A list of the names of the internal RBMs.

normalization(space)[source]

Compute the normalization constant of the state. In the case of a pure state, this is the norm of the unnormalized wavefunction. In the case of a mixed state, this is the trace of the unnormalized density matrix.

Z_{\bm{\lambda}}=
\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})

Parameters

space (torch.Tensor) – A rank 2 tensor of the entire visible space.

phase(v)[source]

Compute the phase of a given vector/matrix of visible states.

In the case of a PositiveWaveFunction, the phase is just zero.

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Matrix/vector containing the phases of v

Return type

torch.Tensor

positive_phase_gradients(samples_batch, *args, **kwargs)[source]

Computes the positive phase of the gradients of the parameters.

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • *args – Ignored.

  • **kwargs – Ignored.

Returns

A two-element list containing the gradients of the effective energy. The second element will always be zero.

Return type

list[torch.Tensor]

probability(v, Z=1.0)[source]

Evaluates the probability of the given vector(s) of visible states. Assumes the visible states were measured in the computational basis.

Parameters
  • v (torch.Tensor) – The visible states.

  • Z (float) – The partition function / normalization constant. Defaults to 1, producing unnormalized probabilities.

Returns

The probability of the given vector(s) of visible units.

Return type

torch.Tensor

psi(v)[source]

Compute the (unnormalized) wavefunction of a given vector/matrix of visible states.

\psi_{\bm{\lambda}}(\bm{\sigma})
    = e^{-\mathcal{E}_{\bm{\lambda}}(\bm{\sigma})/2}

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Complex object containing the value of the wavefunction for each visible state

Return type

torch.Tensor

property rbm_am

The RBM to be used to learn the wavefunction amplitude.

reinitialize_parameters()[source]

Randomize the parameters of the internal RBMs.

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

Performs k steps of Block Gibbs sampling. One step consists of sampling the hidden state \bm{h} from the conditional distribution p_{\bm{\lambda}}(\bm{h}\:|\:\bm{v}), and sampling the visible state \bm{v} from the conditional distribution p_{\bm{\lambda}}(\bm{v}\:|\:\bm{h}).

Parameters
  • k (int) – Number of Block Gibbs steps.

  • num_samples (int) – The number of samples to generate.

  • initial_state (torch.Tensor) – The initial state of the Markov Chains. If given, num_samples will be ignored.

  • overwrite (bool) – Whether to overwrite the initial_state tensor, if it is provided.

save(location, metadata=None)[source]

Saves the NeuralState parameters to the given location along with any given metadata.

Parameters
  • location (str or file) – The location to save the data.

  • metadata (dict) – Any extra metadata to store alongside the NeuralState parameters.

property stop_training

If True, will not train.

If this property is set to True during the training cycle, training will terminate once the current batch or epoch ends (depending on when stop_training was set).

subspace_vector(num, size=None, device=None)[source]

Generates a single vector from the Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space.

  • num (int) – The specific vector to return from the Hilbert space. Since the Hilbert space can be represented by the set of binary strings of length size, num is equivalent to the decimal representation of the returned vector.

  • device – The device to create the vector on. Defaults to the device this model is on.

Returns

A state from the Hilbert space.

Return type

torch.Tensor

Complex WaveFunction

class qucumber.nn_states.ComplexWaveFunction(num_visible, num_hidden=None, unitary_dict=None, gpu=False, module=None)[source]

Bases: qucumber.nn_states.WaveFunctionBase

Class capable of learning wavefunctions with a non-zero phase.

Parameters
  • num_visible (int) – The number of visible units, ie. the size of the system being learned.

  • num_hidden (int) – The number of hidden units in both internal RBMs. Defaults to the number of visible units.

  • unitary_dict (dict[str, torch.Tensor]) – A dictionary mapping unitary names to their matrix representations.

  • gpu (bool) – Whether to perform computations on the default GPU.

  • module (qucumber.rbm.BinaryRBM) – An instance of a BinaryRBM module to use for density estimation; The given RBM object will be used to estimate the amplitude of the wavefunction, while a copy will be used to estimate the phase of the wavefunction. Will be copied to the default GPU if gpu=True (if it isn’t already there). If None, will initialize the BinaryRBMs from scratch.

am_grads(v)[source]

Computes the gradients of the amplitude RBM for given input states

Parameters

v (torch.Tensor) – The input state, \sigma

Returns

The gradients of all amplitude RBM parameters

Return type

torch.Tensor

amplitude(v)[source]

Compute the (unnormalized) amplitude of a given vector/matrix of visible states.

\text{amplitude}(\bm{\sigma})=|\psi_{\bm{\lambda\mu}}(\bm{\sigma})|=
e^{-\mathcal{E}_{\bm{\lambda}}(\bm{\sigma})/2}

Parameters

v (torch.Tensor) – visible states \bm{\sigma}.

Returns

Vector containing the amplitudes of the given states.

Return type

torch.Tensor

static autoload(location, gpu=False)[source]

Initializes a NeuralState from the parameters in the given location.

Parameters
  • location (str or file) – The location to load the model parameters from.

  • gpu (bool) – Whether the returned model should be on the GPU.

Returns

A new NeuralState initialized from the given parameters. The returned NeuralState will be of whichever type this function was called on. An error may be thrown if the loaded parameters correspond to a different type of NeuralState than the caller.

compute_batch_gradients(k, samples_batch, neg_batch, bases_batch=None)[source]

Compute the gradients of a batch of the training data (samples_batch).

If measurements are taken in bases other than the reference basis, a list of bases (bases_batch) must also be provided.

Parameters
  • k (int) – Number of contrastive divergence steps in training.

  • samples_batch (torch.Tensor) – Batch of the input samples.

  • neg_batch (torch.Tensor) – Batch of the input samples for computing the negative phase.

  • bases_batch (numpy.ndarray) – Batch of the input bases corresponding to the samples in samples_batch.

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with a Gibbs sampled negative phase update

Return type

list[torch.Tensor]

compute_exact_gradients(samples_batch, space, bases_batch=None)[source]

Computes the gradients of the parameters, using exact sampling for the negative phase update instead of Gibbs sampling

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • space (torch.Tensor) – A rank 2 tensor of the entire visible space.

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with an exact negative phase update

Return type

list[torch.Tensor]

compute_normalization(space)[source]

Alias for normalization

property device

The device that the model is on.

fit(data, epochs=100, pos_batch_size=100, neg_batch_size=None, k=1, lr=0.001, input_bases=None, progbar=False, starting_epoch=1, time=False, callbacks=None, optimizer=torch.optim.SGD, optimizer_args=None, scheduler=None, scheduler_args=None, **kwargs)[source]

Train the NeuralState.

Parameters
  • data (numpy.ndarray) – The training samples

  • epochs (int) – The number of full training passes through the dataset. Technically, this specifies the index of the last training epoch, which is relevant if starting_epoch is being set.

  • pos_batch_size (int) – The size of batches for the positive phase taken from the data.

  • neg_batch_size (int) – The size of batches for the negative phase taken from the data. Defaults to pos_batch_size.

  • k (int) – The number of contrastive divergence steps.

  • lr (float) – Learning rate

  • input_bases (numpy.ndarray) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction or DensityMatrix.

  • progbar (bool or str) – Whether or not to display a progress bar. If “notebook” is passed, will use a Jupyter notebook compatible progress bar.

  • starting_epoch (int) – The epoch to start from. Useful if continuing training from a previous state.

  • callbacks (list[qucumber.callbacks.CallbackBase]) – Callbacks to run while training.

  • optimizer (torch.optim.Optimizer) – The constructor of a torch optimizer.

  • scheduler – The constructor of a torch scheduler

  • optimizer_args (dict) – Arguments to pass to the optimizer

  • scheduler_args (dict) – Arguments to pass to the scheduler

  • **kwargs – Ignored; exists for backwards compatibility.

generate_hilbert_space(size=None, device=None)[source]

Generates Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space. Defaults to the number of visible units.

  • device – The device to create the Hilbert space matrix on. Defaults to the device this model is on.

Returns

A tensor with all the basis states of the Hilbert space.

Return type

torch.Tensor

gradient(samples, bases=None)[source]

Compute the gradient of a batch of sample, measured in given bases.

Parameters
Returns

A list of 2 tensors containing the accumulated gradients of each of the internal RBMs.

Return type

list[torch.Tensor]

importance_sampling_denominator(v)[source]

Compute the denominator of the weight of an arbitrary sample, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters

v (torch.Tensor) – A batch containing the samples \bm{\sigma}

Returns

A complex tensor containing the denominator of the weights with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_numerator(vp, v)[source]

Compute the numerator of the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma'}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters
Returns

A complex tensor containing the numerator of the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_weight(vp, v)[source]

Compute the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this ratio is:

\frac{\rho(\bm{\sigma'}, \bm{\sigma})}{\rho(\bm{\sigma}, \bm{\sigma})}

While in the pure case:

\frac{\psi(\bm{\sigma'})}{\psi(\bm{\sigma})}

Parameters
Returns

A complex tensor containing the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

load(location)[source]

Loads the NeuralState parameters from the given location ignoring any metadata stored in the file. Overwrites the NeuralState’s parameters.

Note

The NeuralState object on which this function is called must have the same parameter shapes as the one who’s parameters are being loaded.

Parameters

location (str or file) – The location to load the NeuralState parameters from.

property max_size

Maximum size of the Hilbert space for full enumeration

property networks

A list of the names of the internal RBMs.

normalization(space)[source]

Compute the normalization constant of the state. In the case of a pure state, this is the norm of the unnormalized wavefunction. In the case of a mixed state, this is the trace of the unnormalized density matrix.

Z_{\bm{\lambda}}=
\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})

Parameters

space (torch.Tensor) – A rank 2 tensor of the entire visible space.

ph_grads(v)[source]

Computes the gradients of the phase RBM for given input states

Parameters

v (torch.Tensor) – The input state, \sigma

Returns

The gradients of all phase RBM parameters

Return type

torch.Tensor

phase(v)[source]

Compute the phase of a given vector/matrix of visible states.

\text{phase}(\bm{\sigma})=-\mathcal{E}_{\bm{\mu}}(\bm{\sigma})/2

Parameters

v (torch.Tensor) – visible states \bm{\sigma}.

Returns

Vector containing the phases of the given states.

Return type

torch.Tensor

positive_phase_gradients(samples_batch, bases_batch=None)[source]

Computes the positive phase of the gradients of the parameters.

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients

Return type

list[torch.Tensor]

probability(v, Z=1.0)[source]

Evaluates the probability of the given vector(s) of visible states. Assumes the visible states were measured in the computational basis.

Parameters
  • v (torch.Tensor) – The visible states.

  • Z (float) – The partition function / normalization constant. Defaults to 1, producing unnormalized probabilities.

Returns

The probability of the given vector(s) of visible units.

Return type

torch.Tensor

psi(v)[source]

Compute the (unnormalized) wavefunction of a given vector/matrix of visible states.

\psi_{\bm{\lambda\mu}}(\bm{\sigma})
    = e^{-[\mathcal{E}_{\bm{\lambda}}(\bm{\sigma})
            + i\mathcal{E}_{\bm{\mu}}(\bm{\sigma})]/2}

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Complex object containing the value of the wavefunction for each visible state

Return type

torch.Tensor

property rbm_am

The RBM to be used to learn the wavefunction amplitude.

property rbm_ph

RBM used to learn the wavefunction phase.

reinitialize_parameters()[source]

Randomize the parameters of the internal RBMs.

rotated_gradient(basis, sample)[source]

Computes the gradients rotated into the measurement basis

Parameters
  • basis (numpy.ndarray) – The bases in which the measurement is made

  • sample (torch.Tensor) – The measurement (either 0 or 1)

Returns

A list of two tensors, representing the rotated gradients of the amplitude and phase RBMS

Return type

list[torch.Tensor, torch.Tensor]

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

Performs k steps of Block Gibbs sampling. One step consists of sampling the hidden state \bm{h} from the conditional distribution p_{\bm{\lambda}}(\bm{h}\:|\:\bm{v}), and sampling the visible state \bm{v} from the conditional distribution p_{\bm{\lambda}}(\bm{v}\:|\:\bm{h}).

Parameters
  • k (int) – Number of Block Gibbs steps.

  • num_samples (int) – The number of samples to generate.

  • initial_state (torch.Tensor) – The initial state of the Markov Chains. If given, num_samples will be ignored.

  • overwrite (bool) – Whether to overwrite the initial_state tensor, if it is provided.

save(location, metadata=None)[source]

Saves the NeuralState parameters to the given location along with any given metadata.

Parameters
  • location (str or file) – The location to save the data.

  • metadata (dict) – Any extra metadata to store alongside the NeuralState parameters.

property stop_training

If True, will not train.

If this property is set to True during the training cycle, training will terminate once the current batch or epoch ends (depending on when stop_training was set).

subspace_vector(num, size=None, device=None)[source]

Generates a single vector from the Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space.

  • num (int) – The specific vector to return from the Hilbert space. Since the Hilbert space can be represented by the set of binary strings of length size, num is equivalent to the decimal representation of the returned vector.

  • device – The device to create the vector on. Defaults to the device this model is on.

Returns

A state from the Hilbert space.

Return type

torch.Tensor

Density Matrix

class qucumber.nn_states.DensityMatrix(num_visible, num_hidden=None, num_aux=None, unitary_dict=None, gpu=False, module=None)[source]

Bases: qucumber.nn_states.NeuralStateBase

Parameters
  • num_visible (int) – The number of visible units, i.e. the size of the system

  • num_hidden (int) – The number of units in the hidden layer

  • num_aux (int) – The number of units in the purification layer

  • unitary_dict (dict[str, torch.Tensor]) – A dictionary associating bases with their unitary rotations

  • gpu (bool) – Whether to perform computations on the default gpu.

am_grads(v)[source]

Computes the gradients of the amplitude RBM for given input states

Parameters

v (torch.Tensor) – The first input state, \sigma

Returns

The gradients of all amplitude RBM parameters

Return type

torch.Tensor

static autoload(location, gpu=False)[source]

Initializes a NeuralState from the parameters in the given location.

Parameters
  • location (str or file) – The location to load the model parameters from.

  • gpu (bool) – Whether the returned model should be on the GPU.

Returns

A new NeuralState initialized from the given parameters. The returned NeuralState will be of whichever type this function was called on. An error may be thrown if the loaded parameters correspond to a different type of NeuralState than the caller.

compute_batch_gradients(k, samples_batch, neg_batch, bases_batch=None)[source]

Compute the gradients of a batch of the training data (samples_batch).

If measurements are taken in bases other than the reference basis, a list of bases (bases_batch) must also be provided.

Parameters
  • k (int) – Number of contrastive divergence steps in training.

  • samples_batch (torch.Tensor) – Batch of the input samples.

  • neg_batch (torch.Tensor) – Batch of the input samples for computing the negative phase.

  • bases_batch (numpy.ndarray) – Batch of the input bases corresponding to the samples in samples_batch.

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with a Gibbs sampled negative phase update

Return type

list[torch.Tensor]

compute_exact_gradients(samples_batch, space, bases_batch=None)[source]

Computes the gradients of the parameters, using exact sampling for the negative phase update instead of Gibbs sampling

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • space (torch.Tensor) – A rank 2 tensor of the entire visible space.

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with an exact negative phase update

Return type

list[torch.Tensor]

compute_normalization(space)[source]

Alias for normalization

property device

The device that the model is on.

fit(data, epochs=100, pos_batch_size=100, neg_batch_size=None, k=1, lr=1, input_bases=None, progbar=False, starting_epoch=1, time=False, callbacks=None, optimizer=torch.optim.SGD, optimizer_args=None, scheduler=None, scheduler_args=None, **kwargs)[source]

Train the NeuralState.

Parameters
  • data (numpy.ndarray) – The training samples

  • epochs (int) – The number of full training passes through the dataset. Technically, this specifies the index of the last training epoch, which is relevant if starting_epoch is being set.

  • pos_batch_size (int) – The size of batches for the positive phase taken from the data.

  • neg_batch_size (int) – The size of batches for the negative phase taken from the data. Defaults to pos_batch_size.

  • k (int) – The number of contrastive divergence steps.

  • lr (float) – Learning rate

  • input_bases (numpy.ndarray) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction or DensityMatrix.

  • progbar (bool or str) – Whether or not to display a progress bar. If “notebook” is passed, will use a Jupyter notebook compatible progress bar.

  • starting_epoch (int) – The epoch to start from. Useful if continuing training from a previous state.

  • callbacks (list[qucumber.callbacks.CallbackBase]) – Callbacks to run while training.

  • optimizer (torch.optim.Optimizer) – The constructor of a torch optimizer.

  • scheduler – The constructor of a torch scheduler

  • optimizer_args (dict) – Arguments to pass to the optimizer

  • scheduler_args (dict) – Arguments to pass to the scheduler

  • **kwargs – Ignored; exists for backwards compatibility.

generate_hilbert_space(size=None, device=None)[source]

Generates Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space. Defaults to the number of visible units.

  • device – The device to create the Hilbert space matrix on. Defaults to the device this model is on.

Returns

A tensor with all the basis states of the Hilbert space.

Return type

torch.Tensor

gradient(samples, bases=None)[source]

Compute the gradient of a batch of sample, measured in given bases.

Parameters
Returns

A list of 2 tensors containing the accumulated gradients of each of the internal RBMs.

Return type

list[torch.Tensor]

importance_sampling_denominator(v)[source]

Compute the denominator of the weight of an arbitrary sample, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters

v (torch.Tensor) – A batch containing the samples \bm{\sigma}

Returns

A complex tensor containing the denominator of the weights with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_numerator(vp, v)[source]

Compute the numerator of the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma'}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters
Returns

A complex tensor containing the numerator of the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_weight(vp, v)[source]

Compute the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this ratio is:

\frac{\rho(\bm{\sigma'}, \bm{\sigma})}{\rho(\bm{\sigma}, \bm{\sigma})}

While in the pure case:

\frac{\psi(\bm{\sigma'})}{\psi(\bm{\sigma})}

Parameters
Returns

A complex tensor containing the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

load(location)[source]

Loads the NeuralState parameters from the given location ignoring any metadata stored in the file. Overwrites the NeuralState’s parameters.

Note

The NeuralState object on which this function is called must have the same parameter shapes as the one who’s parameters are being loaded.

Parameters

location (str or file) – The location to load the NeuralState parameters from.

property max_size

Maximum size of the Hilbert space for full enumeration

property networks

A list of the names of the internal RBMs.

normalization(space)[source]

Compute the normalization constant of the state. In the case of a pure state, this is the norm of the unnormalized wavefunction. In the case of a mixed state, this is the trace of the unnormalized density matrix.

Z_{\bm{\lambda}}=
\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})

Parameters

space (torch.Tensor) – A rank 2 tensor of the entire visible space.

ph_grads(v)[source]

Computes the gradients of the phase RBM for given input states

Parameters

v (torch.Tensor) – The first input state, \sigma

Returns

The gradients of all phase RBM parameters

Return type

torch.Tensor

pi(v, vp, expand=True)[source]

Calculates elements of the \Pi matrix. If expand is True, will return a complex matrix A_{ij} = \langle\sigma_i|\Pi|\sigma'_j\rangle. Otherwise will return a complex vector A_{i} = \langle\sigma_i|\Pi|\sigma'_i\rangle.

Parameters
  • v (torch.Tensor) – A batch of visible states, \sigma.

  • vp (torch.Tensor) – The other batch of visible state, \sigma'.

  • expand (bool) – Whether to return a matrix (True) or a vector (False).

Returns

The matrix elements given by \langle\sigma|\Pi|\sigma'\rangle

Return type

torch.Tensor

pi_grad(v, vp, phase=False, expand=False)[source]
Calculates the gradient of the \Pi matrix with

respect to the amplitude RBM parameters for two input states

Parameters
  • v (torch.Tensor) – One of the visible states, \sigma

  • vp (torch.Tensor) – The other visible state, :math`sigma’`

  • phase (bool) – Whether to compute the gradients for the phase RBM (True) or the amplitude RBM (False)

Returns

The matrix element of the gradient given by \langle\sigma|\nabla_\lambda\Pi|\sigma'\rangle

Return type

torch.Tensor

positive_phase_gradients(samples_batch, bases_batch=None)[source]

Computes the positive phase of the gradients of the parameters.

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients

Return type

list[torch.Tensor]

probability(v, Z=1.0)[source]

Evaluates the probability of the given vector(s) of visible states. Assumes the visible states were measured in the computational basis.

Parameters
  • v (torch.Tensor) – The visible states.

  • Z (float) – The partition function / normalization constant. Defaults to 1, producing unnormalized probabilities.

Returns

The probability of the given vector(s) of visible units.

Return type

torch.Tensor

property rbm_am

The RBM to be used to learn the wavefunction amplitude.

property rbm_ph

RBM used to learn the wavefunction phase.

reinitialize_parameters()[source]

Randomize the parameters of the internal RBMs.

rho(v, vp=None, expand=True)[source]

Computes the matrix elements of the (unnormalized) density matrix. If expand is True, will return a complex matrix A_{ij} = \langle\sigma_i|\widetilde{\rho}|\sigma'_j\rangle. Otherwise will return a complex vector A_{i} = \langle\sigma_i|\widetilde{\rho}|\sigma'_i\rangle.

Parameters
  • v (torch.Tensor) – One of the visible states, \sigma.

  • vp (torch.Tensor) – The other visible state, \sigma'. If None, will be set to v.

  • expand (bool) – Whether to return a matrix (True) or a vector (False).

Returns

The elements of the current density matrix \langle\sigma|\widetilde{\rho}|\sigma'\rangle

Return type

torch.Tensor

rotated_gradient(basis, sample)[source]

Computes the gradients rotated into the measurement basis

Parameters
  • basis (numpy.ndarray) – The bases in which the measurement is made

  • sample (torch.Tensor) – The measurement (either 0 or 1)

Returns

A list of two tensors, representing the rotated gradients of the amplitude and phase RBMs

Return type

list[torch.Tensor, torch.Tensor]

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

Performs k steps of Block Gibbs sampling. One step consists of sampling the hidden state \bm{h} from the conditional distribution p_{\bm{\lambda}}(\bm{h}\:|\:\bm{v}), and sampling the visible state \bm{v} from the conditional distribution p_{\bm{\lambda}}(\bm{v}\:|\:\bm{h}).

Parameters
  • k (int) – Number of Block Gibbs steps.

  • num_samples (int) – The number of samples to generate.

  • initial_state (torch.Tensor) – The initial state of the Markov Chains. If given, num_samples will be ignored.

  • overwrite (bool) – Whether to overwrite the initial_state tensor, if it is provided.

save(location, metadata=None)[source]

Saves the NeuralState parameters to the given location along with any given metadata.

Parameters
  • location (str or file) – The location to save the data.

  • metadata (dict) – Any extra metadata to store alongside the NeuralState parameters.

property stop_training

If True, will not train.

If this property is set to True during the training cycle, training will terminate once the current batch or epoch ends (depending on when stop_training was set).

subspace_vector(num, size=None, device=None)[source]

Generates a single vector from the Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space.

  • num (int) – The specific vector to return from the Hilbert space. Since the Hilbert space can be represented by the set of binary strings of length size, num is equivalent to the decimal representation of the returned vector.

  • device – The device to create the vector on. Defaults to the device this model is on.

Returns

A state from the Hilbert space.

Return type

torch.Tensor

Abstract WaveFunction

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.nn_states.WaveFunctionBase[source]

Bases: qucumber.nn_states.NeuralStateBase

Abstract Base Class for WaveFunctions.

amplitude(v)[source]

Compute the (unnormalized) amplitude of a given vector/matrix of visible states.

\text{amplitude}(\bm{\sigma})=|\psi(\bm{\sigma})|

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Matrix/vector containing the amplitudes of v

Return type

torch.Tensor

importance_sampling_denominator(v)[source]

Compute the denominator of the weight of an arbitrary sample, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters

v (torch.Tensor) – A batch containing the samples \bm{\sigma}

Returns

A complex tensor containing the denominator of the weights with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_numerator(vp, v)[source]

Compute the numerator of the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma'}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters
Returns

A complex tensor containing the numerator of the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

abstract phase(v)[source]

Compute the phase of a given vector/matrix of visible states.

\text{phase}(\bm{\sigma})

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Matrix/vector containing the phases of v

Return type

torch.Tensor

psi(v)[source]

Compute the (unnormalized) wavefunction of a given vector/matrix of visible states.

\psi(\bm{\sigma})

Parameters

v (torch.Tensor) – visible states \bm{\sigma}

Returns

Complex object containing the value of the wavefunction for each visible state

Return type

torch.Tensor

reinitialize_parameters()[source]

Randomize the parameters of the internal RBMs.

Abstract NeuralState

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.nn_states.NeuralStateBase[source]

Bases: abc.ABC

Abstract Base Class for Neural Network Quantum States.

abstract static autoload(location, gpu=False)[source]

Initializes a NeuralState from the parameters in the given location.

Parameters
  • location (str or file) – The location to load the model parameters from.

  • gpu (bool) – Whether the returned model should be on the GPU.

Returns

A new NeuralState initialized from the given parameters. The returned NeuralState will be of whichever type this function was called on. An error may be thrown if the loaded parameters correspond to a different type of NeuralState than the caller.

compute_batch_gradients(k, samples_batch, neg_batch, bases_batch=None)[source]

Compute the gradients of a batch of the training data (samples_batch).

If measurements are taken in bases other than the reference basis, a list of bases (bases_batch) must also be provided.

Parameters
  • k (int) – Number of contrastive divergence steps in training.

  • samples_batch (torch.Tensor) – Batch of the input samples.

  • neg_batch (torch.Tensor) – Batch of the input samples for computing the negative phase.

  • bases_batch (numpy.ndarray) – Batch of the input bases corresponding to the samples in samples_batch.

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with a Gibbs sampled negative phase update

Return type

list[torch.Tensor]

compute_exact_gradients(samples_batch, space, bases_batch=None)[source]

Computes the gradients of the parameters, using exact sampling for the negative phase update instead of Gibbs sampling

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • space (torch.Tensor) – A rank 2 tensor of the entire visible space.

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients calculated with an exact negative phase update

Return type

list[torch.Tensor]

compute_normalization(space)[source]

Alias for normalization

abstract property device

The device that the model is on.

fit(data, epochs=100, pos_batch_size=100, neg_batch_size=None, k=1, lr=0.001, input_bases=None, progbar=False, starting_epoch=1, time=False, callbacks=None, optimizer=torch.optim.SGD, optimizer_args=None, scheduler=None, scheduler_args=None, **kwargs)[source]

Train the NeuralState.

Parameters
  • data (numpy.ndarray) – The training samples

  • epochs (int) – The number of full training passes through the dataset. Technically, this specifies the index of the last training epoch, which is relevant if starting_epoch is being set.

  • pos_batch_size (int) – The size of batches for the positive phase taken from the data.

  • neg_batch_size (int) – The size of batches for the negative phase taken from the data. Defaults to pos_batch_size.

  • k (int) – The number of contrastive divergence steps.

  • lr (float) – Learning rate

  • input_bases (numpy.ndarray) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction or DensityMatrix.

  • progbar (bool or str) – Whether or not to display a progress bar. If “notebook” is passed, will use a Jupyter notebook compatible progress bar.

  • starting_epoch (int) – The epoch to start from. Useful if continuing training from a previous state.

  • callbacks (list[qucumber.callbacks.CallbackBase]) – Callbacks to run while training.

  • optimizer (torch.optim.Optimizer) – The constructor of a torch optimizer.

  • scheduler – The constructor of a torch scheduler

  • optimizer_args (dict) – Arguments to pass to the optimizer

  • scheduler_args (dict) – Arguments to pass to the scheduler

  • **kwargs – Ignored; exists for backwards compatibility.

generate_hilbert_space(size=None, device=None)[source]

Generates Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space. Defaults to the number of visible units.

  • device – The device to create the Hilbert space matrix on. Defaults to the device this model is on.

Returns

A tensor with all the basis states of the Hilbert space.

Return type

torch.Tensor

gradient(samples, bases=None)[source]

Compute the gradient of a batch of sample, measured in given bases.

Parameters
Returns

A list of 2 tensors containing the accumulated gradients of each of the internal RBMs.

Return type

list[torch.Tensor]

abstract importance_sampling_denominator(v)[source]

Compute the denominator of the weight of an arbitrary sample, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters

v (torch.Tensor) – A batch containing the samples \bm{\sigma}

Returns

A complex tensor containing the denominator of the weights with respect to \bm{\sigma}

Return type

torch.Tensor

abstract importance_sampling_numerator(vp, v)[source]

Compute the numerator of the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this quantity is \rho(\bm{\sigma'}, \bm{\sigma}), while in the pure case it is \psi(\bm{\sigma'})

Parameters
Returns

A complex tensor containing the numerator of the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

importance_sampling_weight(vp, v)[source]

Compute the weight of sample vp, with respect to the sample v.

In the case of a mixed state, this ratio is:

\frac{\rho(\bm{\sigma'}, \bm{\sigma})}{\rho(\bm{\sigma}, \bm{\sigma})}

While in the pure case:

\frac{\psi(\bm{\sigma'})}{\psi(\bm{\sigma})}

Parameters
Returns

A complex tensor containing the weights of \bm{\sigma'} with respect to \bm{\sigma}

Return type

torch.Tensor

load(location)[source]

Loads the NeuralState parameters from the given location ignoring any metadata stored in the file. Overwrites the NeuralState’s parameters.

Note

The NeuralState object on which this function is called must have the same parameter shapes as the one who’s parameters are being loaded.

Parameters

location (str or file) – The location to load the NeuralState parameters from.

property max_size

Maximum size of the Hilbert space for full enumeration

abstract property networks

A list of the names of the internal RBMs.

normalization(space)[source]

Compute the normalization constant of the state. In the case of a pure state, this is the norm of the unnormalized wavefunction. In the case of a mixed state, this is the trace of the unnormalized density matrix.

Z_{\bm{\lambda}}=
\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})

Parameters

space (torch.Tensor) – A rank 2 tensor of the entire visible space.

positive_phase_gradients(samples_batch, bases_batch=None)[source]

Computes the positive phase of the gradients of the parameters.

Parameters
  • samples_batch (torch.Tensor) – The measurements

  • bases_batch (numpy.ndarray) – The bases in which the measurements are made

Returns

A two-element list containing the amplitude and phase RBM gradients

Return type

list[torch.Tensor]

probability(v, Z=1.0)[source]

Evaluates the probability of the given vector(s) of visible states. Assumes the visible states were measured in the computational basis.

Parameters
  • v (torch.Tensor) – The visible states.

  • Z (float) – The partition function / normalization constant. Defaults to 1, producing unnormalized probabilities.

Returns

The probability of the given vector(s) of visible units.

Return type

torch.Tensor

abstract property rbm_am

The RBM to be used to learn the wavefunction amplitude.

reinitialize_parameters()[source]

Randomize the parameters of the internal RBMs.

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

Performs k steps of Block Gibbs sampling. One step consists of sampling the hidden state \bm{h} from the conditional distribution p_{\bm{\lambda}}(\bm{h}\:|\:\bm{v}), and sampling the visible state \bm{v} from the conditional distribution p_{\bm{\lambda}}(\bm{v}\:|\:\bm{h}).

Parameters
  • k (int) – Number of Block Gibbs steps.

  • num_samples (int) – The number of samples to generate.

  • initial_state (torch.Tensor) – The initial state of the Markov Chains. If given, num_samples will be ignored.

  • overwrite (bool) – Whether to overwrite the initial_state tensor, if it is provided.

save(location, metadata=None)[source]

Saves the NeuralState parameters to the given location along with any given metadata.

Parameters
  • location (str or file) – The location to save the data.

  • metadata (dict) – Any extra metadata to store alongside the NeuralState parameters.

property stop_training

If True, will not train.

If this property is set to True during the training cycle, training will terminate once the current batch or epoch ends (depending on when stop_training was set).

subspace_vector(num, size=None, device=None)[source]

Generates a single vector from the Hilbert space of dimension 2^{\text{size}}.

Parameters
  • size (int) – The size of each element of the Hilbert space.

  • num (int) – The specific vector to return from the Hilbert space. Since the Hilbert space can be represented by the set of binary strings of length size, num is equivalent to the decimal representation of the returned vector.

  • device – The device to create the vector on. Defaults to the device this model is on.

Returns

A state from the Hilbert space.

Return type

torch.Tensor