Gaussian Error Models#

Standard Gaussian Error Models with Binary Design#

This module implements the most basic form of a Gaussian error model with support for binary design. The role of a binary design is to activate/deactivate entries (dimensions) of the random variable (probability space) modeled by the Gaussian error model implemented here.

The Gaussian error model here is defined as follows:

\[x \sim \mathcal{N}(\mu, \mathbf{D} \mathbf{\Sigma} \mathbf{D} ),\]

where \(x\) is a normally distributed random vector with mean \(\mu\) and covariance matrix \(\mathbf{\Sigma}\). The matrix \(\mathbf{D}\) is a diagonal (square) matrix with a binary design vector \(\mathbf{\zeta}\) on its diagonal. An entry in \(\mathbf{\zeta}\) set to 1 corresponds to an active entry, and an entry set to 0 corresponds to an inactive (degenerate) entry that is eliminated from calculations.

class GaussianErrorModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None)[source]#

Bases: ErrorModelConfigs

Configuration settings for Gaussian error models.

Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • design (None | bool | Sequence[bool] | ndarray) –

    an experimental design to define active/inactive entries of the random variable (mean, variance/covariance matrix).

    Note

    • If the design is None, it is set to all ones; that is everything is observed (default)

    • If the design is a binary vector ( or int dtype attributes with 0/1 entries) the mean, the covariance, and all random vectors are projected onto the space identified by the 1/True entries.

  • size (int | None) – dimension of the error model space. Detected from mean if None.

  • mean (float | ndarray) – mean of the error model

  • variance (float | ndarray | spmatrix) – variance/covariance of the error model

  • sparse (bool) – convert covariance to scipy.csc_matrix used if size > 1

  • random_seed (int | None) – random seed used when the Gaussian model is initiated. This is useful for reproductivity.

size: int | None#
mean: float | ndarray#
variance: float | ndarray | spmatrix#
sparse: bool#
random_seed: int | None#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None)#
class GaussianErrorModel(configs=None)[source]#

Bases: ErrorModel, RandomNumberGenerationMixin

A simple Numpy-based (or scipy sparse) Gaussian error model. In addition to standard functionality, here we provide a specific attribute ‘design’ which enables modifying the space of the error model by projection or reweighting.

Note

This version does not support non-binary designs. For non-bianry (relaxed) design, consider PointwiseWeightedGaussianErrorModel or PrePostWeightedGaussianErrorModel.

Note

If mean, or variance is scalar, the size is inferred from size or from the argument with larger size, as long as there is no contradiction, otherwise an AssertionError is raised.

Note

This model creates lazy objects under the hood. These are lazy in the sense that they are constructed/calculated only when they are needed, and are kept in memory unless the design changes. These objects are accessible through the following properties:

  1. stdev: this refers to a lazy evaluation of the lower Cholesky factor of the covariance matrix.

  2. stdev_inv: this refers to a lazy evaluation of the inverse of the lower Cholesky factor of the covariance matrix.

  3. stdev_logdet: this refers to a lazy evaluation of the logarithm of the the determinant (logdet) of the lower Cholesky factor of the covariance matrix (used for normalizing the PDF valued/gradient when/if needed).

Note

We use the fact that the logdet of the covariance matrix is obtained from the the Cholesky factorization as follows

\[logdet (C) = log (det(L L^T)) = log (det(L) det(L^T)) = logdet(L) + logdet (L^T) ,\]

Thus, \(0.5 logdet(C) = logdet(L)\), a fact used in calculating the (normalized) PDF, etc.

Parameters:

configs (GaussianErrorModelConfigs | dict | None) – an object containing configurations of the error model

Raises:
__init__(configs=None)[source]#

Initialize the random number generator

standardize_configurations(configs, mean_dtype=<class 'float'>, variance_dtype=<class 'float'>, design_dtype=<class 'bool'>)[source]#

Check the configurations of the error model (size, mean, design, and variance), and make sure they are consistent.

Note

Here are the rules:

  1. If the size is passed, the mean and the design must be one-dimensional arrays/vectors of this size (if either is scalar, they are casted to vectors), and the variance’s size/shape is asserted accordingly.

  2. If the size is not passed, it is inferred from mean and/or variance

Raises:

PyOEDConfigsValidationError – if the validation of the configurations fail

validate_configurations(configs, raise_for_invalid=False)[source]#

Validate the passed configurations for the Gaussian error model

Parameters:

  • configs (dict | GaussianErrorModelConfigs) – configurations to validate. If a configs dataclass is passed validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

  • raise_for_invalid (bool) – raise an exception if the configurations are invalid

Returns:

True if the configurations are valid, otherwise False

Raises:
update_configurations(**kwargs)[source]#

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

TypeError – if any of the passed keys in kwargs is invalid/unrecognized

generate_white_noise(ignore_design=False, truncate=False)[source]#
Generate a standard normal random vector of size size with values truncated

at -/+3 if truncate is set to True

Parameters:

  • ignore_design (bool) – the size of the white noise vector is in the full (ignore the design) if True, otherwise the size matches the dimension of the active subspace.

  • truncate (bool) – if True, truncate the samples at -/+3, that is any sample point/entry above 3 is set to 3, and any value below -3 is set to -3.

Returns:

numpy array (even if the dimension is 1) containing white noise

generate_noise()[source]#

Generate a random noise vector sampled from the underlying Gaussian distribution

sample()[source]#

Sample a random vector from the underlying Gaussian distribution

pdf(x, normalize=False, log=False)[source]#

Evaluate the value of the density function (normalized or upto a fixed scaling constant) at the passed state/vector.

Parameters:

  • x – realization of the random variable

  • normalize (bool) – scale the PDF by the normalization factor

  • log (bool) – if True, evaluate the gradient of the logarithm of the PDF

Returns:

the value of the density function evaluated at the passed state/vector.

log_density(x, normalize=False)[source]#

Evaluate the logarithm of the density function at the passed state x.

Parameters:

  • x – realization of the random variable

  • normalize (bool) – scale the PDF by the normalization factor

Returns:

the logarithm of the density function evaluated at the passed state.

pdf_gradient(x, normalize=False, log=False, in_place=False)[source]#

Evaluate the gradient of the density function at the passed state/vector.

Parameters:

  • x – realization of the random variable

  • normalize (bool) – scale the PDF by the normalization factor

  • log (bool) – if True, evaluate the gradient of the logarithm of the PDF

Returns:

the value of the density function evaluated at the passed state/vector.

log_density_gradient(x, normalize=False, in_place=False)[source]#

Evaluate the gradient of the logarithm of the density function at the passed state x.

Parameters:

  • x – realization of the random variable

  • normalize (bool) – scale the PDF by the normalization factor

Note

The derivative of the log of the normalization factor vanishes; thus, normalize takes no effect here. Just added for unification

Returns:

the gradient of the logarithm of the density function evaluated at the passed state.

add_noise(x, in_place=False)[source]#

Add random noise to the passed vector x

Parameters:

  • x – vector in a space of dimension equal to size of the underlying error model

  • in_place (bool) – overwrite the passed vector x (if True). If set to False, a new instance (based on the distribution size) is created and returned. This is ignored of course if x is a non-iterable, i.e., a scalar.

Raises:

TypeError – if x is of the wrong shape or type

covariance_matvec(x, in_place=False)[source]#

Evaluate and return the product of covariance matrix by a vector x. The product is determined by applying the cholesky decomposition of the covariance matrix twice (dot product) to the passed state x

Parameters:

  • x – vector in a space of dimension equal to the size of the underlying error model. x could be scalar or number array, however, it must match the distribution size.

  • in_place (bool) – overwrite the passed vector x (if True). If set to False, a new instance (based on the distribution size) is created and returned. This is ignored of course if x is a non-iterable, i.e., a scalar.

Returns:

the product of the covariance matrix by x

unweighted_covariance_matrix()[source]#

Construct a numpy array representation of the covariance matrix discarding any design effect

unweighted_precision_matrix()[source]#

Construct a numpy array representation of the precision matrix discarding any design effect

covariance_inv_matvec(x, in_place=False)[source]#

Evaluate and return the product of inverse of the error covariance matrix by a vector x. The inverse of the lower Cholesky factor is used

Parameters:

  • x – vector in a space of dimension equal to the size of the underlying error model. x could be scalar or number array, however, it must match the distribution size.

  • in_place (bool) – overwrite the passed vector x (if True). If set to False, a new instance (based on the distribution size) is created and returned. This is ignored of course if x is a non-iterable, i.e., a scalar.

Returns:

the product of inverse of the error covariance matrix by x

covariance_sqrt_matvec(x, lower=True, in_place=False)[source]#

Evaluate and return the product of Square root (Lower Cholesky) covariance matrix by a vector x. The product is determined by applying the cholesky decomposition of the covariance matrix once (dot product) to the passed state x This metho is tricky. See remarks below to understand how it works.

Note

This function multiples the Cholesky factor (lower or upper/lower-transpose) by a vector. The covariance matrix is weighted based on the underlying design. When the design has some zero entries (rows/columns of the covariance are eliminated), the dimension of the model reduces. Let us assume the full space has size \(n\) and the design is all ones, then the covariance matrix is \(C:=LL^T\) where \(L\) is the lower Cholesky factor of size \(n\times n\). Thus, applying the lower Cholesky factor (matvec-product) takes a vector in the full space (size \(n\)) and returns a vector of the same size. However, when the design has zeros the output of the lower Cholesky matvec product is a vector of size equal to the number of active entries. Similar analogy is followed for multiplying the Upper Cholesky factor \(L^T\). In all cases, when lower is True, the input must reside in the full observation space, otherwise, the Cholesky factor is no longer valid and must be recalculated in the reduced space for the projected covariance.

Parameters:

  • x – vector in a space of dimension equal to the size of the underlying error model. x` could be scalar or number array, however, it must match the distribution size.

  • lower (bool) – use the lower Cholesky as the square root

  • in_place (bool) – overwrite the passed vector x (if True). If set to False, a new instance (based on the distribution size) is created and returned. This is ignored of course if x is a non-iterable, i.e., a scalar.

Returns:

the product of the sqrt-covariance matrix by x:

  • when lower==True, the output is in the space of active sensors. The input can be either in the full space or the space of active sensors if in_place==False, however it must be in the reduced space if in_place==True otherwise a ValueError is raised.

  • when lower==False, the output is in the full space. The input must be in the space of active sensors and in_place must be set to False otherwise a ValueError is raised.

covariance_sqrt_inv_matvec(x, lower=True, in_place=False)[source]#

Evaluate and return the product of inverse of the square root of the error covariance matrix by a vector x. A linear system is solved using the cholesky decomposition of the covariance matrix

Parameters:

  • x – vector in a space of dimension equal to the size of the underlying error model. x could be scalar or number array, however, it must match the distribution size.

  • lower (bool) – use the lower Cholesky as the square root

  • in_place (bool) – overwrite the passed vector x (if True). If set to False, a new instance (based on the distribution size) is created and returned. This is ignored of course if x is a non-iterable, i.e., a scalar.

Returns:

the product of inverse of the square root of the error covariance matrix by x

covariance_matrix()[source]#

Construct a numpy array representation (if the dimension is more than 1) of the underlying covariance matrix. (projected onto the observation space)

precision_matrix()[source]#

Construct a numpy array representation (if the dimension is more than 1) of the precision matrix (inverse of the underlying covariance matrix).

covariance_diagonal()[source]#

Return a copy the diagonal of the covariance matrix, i.e., the variances

Returns:

1D numpy array holding the diagonal of the underlying covariance matrix. If the size of the underlying distribution is 1, this returns a scalar (variance)

variance()[source]#

Same as covariance_diagonal()

covariance_trace(method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', random_seed=None, accuracy=0.01)[source]#

Evaluate/Approximate the trace of the covariance matrix

Note

This is a wrapper around the utility function pyoed.utility.math.matrix_trace that is called with the method covariance_matvec() as the operator to compute the trace of.

Parameters:

  • method – Method of evaluation. If “exact”, we simply sum the diagonal of A. If “randomized”, a Hutchinson style trace estimator, as described in pyoed.utility.trace_estimator(), is employed. All of the futher keyword arguments are in the case of method=”randomized” and are otherwise ignored if method=”exact”.

  • randomization_vectors – The randomization vectors drawn to perform the computation. If not passed, they will be sampled.

  • sample_size (int) – The number of samples to use. :param optimize_sample_size: if True, sample_size is replaced with an optimized version, where the optimal sample size minimizes the variance of the estimator and is between min_sample_size, and max_sample_size.

  • min_sample_size (int) – Minimum number of random samples.

  • max_sample_size (int) – Maximum number of random samples.

  • distribution (str) – The probability distribution used for random sampling. Both ‘Rademacher’ and ‘Gaussian’ are supported.

  • random_seed (None | int) – The random seed to use for the distribution samples.

  • accuracy (float) – convergence criterion.

Returns:

exact/approximate value of the trace of the covariance matrix. of the underlying model.

Return type:

float

covariance_logdet(method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', random_seed=None, accuracy=0.01)[source]#

Evaluate/approximate the logarithm of the determinant of the covariance matrix of the passed error model

Note

This is a wrapper around the utility function pyoed.utility.math.matrix_logdet that is called with the method covariance_matvec() as the operator to compute the trace of.

Parameters:

  • method – Method of evaluation. If “exact”, we simply sum the diagonal of A. If “randomized”, a chebyshev-approximation type-method is employed from pyoed.utility.logdet_estimator(). All of the futher keyword arguments are in the case of method=”randomized” and are otherwise ignored if method=”exact”.

  • randomization_vectors – The randomization vectors drawn to perform the computation. If not passed, they will be sampled.

  • sample_size (int) – The number of samples to use. :param optimize_sample_size: if True, sample_size is replaced with an optimized version, where the optimal sample size minimizes the variance of the estimator and is between min_sample_size, and max_sample_size.

  • min_sample_size (int) – Minimum number of random samples.

  • max_sample_size (int) – Maximum number of random samples.

  • distribution (str) – The probability distribution used for random sampling. Both ‘Rademacher’ and ‘Gaussian’ are supported.

  • random_seed (None | int) – The random seed to use for the distribution samples.

  • accuracy (float) – convergence criterion.

Returns:

exact/approximate value of the logdet of the covariance matrix of the underlying model.

Return type:

float

update_design(design)[source]#

Update the experimental design and related values (local covariance, etc.)

Parameters:

design – the design to be used update model’s configurations

Raises:

PyOEDConfigsValidationError – if the passed design is of invalid type/shape/size

update_mean(mean)[source]#

Update the mean of the error model (in the full space) regardless the design dimensionalty

Parameters:

mean – the mean to be used update model’s configurations

Raises:

PyOEDConfigsValidationError – if the passed mean is of invalid type/shape/size

update_covariance_matrix(variance)[source]#

Update the covariance matrix (and the square root) in the full space, regardless the design

Parameters:

variance – covariance matrix (or its square root) to be used in the error model

apply_weighting_matrix(variance, design=None)[source]#

Apply the weighting matrix (binary activation/deactivation) of the elements in variance. Is expected to be of dimension (design.size, design.size ). Rows/columns in variance corresponding to 0 in design are zero’d out. If variance has dimension equal to active entries only in design, nothing is done, and variance is returned as is.

Parameters:

  • variance – the variance covariance matrix

  • design – an experimental design used to calculate the weights. This is only added for flexibility. If None, the internal/current deesign is used.

Returns:

variance with inactive entries in design or registered design set to ‘0’

property sparse#

True if the covariance data structure is constructed using scipy.spmatrix)

property size#

Dimension of the underlying probability distribution

property design#

Get a copy of the design vector

property active#

Flags (boolean 1d array-like) corresponding to active/inactive dimensions according to the experimental design. This vector is of exactly the same size as the observation vector (ignoring the experimental design).

property active_indexes#

An array of the indexes of the observation vector that is active (associated with non-zero design) according to the experimental design.

property active_size#

Dimension of the probability distribution projected onto the design space (only active/nonzero entries of the design)

property mean#

Get a copy of the distribution mean

property stdev#

Construct and return the lower Cholesky factor (if not available) in the projected space (after applying the design) of the covariance matrix

property stdev_inv#

Construct and return the inverse of the lower Cholesky factor (if not available) of the covariance matrix in the projected space (after applying the design)

property stdev_logdet#

Evaluate the log-det (logarithm of the determinant) of the lower Cholesky factor (if not available) of the covariance matrix. This is carried out in the projection (active) design space if PYOED is configured to carry out opereations in the projected space (default). See self.project_onto_active_design_space().

Note

We use the fact that the determinant is the product of the diagonal elements of the lower Cholesky factor. Thus, the log-det is the sum of log of diagonal elements.

Gaussian Error Models with Pre-Post-Weighted Design#

This module implements weighted versions of Gaussian error model with support for binary as well as relaxed (non-binary) design. The role of a design is to activate/deactivate entries (dimensions) if it is binary, however, if it is relaxed, the design applies some weights to the entries of the covariance (and the precision) matrix based on the formulation approach taken.

The approach taken here is pre-post multiplication. This means either the covariance matrix (or its inverse) is multiplied (pre -> from left, and post -> from right) by a diagonal matrix with the design vector (relaxed) on its main diagonal.

Note

This is reduces to the functionality provided by GaussianErrorModel only when the design is binary, and when the covariance is pre-post multiplied.

Warning

The functionality here is provided for testing widely used approaches in the literature of optimal experimental design. We have shown, however, that pre-post multiplication of either the covariance matrix or its inverse by relaxed design is generally wrong if the covariance matrix is non-diagonal, that is if there are correlations in the error model. To apply proper weighting for relaxed (non-binary) designs, use the functionality provided by PointwiseWeightedGaussianErrorModel instead of using PrePostWeightedGaussianErrorModel. For details, on why pre-post multiplication is incorrect, see:

  1. Ahmed Attia, and Emil Constantinescu. “Optimal experimental design for inverse problems in the presence of observation correlations.” SIAM Journal on Scientific Computing 44, no. 4 (2022): A2808-A2842.

class PrePostWeightedGaussianErrorModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None, design_weighting_scheme='covariance')[source]#

Bases: GaussianErrorModelConfigs

Configuration settings for PrePostWeightedGaussianErrorModel. These are exactly the same as the configurations of the parent class

Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • design (None | bool | Sequence[bool] | ndarray) –

    an experimental design to define active/inactive entries of the random variable (mean, variance/covariance matrix).

    Note

    • If the design is None, it is set to all ones; that is everything is observed (default)

    • If the design is a binary vector ( or int dtype attributes with 0/1 entries) the mean, the covariance, and all random vectors are projected onto the space identified by the 1/True entries.

  • size (int | None) – dimension of the error model space. Detected from mean if None.

  • mean (float | ndarray) – mean of the error model

  • variance (float | ndarray | spmatrix) – variance/covariance of the error model

  • sparse (bool) – convert covariance to scipy.csc_matrix used if size > 1

  • random_seed (int | None) – random seed used when the Gaussian model is initiated. This is useful for reproductivity.

  • design_weighting_scheme (str) –

    a string describing the weighting scheme; you can choose from the following options:

    • ’covariance’: the covariance matrix is pre- and post-multiplied by the design matrix defined as a diagonal matrix with the design on its diagonal.

    • ’precision’: the precision (inverse of the covariance) matrix is pre- and post-multiplied by the design matrix defined as a diagonal matrix with the design on its diagonal.

design_weighting_scheme: str#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None, design_weighting_scheme='covariance')#
class PrePostWeightedGaussianErrorModel(configs=None)[source]#

Bases: GaussianErrorModel

A simple Numpy-based (or scipy sparse) Gaussian error model with pre- and post-multiplicative design weighting. Specifically, the design (binary or relaxed) takes place by pre- and post-multiplication of the covariance or the precision matrix (based on the design_weighting_scheme in the configurations) by a diagonal matrix with the design set to its diagonal (the design matrix here).

As a clarifying example, consider the A-optimal design for linear inverse problems. In this case, the posterior covariance \(\Gamma_{\rm post}\) takes on the following forms:

  1. design_weighting_scheme==’covariance’: pre-post multiplication of the covariance matrix). The covariance of the Gaussian posterior is:

    \[\Gamma_{\rm post} = \left( \mathbf{F}^{T} \left( diag(\mathbf{d}) \Gamma_{\rm noise} diag(\mathbf{d}) \right)^{-1} \mathbf{F} + \Gamma_{\rm prior}^{-1} \right)^{-1} \,,\]

  2. design_weighting_scheme==’precision’: pre-post imultiplication of the precision matrix). The covariance of the Gaussian posterior is:

    \[\Gamma_{\rm post} = \left( \mathbf{F}^{T} diag(\mathbf{d}) \Gamma_{\rm noise}^{-1} diag(\mathbf{d}) \mathbf{F} + \Gamma_{\rm prior}^{-1} \right)^{-1} \,,\]

where \(\mathbf{F}\) is the forward model (e.g., parameter-to-observable map), \(\mathbf(d)\) is the relaxed/binary design vector, \(diag(\mathbf{d})\) is a diagonal matrix with \(\mathbf{d}\) on its main diagonal, \(\Gamma_{\rm prior}\) is the covariance matrix of the Gaussian prior, and \(\Gamma_{\rm noise}\) is the covariance matrix of the Gaussian observation noise/error model.

Thus, in this formulation/implementation, the effect of the design takes place on the covariance/precision matrix.

Note

This implementation is not accurate for correlated covariances as it creates discontinuity at the corner (binary) points. Though, we add it for comparison as it has been utilized in the past in the OED literature, and the implementation is simpler and less computationally expensive.

Parameters:

configs (PrePostWeightedGaussianErrorModelConfigs | dict | None) – an object containing configurations of the error model

Raises:
__init__(configs=None)[source]#

Initialize the random number generator

validate_configurations(configs, raise_for_invalid=False)[source]#

Validate the passed configurations for the Gaussian error model

Parameters:

  • configs (dict | PrePostWeightedGaussianErrorModelConfigs) – configurations to validate. If a configs dataclass is passed validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

  • raise_for_invalid (bool) – raise an exception if the configurations are invalid

Returns:

True if the configurations are valid, otherwise False

Raises:
standardize_configurations(configs, mean_dtype=<class 'float'>, variance_dtype=<class 'float'>, design_dtype=<class 'float'>)[source]#

Check the configurations of the error model (size, mean, design, and variance), and make sure they are consistent.

Note

Here are the rules:

  1. If the size is passed, the mean and the design must be one-dimensional arrays/vectors of this size (if either is scalar, they are casted to vectors), and the variance’s size/shape is asserted accordingly.

  2. If the size is not passed, it is inferred from mean and/or variance

Raises:

PyOEDConfigsValidationError – if the validation of the configurations fail

update_design(design)[source]#

Update the design and related quantities such as local covariances.

Parameters:

design – the design to be used update model’s configurations

Raises:

PyOEDConfigsValidationError – if the passed design is of invalid type/shape/size

update_configurations(**kwargs)[source]#

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

TypeError – if any of the passed keys in kwargs is invalid/unrecognized

update_design_weighting_scheme(design_weighting_scheme)[source]#

Update the design weighting scheme.

Parameters:

design_weighting_scheme (str) – name of the design weighting scheme; expected ‘covariance’ or ‘precision’

Raises:

PyOEDConfigsValidationError – if the scheme is invalid

apply_weighting_matrix(variance, design=None)[source]#

Apply the design weighting matrix by pre- and post-multiplying the passed variance matrix with the passed design or the registered one.

Parameters:

  • variance – the variance covariance matrix

  • design – an experimental design used to calculate the weights. This is only added for flexibility. If None, the internal/current deesign is used.

Returns:

variance pointwise multiplied by the underlying weighting matix

property design_weighting_scheme#

Name of the design weighting scheme

property stdev#

Construct and return the lower Cholesky factor (if not available) in the projected space (after applying the design) of the covariance matrix

Note

The update of the covariance Cholesky factor based on the weighting scheme is as follows:

  1. design_weighting_scheme is ‘covariance’:

    \[C \gets D C D^T; \qquad C \gets D (L L^T) D^T = (DL) (DL)^T \,.\]

    Thus, the covariance matrix is projected onto the active subspace, and the lower Cholesky factor is calculated there, and then weights are applied.

  2. design_weighting_scheme is ‘precision’:

    \[C^{-1} \gets D C^{-1} D; C \gets ( D (L L^T)^{-1} D )^{-1}; \qquad\]

    where the inverse is replaced with pseudo inverse when the design includes inactive entries. Here, the Lower Cholesky factor is calculated for the full covariance matrix (by ignoring the design and including inactive entries), and then the lower factor is projected onto the active subspace and is then weighted by the inverse of the active design entries (weights).

Gaussian Error Models with Pointwise-Weighted Design#

This module implements weighted versions of Gaussian error model with support for binary as well as relaxed (non-binary) design. The role of a design is to activate/deactivate entries (dimensions) if it is binary, however, if it is relaxed, the design applies some weights to the entries of the covariance (and the precision) matrix based on the formulation approach taken.

The approach taken here is pre-post multiplication. This means either the covariance matrix (or its inverse) is multiplied (pre -> from left, and post -> from right) by a diagonal matrix with the design vector (relaxed) on its main diagonal.

Note

This is the right approach to applying relaxed design for sensor placement in inverse problems. For details of the approach, see:

  1. Ahmed Attia, and Emil Constantinescu. “Optimal experimental design for inverse problems in the presence of observation correlations.” SIAM Journal on Scientific Computing 44, no. 4 (2022): A2808-A2842.

class PointwiseWeightedGaussianErrorModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None, design_weighting_scheme='covariance', pointwise_weighting_kernel=<function PointwiseWeightedGaussianErrorModelConfigs.<lambda>>)[source]#

Bases: PrePostWeightedGaussianErrorModelConfigs

Configuration settings for PointwiseWeightedGaussianErrorModel. These are exactly the same as the configurations of the parent class

Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • design (None | bool | Sequence[bool] | ndarray) –

    an experimental design to define active/inactive entries of the random variable (mean, variance/covariance matrix).

    Note

    • If the design is None, it is set to all ones; that is everything is observed (default)

    • If the design is a binary vector ( or int dtype attributes with 0/1 entries) the mean, the covariance, and all random vectors are projected onto the space identified by the 1/True entries.

  • size (int | None) – dimension of the error model space. Detected from mean if None.

  • mean (float | ndarray) – mean of the error model

  • variance (float | ndarray | spmatrix) – variance/covariance of the error model

  • sparse (bool) – convert covariance to scipy.csc_matrix used if size > 1

  • random_seed (int | None) – random seed used when the Gaussian model is initiated. This is useful for reproductivity.

  • design_weighting_scheme (str) –

    a string describing the weighting scheme; you can choose from the following options:

    • ’covariance’: the covariance matrix is pointwise-multiplied by the weighting matrix constructed (elementwise) by useing the passed pointwise_weighting_kernel.

    • ’precision’: the precision (inverse of the covariance) matrix is

      pointwise-multiplied by the weighting matrix constructed (elementwise) by useing the passed pointwise_weighting_kernel.

  • pointwise_weighting_kernel (Callable[[ndarray, int, int], float]) – a callable (function) that accpts three arguments (design, i, j) and evaluates a weighting value; used only when design_weighting_scheme is ‘pointwise-covariance’ or ‘pointwise-precision’

pointwise_weighting_kernel: Callable[[ndarray, int, int], float]#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, size=None, mean=0.0, variance=1.0, sparse=True, random_seed=None, design_weighting_scheme='covariance', pointwise_weighting_kernel=<function PointwiseWeightedGaussianErrorModelConfigs.<lambda>>)#
class PointwiseWeightedGaussianErrorModel(configs=None)[source]#

Bases: PrePostWeightedGaussianErrorModel

A simple Numpy-based (or scipy sparse) Gaussian error model with pre- and post-multiplicative design weighting. Specifically, the design (binary or relaxed) takes place by pre- and post-multiplication of the covariance or the precision matrix (based on the design_weighting_scheme in the configurations) by a diagonal matrix with the design set to its diagonal (the design matrix here).

As a clarifying example, consider the A-optimal design for linear inverse problems. In this case, the posterior covariance \(\Gamma_{\rm post}\) takes on the following forms:

  1. design_weighting_scheme==’covariance’: pre-post multiplication of the covariance matrix). The covariance of the Gaussian posterior is:

    \[\Gamma_{\rm post} = \left( \mathbf{F}^{T} \left( \Gamma_{\rm noise} \cdot \mathbf{W} \right)^{\dager} \mathbf{F} + \Gamma_{\rm prior}^{-1} \right)^{-1} \,,\]

  2. design_weighting_scheme==’precision’: pre-post imultiplication of the precision matrix). The covariance of the Gaussian posterior is:

    \[\Gamma_{\rm post} = \left( \mathbf{F}^{T} \left( \mathbf{W} \cdot \Gamma_{\rm noise}^{-1} \right) \mathbf{F} + \Gamma_{\rm prior}^{-1} \right)^{-1} \,,\]

where \(\mathbf{F}\) is the forward model (e.g., parameter-to-observable map), \(\mathbf(W)\) is the weighting matrix constructed elementwise by using the pointwise_weighting_kernel in the configurations. \(\Gamma_{\rm prior}\) is the covariance matrix of the Gaussian prior, and \(\Gamma_{\rm noise}\) is the covariance matrix of the Gaussian observation noise/error model.

Thus, in this formulation/implementation, the effect of the design takes place on the covariance/precision matrix.

Warning

The value “precision” of the design weighting scheme here is not mathematically correct, and is only added for testing and validation.

Parameters:

configs (PointwiseWeightedGaussianErrorModelConfigs | dict | None) – an object containing configurations of the error model

Raises:
__init__(configs=None)[source]#

Initialize the random number generator

validate_configurations(configs, raise_for_invalid=False)[source]#

Validate the passed configurations for the Gaussian error model

Parameters:

  • configs (dict | PointwiseWeightedGaussianErrorModelConfigs) – configurations to validate. If a configs dataclass is passed validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

  • raise_for_invalid (bool) – raise an exception if the configurations are invalid

Returns:

True if the configurations are valid, otherwise False

Raises:
build_weighting_matrix(design=None, full_space=False)[source]#

Use the registered weighting kernel to build the weighting matrix. If no design is passed, the current design is used.

Parameters:

  • design – an experimental design used to calculate the weights. This is only added for flexibility. If None, the internal/current deesign is used.

  • full_space – if True, the weighting matrix will include weights corresponding to non-zero entries only. If False, the weights are calculated for active entries only.

apply_weighting_matrix(variance, design=None)[source]#

Apply (poinwise) the weighting matrix W created by calling build_weighting_matrix() to the passed variance/covariance matrix variance. The weighting is carried out in the full or projected (based on design/active) space based on the dimension of variance.

Parameters:

  • variance – the variance covariance matrix

  • design – an experimental design used to calculate the weights. This is only added for flexibility. If None, the internal/current deesign is used.

Returns:

variance pointwise multiplied by the underlying weighting matix

property pointwise_weighting_kernel#

Name of the design weighting scheme

property stdev#

Construct and return the lower Cholesky factor (if not available) in the projected space (after applying the design) of the covariance matrix

Note

The update of the covariance Cholesky factor based on the weighting scheme is as follows:

  1. design_weighting_scheme is ‘covariance’:

    \[C \gets W \codt C \,.\]

    Thus, the covariance matrix is projected onto the active subspace, and the lower Cholesky factor is calculated there, and then weights are applied.

  2. design_weighting_scheme is ‘precision’:

    \[C \gets \left( W \codt C^{-1} \right)^{\dagger} \,.\]

Gaussian Error Models for Fenics (Dolfin) Developments#

Gaussian error model for FEniCSx-based forward problems.

This module has been migrated from the legacy FEniCS (dolfin 2019) API to FEniCSx (dolfinx 0.10). Because DolfinGaussianErrorModel uses a Real (constant) finite-element space, the FEM assembly machinery in the original code reduced to plain linear-algebra operations on constant-coefficient matrices. The migrated implementation stores all covariance operators as numpy/scipy.sparse arrays, removing the runtime dependency on dolfin/PETSc for the Gaussian model specifically.

A dolfinx function space can still be passed as Vh to extract the DOF count automatically; a plain int is also accepted for convenience.

class DolfinGaussianErrorModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, Vh=None, mean=0.0, variance=1.0, random_seed=None)[source]#

Bases: ErrorModelConfigs

Configuration settings for DolfinGaussianErrorModel.

Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • design (None | bool | Sequence[bool] | ndarray) –

    an experimental design to define active/inactive entries of the random variable (mean, variance/covariance matrix).

    Note

    • If the design is None, it is set to all ones; that is everything is observed (default)

    • If the design is a binary vector ( or int dtype attributes with 0/1 entries) the mean, the covariance, and all random vectors are projected onto the space identified by the 1/True entries.

  • Vh (None | Any) – Finite-element function space that defines the dimension of the distribution. Accepts a dolfinx.fem.FunctionSpace or a plain int (the DOF count).

  • mean (float | ndarray) – Mean of the distribution. Scalar or numpy array; scalar is broadcast to the full DOF count.

  • variance (float | ndarray | spmatrix) – Variance / covariance of the distribution. Accepts a scalar (isotropic), a 1-D numpy array (diagonal), or a 2-D array / scipy sparse matrix (full covariance).

  • random_seed (int | None) – Seed for the internal random-number generator. None defers to global numpy rules.

Vh: None | Any#
mean: float | ndarray#
variance: float | ndarray | spmatrix#
random_seed: int | None#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=True, Vh=None, mean=0.0, variance=1.0, random_seed=None)#
class DolfinGaussianErrorModel(configs=None)[source]#

Bases: ErrorModel, RandomNumberGenerationMixin

Gaussian error model for FEniCSx-based forward problems.

The distribution is \(\mathcal{N}(\boldsymbol{\mu}, \mathbf{B})\) where \(\boldsymbol{\mu}\) is the mean and \(\mathbf{B}\) is the covariance matrix. Internally the covariance is stored as its lower Cholesky factor \(\mathbf{L}\) (so \(\mathbf{B} = \mathbf{L} \mathbf{L}^{\top}\)); all matvec operations are performed in numpy/scipy.

A finite-element function space Vh (or its DOF count as a plain int) defines the dimension of the distribution. The mesh geometry is not required; only the DOF count is used.

Parameters:

configs (DolfinGaussianErrorModelConfigs | dict | None) – Configuration object or dictionary. See DolfinGaussianErrorModelConfigs for accepted keys.

Raises:

  • TypeError – If mean or variance are of unsupported types, or if Vh is not a recognised type.

  • ValueError – If Vh is None, or if the mean / covariance sizes are inconsistent with the DOF count.

  • AssertionError – If the design vector has the wrong size or contains invalid values.

__init__(configs=None)[source]#

Initialize the random number generator

update_mean(mean)[source]#

Update the distribution mean.

Parameters:

mean – Scalar, 1-D numpy array, or scipy sparse vector. Scalars are broadcast to the full DOF count.

Raises:
update_covariance_matrix(cov)[source]#

Define the covariance operator and its Cholesky factorisation.

Accepted forms for cov:

  • Scalar – isotropic covariance \(\sigma^2 \mathbf{I}\).

  • 1-D array of length n – diagonal covariance.

  • 2-D array or scipy sparse matrix of shape (n, n) – full covariance (must be symmetric positive semi-definite).

Raises:

  • TypeError – If cov is of an unsupported type.

  • AssertionError – If the covariance shape is incompatible with the DOF count.

update_design(design)[source]#

Update the experimental design (which sensors are active).

Parameters:

design –

1-D numpy array of length n.

  • Boolean – each entry flags whether the corresponding sensor is active.

  • Integer – treated as boolean after a non-negativity check.

  • Float – non-negative weights; zero entries are treated as inactive.

Raises:
create_vector(return_np=True, ignore_design=False)[source]#

Create a zero vector compatible with the covariance domain.

Parameters:

  • return_np (bool) – Always True; kept for API compatibility.

  • ignore_design (bool) – If True the full DOF space is used; otherwise the active subspace is used.

Returns:

1-D zero numpy array.

Return type:

ndarray

generate_white_noise(ignore_design=False, truncate=False, return_np=True)[source]#

Generate a standard normal random vector.

Parameters:

  • ignore_design (bool) – Use the full space (True) or the active subspace (False).

  • truncate (bool) – If True, clamp samples to \([-3, 3]\).

  • return_np (bool) – Always True; kept for API compatibility.

Returns:

1-D numpy array of standard-normal samples.

Return type:

ndarray

add_noise(x, in_place=False)[source]#

Add a random noise sample to the vector x.

Parameters:

  • x – 1-D numpy array of size active_size.

  • in_place (bool) – If True, overwrite x; otherwise return a new array.

Returns:

Noisy copy of x (or x itself if in_place).

Raises:

TypeError – If x is not a numpy array or has the wrong size.

Return type:

ndarray

generate_noise(return_np=True, ignore_design=False)[source]#

Sample a random noise vector from \(\mathcal{N}(\boldsymbol{\mu}, \mathbf{B})\).

Parameters:

  • return_np (bool) – Always True; kept for API compatibility.

  • ignore_design (bool) – If True, return a vector in the full space; otherwise return a vector in the active subspace.

Returns:

1-D numpy array containing the noise sample (including mean).

Return type:

ndarray

sample(return_np=True, ignore_design=False)[source]#

Sample a random vector from \(\mathcal{N}(\boldsymbol{\mu}, \mathbf{B})\).

Parameters:

  • return_np (bool) – Always True; kept for API compatibility.

  • ignore_design (bool) – If True, return a vector in the full space; otherwise return a vector in the active subspace.

Returns:

1-D numpy array containing the sample.

Return type:

ndarray

pdf(x, normalize=False, log=False)[source]#

Evaluate the Gaussian density at x.

Parameters:

  • x – Realization of the random variable (1-D array-like).

  • normalize (bool) – Include the normalization constant.

  • log (bool) – Return the log-density instead of the density.

Returns:

Scalar density (or log-density) value.

Return type:

float

pdf_gradient(x, normalize=False, log=False)[source]#

Evaluate the gradient of the Gaussian density at x.

Parameters:

  • x – Realization of the random variable.

  • normalize (bool) – Include the normalization factor.

  • log (bool) – Return the gradient of the log-density.

Returns:

1-D numpy array (gradient vector).

Return type:

ndarray

log_density(x, normalize=False)[source]#

Evaluate the log-density at x.

Parameters:

  • x – Realization of the random variable.

  • normalize (bool) – Include the log-normalization constant.

Returns:

Scalar log-density value.

Raises:

TypeError – If x has the wrong size.

Return type:

float

log_density_gradient(x, normalize=False)[source]#

Evaluate the gradient of the log-density at x.

Parameters:

  • x – Realization of the random variable.

  • normalize (bool) – Unused (included for API symmetry).

Returns:

1-D numpy array (gradient vector).

Raises:

TypeError – If x has the wrong size.

Return type:

ndarray

covariance_sqrt_matvec(x, lower=True, return_np=True, in_place=False, ignore_design=False)[source]#

Apply the square root of the covariance matrix to x.

The covariance square root is the lower Cholesky factor \(\mathbf{L}\) (so \(\mathbf{B} = \mathbf{L}\mathbf{L}^{\top}\)).

When ignore_design is False, the design matrix \(\mathbf{D}\) is incorporated:

  • lower=True: \(\mathbf{D} \mathbf{L} \, x\)

  • lower=False: \(\mathbf{L}^{\top} \mathbf{D}^{\top} x\)

Parameters:

  • x – Input vector (1-D array-like).

  • lower (bool) – Apply \(\mathbf{L}\) (True) or \(\mathbf{L}^{\top}\) (False).

  • return_np (bool) – Always True; kept for API compatibility.

  • in_place (bool) – If True and x is a numpy array, overwrite x with the result.

  • ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

1-D numpy result array.

Raises:

TypeError – If x has the wrong size.

Return type:

ndarray

covariance_matvec(x, return_np=True, in_place=False, ignore_design=False)[source]#

Apply the covariance matrix \(\mathbf{B} = \mathbf{L}\mathbf{L}^{\top}\) to x.

Computed as two triangular matvecs: \(\mathbf{B}\,x = \mathbf{L}(\mathbf{L}^{\top} x)\).

Parameters:

x – Input vector (1-D array-like) of size size (or active_size when ignore_design is False).

Returns:

1-D numpy result array.

Return type:

ndarray

covariance_diagonal(ignore_design=False)[source]#

Return the diagonal of the covariance matrix (the per-DOF variances).

Parameters:

ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

1-D numpy array of variances.

Return type:

ndarray

variance(ignore_design=False)[source]#

Alias for covariance_diagonal().

covariance_inv_matvec(x, in_place=False, return_np=True, ignore_design=False)[source]#

Apply the precision matrix (inverse covariance) to x via GMRES.

Parameters:

  • x – Input vector (1-D array-like).

  • in_place (bool) – Overwrite x if True.

  • return_np (bool) – Always True; kept for API compatibility.

  • ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

1-D numpy result array.

Raises:

ValueError – If GMRES does not converge.

Return type:

ndarray

covariance_sqrt_inv_matvec(x, lower=True, return_np=True, in_place=False, ignore_design=False)[source]#

Apply the inverse of the covariance square root to x via GMRES.

Parameters:

  • x – Input vector (1-D array-like).

  • lower (bool) – Use \(\mathbf{L}\) (True) or \(\mathbf{L}^{\top}\) (False) as the “sqrt”.

  • return_np (bool) – Always True; kept for API compatibility.

  • in_place (bool) – Overwrite x if True.

  • ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

1-D numpy result array.

Raises:

ValueError – If GMRES does not converge.

Return type:

ndarray

covariance_matrix(ignore_design=False)[source]#

Construct the full covariance matrix as a dense numpy array.

Parameters:

ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

2-D numpy array of shape (n, n).

Return type:

ndarray

precision_matrix(ignore_design=False)[source]#

Construct the full precision matrix (inverse covariance) as a dense numpy array.

Parameters:

ignore_design (bool) – Use the full space (True) or the active subspace (False).

Returns:

2-D numpy array of shape (n, n).

Return type:

ndarray

covariance_trace(ignore_design=False, method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', accuracy=0.01)[source]#

Evaluate or approximate the trace of the covariance matrix.

Parameters:

  • ignore_design (bool) – Use the full space (True) or active subspace (False).

  • method (str) – "exact" (sum of diagonal) or "randomized" (Hutchinson estimator).

Returns:

Trace value.

Raises:

ValueError – If method is unrecognised.

Return type:

float

covariance_logdet(ignore_design=False, method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', accuracy=0.01)[source]#

Evaluate or approximate the log-determinant of the covariance matrix.

Parameters:

  • ignore_design (bool) – Use the full space (True) or active subspace (False).

  • method (str) – "exact" or "randomized".

Returns:

Log-determinant value.

Raises:

ValueError – If method is unrecognised or the covariance is singular.

Return type:

float

kl_divergence(other)[source]#

KL divergence between this Gaussian and other.

Note

Not yet implemented for DolfinGaussianErrorModel.

property size: int#

Dimension of the underlying probability distribution.

property design: ndarray#

Get a copy of the current design vector.

property active: ndarray#

Boolean array of length n flagging active sensors.

This is the same as design.astype(bool).

property active_indexes: ndarray#

Indices of the active (non-zero design) sensors.

Returns:

1-D integer numpy array.

property active_size: int#

Number of active sensors (dimension of the projected subspace).

property mean: ndarray#

Get the distribution mean.

Returns the full mean when PROJECT_ONTO_ACTIVE_DESIGN_SPACE is False, or the active-subspace mean otherwise.

Helper Functions#

This module provides access to several flavors of Gaussian Error Models with various formulations of the design effect.

kl_divergence(N0, N1, method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', random_seed=None, accuracy=0.01)[source]#

Calculate the KL divergence between two Gaussian distributions,

\[D_{\text{KL}}\left({\mathcal {N}}_{0}\parallel {\mathcal {N}}_{1}\right) ={\frac {1}{2}}\left(\operatorname {tr} \left(\Sigma_{1}^{-1}\Sigma_{0}\right) +\left(\mu_{1}-\mu_{0}\right)^{\mathsf{T}}\Sigma_{1}^{-1}\left(\mu_{1}-\mu_{0}\right) -k+\ln \left({\frac {\det \Sigma_{1}}{\det \Sigma_{0}}}\right)\right)\]

Note

See https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence

Parameters:

  • N0 (GaussianErrorModel) – the reference (numerator) Gaussian distribution \(\mathcal{N}_0(\mu_0, \Sigma_0)\).

  • N1 (GaussianErrorModel) – the comparison (denominator) Gaussian distribution \(\mathcal{N}_1(\mu_1, \Sigma_1)\).

  • method – trace-estimation method passed to matrix_trace(). Use "exact" (default) for the deterministic trace or a stochastic estimator name otherwise.

  • sample_size – number of random vectors used by stochastic estimators.

  • optimize_sample_size – if True, adaptively adjust the sample size to meet the accuracy tolerance.

  • min_sample_size – minimum sample size when optimize_sample_size is enabled.

  • max_sample_size – maximum sample size when optimize_sample_size is enabled.

  • distribution – distribution used to generate the random vectors for stochastic trace estimation (e.g., "Rademacher").

  • random_seed – seed for reproducibility. None uses global state.

  • accuracy – target relative accuracy when optimize_sample_size is enabled.

Returns:

the scalar KL divergence \(D_{\text{KL}}(\mathcal{N}_0 \| \mathcal{N}_1)\).

Return type:

float

Raises:

  • TypeError – if either N0 or N1 is not a GaussianErrorModel instance.

  • AssertionError – if N0 and N1 have different sizes.

create_GaussianErrorModel(size, mean=0.0, variance=1.0, sparse=False, random_seed=None)[source]#

Convenience factory for GaussianErrorModel.

Parameters:

  • size (int) – dimension of the distribution (number of observations).

  • mean – scalar or array mean of the distribution. A scalar is broadcast to a vector of length size. Defaults to 0.0.

  • variance – scalar variance (isotropic) or a full covariance matrix. Defaults to 1.0.

  • sparse – if True, store the covariance using a scipy sparse matrix. Defaults to False.

  • random_seed – seed for the random number generator. None means the global NumPy state is used. Defaults to None.

Returns:

a configured GaussianErrorModel instance.

Return type:

GaussianErrorModel

create_PrePostWeightedGaussianErrorModel(size, mean=0.0, variance=1.0, sparse=False, random_seed=None)[source]#

Convenience factory for PrePostWeightedGaussianErrorModel.

This variant weights the covariance by pre- and post-multiplying with the experimental design diagonal matrix, enabling design-dependent noise scaling.

Parameters:

  • size (int) – dimension of the distribution.

  • mean – scalar or array mean. Defaults to 0.0.

  • variance – scalar or matrix variance/covariance. Defaults to 1.0.

  • sparse – use sparse covariance storage. Defaults to False.

  • random_seed – seed for the RNG. Defaults to None.

Returns:

a configured PrePostWeightedGaussianErrorModel instance.

Return type:

PrePostWeightedGaussianErrorModel

create_PointwiseWeightedGaussianErrorModel(size, mean=0.0, variance=1.0, sparse=False, random_seed=None)[source]#

Convenience factory for PointwiseWeightedGaussianErrorModel.

This variant scales individual entries of the covariance pointwise by the experimental design vector, making each observation’s noise strength proportional to its design weight.

Parameters:

  • size (int) – dimension of the distribution.

  • mean – scalar or array mean. Defaults to 0.0.

  • variance – scalar or matrix variance/covariance. Defaults to 1.0.

  • sparse – use sparse covariance storage. Defaults to False.

  • random_seed – seed for the RNG. Defaults to None.

Returns:

a configured PointwiseWeightedGaussianErrorModel instance.

Return type:

PointwiseWeightedGaussianErrorModel

On this page