geobed.core#
Base classes for Bayesian experimental design methods.
The class BED_base defines the base class for Bayesian experimental design methods. This class can not be used directly. Instead, it is inherited by the other classes in this module. All other classes in this module inherit from this class and therefore have access to all its methods.
Classes#
Defines the base class for Bayesian experimental design methods. |
|
Defines the base class for Bayesian experimental design methods that do not have nuisance parameters. |
|
Defines the base class for Bayesian experimental design methods that have nuisance parameters. |
Descriptions#
- class geobed.core.BED_base(m_prior_dist)#
Defines the base class for Bayesian experimental design methods.
- get_m_prior_entropy()#
Returns the entropy of the model parameter prior distribution.
Entropy will be calculated analytically if possible. If not, it will be calculated numerically. If neither is possible, the entropy will be set to zero, which will have no effect on the design optimisation.
- Returns
The entropy of the model parameter prior distribution.
- Return type
- get_m_prior_samples(sample_shape=1, random_seed=None)#
Returns samples from the model parameter prior distribution.
- Parameters
sample_shape (Union[int, tuple]) – The number of samples to return. If an integer is provided, the shape is (sample_shape, dim_model_parameters). If a tuple is provided, the shape is (sample_shape, dim_model_parameters). Defaults to 1.
random_seed (Optional[int]) – The random seed to use for sampling from the prior distribution. Defaults to None.
- Returns
Samples from the model parameter prior distribution.
- Return type
- calculate_EIG(design, eig_method, eig_method_kwargs, filename=None, num_workers=1, parallel_library='joblib', random_seed=None, progress_bar=True)#
- Returns the expected information gain (EIG) for a design or a list of designs. The EIG is calculated using the method specified by eig_method. The method must be one of the following:
‘nmc’: Nested Monte Carlo (
geobed.eig.nmc)‘dn’: DN-Method (
geobed.eig.dn)‘laplace’: Laplace approximation (
geobed.eig.laplace)‘variational_marginal’: Variational marginal (
geobed.eig.variational_marginal)‘variational_marginal_likelihood’: Variational marginal likelihood (
geobed.eig.variational_marginal_likelihood)‘variational_posterior’: Variational posterior (
geobed.eig.variational_posterior)‘minebed’: Mutual information neural estimator (
geobed.eig.minebed)‘nce’: Noise contrastive estimation mutual information estimator (
geobed.eig.nce)‘flo’: Fenchel-Legendre Optimization mutual information estimator (
geobed.eig.flo)
For more information on the methods, see the documentation of the methods in the
geobed.eigmodule.- Parameters
design (Tensor) – A tensor of shape (design_dim) describing a single design or a tensor of shape (n_designs, design_dim) describing a list of designs.
eig_method (str) – The method used to calculate the EIG. Must be one of the methods listed above.
eig_method_kwargs (dict) – A dictionary of keyword arguments passed to the EIG method.
filename (Optional[str]) – The filename of a file to save the results to. If the file exists, the results are loaded from the file. If the file does not exist, the results are calculated and saved to the file. Defaults to None.
num_workers (int) – The number of workers to use for parallelisation. Defaults to 1.
parallel_library (str) – The parallel library to use. Must be either ‘mpire’ or ‘joblib’. Defaults to ‘joblib’.
random_seed (Optional[int]) – The random seed to use for sampling from the model and nuisance parameter prior distributions as well as the data noise distribution. Defaults to None.
progress_bar (bool) – If True, a progress bar is shown. Defaults to True.
- class geobed.core.BED_base_explicit(m_prior_dist, data_likelihood_func)#
Defines the base class for Bayesian experimental design methods that do not have nuisance parameters. This is the classic case of Bayesian experimental design.
The data likelihood is assumed to be a function of the model parameters and the experimental design only. The data likelihood is function takes two arguments: the model parameters and the experimental design. The model parameters are assumed to be a tensor of shape (n_model_samples, dim_model_parameters). The experimental design is assumed to be a tensor of shape (design_dim). The data likelihood function returns a
torch.distributions.Distributionobject. The data likelihood function must be provided as an argument to the constructor of the class.The model parameter prior distribution is assumed to be a
torch.distributions.Distributionobject. The model parameter prior distribution needs to return samples of shape (n_model_samples, dim_model_parameters). The model parameter prior distribution is assumed to be provided as an argument to the constructor of the class. Be carefull when using one dimensional :torch.distributions.Distribution` objects such as :torch.distributions.Normal` or :torch.distributions.Uniform`. Use :torch.distributions.Independent` if necessary to make sure that the samples are of shape (n_model_samples, dim_model_parameters).- get_data_likelihood(design, n_model_samples=1, random_seed_model=None)#
Samples model parameters from the model prior distribution and return the data likelihood at the design and the sampled parameters.
- Parameters
design (Tensor) – Tensor describing the experimental design at which the data likelihood is evaluated.
n_model_samples (int) – Number of model parameter samples to return. Defaults to 1.
random_seed_model (Optional[int]) – Random seed to use for sampling from the model parameter prior distribution. Defaults to None.
- Returns
Returns a distribution of data samples.
- Return type
- get_data_likelihood_samples(design, n_model_samples=1, n_likelihood_samples=1, random_seed_model=None, random_seed_likelihood=None)#
Samples model parameters from their prior distribution, evaluates the data likelihood at the design and the sampled model parameters and returns samples from the data likelihood distribution.
- Parameters
design (Tensor) – Tensor describing the experimental design at which the data likelihood is evaluated.
n_model_samples (int) – Number of model parameter samples to return. Defaults to 1.
n_likelihood_samples (int) – Number of samples to return from the data likelihood distribution. Defaults to 1.
random_seed_model (Optional[int]) – Random seed to use for sampling from the model parameter prior distribution. Defaults to None.
random_seed_likelihood (Optional[int]) – Random seed to use for sampling from the data likelihood distribution. Defaults to None.
- Returns
Returns a tensor of data samples of shape (n_likelihood_samples, n_model_samples, dim_data_samples).
- Return type
- class geobed.core.BED_base_nuisance(m_prior_dist, nuisance_dist, data_likelihood_func)#
Defines the base class for Bayesian experimental design methods that have nuisance parameters. This is the case when the data likelihood is a function of the nuisance parameters, the model parameters, and the experimental design. The data likelihood is function takes three arguments: the experimental design, the model parameters and the nuisance parameters. The model parameters are assumed to be a tensor of shape (n_model_samples, dim_model_parameters). The nuisance parameters are assumed to be a tensor of shape (n_nuisance_samples, n_model_samples, dim_nuisance_parameters). The experimental design is assumed to be a tensor of shape (design_dim). The data likelihood function returns a
torch.distributions.Distributionobject. The data likelihood function must be provided as an argument to the constructor of the class.The model parameter prior distribution is assumed to be a
torch.distributions.Distributionobject. The model parameter prior distribution needs to return samples of shape (n_model_samples, dim_model_parameters). The model parameter prior distribution is assumed to be provided as an argument to the constructor of the class. Be carefull when using one dimensional :torch.distributions.Distribution` objects such as :torch.distributions.Normal` or :torch.distributions.Uniform`. Use :torch.distributions.Independent` if necessary to make sure that the samples are of shape (n_model_samples, dim_model_parameters).The nuisance parameter prior distribution can be either a
torch.distributions.Distributionobject or a function that takes the model parameters as an argument and returns atorch.distributions.Distributionobject. The nuisance parameter prior distribution needs to return samples of shape (n_nuisance_samples, n_model_samples, dim_nuisance_parameters). If the nuisance parameter distribution is independent of the model parameters, it is recommended to use atorch.distributions.Distributionobject, since the provided distribution will automatically be expanded to return samples of shape (n_nuisance_samples, n_model_samples, dim_nuisance_parameters).- Parameters
m_prior_dist (Union[Distribution, Tensor]) – The prior distribution of the model parameters. Must be a
torch.distributions.Distributionobject.nuisance_dist (Union[Distribution, callable, Tensor]) – The prior distribution of the nuisance parameters. Must be a
torch.distributions.Distributionobject or a function that takes the model parameters as an argument and returns atorch.distributions.Distributionobject.data_likelihood_func (callable) – The data likelihood function. Must be a function that takes three arguments: the experimental design, the model parameters and the nuisance parameters. The model parameters are assumed to be a tensor of shape (n_nuisance_samples, n_model_samples, dim_model_parameters). The nuisance parameters are assumed to be a tensor of shape (n_nuisance_samples, n_model_samples, dim_nuisance_parameters). The experimental design is assumed to be a tensor of shape (design_dim). The data likelihood function returns a
torch.distributions.Distributionobject.
- get_nuisance_samples(model_samples, n_nuisance_samples=1, random_seed=None)#
Samples nuisance parameters from their prior distribution.
- Parameters
model_samples (Tensor) – Tensor of model parameter samples of shape (n_model_samples, dim_model_parameters).
n_nuisance_samples (int) – Number of nuisance parameter samples to return. Defaults to 1.
random_seed_nuisance – Random seed to use for sampling from the nuisance parameter prior distribution. Defaults to None.
- Returns
Returns a tensor of nuisance parameter samples of shape (n_nuisance_samples, n_model_samples, dim_nuisance_parameters).
- Return type
- get_data_likelihood(design, n_model_samples=1, n_nuisance_samples=1, random_seed_model=None, random_seed_nuisance=None)#
Samples model and nuisance parameters from their prior distributions and evaluates the data likelihood at the design and the sampled parameters.
- Parameters
design (Tensor) – Tensor describing the experimental design at which the data likelihood is evaluated.
n_model_samples (int) – Number of model parameter samples to return. Defaults to 1.
n_nuisance_samples (int) – Number of nuisance parameter samples to return. Defaults to 1.
random_seed_model (Optional[int]) – Random seed to use for sampling from the model parameter prior distribution. Defaults to None.
random_seed_nuisance (Optional[int]) – Random seed to use for sampling from the nuisance parameter prior distribution. Defaults to None.
- Returns
Returns a distribution of data samples.
- Return type
- get_data_likelihood_samples(design, n_model_samples=1, n_nuisance_samples=1, n_likelihood_samples=1, random_seed_model=None, random_seed_nuisance=None, random_seed_likelihood=None)#
Samples model and nuisance parameters from their prior distributions, evaluates the data likelihood at the design and the sampled parameters and returns samples from the data likelihood distribution.
- Parameters
design (Tensor) – Tensor describing the experimental design at which the data likelihood is evaluated.
n_model_samples (int) – Number of model parameter samples to return. Defaults to 1.
n_nuisance_samples (int) – Number of nuisance parameter samples to return. Defaults to 1.
n_likelihood_samples (int) – Number of samples to return from the data likelihood distribution. Defaults to 1.
random_seed_model (Optional[int]) – Random seed to use for sampling from the model parameter prior distribution. Defaults to None.
random_seed_nuisance (Optional[int]) – Random seed to use for sampling from the nuisance parameter prior distribution. Defaults to None.
random_seed_likelihood (Optional[int]) – Random seed to use for sampling from the data likelihood distribution. Defaults to None.
- Returns
Returns a tensor of data samples of shape (n_likelihood_samples, n_model_samples, n_nuisance_samples, dim_data_samples).
- Return type