Torch RBM API

rbms

rbms.classes

class rbms.classes.EBM

Bases: ABC

An abstract class representing the parameters of an Energy-Based Model.

abstractmethod clone(device: device | None = None, dtype: dtype | None = None) → Self

Create a clone of the RBM instance.

Parameters:

  • device (Optional[torch.device], optional) – The device for the cloned parameters. Defaults to the current device.

  • dtype (Optional[torch.dtype], optional) – The data type for the cloned parameters. Defaults to the current data type.

Returns:

A new RBM instance with cloned parameters.

Return type:

RBM

abstractmethod compute_energy_visibles(v: Tensor) → Tensor

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

v (Tensor) – Visible configurations

Returns:

The computed energy.

Return type:

Tensor

abstractmethod compute_gradient(data: dict[str, Tensor], chains: dict[str, Tensor], centered: bool = True) → None

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

device: device
abstractmethod independent_model() → Self

Independent model where only local fields are preserved.

abstractmethod init_chains(num_samples: int, weights: Tensor | None = None, start_v: Tensor | None = None) → dict[str, Tensor]

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • start_v (Tensor, optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

abstractmethod static init_parameters(num_hiddens: int, dataset: RBMDataset, device: device, dtype: dtype, var_init: float = 0.0001) → Self

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

abstractmethod named_parameters() → dict[str, Tensor]
abstractmethod num_visibles() → int

Number of visible units

abstractmethod parameters() → List[Tensor]

Returns a list containing the parameters of the RBM.

Returns:

A list containing the weight matrix, visible bias, and hidden bias.

Return type:

List[Tensor]

abstractmethod ref_log_z() → float

Reference log partition function with weights set to 0 (except for the visible bias).

abstractmethod sample_state(chains: dict[str, Tensor], n_steps: int, beta: float = 1.0) → dict[str, Tensor]

Sample the model for n_steps

Parameters:

  • () (chains) – The starting position of the chains.

  • n_steps (int) – The number of sampling steps.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0

Returns:

The updated chains after n_steps of sampling.

Return type:

dict[str, Tensor]

abstractmethod sample_visibles(chains: dict[str, Tensor], beta: float = 1.0) → dict[str, Tensor]

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

abstractmethod static set_named_parameters(named_params: dict[str, Tensor]) → Self
abstractmethod to(device: device | None = None, dtype: dtype | None = None) → Self

Move the parameters to the specified device and/or convert them to the specified data type.

Parameters:

  • device (Optional[torch.device], optional) – The device to move the parameters to. Defaults to None.

  • dtype (Optional[torch.dtype], optional) – The data type to convert the parameters to. Defaults to None.

Returns:

The modified RBM instance.

Return type:

RBM

class rbms.classes.RBM

Bases: EBM

An abstract class representing the parameters of a RBM.

abstractmethod compute_energy(v: Tensor, h: Tensor) → Tensor

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

Returns:

The computed energy.

Return type:

Tensor

abstractmethod compute_energy_hiddens(h: Tensor) → Tensor

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

h (Tensor) – The computed energy

abstractmethod num_hiddens() → int

Number of hidden units

abstractmethod sample_hiddens(chains: dict[str, Tensor], beta: float = 1.0) → dict[str, Tensor]

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

sample_state(chains, n_steps, beta=1.0)

Sample the model for n_steps

Parameters:

  • () (chains) – The starting position of the chains.

  • n_steps (int) – The number of sampling steps.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0

Returns:

The updated chains after n_steps of sampling.

Return type:

dict[str, Tensor]

rbms.const

rbms.custom_fn

rbms.custom_fn.log2cosh(x: Tensor) → Tensor

Numerically stable version of log(2*cosh(x)).

Parameters:

x (Tensor) – Input tensor.

Returns:

Output tensor.

Return type:

Tensor

rbms.custom_fn.one_hot(x: Tensor, num_classes: int = -1, dtype: dtype = torch.float32) → Tensor

A one-hot encoding function faster than the PyTorch one working with torch.int32 and returning a float Tensor

Parameters:

  • x (Tensor) – Input tensor.

  • num_classes (int, optional) – Number of classes for the one_hot encoding. If negative, then the number of classes is automatically detected.

  • dtype (torch.dtype, optional) – Dtype of the returned tensor. Defaults to torch.float32

Returns

Tensor: One-hot encoded version of the input tensor.

rbms.parser

class rbms.classes.EBM

Bases: ABC

An abstract class representing the parameters of an Energy-Based Model.

abstractmethod clone(device: device | None = None, dtype: dtype | None = None) → Self

Create a clone of the RBM instance.

Parameters:

  • device (Optional[torch.device], optional) – The device for the cloned parameters. Defaults to the current device.

  • dtype (Optional[torch.dtype], optional) – The data type for the cloned parameters. Defaults to the current data type.

Returns:

A new RBM instance with cloned parameters.

Return type:

RBM

abstractmethod compute_energy_visibles(v: Tensor) → Tensor

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

v (Tensor) – Visible configurations

Returns:

The computed energy.

Return type:

Tensor

abstractmethod compute_gradient(data: dict[str, Tensor], chains: dict[str, Tensor], centered: bool = True) → None

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

device: device
abstractmethod independent_model() → Self

Independent model where only local fields are preserved.

abstractmethod init_chains(num_samples: int, weights: Tensor | None = None, start_v: Tensor | None = None) → dict[str, Tensor]

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • start_v (Tensor, optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

abstractmethod static init_parameters(num_hiddens: int, dataset: RBMDataset, device: device, dtype: dtype, var_init: float = 0.0001) → Self

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

abstractmethod named_parameters() → dict[str, Tensor]
abstractmethod num_visibles() → int

Number of visible units

abstractmethod parameters() → List[Tensor]

Returns a list containing the parameters of the RBM.

Returns:

A list containing the weight matrix, visible bias, and hidden bias.

Return type:

List[Tensor]

abstractmethod ref_log_z() → float

Reference log partition function with weights set to 0 (except for the visible bias).

abstractmethod sample_state(chains: dict[str, Tensor], n_steps: int, beta: float = 1.0) → dict[str, Tensor]

Sample the model for n_steps

Parameters:

  • () (chains) – The starting position of the chains.

  • n_steps (int) – The number of sampling steps.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0

Returns:

The updated chains after n_steps of sampling.

Return type:

dict[str, Tensor]

abstractmethod sample_visibles(chains: dict[str, Tensor], beta: float = 1.0) → dict[str, Tensor]

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

abstractmethod static set_named_parameters(named_params: dict[str, Tensor]) → Self
abstractmethod to(device: device | None = None, dtype: dtype | None = None) → Self

Move the parameters to the specified device and/or convert them to the specified data type.

Parameters:

  • device (Optional[torch.device], optional) – The device to move the parameters to. Defaults to None.

  • dtype (Optional[torch.dtype], optional) – The data type to convert the parameters to. Defaults to None.

Returns:

The modified RBM instance.

Return type:

RBM

class rbms.classes.RBM

Bases: EBM

An abstract class representing the parameters of a RBM.

abstractmethod compute_energy(v: Tensor, h: Tensor) → Tensor

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

Returns:

The computed energy.

Return type:

Tensor

abstractmethod compute_energy_hiddens(h: Tensor) → Tensor

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

h (Tensor) – The computed energy

abstractmethod num_hiddens() → int

Number of hidden units

abstractmethod sample_hiddens(chains: dict[str, Tensor], beta: float = 1.0) → dict[str, Tensor]

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

sample_state(chains, n_steps, beta=1.0)

Sample the model for n_steps

Parameters:

  • () (chains) – The starting position of the chains.

  • n_steps (int) – The number of sampling steps.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0

Returns:

The updated chains after n_steps of sampling.

Return type:

dict[str, Tensor]

rbms.plot

rbms.plot.plot_PCA(data1, data2, labels, dir1=0, dir2=1)

Args: data1 data2 labels dir1: (Default value = 0) dir2: (Default value = 1)

rbms.plot.plot_hist(ax, data_proj, gen_data_proj, color, proj, labels, orientation='vertical')

Args: ax data_proj gen_data_proj color proj labels orientation: (Default value = “vertical”)

rbms.plot.plot_image(sample, shape=(28, 28), grid_size=(10, 10), show_grid=False, randomize=True)

Args: sample shape: (Default value = (28) 28) grid_size: (Default value = (10) 10) show_grid: (Default value = False) randomize: (Default value = True)

rbms.plot.plot_scatter_labels(ax, data_proj, gen_data_proj, proj1, proj2, labels)

Args: ax data_proj gen_data_proj proj1 proj2 labels

rbms.utils

rbms.utils.check_file_existence(filename: str)

Checks if a file exists at the given filename path. If the file exists, prompts the user with a yes/no question on whether to override the file. If the user agrees, the file is deleted. If the user disagrees, the program exits.

Parameters:

filename (str) – The path to the file to check.

Raises:

SystemExit – If the file exists and the user chooses not to override it.

rbms.utils.compute_log_likelihood(v_data: Tensor, w_data: Tensor, params: RBM, log_z: float) → float

Compute the log likelihood of the RBM on the data, given its log partition function.

Parameters:

  • v_data (Tensor) – Data to estimate the log likelihood.

  • w_data (Tensor) – Weights associated to the samples.

  • params (RBM) – Parameters of the RBM.

  • log_z (float) – Log partition function.

Returns:

Log Likelihood.

Return type:

float

rbms.utils.get_categorical_configurations(n_states: int, n_dim: int, device: device = device(type='cpu'), dtype: dtype = torch.float32) → Tensor

Generate all possible categorical configurations for a given number of states and dimensions.

Parameters:

  • n_states (int) – Number of possible states for each dimension.

  • n_dim (int) – Number of dimensions.

  • device (torch.device, optional) – Device on which to place the tensor. Default is CPU.

  • dtype (torch.dtype, optional) – Data type of the returned tensor. Default is torch.float32.

Returns:

A tensor containing all possible categorical configurations.

Return type:

Tensor

Raises:

ValueError – If the number of dimensions exceeds the maximum allowed (20).

rbms.utils.get_eigenvalues_history(filename: str)

Extracts the history of eigenvalues of the RBM’s weight matrix.

Parameters:

filename (str) – Path to the HDF5 training archive.

Returns:

A tuple containing two elements:

  • gradient_updates (np.ndarray): Array of gradient update steps.

  • eigenvalues (np.ndarray): Eigenvalues along training.

Return type:

tuple

rbms.utils.get_flagged_updates(filename: str, flag: str) → ndarray

Retrieve a sorted list of update indices from an HDF5 file that have a specific flag set.

Parameters:

  • filename (str) – Path to the HDF5 file.

  • flag (str) – Flag to check for in the updates.

Returns:

Sorted array of update indices that have the specified flag set.

Return type:

np.ndarray

rbms.utils.get_saved_updates(filename: str) → ndarray

Extracts the saved index from an RBM training archive

Parameters:

filename (str) – The path to the HDF5 file from which to extract update indices.

Returns:

Sorted array of update indices.

Return type:

np.ndarray

rbms.utils.log_to_csv(logs: dict[str, float], log_file: str) → None

Append log data to a CSV file.

Parameters:

  • logs (dict[str, float]) – Dictionary containing log data where keys are the log names and values are the log values.

  • log_file (str) – Path to the CSV file.

rbms.utils.query_yes_no(question: str, default: str = 'yes') → bool

Ask a yes/no question via raw_input() and return their answer.

Parameters:

  • question (str) – Question asked

  • default (str, optional) – Default answer to the question. Defaults to

Returns:

True if yes, False if no

Return type:

bool

Notes

Credits to “https://stackoverflow.com/questions/3041986/apt-command-line-interface-like-yes-no-input”

rbms.utils.restore_rng_state(filename: str, index: int)

Restores the random number generator (RNG) states for both PyTorch and NumPy from a RBM training archive.

Parameters:

  • filename (str) – Path to the HDF5 file.

  • index (int) – Training index to load.

Raises:

  • KeyError – If the specified index does not exist in the HDF5 file.

  • OSError – If the file cannot be opened or read.

  • ValueError – If the RNG state data is not in the expected format.

rbms.bernoulli_bernoulli

This submodule handles methods and classes specific to Bernoulli-Bernoulli RBM

rbms.bernoulli_bernoulli.classes

class rbms.bernoulli_bernoulli.classes.BBRBM(weight_matrix: Tensor, vbias: Tensor, hbias: Tensor, device: device | None = None, dtype: dtype | None = None)

Bases: RBM

Parameters of the Bernoulli-Bernoulli RBM

clone(device: device | None = None, dtype: dtype | None = None)

Create a clone of the RBM instance.

Parameters:

  • device (Optional[torch.device], optional) – The device for the cloned parameters. Defaults to the current device.

  • dtype (Optional[torch.dtype], optional) – The data type for the cloned parameters. Defaults to the current data type.

Returns:

A new RBM instance with cloned parameters.

Return type:

RBM

compute_energy(v: Tensor, h: Tensor) → Tensor

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

Returns:

The computed energy.

Return type:

Tensor

compute_energy_hiddens(h: Tensor) → Tensor

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

h (Tensor) – The computed energy

compute_energy_visibles(v: Tensor) → Tensor

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

v (Tensor) – Visible configurations

Returns:

The computed energy.

Return type:

Tensor

compute_gradient(data, chains, centered=True)

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

independent_model()

Independent model where only local fields are preserved.

init_chains(num_samples, weights=None, start_v=None)

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • start_v (Tensor, optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

static init_parameters(num_hiddens, dataset, device, dtype, var_init=0.0001)

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

named_parameters()
num_hiddens()

Number of hidden units

num_visibles()

Number of visible units

parameters() → List[Tensor]

Returns a list containing the parameters of the RBM.

Returns:

A list containing the weight matrix, visible bias, and hidden bias.

Return type:

List[Tensor]

ref_log_z()

Reference log partition function with weights set to 0 (except for the visible bias).

sample_hiddens(chains: dict[str, Tensor], beta=1) → dict[str, Tensor]

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

sample_visibles(chains: dict[str, Tensor], beta=1) → dict[str, Tensor]

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

static set_named_parameters(named_params: dict[str, Tensor]) → Self
to(device: device | None = None, dtype: dtype | None = None)

Move the parameters to the specified device and/or convert them to the specified data type.

Parameters:

  • device (Optional[torch.device], optional) – The device to move the parameters to. Defaults to None.

  • dtype (Optional[torch.dtype], optional) – The data type to convert the parameters to. Defaults to None.

Returns:

The modified RBM instance.

Return type:

RBM

rbms.bernoulli_bernoulli.functional

rbms.bernoulli_bernoulli.functional.compute_energy(v: Tensor, h: Tensor, params: BBRBM) → Tensor

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

  • params (BBRBM) – Parameters of the RBM.

Returns:

The computed energy.

Return type:

Tensor

rbms.bernoulli_bernoulli.functional.compute_energy_hiddens(h: Tensor, params: BBRBM) → Tensor

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

  • h (Tensor) – Hidden configurations.

  • params (BBRBM) – Parameters of the RBM.

rbms.bernoulli_bernoulli.functional.compute_energy_visibles(v: Tensor, params: BBRBM) → Tensor

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

  • v (Tensor) – Visible configurations

  • params (BBRBM) – Parameters of the RBM

Returns:

The computed energy.

Return type:

Tensor

rbms.bernoulli_bernoulli.functional.compute_gradient(data: dict[str, Tensor], chains: dict[str, Tensor], params: BBRBM, centered: bool = True) → None

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • params (BBRBM) – The parameters of the RBM.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

rbms.bernoulli_bernoulli.functional.init_chains(num_samples: int, params: BBRBM, weights: Tensor | None = None, start_v: Tensor | None = None) → dict[str, Tensor]

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • params (BBRBM) – The parameters of the RBM.

  • weights (Tensor, optional) – The weights of each configuration. Defaults to None.

  • start_v (Optional[Tensor], optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

rbms.bernoulli_bernoulli.functional.init_parameters(num_hiddens: int, dataset: RBMDataset, device: device, dtype: dtype, var_init: float = 0.0001) → BBRBM

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

rbms.bernoulli_bernoulli.functional.sample_hiddens(chains: dict[str, Tensor], params: BBRBM, beta: float = 1.0) → dict[str, Tensor]

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • params (BBRBM) – The parameters of the RBM.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

rbms.bernoulli_bernoulli.functional.sample_visibles(chains: dict[str, Tensor], params: BBRBM, beta: float = 1.0) → dict[str, Tensor]

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • params (BBRBM) – The parameters of the RBM.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled visible states.

Return type:

dict[str, Tensor]

rbms.bernoulli_bernoulli.utils

rbms.dataset

This submodule handles the RBMDataset class for FASTA and HDF5 files.

rbms.dataset.dataset_class

class rbms.dataset.dataset_class.RBMDataset(data: ndarray, labels: ndarray, weights: ndarray, names: ndarray, dataset_name: str, is_binary: bool, device: str = 'cuda', dtype: dtype = torch.float32)

Bases: Dataset

A dataset class for RBM training and evaluation.

get_effective_size() → int

Get the effective size of the dataset.

Returns:

The effective size of the dataset.

Return type:

int

get_gzip_entropy(mean_size: int = 50, num_samples: int = 100)

Compute the gzip entropy of the dataset.

Parameters:

  • mean_size (int, optional) – The number of samples to average over. Defaults to 50.

  • num_samples (int, optional) – The number of samples to use for each entropy calculation. Defaults to 100.

Returns:

The computed gzip entropy.

Return type:

float

get_num_states() → int

Get the number of states.

Returns:

The number of states.

Return type:

int

get_num_visibles() → int

Get the number of visible units.

Returns:

The number of visible units.

Return type:

int

rbms.dataset.fasta_utils

rbms.dataset.fasta_utils.compute_weights(data: Tuple[ndarray, List], th: float = 0.8, device: device = 'cpu') → ndarray

Computes the weight to be assigned to each sequence ‘s’ in ‘data’ as 1 / n_clust, where ‘n_clust’ is the number of sequences that have a sequence identity with ‘s’ >= th.

Parameters:

  • data (ArrayLike) – Encoded input dataset.

  • th (float, optional) – Sequence identity threshold for the clustering. Defaults to 0.8.

  • device (torch.device) – Device.

Returns:

Array with the weights of the sequences.

Return type:

np.ndarray

rbms.dataset.fasta_utils.decode_sequence(sequence: Tuple[ndarray, List], tokens: str) → str

Takes a numeric sequence in input an returns the string encoding.

Parameters:

  • sequence (ArrayLike) – Encoded sequence.

  • tokens (str) – Vocabulary.

Returns:

Decoded sequence.

Return type:

list

rbms.dataset.fasta_utils.encode_sequence(sequence: str, tokens: str) → ndarray

Takes a string sequence in input an returns the numeric encoding.

Parameters:

  • sequence (str) – Sequence.

  • tokens (str) – Vocabulary.

Returns:

Encoded sequence.

Return type:

list

rbms.dataset.fasta_utils.get_tokens(alphabet: str)

Load the vocabulary associated to the alphabet type. :param alphabet: alphabet type (one of ‘protein’, ‘rna’, ‘dna’). :type alphabet: str

Returns:

Vocabulary.

Return type:

str

rbms.dataset.fasta_utils.import_from_fasta(fasta_name: str | Path) → Tuple[ndarray, ndarray]

Import data from a fasta file.

Parameters:

fasta_name (Union[str, Path]) – Path to the fasta file.

Raises:

RuntimeError – The file is not in fasta format.

Returns:

headers, sequences.

Return type:

Tuple[list, list]

rbms.dataset.fasta_utils.validate_alphabet(sequences: Tuple[ndarray, List], tokens: str)
rbms.dataset.fasta_utils.write_fasta(fname: str, headers: Tuple[ndarray, List], sequences: Tuple[ndarray, List], numeric_input: bool = False, remove_gaps: bool = False, alphabet: str = 'protein')

Generate a fasta file with the input sequences.

Parameters:

  • fname (str) – Name of the output fasta file.

  • headers (ArrayLike) – List of sequences’ headers.

  • sequences (ArrayLike) – List of sequences.

  • numeric_input (bool, optional) – Whether the sequences are in numeric (encoded) format or not. Defaults to False.

  • remove_gaps (bool, optional) – If True, removes the gap from the alignment. Defaults to False.

  • alphabet (str, optional) – Selects the type of sequences. Possible chooses are (“protein”, “rna”). Defaults to “protein”.

Raises:

RuntimeError – The alphabet is not a valid choice.

rbms.dataset.load_fasta

rbms.dataset.load_fasta.load_FASTA(filename: str | Path, binarize: bool = False, use_weights: bool = False, alphabet: str = 'protein', device='cuda') → Tuple[ndarray, ndarray, ndarray]

Load a dataset from a FASTA file.

Parameters:

  • filename (str) – The name of the FASTA file to load.

  • binarize (bool, optional) – Binarize the dataset to [0,1]. Defaults to “Potts”.

  • use_weights (bool, optional) – Whether to use weights in the dataset. Defaults to False.

  • alphabet (str, optional) – The alphabet used in the dataset. Defaults to “protein”.

  • device (str, optional) – The device to use for PyTorch tensors. Defaults to “cuda”.

Returns:

Tuple[np.ndarray, np.ndarray, np.ndarray] The dataset, weights and names.

rbms.dataset.load_h5

rbms.dataset.load_h5.load_HDF5(filename: str | Path, binarize: bool = True) → Tuple[ndarray, ndarray | None]

Load a dataset from an HDF5 file.

Parameters:

  • filename (str) – The name of the HDF5 file to load.

  • binarize (str, optional) – Binarize the dataset. Defaults to True.

Returns:

The dataset and labels.

Return type:

Tuple[np.ndarray, np.ndarray]

rbms.dataset.utils

rbms.dataset.utils.get_subset_labels(data: ndarray, labels: ndarray, subset_labels: ndarray) → Tuple[ndarray, ndarray]

rbms.potts_bernoulli

This submodule handles methods and classes specific to Potts-Bernoulli RBM

rbms.potts_bernoulli.classes

class rbms.potts_bernoulli.classes.PBRBM(weight_matrix: Tensor, vbias: Tensor, hbias: Tensor, device: device | None = None, dtype: dtype | None = None)

Bases: RBM

Parameters of the Potts-Bernoulli RBM

clone(device: device | None = None, dtype: dtype | None = None)

Create a clone of the RBM instance.

Parameters:

  • device (Optional[torch.device], optional) – The device for the cloned parameters. Defaults to the current device.

  • dtype (Optional[torch.dtype], optional) – The data type for the cloned parameters. Defaults to the current data type.

Returns:

A new RBM instance with cloned parameters.

Return type:

RBM

compute_energy(v, h)

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

Returns:

The computed energy.

Return type:

Tensor

compute_energy_hiddens(h)

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

h (Tensor) – The computed energy

compute_energy_visibles(v)

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

v (Tensor) – Visible configurations

Returns:

The computed energy.

Return type:

Tensor

compute_gradient(data, chains, centered=True)

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

independent_model()

Independent model where only local fields are preserved.

init_chains(num_samples, weights=None, start_v=None)

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • start_v (Tensor, optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

static init_parameters(num_hiddens, dataset, device, dtype, var_init=0.0001)

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

named_parameters()
num_hiddens()

Number of hidden units

num_states() → int

Number of colors for the Potts variables

num_visibles()

Number of visible units

parameters() → List[Tensor]

Returns a list containing the parameters of the RBM.

Returns:

A list containing the weight matrix, visible bias, and hidden bias.

Return type:

List[Tensor]

ref_log_z()

Reference log partition function with weights set to 0 (except for the visible bias).

sample_hiddens(chains, beta=1)

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

sample_visibles(chains, beta=1)

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

static set_named_parameters(named_params)
to(device: device | None = None, dtype: dtype | None = None)

Move the parameters to the specified device and/or convert them to the specified data type.

Parameters:

  • device (Optional[torch.device], optional) – The device to move the parameters to. Defaults to None.

  • dtype (Optional[torch.dtype], optional) – The data type to convert the parameters to. Defaults to None.

Returns:

The modified RBM instance.

Return type:

RBM

rbms.potts_bernoulli.functional

rbms.potts_bernoulli.functional.compute_energy(v: Tensor, h: Tensor, params: PBRBM) → Tensor

Compute the energy of the RBM on the visible and hidden variables.

Parameters:

  • v (Tensor) – Visible configurations.

  • h (Tensor) – Hidden configurations.

  • params (PBRBM) – Parameters of the RBM.

Returns:

The computed energy.

Return type:

Tensor

rbms.potts_bernoulli.functional.compute_energy_hiddens(h: Tensor, params: PBRBM) → Tensor

Returns the marginalized energy of the model computed on hidden configurations

Parameters:

  • h (Tensor) – Hidden configurations.

  • params (PBRBM) – Parameters of the RBM.

rbms.potts_bernoulli.functional.compute_energy_visibles(v: Tensor, params: PBRBM) → Tensor

Returns the marginalized energy of the model computed on the visible configurations

Parameters:

  • v (Tensor) – Visible configurations

  • params (PBRBM) – Parameters of the RBM

Returns:

The computed energy.

Return type:

Tensor

rbms.potts_bernoulli.functional.compute_gradient(data: dict[str, Tensor], chains: dict[str, Tensor], params: PBRBM, centered: bool = True) → None

Compute the gradient for each of the parameters and attach it.

Parameters:

  • data (dict[str, Tensor]) – The data state.

  • chains (dict[str, Tensor]) – The parallel chains used for gradient computation.

  • params (PBRBM) – The parameters of the RBM.

  • centered (bool, optional) – Whether to use centered gradients. Defaults to True.

rbms.potts_bernoulli.functional.init_chains(num_samples: int, params: PBRBM, weights: Tensor | None = None, start_v: Tensor | None = None) → dict[str, Tensor]

Initialize a Markov chain for the RBM by sampling a uniform distribution on the visible layer and sampling the hidden layer according to the visible one.

Parameters:

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

  • params (PBRBM) – The parameters of the RBM.

  • weights (Tensor, optional) – The weights of each configuration. Defaults to None.

  • start_v (Optional[Tensor], optional) – The initial visible states. Defaults to None.

Returns:

The initialized Markov chain.

Return type:

dict[str, Tensor]

Notes

  • If start_v is specified, its number of samples will override the num_samples argument.

rbms.potts_bernoulli.functional.init_parameters(num_hiddens: int, dataset: RBMDataset, device: device, dtype: dtype, var_init: float = 0.0001) → PBRBM

Initialize the parameters of the RBM.

Parameters:

  • num_hiddens (int) – Number of hidden units.

  • dataset (RBMDataset) – Training dataset.

  • device (torch.device) – PyTorch device for the parameters.

  • dtype (torch.dtype) – PyTorch dtype for the parameters.

  • var_init (float, optional) – Variance of the weight matrix. Defaults to 1e-4.

Notes

  • The number of visible units is induced from the dataset provided.

  • Hidden biases are set to 0.

  • Visible biases are set to the frequencies of the dataset.

  • The weight matrix is initialized with a Gaussian distribution of variance var_init.

rbms.potts_bernoulli.functional.sample_hiddens(chains: dict[str, Tensor], params: PBRBM, beta: float = 1.0) → dict[str, Tensor]

Sample the hidden layer conditionally to the visible one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • params (PBRBM) – The parameters of the RBM.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled hidden states.

Return type:

dict[str, Tensor]

rbms.potts_bernoulli.functional.sample_visibles(chains: dict[str, Tensor], params: PBRBM, beta: float = 1.0) → dict[str, Tensor]

Sample the visible layer conditionally to the hidden one.

Parameters:

  • chains (dict[str, Tensor]) – The parallel chains used for sampling.

  • params (PBRBM) – The parameters of the RBM.

  • beta (float, optional) – The inverse temperature. Defaults to 1.0.

Returns:

The updated chains with sampled visible states.

Return type:

dict[str, Tensor]

rbms.potts_bernoulli.utils