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=False)[source]¶

Initializes a WaveFunction 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 WaveFunction initialized from the given parameters. The returned WaveFunction will be of whichever type this function was called on.

compute_batch_gradients(k, samples_batch, neg_batch)[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.

Returns

List containing the gradients of the parameters.

Return type

list

compute_normalization(space)[source]¶

Compute the normalization constant of the wavefunction.

$Z_{\bm{\lambda}}=\sqrt{\sum_{\bm{\sigma}}|\psi_{\bm{\lambda}}|^2}= \sqrt{\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})}$

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

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, **kwargs)[source]¶

Train the WaveFunction.

Parameters

data (np.array) – 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
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.
kwargs – Keyword arguments to pass to the optimizer

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)[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}$
Returns: A single tensor containing all of the parameter gradients.
Return type: torch.Tensor

load(location)[source]¶

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

Note

The WaveFunction 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 WaveFunction 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.

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

probability(v, Z)[source]¶

Evaluates the probability of the given vector(s) of visible states.

Parameters

v (torch.Tensor) – The visible states.
Z (float) – The partition function.

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 WaveFunction 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 WaveFunction 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=True, 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.

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 WaveFunction 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 WaveFunction initialized from the given parameters. The returned WaveFunction will be of whichever type this function was called on.

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 (np.array) – Batch of the input bases corresponding to the samples in samples_batch.

Returns

List containing the gradients of the parameters.

Return type

list

compute_normalization(space)[source]¶

Compute the normalization constant of the wavefunction.

$Z_{\bm{\lambda}}= \sqrt{\sum_{\bm{\sigma}}|\psi_{\bm{\lambda\mu}}|^2}= \sqrt{\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})}$

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

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, **kwargs)[source]¶

Train the WaveFunction.

Parameters

data (np.array) – 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 (np.array) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction.
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.
kwargs – Keyword arguments to pass to the optimizer

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(basis, sample)[source]¶

Compute the gradient of a sample, measured in different bases.

Parameters

basis (np.array) – A set of bases.
sample (np.array) – A sample to compute the gradient of.

Returns

A list of 2 tensors containing the parameters of each of the internal RBMs.

Return type

list[torch.Tensor]

load(location)[source]¶

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

Note

The WaveFunction 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 WaveFunction 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.

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

probability(v, Z)[source]¶

Evaluates the probability of the given vector(s) of visible states.

Parameters

v (torch.Tensor) – The visible states.
Z (float) – The partition function.

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.

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 WaveFunction 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 WaveFunction 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: abc.ABC

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

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

Initializes a WaveFunction 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 WaveFunction initialized from the given parameters. The returned WaveFunction will be of whichever type this function was called on.

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 (np.array) – Batch of the input bases corresponding to the samples in samples_batch.

Returns

List containing the gradients of the parameters.

Return type

list

compute_normalization(space)[source]¶

Compute the normalization constant of the wavefunction.

$Z_{\bm{\lambda}}= \sqrt{\sum_{\bm{\sigma}}|\psi_{\bm{\lambda\mu}}|^2}= \sqrt{\sum_{\bm{\sigma}} p_{\bm{\lambda}}(\bm{\sigma})}$

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

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, **kwargs)[source]¶

Train the WaveFunction.

Parameters

data (np.array) – 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 (np.array) – The measurement bases for each sample. Must be provided if training a ComplexWaveFunction.
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.
kwargs – Keyword arguments to pass to the optimizer

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

abstract gradient()[source]¶: Compute the gradient of a set of samples.

load(location)[source]¶

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

Note

The WaveFunction 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 WaveFunction 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.

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

probability(v, Z)[source]¶

Evaluates the probability of the given vector(s) of visible states.

Parameters

v (torch.Tensor) – The visible states.
Z (float) – The partition function.

Returns

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

Return type

torch.Tensor

abstract 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

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 WaveFunction 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 WaveFunction 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