# API Reference¶

## qupa module¶

class qupa.PopulationAnnealer(left_size, right_size, num_samples, name=None, dtype=None)

Bases: object

biases_var

Tensorflow variable containing current biases.

left_size

Number of left-side variables in the RBM.

log_z_var

Tensorflow variable containing current log Z estimate.

num_samples

Number of samples.

right_size

Number of right-side variables in the RBM.

sample_size

Total number of variables in the RBM.

samples()

Returns current samples.

samples_var

Tensorflow variable containing samples.

training_log_z(biases, weights, num_steps=1, max_extra_steps=None, min_search_iters=None, num_mcmc_sweeps=None, name=None)

This function ostensibly estimates log Z but the value it returns is full of accumulated errors. Its real power is that it provides gradients with respect to the RBM parameters (i.e. it is intended for use in training).

After running this operation, the current bias and weight variables of this PopulationAnnealer instance are assigned the values of the biases and weights arguments. The point is that repeated runs with slightly-changing parameters will maintain a population of samples that accurately reflects the Boltzmann distribution.

If you need a decent log Z estimate, use qupa.evaluation_log_z(). If you need gradients, use this function.

See qupa.mcmc() for the precise partition function definition.

Parameters: biases – A tensor of the same type and shape as self.biases_var containing new RBM biases. weights – A tensor of the same type and shape as self.weights_var containing new RBM weights. num_steps – See qupa.anneal_population(). max_extra_steps – See qupa.anneal_population(). min_search_iters – See qupa.anneal_population(). num_mcmc_sweeps – See qupa.anneal_population(). name – Name for the Tensorflow name_scope created.
weights_var

Tensorflow variable containing current weights.

qupa.anneal_population(samples, logz, start_biases, start_weights, end_biases, end_weights, num_steps=1, max_extra_steps=1000, min_search_iters=7, num_mcmc_sweeps=1)

Anneals samples to a new distribution.

This function takes samples from a starting RBM and updates them to reflect a new RBM using the population annealing algorithm.

See qupa.mcmc() for a precise definition of the probability distribution.

Parameters: samples – A Tensorflow variable of shape [N, L+R] containing current samples that will be updated to reflect new distribution. Current samples should reflect the RBM determined by start_biases and start_weights. logz – A scalar Tensorflow variable that will be updated by adding estimated log Z change (so existing estimation error is preserved). start_biases – A tensor of shape [L+R] containing starting RBM biases (left side then right side). start_weights – A tensor of shape [L, R] containing starting RBM weights. end_biases – A tensor of shape [L+R] containing target RBM biases (left side then right side). end_weights – A tensor of shape [L, R] containing target RBM weights. num_steps – As in qupa.evaluation_log_z() but useful values here are typically smaller assuming starting and ending parameters are similar. max_extra_steps – See qupa.evaluation_log_z(). min_search_iters – See qupa.evaluation_log_z(). num_mcmc_sweeps – See qupa.evaluation_log_z().

All of samples, logz, start_biases, start_weights, end_biases, and end_weights must have the same data type, which must be either tf.float32 or tf.float64.

All of num_steps, max_extra_steps, min_search_iters, and num_mcmc_sweeps must be convertible to integral scalar tensors.

Returns: A list of tensors [new_samples, new_logz], the new samples and logz values, respectively.
qupa.evaluation_log_z(biases, weights, init_biases=None, num_samples=128, num_steps=10, max_extra_steps=1000, min_search_iters=7, num_mcmc_sweeps=1)

Estimates log Z of a restricted Boltzmann machine.

This function approximates the log partition function using the population annealing algorithm. The algorithm moves slowly from an easy initial RBM to the target RBM, updating log Z along the way. The initial RBM has only biases, no pairwise weights. Let L and R denote the number of left-side and right-side variables, respectively.

See qupa.mcmc() for the precise partition function definition.

Parameters: biases – A tensor of shape [L+R] containing RBM biases (left side then right side). weights – A tensor of shape [L, R] containing RBM weights. init_biases – A tensor of shape [L+R] containing the initial RBM biases. Defaults to all zeros. num_samples – The number of samples to use. Must be positive. num_steps – The number of equally-spaced steps in the interpolated path from the initial to target RBMs. Must be positive. max_extra_steps – Maximum number of extra steps allowed between regular steps in the interpolated path. Extra points are added when necessary to keep sample weight variance under control. Must be non-negative. You probably don’t want to change this value; setting it too low will cause errors. min_search_iters – Number of binary search iterations used to choose extra steps. Must be non-negative. You probably don’t want to change this value. num_mcmc_sweeps – Number of MCMC sweeps at each step.

All of biases, weights, and init_biases must have the same data type, which must be either tf.float32 or tf.float64.

All of num_samples, num_steps, max_extra_steps, min_search_iters, and num_mcmc_sweeps must be convertible to integral scalar tensors.

Returns: A scalar tensor of the same type as biases containing the estimated log Z value.
qupa.mcmc(samples, biases, weights, num_sweeps)

Runs Gibbs sampling on a bipartite Boltzmann machine.

This function updates an existing population of N samples from a restricted Boltzmann machine with L left-side variables and R right-side variable.

The RBM energy function is

E(x) = -b^T x - x_l^T W x_r

where W = weights, b = biases, and x = [x_l x_r] is a single sample. The energy function is used to define the probability distribution:

P(x) = exp(-E(x)) / Z

where Z is the partition function, sum_x exp(-E(x)).

Parameters: samples – A TensorFlow variable of shape [N, L+R] that will be updated. Current values are used as a starting point are therefore should all be 0 or 1 (though it runs without complaint if not). biases – A tensor of shape [L+R] containing linear biases (left side then right side). weights – A tensor of shape [L, R] containing quadratic weights. num_sweeps – Number of Gibbs sweeps to run. Must be convertible to an integral scalar tensor.

All of samples, biases, and weights must have the same data type, which must be either tf.float32 or tf.float64.

TODO: add use_locking parameter to protect samples during update.

Returns: A tensor containing the updated samples.

## qupa.ais module¶

qupa.ais.evaluation_log_z(biases, weights, init_biases=None, betas=None, num_samples=128, num_mcmc_sweeps=1, name=None)

Estimates log Z of a restricted Boltzmann machine using AIS.

This function approximates the log partition function of an RBM using annealed importance sampling (AIS). AIS is a standard method for estimating log Z; this function is provided as a convenience for comparison with qupa.evaluation_logz.

See qupa.mcmc() for the precise partition function definition.

Parameters: biases – A tensor of shape [L+R] containing RBM biases (left side then right side). weights – A tensor of shape [L, R] containing RBM weights. init_biases – A tensor of shape [L+R] containing the initial RBM biases. Defaults to all zeros. betas – A rank-one tensor containing interpolation coefficients from the initial RBM to the final RBM. Values should strictly increase from 0 to 1. Defaults to 100 evenly- spaced values. num_samples – The number of samples to use. Must be positive. num_mcmc_sweeps – Number of MCMC sweeps at each step. name – TensorFlow variable_scope name.

All of biases, weights, init_biases, and betas must have the same data type, which must be either tf.float32 or tf.float64.

num_samples and num_mcmc_sweeps must be convertible to integral scalar tensors.

Returns: A scalar tensor of the same type as biases containing the estimated log Z value.

## qupa.pcd module¶

class qupa.pcd.PCD(left_size, right_size, num_samples, name=None, dtype=None)

Bases: object

log_z_var

Tensorflow variable containing current log Z estimate.

This variable is always returned by PCD.training_log_z() (with gradients attached). Note that nothing in this class ever updates this variable and you are free to update it with log Z estimates obtained elsewhere. It is provided for compatibility with qupa.PopulationAnnealer.

samples()

Returns current samples.

samples_var

Tensorflow variable containing samples.

training_log_z(biases, weights, num_mcmc_sweeps=1, name=None)