core.latents#

This module contains the classes implementing the components of the latent space of the core.model.BulkDGD, namely the Gaussian mixture model (core.latent.GaussianMixtureModel) and the representation layer (core.latent.RepresentationLayer).

class bulkdgd.core.latents.GaussianMixtureModelLegacy(dim: int, n_components: int, means_prior_name: str, weights_prior_name: str, log_var_prior_name: str, means_prior_options: dict[str, object], weights_prior_options: dict[str, object], log_var_prior_options: dict[str, object], covariance_type: str = 'diagonal')#

A class implementing the legacy mixture of multivariate Gaussian distributions (Gaussian mixture model or GMM).

forward(x: Tensor) → Tensor#

Forward pass - compute the absolute log-probability density for a set of data points.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

ytorch.Tensor

The result of the forward pass.

This is a 1D tensor whose size is equal to the number of input data points.

Each element of the tensor is the absolute log-probability density of a data point.

get_mixture_probs() → Tensor#

Convert the weights into mixture probabilities using the softmax function.

Returns:

mixture_probstorch.Tensor

The mixture probabilities.

This is a 1D tensor whose size equals the number of components in the Gaussian mixture model.

get_prior_log_prob() → float#

Calculate the log-probability of the prior over the means, log-variance, and mixture coefficients.

Returns:

pfloat: The log-probability of the prior.

log_prob(x: Tensor) → Tensor#

Get the log-probability density of a set of samples drawn from the Gaussian mixture model.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

log_probtorch.Tensor

A 1D tensor storing the log-probability density of each input data point to be drawn from the Gaussian mixture model.

The tensor has a size equal to the number of data points passed.

sample_new_points(n_points: int, n_samples_per_comp: int = 1, sampling_method: str = 'mean') → Tensor#

Draw samples for new data points from each component of the Gaussian mixture model.

Parameters:

n_pointsint

The number of data points for which samples should be drawn.

n_samples_per_compint, 1

The number of samples to draw per data point per component of the Gaussian mixture.

sampling_methodstr, {"mean"}, "mean"

How to draw the samples for the given data points.

Available options are:

"mean" means taking the mean of each component as the value of each n_samples_per_comp sample taken for each data point.

Returns:

new_pointstorch.Tensor

The samples drawn.

This is a 2D tensor where:

The first dimension has a length equal to n_points * n_reps_per_mix_comp * n_components.
The second dimension has a length equal to the dimensionality of the Gaussian mixture model.

sample_probs(x: Tensor) → Tensor#

Get the probability density per sample per component.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

probstorch.Tensor

The probability densities.

This is a 2D tensor where:

The first dimension has a length equal to the number of input data points.
The second dimension has a length equal to the number of components in the Gaussian mixture.

Each element of the tensor stores a per-data point, per-component probability density.

save(file: str) → None#

Save the legacy GMM parameters to a .pth file.

Parameters:

filestr: The .pth file where to save the model parameters.

set_log_var(log_var: Tensor) → None#

Set the log-variance of the components of the Gaussian mixture model.

Parameters:

log_vartorch.Tensor

The log-variance of the components of the Gaussian mixture model.

This is a 2D tensor where:

The first dimension has a length equal to the number of components in the Gaussian mixture.
The second dimension has a length equal to the dimensionality of the Gaussian mixture model.

set_means(means: Tensor) → None#

Set the means of the components of the Gaussian mixture model.

Parameters:

meanstorch.Tensor

The means of the components of the Gaussian mixture model.

This is a 2D tensor where:

The first dimension has a length equal to the number of components in the Gaussian mixture.
The second dimension has a length equal to the dimensionality of the Gaussian mixture model.

set_weights(weights: Tensor) → None#

Set the weights of the components of the Gaussian mixture model.

Parameters:

weightstorch.Tensor

The weights of the components of the Gaussian mixture model.

This is a 1D tensor whose size equals the number of components in the Gaussian mixture model.

property covariance_type#: The type of the covariance matrix.

property dim#: The dimensionality of the Gaussian mixture model.

property log_var#: The log-variance of the components of the Gaussian mixture model.

property log_var_prior#: A dictionary containing the name of the prior over the log-variance of the components of the Gaussian mixture model and the options used to set it up.

property means#: The means of the components of the Gaussian mixture model.

property means_prior#: A dictionary containing the name of the prior over the means of the components of the Gaussian mixture model and the options used to set it up.

property n_components#: The number of components in the Gaussian mixture.

property weights#: The weights of the components of the Gaussian mixture model.

property weights_prior#: A dictionary containing the name of the prior over the weights of the components of the Gaussian mixture model and the options used to set it up.

class bulkdgd.core.latents.GaussianMixtureModelTGMM(n_components: int = 1, n_features: int = None, covariance_type: str = 'full', max_iter: int = 1000, tol: float = 0.0001, reg_covar: float = 1e-06, n_init: int = 1, init_means='kmeans', init_weights='uniform', init_covariances='empirical', random_state: int = None, warm_start: bool = False, cem: bool = False, weight_concentration_prior: Tensor = None, mean_prior: Tensor = None, mean_precision_prior: float = None, covariance_prior: Tensor = None, degrees_of_freedom_prior: float = None, verbose: bool = False, verbose_interval: int = 10, device: str = None, **kwargs)#

Compatibility wrapper for tgmm.GaussianMixture.

forward(x: Tensor) → Tensor#

Return negative log-density.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

ytorch.Tensor

A 1D tensor whose size is equal to the number of input data points.

Each element of the tensor is the negative log-probability density of a data point.

get_mixture_probs() → Tensor#

Get the mixture probabilities.

Returns:

mixture_probstorch.Tensor: The mixture probabilities.

load_state_dict(state_dict, strict=False, *args, **kwargs)#: Load the state dictionary.

log_prob(x: Tensor) → Tensor#

Return the log-density.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

log_probtorch.Tensor: A 1D tensor whose size is equal to the number of input data points.

sample_new_points(n_points: int, n_samples_per_comp: int = 1, sampling_method: str = 'mean') → Tensor#

Draw samples from each component.

Parameters:

n_pointsint

The number of data points for which samples should be drawn.

n_samples_per_compint, 1

The number of samples to draw per data point per component of the Gaussian mixture.

sampling_methodstr, {"mean"}, "mean"

How to draw the samples for the given data points.

Available options are:

"mean" means taking the mean of each component as the value of each n_samples_per_comp sample taken for each data point.

Returns:

new_pointstorch.Tensor: The samples drawn.

sample_probs(x: Tensor) → Tensor#

Sample probabilities.

Parameters:

xtorch.Tensor

The input data points. This is a 2D tensor where:

The first dimension has a length equal to the number of data points.
The second dimension has a length equal to the dimensionality of the data points.

Returns:

probstorch.Tensor

The probability densities.

This is a 2D tensor where:

The first dimension has a length equal to the number of input data points.
The second dimension has a length equal to the number of components in the Gaussian mixture.

Each element of the tensor stores a per-data point, per-component probability density.

state_dict(*args, **kwargs)#: Get the state dictionary containing the parameters of the model.

to(*args, **kwargs)#: Move the model parameters and internal tensors to the target device.

property dim#: Alias for TGMM n_features.

property means#: Alias for TGMM means_.

property weights#: Alias for TGMM weights_.

Class implementing a representation layer accumulating gradients.

This layer stores learned embeddings for data samples that can be optimized during training. It supports various initialization methods and utility functions for representation manipulation and analysis.

classmethod load(file: str, device: str | device | None = None) → RepresentationLayer#

Load representations from a file.

Parameters:

pathstr: The file from which to load the representations.
devicestr or torch.device, optional: The device where to load the representations.

Returns:

rep_layercore.latent.RepresentationLayer: The representation layer.

forward(ixs: list[int] | Tensor | None = None, index_map: dict[int, int] | None = None, batch_size: int | None = None) → Tensor#

Forward pass that returns the values of the representations.

Parameters:

ixsint or torch.Tensor, optional: The indexes of the samples whose representations should be returned. If not passed, all representations will be returned.
index_mapdict, optional: A mapping from dataset indices to representation indices.
batch_sizeint, optional: Process representations in batches of size batch_size for memory efficiency.

Returns:

repstorch.Tensor

A tensor containing the values of the representations for the samples of interest.

This is a 2D tensor where:

The first dimension has a length equal to the number of representations.
The second dimension has a length equal to the dimensionality of the representations.

rescale() → None#

Rescale the representations by subtracting the mean of the representations’ values from each of them and dividing each of them by the standard deviation of all representations.

Given \(N\) samples, we can indicate with \(z^{n}\) the value of the representation of sample \(x^{n}\).

Therefore, the rescaled value of the representation \(z^{n}_{rescaled}\) will be:

\[z^{n}_{rescaled} = \frac{z^{n} - \bar{z}}{s}\]

Where \(\bar{z}\) is the mean of the representations’ values and \(s\) is the standard deviation.

save(file: str) → None#

Save the representations to a .pth file.

Parameters:

filestr: The .pth file where to save the representations.

property device#: The device where the model is.

property dim#: The dimensionality of the representations.

property n_rep#: The number of representations in the layer.

property options#: The dictionary ot options used to generate the representations, if no values were passed when initializing the layer.

property z#: The values of the representations.