cofi.BaseProblem

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, or
data_misfit function plus regularization function
data_misfit="L2", data, forward and regularization function
In 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, or
log_likelihood and log_prior functions

Here is a complete list of how we would deduce from existing information about the BaseProblem object you’ve defined:

Table: user defined -> we generate for you#
what you define	what we generate for you	examples
`data_misfit`	`objective` (assuming there’s no regularization)	(work in progress)
`data_misfit`, `regularization`	`objective`	linear regression (optimizer)
`forward`, `data`	`residual`	(work in progress)
`hessian`	`hessian_times_vector`	(work in progress)
`jacobian`	`jacobian_times_vector`	linear regression (linear system solver)
`log_prior`, `log_likelihood`	`log_posterior`	linear regression (sampler)

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 and residual for you. The summary() 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.

back to top

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
`BaseProblem.set_log_posterior_with_blobs`(...)	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`([...])	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

back to top

Helper Methods

Here are helper methods that check what you’ve defined to the BaseProblem:

`BaseProblem.summary`()	Helper method that prints a summary of current `BaseProblem` object to console
`BaseProblem.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 method
`BaseProblem.defined_components`()	Returns a set of components that are defined for the `BaseProblem` object

back to top

Properties/Functions of the Problem

In case you’d like to check, the properties/functions defined using the set methods above are attached directly to BaseProblem 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
`BaseProblem.name`	Name of the current BaseProblem object, for display purposes, no actual meaning
`BaseProblem.data`	the observations, set by `set_data` or `set_data_from_file`
`BaseProblem.data_covariance`	the data covariance matrix, set by `set_data_covariance`, `set_data` or `set_data_from_file`.
`BaseProblem.data_covariance_inv`	the data covariance matrix, set by `set_data_covariance_inv`, `set_data` or `set_data_from_file`.
`BaseProblem.model_covariance`(model)
`BaseProblem.model_covariance_inv`(model)
`BaseProblem.initial_model`	the initial model, needed for some iterative optimization tools that requires a starting point
`BaseProblem.model_shape`	the model shape
`BaseProblem.blobs_dtype`	the name and type for the blobs that `log_posterior_with_blobs` will return
`BaseProblem.bounds`	document me!
`BaseProblem.constraints`	document me!

back to top

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 object

These 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 with emcee.

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

model_covariance(model: ndarray)[source]#

model_covariance_inv(model: ndarray)[source]#

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 or numpy.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, or data and forward 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 matches data_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 signature
args (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 signature
args (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 signature
args (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 and set_log_likelihood are defined.

Parameters:

log_posterior_func (Callable[[np.ndarray], Number]) – the log_posterior function that matches log_posterior in signature
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_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 generate log_posterior to return only the first output from log_posterior_with_blobs.

This method is also generated automatically by us if you’ve defined both log_prior and log_likelihood. In that case, the blobs_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 signature
blobs_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 from log_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 signature
args (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 + set_regularization
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 signature
args (list, optional) – extra list of positional arguments for the objective function
kwargs (dict, optional) – extra dict of keyword arguments for the objective function

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:

Parameters:

regularization (function - np.ndarray -> Number) – 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 or set_data_from_file) are defined.

Parameters:

res_func (Callable[[np.ndarray], np.ndarray]) – the residual function that matches residual in signature
args (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 to False, then it will not print to console and will only return the dictionary; by default True
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 console

Examples

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 or set_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

bounds_defined#: indicates whether bounds has been defined

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 or set_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 or set_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 or set_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_defined#: indicates whether data has been defined

data_misfit_defined#: indicates whether data_misfit has been defined

forward_defined#: indicates whether forward has been defined

gradient_defined#: indicates whether gradient has been defined

hessian_defined#: indicates whether hessian 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_defined#: indicates whether jacobian 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

log_prior_defined#: indicates whether log_prior has been defined

model_shape#

the model shape

Raises:: NotDefinedError – when this property has not been defined (by either set_model_shape or set_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

objective_defined#: indicates whether objective has been defined

regularization_defined#: indicates whether regularization has been defined

regularization_matrix_defined#: indicates whether regularization_matrix has been defined

residual_defined#: indicates whether residual has been defined

back to top

cofi.BaseProblem

Contents

cofi.BaseProblem#