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
andoptimization
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.
Sets the solving method
Unsets the chosen solving approach
Set/Unset Backend Tools
To select/unselect a backend tool, use the following methods
Sets the tool that will be the backend solver for your inversion problem
Unsets the chosen backend tool
Get the backend tool chosen so far, or the default tool if not chosen
Get the default tool based on the chosen solving method
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
Get solver-specific parameters defined so far
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 fromor 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 consoleExamples
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.