# Models

class gmmvi.models.gmm.GMM(log_weights: Variable, means: Variable, chol_covs: Variable)

  An abstract class for Gaussian mixture models (GMMs).

  This class stores the parameters of a GMM (weights, means and Cholesky matrices) and provides functionality that is common for different types of GMMs (e.g., GMMs with full covariance matrices, and those with diagonal covariance matrices). For example, this class provides methods for sampling the GMM, evaluating its probability density function, and entropy, while relying on the subclass for sampling the components, etc.

  Parameters:

    - log_weights – tf.Variable(float) A tensorflow Variable for storing the log-probabilities of the component weights.

    - means – tf.Variable(float) A tensorflow Variable for storing the component means (number of components X number of dimensions)

    - chol_covar – tf.Variable(float) A tensorflow Variable for storing the Cholesky matrix of the component’s covariance matrix. The first dimension specifies the index of the components. The rank may vary depending on the subclass. For example, when storing the Cholesky matrix for a diagonal covariance matrix, it is possible to use a rank-2 Tensor (number of components X number of dimensions) for better memory efficiency.

  add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)

    Add a component to the mixture model. The weights will be automatically normalized.

    Parameters:

      - initial_weight – tf.Tensor The weight of the new component (before re-normalization)

      - initial_mean – tf.Tensor The mean of the new component

      - initial_cov – tf.Tensor The covariance matrix of the new component

  component_entropies() → Tensor

    Computes the entropy of each component.

    Returns:

      a one-dimensional tensor of shape num_components containing the component entropies.

    Return type:

      tf.Tensor

  component_log_densities(samples: Tensor) → Tensor

    Evaluate the log densities for each mixture component on the given samples.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

    Return type:

      tf.Tensor

  component_log_density(index: int, samples: Tensor) → Tensor

    Use the specified component to evaluate the Gaussian log-density at the given samples.

    Parameters:

      - index – int The index of the component of which we want to compute the log densities.

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a one-dimensional tensor of size number_of_samples, containing the log-densities.

    Return type:

      tf.Tensor

  component_log_density_and_grad(index: int, samples: Tensor) → [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>]

    Evaluates for the given component the log-density and its gradient.

    Parameters:

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

      - Returns –

        component_log_densities - a one-dimensional tf.Tensor of shape num_samples containing the log-densities of the given component.

        component_log_density_grads - a two-dimensional tf.Tensor of shape num_samples x num_dimensions containing the gradients of the component’s log-densities.

  component_marginal_log_densities(samples: Tensor, dimension: int) → Tensor

    Evaluate the marginal log densities for each mixture component along the given dimension for each sample.

    Parameters:

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate. Note that for providing an easier interface, each sample has the number of dimensions compatible with this GMM, although only a single entry is actually used for evaluating the marginal density.

      - dimension – int The dimension of interest.

    Returns:

      a two-dimensional tensor of size number_of_components x number_of_samples, containing the marginal log-densities for each component.

    Return type:

      tf.Tensor

  property covs: Tensor

    Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

  density(samples: Tensor) → Tensor

    Evaluates the given samples on this GMM.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

    Returns:

      a one-dimensional tensor of shape num_samples containing the model densities.

    Return type:

      tf.Tensor

  gaussian_entropy(chol: Tensor) → Tensor

    Computes the entropy of Gaussian distribution with the given Cholesky matrix.

    Parameters:

      chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

    Returns:

      The entropy

    Return type:

      tf.float32

  get_average_entropy() → tf.float32

    Averages the entropies of the individual components based on their respective weights.

    Returns:

      the average component entropy

    Return type:

      tf.float32

  log_densities_also_individual(samples: Tensor) → [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>]

    Evaluates the given samples on this GMM, but also returns individual log-densities for each Gaussian component.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

    Returns:

      model_log_densities - a one-dimensional tnsor of shape num_samples containing the model log-densities.

      component_log_densities - a two-dimensional tensor of shape num_components x num_samples containing the component log-densities

    Return type:

      tuple(tf.Tensor, tf.Tensor)

  log_density(samples: Tensor) → Tensor

    Evaluates the given samples on this GMM.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a one-dimensional tensor of shape num_samples containing the model log-densities.

    Return type:

      tf.Tensor

  log_density_and_grad(samples: Tensor) → [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>]

    Evaluates the given samples on this GMM, returns the log-densities of the whole model, their gradients, and also the individual log-densities for each Gaussian component.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      model_log_densities - a one-dimensional tensor of shape num_samples containing the model log-densities.

      model_log_density_grads - a two-dimensional tf.Tensor of shape num_samples x num_dimensions containing the gradients of the model log-densities.

      component_log_densities - a two-dimensional tf.Tensor of shape num_components x num_samples containing the component log-densities.

    Return type:

      tuple(tf.Tensor, tf.Tensor)

  marginal_log_density(samples: Tensor, dimension: int) → Tensor

    Evaluates this GMM on the given samples with respect to the marginal log-density along the given dimensions

    Parameters:

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

      - dimension – int The dimension of interest

    Returns:

      a one-dimensional tensor of shape num_samples containing the marginal log-densities

    Return type:

      tf.Tensor

  property num_components: int

    Returns: int: the number of components of this GMM

  remove_component(idx: int)

    Removes the specified component, and renormalizes the weights afterwards.

    Parameters:

      idx – int The idx of the component to be removed.

  replace_components(new_means: Tensor, new_chols: Tensor)

    Updates the means and covariances matrices (Cholesky) of the GMM. The weights and, therefore, the number of components can not be changed with this method.

    Parameters:

      - new_means – tf.Tensor a two-dimensional tensor of shape current_number_of_components x dimensions, specifying the updated means.

      - new_chols – tf.Tensor a three-dimensional tensor of shape current_number_of_components x dimensions x dimensions, specifying the updated Cholesky matrix.

  replace_weights(new_log_weights: Tensor)

    Overwrites the component log(weights). This method will take care of normalization.

    Parameters:

      new_log_weights – tf.Tensor a one-dimensional tensor of size num_components, containing the new log(weights)

  sample(num_samples: int) → [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>]

    Draw samples from this GMM, also returns for every sample, the index of the component that was used for sampling it.

    Parameters:

      num_samples – int The number of samples to be drawn

    Returns:

      drawn_samples - a two-dimensional tensor of shape num_samples x num_dimensions, containing the drawn samples.

      component_indices - a one-dimensional tensor of int, containing the component indices.

    Return type:

      tuple(tf.Tensor, tf.Tensor)

  sample_categorical(num_samples: int) → Tensor

    Sample components according to the weights

    Parameters:

      num_samples – int The number of components to be drawn

    Returns:

      a one-dimensional tensor of int, containing the component indices.

    Return type:

      tf.Tensor

  sample_from_component(index: int, num_samples: int) → Tensor

    draw samples from the specified components

    Parameters:

      - index – int The index of the component from which we want to sample.

      - num_samples – int The number of samples to be drawn.

    Returns:

      The drawn samples, tensor of size num_samples x dimensions.

    Return type:

      tf.Tensor

  sample_from_components(samples_per_component: Tensor) → Tensor

    Draws from each component the corresponding number of samples (provided as a one-dimensional tensor).

    Parameters:

      samples_per_component – tf.Tensor a one-dimensional tensor of size number_of_component, containint for each component the number of samples to be drawn.

    Returns:

      a tensor of shape sum(samples_per_component) x num_dimensions containing the samples (shuffled).

    Return type:

      tf.Tensor

  sample_from_components_no_shuffle(samples_per_component: Tensor) → [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>]

    Draws from each component the corresponding number of samples (provided as a one-dimensional tensor). Similar to `sample_from_components`, but the returned samples are not shuffled.

    Parameters:

      samples_per_component – tf.Tensor a one-dimensional tensor of size number_of_component, containint for each component the number of samples to be drawn.

    Returns:

      a tensor of shape sum(samples_per_component) x num_dimensions containing the samples (not shuffled).

    Return type:

      tf.Tensor

  property weights: Tensor

    Returns: tf.Tensor: a one-dimensional tensor of size num_components, containing the component weights.

class gmmvi.models.full_cov_gmm.FullCovGMM(weights: Tensor, means: Tensor, covs: Tensor)

  A Gaussian mixture model with full covariance matrices.

  Parameters:

    - weights – tf.Tensor a one-dimensional tensor containing the initial weights of the GMM.

    - means – tf.Tensor a two-dimensional tensor containing the component means.

    - covs – tf.Tensor a three-dimensional tensor containing the component covariance matrices.

  add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)

    Add a component to the mixture model. The weights will be automatically normalized.

    Parameters:

      - initial_weight – tf.Tensor The weight of the new component (before re-normalization)

      - initial_mean – tf.Tensor The mean of the new component

      - initial_cov – tf.Tensor The covariance matrix of the new component

  component_log_densities(samples: Tensor) → Tensor

    Evaluate the log densities for each mixture component on the given samples.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

    Return type:

      tf.Tensor

  component_log_density(index: int, samples: Tensor) → Tensor

    Use the specified component to evaluate the Gaussian log-density at the given samples.

    Parameters:

      - index – int The index of the component of which we want to compute the log densities.

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a one-dimensional tensor of size number_of_samples, containing the log-densities.

    Return type:

      tf.Tensor

  component_marginal_log_densities(samples: Tensor, dim: int) → Tensor

    Evaluate the marginal log densities for each mixture component along the given dimension for each sample.

    Parameters:

      - samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate. Note that for providing an easier interface, each sample has the number of dimensions compatible with this GMM, although only a single entry is actually used for evaluating the marginal density.

      - dimension – int The dimension of interest.

    Returns:

      a two-dimensional tensor of size number_of_components x number_of_samples, containing the marginal log-densities for each component.

    Return type:

      tf.Tensor

  property covs: Tensor

    Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

  gaussian_entropy(chol: Tensor) → Tensor

    Computes the entropy of Gaussian distribution with the given Cholesky matrix.

    Parameters:

      chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

    Returns:

      The entropy

    Return type:

      tf.float32

  sample_from_component(index: int, num_samples: int) → Tensor

    draw samples from the specified components

    Parameters:

      - index – int The index of the component from which we want to sample.

      - num_samples – int The number of samples to be drawn.

    Returns:

      The drawn samples, tensor of size num_samples x dimensions.

    Return type:

      tf.Tensor

class gmmvi.models.diagonal_gmm.DiagonalGMM(weights: Tensor, means: Tensor, covs: Tensor)

  A Gaussian mixture model with diagonal covariance matrices.

  Parameters:

    - weights – tf.Tensor a one-dimensional tensor containing the initial weights of the GMM.

    - means – tf.Tensor a two-dimensional tensor containing the component means.

    - covs – tf.Tensor a two-dimensional tensor containing the diagonal entries of the component covariances.

  add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)

    Add a component to the mixture model. The weights will be automatically normalized.

    Parameters:

      - initial_weight – tf.Tensor The weight of the new component (before re-normalization)

      - initial_mean – tf.Tensor The mean of the new component

      - initial_cov – tf.Tensor The covariance matrix of the new component

  component_log_densities(samples: Tensor) → Tensor

    Evaluate the log densities for each mixture component on the given samples.

    Parameters:

      samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

    Returns:

      a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

    Return type:

      tf.Tensor

  property covs: Tensor

    Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

  static diagonal_gaussian_log_pdf(dim: int, mean: Tensor, chol: Tensor, x: Tensor) → Tensor
  gaussian_entropy(chol: Tensor) → Tensor

    Computes the entropy of Gaussian distribution with the given Cholesky matrix.

    Parameters:

      chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

    Returns:

      The entropy

    Return type:

      tf.float32

  sample_from_component(index: int, num_samples: int) → Tensor

    draw samples from the specified components

    Parameters:

      - index – int The index of the component from which we want to sample.

      - num_samples – int The number of samples to be drawn.

    Returns:

      The drawn samples, tensor of size num_samples x dimensions.

    Return type:

      tf.Tensor

class gmmvi.models.gmm_wrapper.GmmWrapper(model: GMM, initial_stepsize: float, initial_regularizer: float, max_reward_history_length: int)

  This method wraps around the `model` to keep track of component-specific meta-information used by the learner (e.g. component-specific stepsizes). This class can be used just like a `model`, because any methods not implemented within the GmmWrapper are forwarded to the encapuslated model. However, some functions have slightly different behavior, for example, when removing a component, not only the component in the encapuslated model will be removed, but also the meta-information, stored in this GmmWrapper. Hence, the model should always be accessed through the GmmWrapper.

  Whenever adding a new component (via py:meth:gmmvi.models.gmm.GmmWrapper.add_component), the GmmWrapper will initialize the meta-information (stepsize and l2-regularizer) with the provided initial_values.

  Parameters:

    - model – `gmmvi.models.gmm.GMM` The model to be encapuslated.

    - initial_stepsize – float The stepsize, that is assigned to a newly added component

    - initial_regularizer – float The l2 regularizer, that is assigned to a newly added component (only used when using a py:class:MoreNgEstimator<gmmvi.optimization.gmmvi_modules.ng_estimator.MoreNgEstimator> for estimating the natural gradients).

    - max_reward_history_length – int The GmmWrapper also keeps track how much reward each component obtained at the previous iterations. This parameter controls after how many iterations the component rewards are forgotten (to save memory).

  add_component(initial_weight: tf.float32, initial_mean: Tensor, initial_cov: Tensor, adding_threshold: Tensor, initial_entropy: Tensor)

    Adds a new component to the encapuslated model (see `GMM`, but also stores / intializes meta-information.

    Parameters:

      - initial_weight – tf.Tensor The weight of the new component (before re-normalization)

      - initial_mean – tf.Tensor The mean of the new component

      - initial_cov – tf.Tensor The covariance matrix of the new component

      - adding_threshold – tf.Tensor The threshold used by `VipsComponentAdaptation`, stored for debugging.

      - initial_entropy – tf.Tensor The initial entropy of the new component (can be computed from initial_cov).

  static build_from_config(model: GMM, config: dict)

    Create a `GmmWrapper` instance from a configuration dictionary.

    This static method provides a convenient way to create a `GmmWrapper` instance, based on an initial `GMM`, and a dictionary containing the parameters.

    Parameters:

      - config – dict The dictionary is typically read from YAML a file, and holds all hyperparameters. The max_reward_history_length, which is needed for instantiating the `GmmWrapper` is typically not provided directly, but chosen depending on whether `VipsComponentAdaptation` is used or not.

      - model – `GMM` The model that we want to encapsulate.

  remove_component(idx: int)

    Deletes the given component in the encapuslated model (see `GMM`), but also deletes the corresponding meta-information.

    Parameters:

      idx – int The idx of the component to be removed.

  replace_weights(new_log_weights: Tensor)

    Overwrites the weights of the encapuslated model, see (see `GMM`), but also keeps track of each component’s weight from previous iterations.

    Parameters:

      new_log_weights – tf.Tensor A one dimensional tensor of size number_of_components, containing the log of the new weight for each component.

  store_rewards(rewards: Tensor)

    Store the provided reward of each component.

    Parameters:

      - rewards – tf.Tensor

      - number_of_components (A one dimensional tensor of size) –

      - component (containing the reward for each) –

  update_stepsizes(new_stepsizes: Tensor)

    This method updates the stepsize for each component.

    Parameters:

      - new_stepsizes – tf.Tensor

      - number_of_components (A one dimensional tensor of size) –

      - component (containing the new stepsize for each) –