petsctools package¶

Submodules¶

petsctools.citation module¶

Module containing functions for registering citations through PETSc.

The functions in this module may be used to record Bibtex citation information and then register that a particular citation is relevant for a particular computation. It hooks up with PETSc’s citation registration mechanism, so that running with -citations does the right thing.

Example usage:

petsctools.add_citation("key", "bibtex-entry-for-my-funky-method")

...

if using_funky_method:
    petsctools.cite("key")

petsctools.citation.add_citation(cite_key: str, entry: str) → None¶

Add a paper to the database of possible citations.

Parameters:

cite_key – The key to use.
entry – The bibtex entry.

petsctools.citation.cite(cite_key: str) → None¶

Cite a paper.

The paper should already have been added to the citations database using add_citation.

Parameters:: cite_key – The key of the relevant citation.
Raises:: KeyError : – If no such citation is found in the database.

petsctools.citation.print_citations_at_exit() → None¶: Print citations at the end of the program.

petsctools.config module¶

exception petsctools.config.MissingPetscException¶: Bases: PetscToolsException

petsctools.config.get_blas_library()¶: Get the path to the BLAS library that PETSc links to.

petsctools.config.get_config()¶

petsctools.config.get_external_packages()¶: Return a list of PETSc external packages that are installed.

petsctools.config.get_petsc_arch()¶

petsctools.config.get_petsc_dir()¶

petsctools.config.get_petscconf_h()¶

Get dict of PETSc include variables from the file: $PETSC_DIR/$PETSC_ARCH/include/petscconf.h

The #define and PETSC_ prefix are dropped in the dictionary key.

The result is memoized to avoid constantly reading the file.

petsctools.config.get_petscvariables()¶: Return PETSc’s configuration information.

petsctools.exceptions module¶

exception petsctools.exceptions.PetscToolsException¶

Bases: Exception

Generic base class for petsctools exceptions.

exception petsctools.exceptions.PetscToolsNotInitialisedException¶

Bases: PetscToolsException

Exception raised when petsctools should have been initialised.

exception petsctools.exceptions.PetscToolsWarning¶

Bases: UserWarning

Generic base class for petsctools warnings.

petsctools.init module¶

exception petsctools.init.InvalidEnvironmentException¶: Bases: PetscToolsException

exception petsctools.init.InvalidPetscVersionException¶: Bases: PetscToolsException

petsctools.init.check_environment_matches_petsc4py_config()¶

petsctools.init.check_petsc_version(version_spec) → None¶

petsctools.init.init(argv=None, *, version_spec='')¶: Initialise PETSc.

petsctools.options module¶

class petsctools.options.OptionsManager(parameters: dict, options_prefix: str | 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.
options_prefix – The prefix to look up items in the global options database (may be None, in which case only entries from parameters will be considered. 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.

count = count(0)¶

inserted_options()¶: Context manager inside which the petsc options database contains the parameters from this object.

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.

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

Raises PetscToolsWarning if this method has already been called.

Matt says: “Only ever call setFromOptions once”. This function ensures we do so.

petsctools.options.attach_options(obj: petsc4py.PETSc.Object, parameters: dict | None = None, options_prefix: str | 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.

See also

OptionsManager

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_options(obj: petsc4py.PETSc.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:: PetscToolsException – If the object does not have an OptionsManager.

See also

OptionsManager

petsctools.options.has_options(obj: petsc4py.PETSc.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.

See also

OptionsManager

petsctools.options.inserted_options(obj)¶: Context manager inside which the PETSc options database contains the parameters from this object’s OptionsManager.

See also

OptionsManager, OptionsManager.inserted_options

petsctools.options.is_set_from_options(obj: petsc4py.PETSc.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:: PetscToolsException – If the object does not have an OptionsManager.

See also

OptionsManager

petsctools.options.petscobj2str(obj: petsc4py.PETSc.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: petsc4py.PETSc.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:

PetscToolsException – If the object does not have an OptionsManager.

petsctools.options.set_from_options(obj: petsc4py.PETSc.Object, parameters: dict | None = None, options_prefix: str | 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.

Raises:

PetscToolsException – If the neither parameters nor options_prefix are provided but obj does not have an OptionsManager attached.
PetscToolsException – If the either parameters or options_prefix are provided but obj already has an OptionsManager attached.
PetscToolsWarning – If set_from_options has already been called for this object.

petsctools package¶

Submodules¶

petsctools.citation module¶

petsctools.config module¶

petsctools.exceptions module¶

petsctools.init module¶

petsctools.options module¶

petsctools.utils module¶

Module contents¶

petsctools

Navigation

Related Topics