cofi.tools.BaseInferenceTool

cofi.tools.BaseInferenceTool#

class cofi.tools.BaseInferenceTool(inv_problem, inv_options)[source]#

Base class for backend inference tool wrappers

This is the point where we connect cofi to other inversion libraries or code. We expose this as a part of cofi’s public interface, to facilitate minimal effort to link cofi to your own inversion code or external libraries that aren’t connected by us yet.

To create your own inference tool, simply subclass BaseInferenceTool and define the following methods & fields.

Example definition of a custom solver

>>> from cofi.tools import BaseInferenceTool
>>> class MyDummySolver(BaseInferenceTool):
...   short_description = "My dummy solver that always return (1,2) as result"
...   documentation_links = ["https://cofi.readthedocs.io/en/latest/api/generated/cofi.tools.BaseInferenceTool.html"]
...   @classmethod
...   def required_in_problem(cls): return ["objective", "gradient"]
...   @classmethod
...   def optional_in_problem(cls): return {"initial_model": [0,0]}
...   @classmethod
...   def required_in_options(cls): return []
...   @classmethod
...   def optional_in_options(cls): return {"method": "dummy"}
...   def __init__(self, inv_problem, inv_options):
...     super().__init__(inv_problem, inv_options)
...   def __call__(self):
...     return {"model": np.array([1,2]), "success": True}
...
>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.set_tool(MyDummySolver)
>>> inv_options.summary()
=============================
Summary for inversion options
=============================
Solving method: None set
Use `suggest_solving_methods()` to check available solving methods.
-----------------------------
Backend tool: `<class '__main__.MyDummySolver'>` - My dummy solver that always return (1,2) as result
References: ['https://cofi.readthedocs.io/en/latest/api/generated/cofi.tools.BaseInferenceTool.html']
Use `suggest_tools()` to check available backend tools.
-----------------------------
Solver-specific parameters: None set
Use `suggest_solver_params()` to check required/optional solver-specific parameters.

Minimal implementation

Define the following minimally. Input validation will be performed automatically when a new instance is created, based on what you’ve returned for the first four class methods below.

BaseInferenceTool.required_in_problem()

a set of components required in BaseProblem instance

BaseInferenceTool.optional_in_problem()

a dictionary of components that are optional in BaseProblem instance

BaseInferenceTool.required_in_options()

a set of solver-specific options required in InversionOptions instance

BaseInferenceTool.optional_in_options()

dict: a dictioanry of solver-specific options that are optional in InversionOptions instance

BaseInferenceTool.__init__(inv_problem, ...)

initialisation routine for the solver instance

BaseInferenceTool.__call__()

the method that calls the backend inversion routines

Displaying

In addition, the following class variables help us display properly. Failure to include them won’t cause an error, but may result in some information mismatch in displaying methods like cofi.Inversion.summary.

BaseInferenceTool.short_description

a short introduction about the solver.

BaseInferenceTool.documentation_links

references about the backend solver.

Make it more complete

All backend inference tools in cofi also update the following field, and this will be displayed via cofi.Inversion.summary. It’s not required but good to keep track of this:

BaseInferenceTool.components_used

a set of strings describing what components defined in BaseProblem are used in this solving process.

back to top

Reference Details

abstract __call__() → dict[source]#

the method that calls the backend inversion routines

This is an abstract method, meaning that you have to implement this on your own in the subclass, otherwise the definition of the subclass will cause an error directly.

Returns:

a Python dictionary that has at least model/models and success as keys

Return type:

dict

__init__(inv_problem, inv_options)[source]#

initialisation routine for the solver instance

You will need to implement this in the subclass, and it’s recommended to have the following line included:

super().__init__(inv_problem, inv_options)

What it does are:

Alternatively (if you want), you can also define your own validation routines, then you don’t have to call the __init__ method defined in this super class, and don’t have to add things to the fields.

Parameters:

  • inv_problem (BaseProblem) – an inversion problem setup

  • inv_options (InversionOptions) – an object that defines how to run the inversion

abstract classmethod optional_in_options() → dict[source]#

dict: a dictioanry of solver-specific options that are optional in InversionOptions instance

This is a standard part for a subclass of BaseInferenceTool and helps validate input InversionOptions instance

abstract classmethod optional_in_problem() → dict[source]#

a dictionary of components that are optional in BaseProblem instance

The keys stand for name of the components in BaseProblem, and the values input BaseProblem instance

abstract classmethod required_in_options() → set[source]#

a set of solver-specific options required in InversionOptions instance

This is a standard part for a subclass of BaseInferenceTool and helps validate input InversionOptions instance

abstract classmethod required_in_problem() → set[source]#

a set of components required in BaseProblem instance

This is a standard part for a subclass of BaseInferenceTool and helps validate input BaseProblem instance

components_used#

a set of strings describing what components defined in BaseProblem are used in this solving process. This is typically the intersection of three sets: cofi.BaseProblem.all_components, BaseInferenceTool.required_in_problem and keys of BaseInferenceTool.optional_in_problem

references about the backend solver. It helps ensure the audience understands what the backend solver does. The list can include the official documentation if the solver wraps an external library, or links to papers and other online resources explaining the approach

For example, we use the following as the documentation_links for solver wrapping scipy.linalg.lstsq, so that users can see the details of what’s in the backend:

documentation_links = [
    "https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.lstsq.html",
    "https://www.netlib.org/lapack/lug/node27.html",
]
Type:

list

inv_options#

the inveersion settings

This is the second argument in the constructor of BaseInferenceTool

inv_problem#

the inversion problem to be solved

This is the first argument in the constructor of BaseInferenceTool

short_description = ''#

a short introduction about the solver. This is for display purpose only

Type:

str

back to top

Contents