cofi.InversionOptions#

class cofi.InversionOptions[source]#

Class for specification on how an inversion will run, including which backend tool to use and solver-specific parameters.

Tip

A typical workflow of InversionOptions:

Step 1 (optional): let the Guidance Methods to walk you through available solving methods in a hierarchical way.

Step 2: Use the Set/Unset Backend Tools to fix your choice on which backend tool to use.

Step 3: Set solver-specific parameters using the Solver Params related methods.

Example usage of InversionOptions

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.get_default_tool()
'scipy.optimize.minimize'
>>> inv_options.suggest_tools()
Here's a complete list of inversion tools supported by CoFI (grouped by methods):
{
    "optimization": [
        "scipy.optimize.minimize",
        "scipy.optimize.least_squares"
    ],
    "matrix solvers": [
        "scipy.linalg.lstsq"
    ],
    "sampling": [
        "emcee"
    ]
}
>>> inv_options.set_tool("scipy.linalg.lstsq")
>>> inv_options.suggest_solver_params()
Current backend tool scipy.linalg.lstsq has the following solver-specific parameters:
Required parameters:
-- nothing --
Optional parameters & default settings:
{'cond': None, 'overwrite_a': False, 'overwrite_b': False, 'check_finite': True, 'lapack_driver': None}
>>> inv_options.summary()
=============================
Summary for inversion options
=============================
Solving method: None set
Use `suggest_solving_methods()` to check available solving methods.
-----------------------------
Backend tool: `scipy.linalg.lstsq` - SciPy's wrapper function over LAPACK's
linear least-squares solver, using 'gelsd', 'gelsy' (default), or 'gelss' as
backend driver
References: ['https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.lstsq.html',
'https://www.netlib.org/lapack/lug/node27.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.

Warning

Methods that guide users through available solvers tree is still under consideration - we are working on deciding how such APIs are named and used. Ideally, we have a tree in the backend, with the root level branching into sampling, direct search and optimization and further categorisations that lead to lists of backend tools as the leaves.

Guidance Methods

Here are how you can walk through our solvers tree as a guidance. Note that this step is optional, and you can always jump to Set/Unset Backend Tools directly.

`InversionOptions.set_solving_method`(method)	Sets the solving method
`InversionOptions.unset_solving_method`()	Unsets the chosen solving approach

Set/Unset Backend Tools

To select/unselect a backend tool, use the following methods

`InversionOptions.set_tool`(tool)	Sets the tool that will be the backend solver for your inversion problem
`InversionOptions.unset_tool`()	Unsets the chosen backend tool
`InversionOptions.get_tool`()	Get the backend tool chosen so far, or the default tool if not chosen
`InversionOptions.get_default_tool`()	Get the default tool based on the chosen solving method
`InversionOptions.suggest_tools`()	Prints a list of tools based on the solving method chosen

Solver Params

To set tool-specific parameters, use the following methods

`InversionOptions.set_params`(**kwargs)	Sets solver-specific parameters
`InversionOptions.get_params`()	Get solver-specific parameters defined so far
`InversionOptions.suggest_solver_params`()	Prints required and optional solver-specific parameters

Reference Details

get_default_tool() → str[source]#

Get the default tool based on the chosen solving method

Returns:: the name of the default backend tool
Return type:: str

get_params() → dict[source]#

Get solver-specific parameters defined so far

Returns:: a Python dictionary that maps solver-specific parameter name to the value you’ve set.
Return type:: dict

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.set_params(method="Nelder-Mead")
>>> inv_options.get_params()
{'method': 'Nelder-Mead'}

get_tool() → str | Type[source]#

Get the backend tool chosen so far, or the default tool if not chosen

Returns:: the name of the backend tool (if it’s supported by us), or the class name of your own solver
Return type:: Union[str, Type]

set_params(**kwargs)[source]#

Sets solver-specific parameters

Use InversionOptions.suggest_solver_params to get a list of parameters required and optional.

To set the parameters, use argument keyword to specify directly which parameter you refer to.

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.suggest_solver_params()
Current backend tool scipy.optimize.minimize (default) has the following solver-specific parameters:
Required parameters:
-- nothing --
Optional parameters & default settings:
{'method': None, 'tol': None, 'callback': None, 'options': None}
>>> inv_options.set_params(method="Nelder-Mead")

set_solving_method(method: str)[source]#

Sets the solving method

Warning

The current version is a flattened version of our inference tools tree, we are going to change this interface very soon.

Use InversionOptions.suggest_solving_methods to get a list of solving methods to choose from.

Parameters:: method (str) – the string that represents a solving approach
Raises:: ValueError – when the solving method you attempt to set is invalid

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.set_solving_method("matrix solvers")
>>> inv_options.suggest_tools()
Based on the solving method you've set, the following tools are suggested:
['scipy.linalg.lstsq']

Use `InversionOptions.set_tool(tool_name)` to set a specific tool from above
Use `InversionOptions.set_solving_method(method_name)` to change solving method
Use `InversionOptions.unset_solving_method()` if you'd like to see more options
Check CoFI documentation 'Advanced Usage' section for how to plug in your own solver

set_tool(tool: str | Type)[source]#

Sets the tool that will be the backend solver for your inversion problem

This can be:

a backend tool we support, use InversionOptions.suggest_tools to get a list of tools you can choose from
or your own solver class, check our tutorial - Advanced Usage for details about how to define and use your custom inference tool

Parameters:: tool (Union[str, Type]) – either the name of a backend tool or your custom tools.BaseInferenceTool class
Raises:: ValueError – when the string you pass in isn’t in our supported tools list, or when the inference tool class you pass in doesn’t implement the __call__(self,) method.

Examples

code example: set a supported tool

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.set_tool("scipy.linalg.lstsq")
>>> inv_options.summary()
=============================
Summary for inversion options
=============================
Solving method: None set
Use `suggest_solving_methods()` to check available solving methods.
-----------------------------
Backend tool: `scipy.linalg.lstsq` - SciPy's wrapper function over LAPACK's linear least-squares solver, using 'gelsd', 'gelsy' (default), or 'gelss' as backend driver
References: ['https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.lstsq.html', 'https://www.netlib.org/lapack/lug/node27.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.

code example: set your own solver

>>> from cofi.tools import BaseInferenceTool
>>> from cofi import InversionOptions
>>> class MyDummySolver(BaseInferenceTool):
...   short_description = "My dummy solver that always return (1,2) as result"
...   def __init__(self, inv_problem, inv_options):
...     super().__init__(inv_problem, inv_options)
...   def __call__(self):
...     return {"model": np.array([1,2]), "success": True}
...
>>> 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: []
Use `suggest_tools()` to check available backend tools.
-----------------------------
Solver-specific parameters: None set
Use `suggest_solver_params()` to check required/optional solver-specific parameters.

suggest_solver_params()[source]#

Prints required and optional solver-specific parameters

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.suggest_solver_params()
Current backend tool scipy.optimize.minimize (default) has the following solver-specific parameters:
Required parameters:
-- nothing --
Optional parameters & default settings:
{'method': None, 'tol': None, 'callback': None, 'options': None}

suggest_solving_methods()[source]#

Prints a list of solving methods to choose from

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.suggest_solving_methods()
The following solving methods are supported:
{'optimization', 'matrix solvers'}

Use `suggest_tools()` to see a full list of backend tools for each method

suggest_tools()[source]#

Prints a list of tools based on the solving method chosen

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.suggest_tools()
Here's a complete list of inversion tools supported by CoFI (grouped by methods):
{
    "optimization": [
        "scipy.optimize.minimize",
        "scipy.optimize.least_squares"
    ],
    "matrix solvers": [
        "scipy.linalg.lstsq"
    ]
}
>>> inv_options.set_solving_method("matrix solvers")
>>> inv_options.suggest_tools()
Based on the solving method you've set, the following tools are suggested:
['scipy.linalg.lstsq']

Use `InversionOptions.set_tool(tool_name)` to set a specific tool from above
Use `InversionOptions.set_solving_method(method_name)` to change solving method
Use `InversionOptions.unset_solving_method()` if you'd like to see more options
Check CoFI documentation 'Advanced Usage' section for how to plug in your own solver

summary()[source]#

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

Examples

code example

>>> from cofi import InversionOptions
>>> inv_options = InversionOptions()
>>> inv_options.summary()
=============================
Summary for inversion options
=============================
Solving method: None set
Use `suggest_solving_methods()` to check available solving methods.
-----------------------------
Backend tool: `scipy.optimize.minimize (by default)` - SciPy's optimizers that minimizes a scalar function with respect to one or more variables, check SciPy's documentation page for a list of methods
References: ['https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.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.

unset_solving_method()[source]#: Unsets the chosen solving approach

unset_tool()[source]#: Unsets the chosen backend tool

cofi.InversionOptions

Contents

cofi.InversionOptions#