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)

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 solvers 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(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

BaseProblem.set_walkers_starting_pos(...)

Sets the starting positions for each walker in sampling methods

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.regularization_factor

regularization factor (lambda) that adjusts weights of the regularization term

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.walkers_starting_pos

the starting positions for each walker

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: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray, *args, **kwargs) Union[numpy.ndarray, numbers.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: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, vector: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, vector: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray, *args, **kwargs) Tuple[numbers.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: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray)[source]#
model_covariance_inv(model: numpy.ndarray)[source]#
objective(model: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray, *args, **kwargs) numbers.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: numpy.ndarray, *args, **kwargs) numpy.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: numpy.ndarray, *args, **kwargs) numpy.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[numbers.Number, numbers.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: numpy.ndarray, data_cov: Optional[numpy.ndarray] = None, data_cov_inv: Optional[numpy.ndarray] = 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: numpy.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: numpy.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: Optional[numpy.ndarray] = 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: Union[str, Callable[[numpy.ndarray], numbers.Number]], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], Union[numpy.ndarray, numbers.Number]], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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: Union[Callable[[numpy.ndarray], numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray, numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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: numpy.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 solvers

Parameters

init_model (np.ndarray) – the initial model

set_jacobian(jac_func: Union[Callable[[numpy.ndarray], numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray, numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], numbers.Number], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], numbers.Number], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], Tuple[numbers.Number]], blobs_dtype=None, args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], numbers.Number], args: Optional[list] = None, kwargs: Optional[dict] = 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[[numpy.ndarray], numbers.Number], args: Optional[list] = None, kwargs: Optional[dict] = 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:

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

set_regularization(regularization: Union[str, Callable[[numpy.ndarray], numbers.Number]], regularization_factor: numbers.Number = 1, regularization_matrix: Optional[Union[numpy.ndarray, Callable[[numpy.ndarray], numpy.ndarray]]] = None, args: Optional[list] = None, kwargs: Optional[dict] = 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_factor (Number, optional) – the regularization factor (lamda) that adjusts the ratio of the regularization term over the data misfit, by default 1. If regularization and data_misfit are set but objective isn’t, then we will generate objective function as following: \(\text{objective}(model)=\text{data_misfit}(model)+\text{factor}\times\text{regularization}(model)\)

  • 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

Raises

InvalidOptionError – when you’ve passed in a string not in our supported regularization list

Examples

We demonstrate with a few examples on a BaseProblem instance.

>>> from cofi import BaseProblem
>>> inv_problem = BaseProblem()
  1. Example with an L1 norm

>>> inv_problem.set_regularization(1)
>>> inv_problem.regularization([1,1])
2
  1. Example with an inf norm

>>> inv_problem.set_regularization("inf")
>>> inv_problem.regularization([1,1])
1
  1. Example with a custom regularization function

>>> inv_problem.set_regularization(lambda x: sum(x))
>>> inv_problem.regularization([1,1])
2
  1. Example with an L2 norm and regularization factor of 0.5 (by default 1)

>>> inv_problem.set_regularization(2, 0.5)
>>> inv_problem.regularization([1,1])
0.7071067811865476
  1. Example with a regularization matrix

>>> inv_problem.set_regularization(2, 0.5, np.array([[2,0], [0,1]]))
>>> inv_problem.regularization([1,1])
1.118033988749895
set_residual(res_func: Callable[[numpy.ndarray], numpy.ndarray], args: Optional[list] = None, kwargs: Optional[dict] = 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

set_walkers_starting_pos(starting_pos: numpy.ndarray)[source]#

Sets the starting positions for each walker in sampling methods

This initialisation is optional. If not set, we rely on the default behaviour of the backend sampling tools.

Parameters

starting_pos (np.ndarray) – starting positions, with the shape (nwalkers, ndims), where nwalkers is the number of walkers you plan to use for the sampler, and ndims is the dimension of your model parameters (for fixed dimension samplers)

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

summary()[source]#

Helper method that prints a summary of current BaseProblem object to console

Examples

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', 'regularization_factor', 'forward', 'data', 'data_covariance', 'data_covariance_inv', 'initial_model', 'model_shape', 'walkers_starting_pos', '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, set_model_shape, or set_walkers_starting_pos)

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_factor#

regularization factor (lambda) that adjusts weights of the regularization term

Raises

NotDefinedError – when this property has not been defined (by set_regularization

regularization_factor_defined#

indicates whether regularization_factor has been defined

regularization_matrix_defined#

indicates whether regularization_matrix has been defined

residual_defined#

indicates whether residual has been defined

walkers_starting_pos#

the starting positions for each walker

Raises

NotDefinedError – when this property has not been defined (by set_walkers_starting_pos)

walkers_starting_pos_defined#

indicates whether walkers_starting_pos has been defined

back to top