cofi.InversionOptions

class cofi.InversionOptions

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.

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

back to top

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

back to top

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

back to top

Reference Details

get_default_tool() → str

Get the default tool based on the chosen solving method

Returns:

the name of the default backend tool

Return type:

str

get_params() → dict

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

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)

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)

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)

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

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

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

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

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

Unsets the chosen solving approach

unset_tool()

Unsets the chosen backend tool

back to top