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 ofcofi
’s public interface, to facilitate minimal effort to linkcofi
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.
a set of components required in
BaseProblem
instancea dictionary of components that are optional in
BaseProblem
instancea set of solver-specific options required in
InversionOptions
instancedict: a dictioanry of solver-specific options that are optional in
InversionOptions
instanceBaseInferenceTool.__init__
(inv_problem, ...)initialisation routine for the solver instance
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
.a short introduction about the solver.
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 viacofi.Inversion.summary
. It’s not required but good to keep track of this:a set of strings describing what components defined in
BaseProblem
are used in this solving process.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
andsuccess
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:
Attaching the
BaseProblem
andInversionOptions
objects toself
;Validating both input objects based on the information in
required_in_problem
,optional_in_problem
,required_in_options
, andoptional_in_options
;Assigning inversion tool parameters to
self._params
based on what are returned by class methodsrequired_in_options
,optional_in_options
, and what are set by users in theInversionOptions
object;Initializing the
self._components_used
dictionary based on what are returned by class methodsrequired_in_problem
,optional_in_problem
, and what are defined by users in theBaseProblem
object. You can overwrite this if your solver is more specific in deciding what components get used.
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
instanceThis is a standard part for a subclass of
BaseInferenceTool
and helps validate inputInversionOptions
instance
- abstract classmethod optional_in_problem() dict [source]#
a dictionary of components that are optional in
BaseProblem
instanceThe keys stand for name of the components in
BaseProblem
, and the values inputBaseProblem
instance
- abstract classmethod required_in_options() set [source]#
a set of solver-specific options required in
InversionOptions
instanceThis is a standard part for a subclass of
BaseInferenceTool
and helps validate inputInversionOptions
instance
- abstract classmethod required_in_problem() set [source]#
a set of components required in
BaseProblem
instanceThis is a standard part for a subclass of
BaseInferenceTool
and helps validate inputBaseProblem
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 ofBaseInferenceTool.optional_in_problem
- documentation_links = []#
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 wrappingscipy.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