petsctools.options module¶

class petsctools.options.AppContextKey¶

Bases: str

A custom key type for Python objects.

Warning

This type should not be instantiated directly by the user, it will be generated as needed by the Options.

See also

Options

class petsctools.options.DefaultOptionSet(base_prefix: str, custom_prefix_endings: Iterable)¶

Bases: object

Defines a set of common default options shared by multiple PETSc objects.

Some solvers, e.g. PCFieldsplit, create multiple subsolvers whose prefixes differ only by the final characters, e.g. 'fieldsplit_0', 'fieldsplit_1'. It is often useful to be able to set default options for these subsolvers using the un-specialised prefix e.g. 'fieldsplit_ksp_type'. However, just grabbing all options with the 'fieldsplit' prefix will erroneously find options like '0_ksp_type' and '1_ksp_type' that were meant for a specific subsolver.

DefaultOptionSet defines a base prefix (e.g. 'fieldsplit') and a set of custom prefix endings (e.g. [0, 1]). If passed to an OptionsManager then any default options present in the global options database will be used if those options are not present either: in the parameters passed to the OptionsManager; or in the global PETSc.Options database with the options_prefix passed to the OptionsManager.

For example, to set up a fieldsplit solver you might have the following options, where both fields are to use ILU as the preconditioner but each field uses a different KSP type.

-fieldsplit_pc_type ilu
-fieldsplit_0_ksp_type preonly
-fieldsplit_1_ksp_type richardson

To create an OptionsManager for each field you would call:

default_options_set = DefaultOptionSet(
     base_prefix='fieldsplit',
     custom_prefix_endings=(0, 1))

fieldsplit_0_options = OptionsManager(
    parameters={},
     options_prefix="fieldsplit_0",
    default_options_set=default_options_set)

fieldsplit_1_options = OptionsManager(
    parameters={},
     options_prefix="fieldsplit_1",
    default_options_set=default_options_set)

Parameters:

base_prefix – The prefix for the default options, which is the beginning of each full custom prefix.
custom_prefix_endings – The ends of each individual custom prefix. Often a range of integers.

Notes

The base prefix and each custom prefix ending will be converted to a string and have an underscore appended if they do not already have one.

property base_prefix¶: The prefix for the default options.

property custom_prefix_endings¶: The ends of each individual custom prefix.

property custom_prefixes¶: The full custom prefixes.

class petsctools.options.Options(prefix: str | None = None)¶

Bases: Options

Class for interacting with the PETSc options database.

This class extends the petsc4py.PETSc.Options class by allowing it to insert and retrieve arbitrary Python objects instead of a select set of native types.

Parameters:: prefix – If provided, all option keys passed to __getitem__ or get will be prepended with this prefix before searching in the global database. i.e. Options("prefix_")["option"] is equivalent to Options()["prefix_option"].

__getitem__(option: str | AppContextKey, /) → Any¶

Return the value corresponding to the key option in the PETSc.Options dictionary.

If this Options instance has a prefix then the value corresponding to the key self.prefix + option will be returned.

Parameters:: option – The PETSc option or key.
Returns:: The value for the key option.
Return type:: Any
Raises:: KeyError – If the Options does not contain a value for option.

get(option: str | AppContextKey, default: Any | None = None) → Any¶

Return the value corresponding to the key option in the PETSc.Options dictionary, or the default value if option is not found in the global options database.

If this petsctools.Options instance has a prefix then the value corresponding to the key self.prefix + option will be returned.

Parameters:

option – The PETSc option or key.
default – The value to return if option is not in the petsctools.Options.

Returns:

The value for the key option, or default.

Return type:

Any

getAll() → dict[str, Any]¶: Return all entries.

class petsctools.options.OptionsManager(parameters: dict[str, Any], options_prefix: str | None = None, default_prefix: str | None = None, default_options_set: DefaultOptionSet | None = None)¶

Bases: object

Class that helps with managing setting PETSc options.

The recommended way to use the OptionsManager is by using the attach_options(), set_from_options(), and inserted_options() free functions. These functions ensure that each OptionsManager is associated to a single PETSc object.

For detail on the previous approach of using OptionsManager as a mixin class (where the user takes responsibility for ensuring an association with a single PETSc object), see below.

To use the OptionsManager:

Pass a PETSc object a parameters dictionary, and optionally an options prefix, to attach_options(). This will create an OptionsManager and set the prefix of the PETSc object, but will not yet set it up.
Once the object is ready, pass it to set_from_options(), which will insert the solver options into PETSc.Options and call obj.setFromOptions.
The inserted_options() context manager must be used when calling methods on the PETSc object within which solver options will be read, for example solve. This will insert the provided parameters into PETSc’s global options dictionary within the context manager, and remove them afterwards. This ensures that the global options dictionary will not grow indefinitely if many OptionsManager instances are used.

ksp = PETSc.KSP().create(comm=comm)
ksp.setOperators(mat)

attach_options(ksp, parameters=parameters,
               options_prefix=prefix)

# ...

set_from_options(ksp)

# ...

with inserted_options(ksp):
    ksp.solve(b, x)

To access the OptionsManager for a PETSc object directly use the get_options() function:

N = get_options(ksp).getInt(prefix+"N")

Using OptionsManager as a mixin class:

To use this, you must call its constructor with the parameters you want in the options database, and optionally a prefix to extract options from the global database.

You then call set_from_options(), passing the PETSc object you’d like to call setFromOptions on. Note that this will actually only call setFromOptions the first time (so really this parameters object is a once-per-PETSc-object thing).

So that the runtime monitors which look in the options database actually see options, you need to ensure that the options database is populated at the time of a SNESSolve or KSPSolve call. Do that using the OptionsManager.inserted_options() context manager.

If using as a mixin class, call the OptionsManager methods directly:

self.set_from_options(self.snes)

with self.inserted_options():
    self.snes.solve(...)

This ensures that the options database has the relevant entries for the duration of the with block, before removing them afterwards. This is a much more robust way of dealing with the fixed-size options database than trying to clear it out using destructors.

This object can also be used only to manage insertion and deletion into the PETSc options database, by using the context manager.

Parameters:

parameters – The dictionary of parameters to use. Parameter keys must be strings and values may be any type. Note that if ‘non-native’ types are passed (e.g. a Python object instead of a number, string or bool) then these may only be accessed by using the Options class. PETSc.Options will not work.
options_prefix – The prefix to look up items in the global options database. If None then the prefix is generated from default_prefix. If no trailing underscore is provided, one is appended. Hence foo_ and foo are treated equivalently. As an exception, if the prefix is the empty string, no underscore is appended.
default_prefix – The base string to generate default prefixes. If options_prefix is not provided then a prefix is automatically generated with the form “{default_prefix}_{n}”, where n is a unique integer. Note that because the unique integer is not stable the auto-generated prefix for a particular solver may change between Python invocations due to changes elsewhere in the code.
default_options_set – The prefix set for any default shared with other solvers. See DefaultOptionSet for more information.

count = 0¶

inserted_options()¶

Context manager inside which the petsc options database contains the parameters from this object.

Non-native types (e.g. Python objects) can only be accessed using Options, not PETSc.Options.

property options_object¶

set_default_parameter(key: str, val: Any) → None¶

Set a default parameter value.

Parameters:

key – The parameter name.
val – The parameter value.
options (Ensures that the right thing happens cleaning up the)
database.

set_from_options(petsc_obj)¶

Set up petsc_obj from the options database.

Before calling petsc_obj.setFromOptions, the options from this OptionsManager’s parameters are inserted into the global PETSc.Options.

A PetscToolsWarning is raised if the method has already been called.

Parameters:: petsc_obj – The PETSc object to call setFromOptions on.

petsctools.options.attach_options(obj: Object, parameters: dict | None = None, options_prefix: str | None = None, default_prefix: str | None = None, default_options_set: DefaultOptionSet | None = None) → None¶

Set up an OptionsManager and attach it to a PETSc Object.

Parameters:

obj – The object to attach an OptionsManager to.
parameters – The dictionary of parameters to use.
options_prefix – The options prefix to use for this object.
default_prefix – Base string for autogenerated default prefixes.
default_options_set – The prefix set for any default shared with other solvers.

petsctools.options.flatten_parameters(parameters, sep='_')¶

Flatten a nested parameters dict, joining keys with sep.

Parameters:

parameters – a dict to flatten.
sep – separator of keys.

Used to flatten parameter dictionaries with nested structure to a flat dict suitable to pass to PETSc. For example:

flatten_parameters({"a": {"b": {"c": 4}, "d": 2}, "e": 1}, sep="_")
=> {"a_b_c": 4, "a_d": 2, "e": 1}

If a “prefix” key already ends with the provided separator, then it is not used to concatenate the keys. Hence:

flatten_parameters({"a_": {"b": {"c": 4}, "d": 2}, "e": 1}, sep="_")
=> {"a_b_c": 4, "a_d": 2, "e": 1}
# rather than
=> {"a__b_c": 4, "a__d": 2, "e": 1}

petsctools.options.get_commandline_options() → frozenset¶: Return the PETSc options passed on the command line.

petsctools.options.get_default_options(default_options_set: DefaultOptionSet, options: Options | Options | None = None) → dict¶

Extract default options for subsolvers with similar prefixes.

Parameters:

default_options_set – The DefaultOptionSet which defines the shared options.
options – The PETSc.Options database to use. If not provided then the global database will be used.

Return type:

The dictionary of default options with the base prefix stripped.

See also

DefaultOptionSet

petsctools.options.get_options(obj: Object) → OptionsManager¶

Return the OptionsManager attached to this PETSc object.

Parameters:: obj – The object to get the OptionsManager from.
Return type:: The OptionsManager attached to the object.
Raises:: petsctools.PetscToolsException – If the object does not have an OptionsManager.

petsctools.options.has_options(obj: Object) → bool¶

Return whether this PETSc object has an OptionsManager attached.

Parameters:: obj – The object which may have an OptionsManager.
Return type:: Whether the object has an OptionsManager.

Context manager inside which the PETSc options database contains the parameters either from obj’s OptionsManager, or from the parameters dictionary with the given prefix.

Parameters:

obj – The object which may have been set from options.
parameters – The dictionary of parameters to use. Ignored if obj is passed.
options_prefix – The options prefix to use for the parameters. Ignored if obj is passed.
default_prefix – Base string for autogenerated default prefixes. Ignored if obj is passed.
default_options_set – The prefix set for any default shared with other solvers. Ignored if obj is passed.

Raises:

petsctools.PetscToolsException – If the object does not have an OptionsManager.

petsctools.options.is_set_from_options(obj: Object) → bool¶

Return whether this PETSc object has been set by the OptionsManager.

Parameters:: obj – The object which may have been set from options.
Return type:: Whether the object has previously been set from options.
Raises:: petsctools.PetscToolsException – If the object does not have an OptionsManager.

petsctools.options.petscobj2str(obj: Object) → str¶

Return a string with a PETSc object type and prefix.

Parameters:: obj – The object to stringify.
Return type:: The stringified name of the object

petsctools.options.set_default_parameter(obj: Object, key: str, val: Any) → None¶

Set a default parameter value in the OptionsManager of a PETSc object.

Parameters:

obj – The object to get the OptionsManager from.
key – The options parameter name
val – The options parameter value

Raises:

petsctools.PetscToolsException – If the object does not have an OptionsManager.

petsctools.options.set_from_options(obj: Object, parameters: dict | None = None, options_prefix: str | None = None, default_prefix: str | None = None, default_options_set: DefaultOptionSet | None = None) → None¶

Set up a PETSc object from the options in its OptionsManager.

Calls obj.setOptionsPrefix and obj.setFromOptions whilst inside the inserted_options context manager, which ensures that all options from parameters are in the global PETSc.Options dictionary.

If neither parameters nor options_prefix are provided, assumes that attach_options has been called with obj. If either parameters and/or options_prefix are provided, then attach_options is called before setting up the obj.

Parameters:

obj – The PETSc object to call setFromOptions on.
parameters – The dictionary of parameters to use.
options_prefix – The options prefix to use for this object.
default_prefix – Base string for autogenerated default prefixes.
default_options_set – The prefix set for any default shared with other solvers.

Raises:

petsctools.PetscToolsException – If the neither parameters nor options_prefix are provided but obj does not have an OptionsManager attached.

petsctools.options module¶

petsctools

Navigation

Related Topics