cofi.BaseProblem#
- class cofi.BaseProblem(**kwargs)[source]#
Base class for an inversion problem setup.
An inversion problem can be defined in different ways, depending on the level of flexibility or control in ways you’d like to evaluate a model, as well as the solving approaches you’d like to apply on the problem.
To define an inversion problem that is intended to be solved by parameter estimation, you may consider setting the following functions or properties:
objective
function, ordata_misfit
function plusregularization
functiondata_misfit="L2"
,data
,forward
andregularization
functionIn addition, it can sometimes be helpful (e.g. increase the speed of inversion) to define more things in a
BaseProblem
object:gradient
of objective function,residual
vector,jacobian
of forward function, etc.
To define an inversion problem that is intended to be solved by ensemble methods (work in progress), you may consider setting the following functions or properties:
log_posterier
function, orlog_likelihood
andlog_prior
functions
Here is a complete list of how we would deduce from existing information about the
BaseProblem
object you’ve defined:# what you define
what we generate for you
examples
data_misfit
objective
(assuming there’s no regularization)(work in progress)
data_misfit
,regularization
objective
forward
,data
residual
(work in progress)
hessian
hessian_times_vector
(work in progress)
jacobian
jacobian_times_vector
log_prior
,log_likelihood
log_posterior
One quick example of BaseProblem
>>> from cofi import BaseProblem >>> import numpy as np >>> inv_problem = BaseProblem() >>> data_x = np.array([1, 2, 3, 4]) >>> data_y = np.array([3.2, 3.9, 5.1, 6.2]) >>> def my_forward(model): ... assert len(model) == 2 ... return model[0] + model[1] * data_x ... >>> inv_problem.set_data(data_y) >>> inv_problem.set_forward(my_forward) >>> inv_problem.set_data_misfit("L2") >>> inv_problem.summary() Summary for inversion problem: BaseProblem ===================================================================== Model shape: Unknown --------------------------------------------------------------------- List of functions/properties set by you: ['forward', 'data'] --------------------------------------------------------------------- List of functions/properties created based on what you have provided: ['objective', 'residual', 'data_misfit'] ( Note that you did not set regularization ) --------------------------------------------------------------------- List of functions/properties not set by you: ['objective', 'gradient', 'hessian', 'hessian_times_vector', 'residual', 'jacobian', 'jacobian_times_vector', 'data_misfit', 'regularization', 'initial_model', 'model_shape', 'bounds', 'constraints']
Tip
Check Set Methods to see a full list of methods to attach information about the problem.
Some blocks above may be deduced from other existing information. For instance, once you’ve defined your data, forward operator and how you’d like to calculate the data misfit, we are able to generate
data_misfit
andresidual
for you. Thesummary()
method prints what blocks you’ve defined, what are not yet defined, and what are generated automatically for you.At any point of defining your inversion problem, the
suggest_tools()
method helps get a list of inference tools that can be applied to your problem based on what have been supplied so far.Tip
Helper Methods are there to help you illustrate what’s in your
BaseProblem
object.Additionally, Properties/Functaions set by you are accessible through the
BaseProblem
object directly.Set Methods
Here are a series of
set
methods:BaseProblem.set_objective
(obj_func[, args, ...])Sets the function to compute the objective function to minimize
BaseProblem.set_log_posterior
(log_posterior_func)Sets the function to compute the log of posterior probability density
Sets the function that computes the log of posterior prabability density and returns extra information along with log posterior
BaseProblem.set_blobs_dtype
(blobs_dtype)Sets the name and type for the extra information you'd like to calculate on each sampling step
BaseProblem.set_log_likelihood
(...[, args, ...])Sets the function to compute the log of likelihood probability density
BaseProblem.set_log_prior
(log_prior_func[, ...])Sets the function to compute the log of prior probability density
BaseProblem.set_gradient
(grad_func[, args, ...])Sets the function to compute the gradient of objective function w.r.t the model
BaseProblem.set_hessian
(hess_func[, args, ...])Sets the function to compute the Hessian of objective function w.r.t the model
BaseProblem.set_hessian_times_vector
(...[, ...])Sets the function to compute the Hessian (of objective function) times an arbitrary vector
BaseProblem.set_residual
(res_func[, args, ...])Sets the function to compute the residual vector/matrix
BaseProblem.set_jacobian
(jac_func[, args, ...])Sets the function to compute the Jacobian matrix, namely first derivative of forward function with respect to the model
BaseProblem.set_jacobian_times_vector
(...[, ...])Sets the function to compute the Jacobian (of forward function) times an arbitrary vector
BaseProblem.set_data_misfit
(data_misfit[, ...])Sets the function to compute the data misfit
BaseProblem.set_regularization
(regularization)Sets the function to compute the regularization
BaseProblem.set_forward
(forward[, args, kwargs])Sets the function to perform the forward operation
BaseProblem.set_data
(data_obs[, data_cov, ...])Sets the data observations and optionally data covariance matrix
BaseProblem.set_data_covariance
(data_cov)Sets the data covariance matrix to help estimate uncertainty
BaseProblem.set_data_covariance_inv
(data_cov_inv)Sets the data covariance matrix to help estimate uncertainty
BaseProblem.set_data_from_file
(file_path[, ...])Sets the data for this problem from a give file path
BaseProblem.set_initial_model
(init_model)Sets the starting point for the model
BaseProblem.set_model_shape
(model_shape)Sets the model shape explicitly
Helper Methods
Here are helper methods that check what you’ve defined to the
BaseProblem
:Helper method that prints a summary of current
BaseProblem
object to consoleBaseProblem.suggest_tools
([print_to_console])Prints / Returns the backend inversion tools that you can use, based on things defined for this
BaseProblem
instance, grouped by solving methodReturns a set of components that are defined for the
BaseProblem
objectProperties/Functions of the Problem
In case you’d like to check, the properties/functions defined using the
set
methods above are attached directly toBaseProblem
and can be accessed:BaseProblem.objective
(model, *args, **kwargs)Method for computing the objective function given a model
BaseProblem.log_posterior
(model, *args, **kwargs)Method for computing the log of posterior probability density given a model
BaseProblem.log_posterior_with_blobs
(model, ...)Method for computing the log of posterior probability density and related information given a model
BaseProblem.log_likelihood
(model, *args, ...)Method for computing the log of likelihood probability density given a model
BaseProblem.log_prior
(model, *args, **kwargs)Method for computing the log of prior probability density given a model
BaseProblem.gradient
(model, *args, **kwargs)Method for computing the gradient of objective function with respect to model, given a model
BaseProblem.hessian
(model, *args, **kwargs)Method for computing the Hessian of objective function with respect to model, given a model
BaseProblem.hessian_times_vector
(model, ...)Method for computing the dot product of the Hessian and an arbitrary vector, given a model
BaseProblem.residual
(model, *args, **kwargs)Method for computing the residual vector given a model.
BaseProblem.jacobian
(model, *args, **kwargs)method for computing the jacobian of forward function with respect to model, given a model
BaseProblem.jacobian_times_vector
(model, ...)Method for computing the dot product of the Jacobian and an arbitrary vector, given a model
BaseProblem.data_misfit
(model, *args, **kwargs)Method for computing the data misfit value given a model
BaseProblem.regularization
(model, *args, ...)Method for computing the regularization value given a model
BaseProblem.regularization_matrix
(model, ...)Method for computing the regularization weighting matrix
BaseProblem.forward
(model, *args, **kwargs)Method to perform the forward operation given a model
Name of the current BaseProblem object, for display purposes, no actual meaning
the observations, set by
set_data
orset_data_from_file
the data covariance matrix, set by
set_data_covariance
,set_data
orset_data_from_file
.the data covariance matrix, set by
set_data_covariance_inv
,set_data
orset_data_from_file
.BaseProblem.model_covariance
(model)the initial model, needed for some iterative optimization tools that requires a starting point
the model shape
the name and type for the blobs that
log_posterior_with_blobs
will returndocument me!
document me!
Reference Details
- data_misfit(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the data misfit value given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the data misfit evaluated based on how you’ve defined it
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- defined_components() set [source]#
Returns a set of components that are defined for the
BaseProblem
objectThese include both the ones you’ve set explicitly through the Set Methods and the ones that are deduced from existing information.
- Returns:
a set of strings describing what are defined
- Return type:
set
- forward(model: ndarray, *args, **kwargs) ndarray | Number [source]#
Method to perform the forward operation given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the synthetics data
- Return type:
np.ndarray or Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- gradient(model: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the gradient of objective function with respect to model, given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the gradient (first derivative) of objective function with repect to the model
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- hessian(model: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the Hessian of objective function with respect to model, given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the Hessian (second derivative) of objective function with respect to the model
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- hessian_times_vector(model: ndarray, vector: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the dot product of the Hessian and an arbitrary vector, given a model
- Parameters:
model (np.ndarray) – a model to evaluate
vector (np.ndarray) – an arbitrary vector
- Returns:
Hessian times an arbitrary vector
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- jacobian(model: ndarray, *args, **kwargs) ndarray [source]#
method for computing the jacobian of forward function with respect to model, given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the jacobian matrix, \(\frac{\partial{\text{forward}(\text{model})}}{\partial\text{model}}\)
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- jacobian_times_vector(model: ndarray, vector: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the dot product of the Jacobian and an arbitrary vector, given a model
- Parameters:
model (np.ndarray) – a model to evaluate
vector (np.ndarray) – an arbitrary vector
- Returns:
the Jacobian matrix times the given vector
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- log_likelihood(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the log of likelihood probability density given a model
This reflects the probability distribution of the observations given the model.
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the likelihood probability density value
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- log_posterior(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the log of posterior probability density given a model
This is typically the sum of log prior and log likelihood.
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the posterior probability density value
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- log_posterior_with_blobs(model: ndarray, *args, **kwargs) Tuple[Number] [source]#
Method for computing the log of posterior probability density and related information given a model
The “related information” can be defined by you (via
set_log_posterior_with_blobs
), but they will only be stored properly when you perform sampling withemcee
.- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the posterior probability density value, and other information you’ve set to return together with the former
- Return type:
Tuple[Number]
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- log_prior(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the log of prior probability density given a model
This reflects your prior belief about the model distribution.
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the prior probability density value
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- objective(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the objective function given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
The objective function value for the given model
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- regularization(model: ndarray, *args, **kwargs) Number [source]#
Method for computing the regularization value given a model
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the regularization value evaluated based on how you’ve defined it
- Return type:
Number
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- regularization_matrix(model: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the regularization weighting matrix
- Parameters:
model (np.ndarray) – a model that helps calculate regularization matrix. In most cases this is not needed, but you have the flexibility to set this as a function
- Returns:
the regularization matrix of dimension
(model_size, model_size)
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set
- residual(model: ndarray, *args, **kwargs) ndarray [source]#
Method for computing the residual vector given a model.
- Parameters:
model (np.ndarray) – a model to evaluate
- Returns:
the residual vector, \(\text{forward}(\text{model})-\text{observations}\)
- Return type:
np.ndarray
- Raises:
NotDefinedError – when this method is not set and cannot be generated from known information
- set_blobs_dtype(blobs_dtype: list)[source]#
Sets the name and type for the extra information you’d like to calculate on each sampling step
This only gets used when you are using
emcee
to sample the posterior distribution. Check this emcee documentation page to understand what blobs are.- Parameters:
blobs_dtype (list) – a list of tuples that specify the names and type of the blobs, e.g.
[("log_likelihood", float), ("log_prior", float)]
- set_bounds(bounds: Sequence[Tuple[Number, Number]])[source]#
TODO document me
- Parameters:
bounds (Sequence[Tuple[Number, Number]]) – _description_
- set_constraints(constraints)[source]#
TODO document me
- Parameters:
constraints (_type_) – _description_
- set_data(data_obs: ndarray, data_cov: ndarray | None = None, data_cov_inv: ndarray | None = None)[source]#
Sets the data observations and optionally data covariance matrix
- Parameters:
data_obs (np.ndarray) – the observations
data_cov (np.ndarray, optional) – the data covariance matrix that helps estimate uncertainty, with dimension (N,N) where N is the number of data points
- set_data_covariance(data_cov: ndarray)[source]#
Sets the data covariance matrix to help estimate uncertainty
- Parameters:
data_cov (np.ndarray) – the data covariance matrix, with dimension (N,N) where N is the number of data points
- set_data_covariance_inv(data_cov_inv: ndarray)[source]#
Sets the data covariance matrix to help estimate uncertainty
- Parameters:
data_cov (np.ndarray) – the data covariance matrix, with dimension (N,N) where N is the number of data points
- set_data_from_file(file_path, obs_idx=-1, data_cov: ndarray | None = None)[source]#
Sets the data for this problem from a give file path
This function uses
numpy.loadtxt
ornumpy.load
to read data file, depending on the file type.- Parameters:
file_path (str) – a relative/absolute file path for the data
obs_idx (int or list, optional) – the index/indices of observations within the data file, by default -1
data_cov (np.ndarray, optional) – the data covariance matrix that helps estimate uncertainty, with dimension (N,N) where N is the number of data points
- set_data_misfit(data_misfit: str | Callable[[ndarray], Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the data misfit
You can either pass in a custom function or a short string that describes the data misfit function (e.g.
"squared error"
)If you choose
data_misfit="squared error"
, and:If you have
residual
defined, ordata
andforward
defined, then \(\text{data_misfit}=\text{residual}^T \text{residual}\)where \(\text{residual}=\text{forward}(\text{model})-\text{observations}\)
If you additionally have
data_covariance_inv
defined, then \(\text{data_misfit}=\text{residual}^TC_d^{-1}\text{residual}\)where \(C_d^{-1}=\text{data_covariance_inv}\)
Otherwise you might face an error when actually calling the
data_misfit
method.
Alternatively, pass in your own data misfit function (or objective function directly through
set_objective
).- Parameters:
data_misfit (str or (function - np.ndarray -> Number)) – either
"squared error"
, or a data misfit function that matchesdata_misfit
in signature.args (list, optional) – extra list of positional arguments for data_misfit function
kwargs (dict, optional) – extra dict of keyword arguments for data_misfit function
- Raises:
InvalidOptionError – when you’ve passed in a string not in our supported data misfit list
- set_forward(forward: Callable[[ndarray], ndarray | Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to perform the forward operation
- Parameters:
forward (function - np.ndarray -> (np.ndarray or Number)) – the forward function that matches
forward
in signatureargs (list, optional) – extra list of positional arguments for forward function
kwargs (dict, optional) – extra dict of keyword arguments for forward function
- set_gradient(grad_func: Callable[[ndarray], ndarray], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the gradient of objective function w.r.t the model
- Parameters:
obj_func (Callable[[np.ndarray], Number]) – the gradient function that matches
gradient
in signatureargs (list, optional) – extra list of positional arguments for gradient function
kwargs (dict, optional) – extra dict of keyword arguments for gradient function
- set_hessian(hess_func: Callable[[ndarray], ndarray] | ndarray, args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the Hessian of objective function w.r.t the model
- Parameters:
hess_func ((function - np.ndarray -> np.ndarray) or np.ndarray) – the Hessian function that matches
hessian
in signature. Alternatively, provide a matrix if the Hessian is a constant.args (list, optional) – extra list of positional arguments for hessian function
kwargs (dict, optional) – extra dict of keyword arguments for hessian function
- set_hessian_times_vector(hess_vec_func: Callable[[ndarray, ndarray], ndarray], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the Hessian (of objective function) times an arbitrary vector
Alternatively, hessian_times_vector function can be set implicitly (computed by us) if
set_hessian
is defined.- Parameters:
hess_vec_func (Callable[[np.ndarray, np.ndarray], np.ndarray]) – the function that computes the product of Hessian and an arbitrary vector, in the same signature as
hessian_times_vector
args (list, optional) – extra list of positional arguments for hessian_times_vector function
kwargs (dict, optional) – extra dict of keyword arguments for hessian_times_vector function
- set_initial_model(init_model: ndarray)[source]#
Sets the starting point for the model
Once set, we will infer the property
model_shape
in case this is required for some inference tools- Parameters:
init_model (np.ndarray) – the initial model
- set_jacobian(jac_func: Callable[[ndarray], ndarray] | ndarray, args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the Jacobian matrix, namely first derivative of forward function with respect to the model
- Parameters:
jac_func ((function - np.ndarray -> np.ndarray) or np.ndarray) – the Jacobian function that matches
residual
in signature. Alternatively, provide a matrix if the Jacobian is a constant.args (list, optional) – extra list of positional arguments for jacobian function
kwargs (dict, optional) – extra dict of keyword arguments for jacobian function
- set_jacobian_times_vector(jac_vec_func: Callable[[ndarray, ndarray], ndarray], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the Jacobian (of forward function) times an arbitrary vector
Alternatively, jacobian_times_vector function can be set implicitly (computed by us) if
set_jacobian
is defined.- Parameters:
jac_vec_func (Callable[[np.ndarray, np.ndarray], np.ndarray]) – the function that computes the product of Jacobian and an arbitrary vector, in the same signature as
jacobian_times_vector
args (list, optional) – extra list of positional arguments for jacobian_times_vector function
kwargs (dict, optional) – extra dict of keyword arguments for jacobian_times_vector function
- set_log_likelihood(log_likelihood_func: Callable[[ndarray], Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the log of likelihood probability density
- Parameters:
log_likelihood_func (Callable[[np.ndarray], Number]) – the log_likelihood function that matches
log_likelihood
in signatureargs (list, optional) – extra list of positional arguments for log_likelihood function
kwargs (dict, optional) – extra dict of keyword arguments for log_likelihood function
- set_log_posterior(log_posterior_func: Callable[[ndarray], Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the log of posterior probability density
Alternatively, log_posterior function can be set implicitly (computed by us) if
set_log_prior
andset_log_likelihood
are defined.- Parameters:
log_posterior_func (Callable[[np.ndarray], Number]) – the log_posterior function that matches
log_posterior
in signatureargs (list, optional) – extra list of positional arguments for log_posterior function
kwargs (dict, optional) – extra dict of keyword arguments for log_posterior function
- set_log_posterior_with_blobs(log_posterior_blobs_func: Callable[[ndarray], Tuple[Number]], blobs_dtype=None, args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function that computes the log of posterior prabability density and returns extra information along with log posterior
The extra blobs returned will only get used when you are using
emcee
to sample the posterior distribution. Check this emcee documentation page to understand what blobs are.If you use other backend samplers, you can still set
log_posterior
using this function, and we will generatelog_posterior
to return only the first output fromlog_posterior_with_blobs
.This method is also generated automatically by us if you’ve defined both
log_prior
andlog_likelihood
. In that case, theblobs_dtype
is set to be[("log_likelihood", float), ("log_prior", float)]
.- Parameters:
log_posterior_blobs_func (Callable[[np.ndarray], Tuple[Number]) – the log_posterior_with_blobs function that matches
log_posterior_blobs_func
in signatureblobs_dtype (list, optional) – a list of tuples that specify the names and type of the blobs, e.g.
[("log_likelihood", float), ("log_prior", float)]
. If not set, the blobs will still be recorded during sampling in the order they are returned fromlog_posterior_blobs_func
args (list, optional) – extra list of positional arguments for log_posterior function
kwargs (dict, optional) – extra dict of keyword arguments for log_posterior function
- set_log_prior(log_prior_func: Callable[[ndarray], Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the log of prior probability density
- Parameters:
log_prior_func (Callable[[np.ndarray], Number]) – the log_prior function that matches
log_prior
in signatureargs (list, optional) – extra list of positional arguments for log_prior function
kwargs (dict, optional) – extra dict of keyword arguments for log_prior function
- set_model_shape(model_shape: Tuple)[source]#
Sets the model shape explicitly
- Parameters:
model_shape (Tuple) – a tuple that describes model shape
- Raises:
DimensionMismatchError – when you’ve defined an initial_model through
set_initial_model
but their shapes don’t match
- set_objective(obj_func: Callable[[ndarray], Number], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the objective function to minimize
Alternatively, objective function can be set implicitly (computed by us) if one of the following combinations is set:
set_data_misfit
(in this case, regularization is default to 0)
- Parameters:
obj_func (Callable[[np.ndarray], Number]) – the objective function that matches
objective
in signatureargs (list, optional) – extra list of positional arguments for the objective function
kwargs (dict, optional) – extra dict of keyword arguments for the objective function
- set_regularization(regularization: Callable[[ndarray], Number], regularization_matrix: ndarray | Callable[[ndarray], ndarray] | None = None, args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the regularization
You can either pass in a custom function or a string/number that describes the order of the norm. We use
numpy.linalg.norm
as our backend implementation, so the order can be chosen from:{
None
,"fro"
,"nuc"
,numpy.inf
,-numpy.inf
} \(\cup\;\mathbb{R}^*\)- Parameters:
regularization (str or (function - np.ndarray -> Number)) – either a string from pre-built functions above, or a regularization function that matches
regularization
in signature.regularization_matrix (np.ndarray or (function - np.ndarray -> np.ndarray)) –
a matrix of shape
(model_size, model_size)
, or a function that takes in a model and calculates the (weighting) matrix.If this is None, \(\text{regularization}(model)=\lambda\times\text{regularization}(model)\)
If this is set to be a matrix (np.ndarray, or other array like types), \(\text{regularization}(model)=\lambda\times\text{regularization}(\text{regularization_matrix}\cdot model)\)
If this is set to be a function that returns a matrix, \(\text{regularization}(model)=\lambda\times\text{regularization}(\text{regularization_matrix}(model)\cdot model)\)
args (list, optional) – extra list of positional arguments for regularization function
kwargs (dict, optional) – extra dict of keyword arguments for regularization function
Examples
We demonstrate with a few examples on a
BaseProblem
instance.>>> from cofi import BaseProblem >>> inv_problem = BaseProblem()
Example with a custom regularization function
>>> inv_problem.set_regularization(lambda x: sum(x)) >>> inv_problem.regularization([1,1]) 2
Example with a custom regularization + a regularization matrix
>>> inv_problem.set_regularization(lambda x: np.sum(x**2), np.eye(3)) >>> inv_problem.regularization([1,1]) 2
- set_residual(res_func: Callable[[ndarray], ndarray], args: list | None = None, kwargs: dict | None = None)[source]#
Sets the function to compute the residual vector/matrix
Alternatively, residual function can be set implicitly (computed by us) if both
set_forward
and data (set_data
orset_data_from_file
) are defined.- Parameters:
res_func (Callable[[np.ndarray], np.ndarray]) – the residual function that matches
residual
in signatureargs (list, optional) – extra list of positional arguments for residual function
kwargs (dict, optional) – extra dict of keyword arguments for residual function
- suggest_tools(print_to_console=True) dict [source]#
Prints / Returns the backend inversion tools that you can use, based on things defined for this
BaseProblem
instance, grouped by solving method- Parameters:
print_to_console (bool, optional) – if set to
True
, this method will both print and return the dictionary of backend tools in a tree structure; if set toFalse
, then it will not print to console and will only return the dictionary; by defaultTrue
- Returns:
a tree structure of solving methods we provide, with the leaf nodes being a list of backend inversion tools suggested based on what information you’ve provided to this
BaseProblem
object- Return type:
dict
Examples
example usage for BaseProblem.suggest_tools()
>>> from cofi import BaseProblem >>> import numpy as np >>> inv_problem = BaseProblem() >>> inv_problem.set_initial_model(np.array([1,2,3])) >>> inv_problem.set_data_misfit("least squares") >>> inv_problem.suggest_tools() Based on what you've provided so far, here are possible tools: { "optimization": [ "scipy.optimize.minimize" ], "matrix solvers": [], "sampling": [] }
- summary()[source]#
Helper method that prints a summary of current
BaseProblem
object to consoleExamples
examples usage for BaseProblem.summary()
>>> from cofi import BaseProblem >>> import numpy as np >>> inv_problem = BaseProblem() >>> inv_problem.set_initial_model(np.array([1,2,3])) >>> inv_problem.set_data_misfit("L2") >>> inv_problem.summary() ===================================================================== Summary for inversion problem: BaseProblem ===================================================================== Model shape: (3,) --------------------------------------------------------------------- List of functions/properties set by you: ['initial_model', 'model_shape'] --------------------------------------------------------------------- List of functions/properties created based on what you have provided: ['objective', 'data_misfit'] ( Note that you did not set regularization ) --------------------------------------------------------------------- List of functions/properties not set by you: (not all of these may be relevant to your inversion workflow) ['objective', 'gradient', 'hessian', 'hessian_times_vector', 'residual', 'jacobian', 'jacobian_times_vector', 'data_misfit', 'regularization', 'forward', 'data', 'bounds', 'constraints']
- all_components = ['objective', 'log_posterior', 'log_posterior_with_blobs', 'log_likelihood', 'log_prior', 'gradient', 'hessian', 'hessian_times_vector', 'residual', 'jacobian', 'jacobian_times_vector', 'data_misfit', 'regularization', 'regularization_matrix', 'forward', 'data', 'data_covariance', 'data_covariance_inv', 'initial_model', 'model_shape', 'blobs_dtype', 'bounds', 'constraints']#
- autogen_table#
- blobs_dtype#
the name and type for the blobs that
log_posterior_with_blobs
will return- Raises:
NotDefinedError – when this property has not been defined (by either
set_blobs_dtype
orset_log_posterior_with_blobs
)
- blobs_dtype_defined#
indicates whether
blobs_dtype
has been defined
- bounds#
document me!
- Raises:
NotDefinedError – when this property has not been defined (by
set_bounds
)- Type:
TODO
- constraints#
document me!
- Raises:
NotDefinedError – when this property has not been defined (by
set_constraints
)- Type:
TODO
- constraints_defined#
indicates whether
constraints
has been defined
- data#
the observations, set by
set_data
orset_data_from_file
- Raises:
NotDefinedError – when this property has not been defined by methods above
- data_covariance#
the data covariance matrix, set by
set_data_covariance
,set_data
orset_data_from_file
.- Raises:
NotDefinedError – when this property has not been defined by methods above
- data_covariance_defined#
indicates whether
data_covariance
has been defined
- data_covariance_inv#
the data covariance matrix, set by
set_data_covariance_inv
,set_data
orset_data_from_file
.- Raises:
NotDefinedError – when this property has not been defined by methods above
- data_covariance_inv_defined#
indicates whether
data_covariance_inv
has been defined
- data_misfit_defined#
indicates whether
data_misfit
has been defined
- hessian_times_vector_defined#
indicates whether
hessian_times_vector
has been defined
- initial_model#
the initial model, needed for some iterative optimization tools that requires a starting point
- Raises:
NotDefinedError – when this property has not been defined (by
set_initial_model
)
- initial_model_defined#
indicates whether
initial_model
has been defined
- jacobian_times_vector_defined#
indicates whether
jacobian_times_vector
has been defined
- log_likelihood_defined#
indicates whether
log_likelihood
has been defined
- log_posterior_defined#
indicates whether
log_posterior
has been defined
- log_posterior_with_blobs_defined#
indicates whether
log_posterior_with_blobs
has been defined
- model_shape#
the model shape
- Raises:
NotDefinedError – when this property has not been defined (by either
set_model_shape
orset_model_shape
)
- model_shape_defined#
indicates whether
model_shape
has been defined
- name#
Name of the current BaseProblem object, for display purposes, no actual meaning
- Returns:
a name you’ve set
- Return type:
str
- regularization_defined#
indicates whether
regularization
has been defined
- regularization_matrix_defined#
indicates whether
regularization_matrix
has been defined