Configuration object

Every knob of the library in one object, hippymfem.config.

The library reads its HIPPYMFEM_* environment variables in a dozen modules. This object names each one as an attribute with a one-line description: hm.config.parmat_device reads the current setting, hm.config.parmat_device = "copy" changes it (through the module’s own setter, so it takes effect exactly as the environment variable would), and hm.config.show() prints them all with their values and sources, which is what a bug report should carry.

Some settings are read by XLA or MPI before the library can act and are therefore import-time only: the device, hypre on the device, JAX’s memory fraction, GPU pinning, the node’s GPU count, PETSc. They appear here read-only, with the environment variable to set before import hippymfem; tools/mpirun_pinned.sh sets the per-rank ones at the launcher. The owning modules are imported on first use, so importing this module loads nothing.

hippymfem.config.FLAG_TRUE = ('1', 'yes', 'true', 'on')

the spellings of an on/off setting, in any case

hippymfem.config.parse_flag(value, default, name='the setting')

The one reading of an on/off setting, at import and by the setters alike: True for 1, yes, true or on, False for 0, no, false or off (any case, spaces around ignored), default for an empty value or None. Anything else raises, naming name, so that a mistyped value does not quietly select one of the two.

hippymfem.config.env_flag(name, default)

parse_flag() of the environment variable name.

hippymfem.config.parse_tristate(value, name='the setting')

"auto", "1" or "0" for a setting that is on, off, or left to the library: auto or an empty value, a spelling of on, a spelling of off (parse_flag()’s). Anything else raises, naming name.

hippymfem.config.env_tristate(name)

parse_tristate() of the environment variable name.

hippymfem.config.env_choice(name, default, allowed)

The environment variable name, lowercased, or default. A value that is not allowed raises, so that a mistyped route name does not select another one.

hippymfem.config.PROFILES = {'default': ("the library's own defaults", {}), 'gpu': ("element Hessians at the quadrature points and, where a single-precision hypre is named in HIPPYMFEM_HYPRE_SINGLE, the Jacobians and their solves in single precision with the chunk planner set for single-precision tangents, and where hypre runs on the card (HIPPYMFEM_HYPRE_DEVICE) BoomerAMG with l1-Jacobi weight 1.8 for the CG solvers (HIPPYMFEM_AMG_CG; on an L40S 21 to 31 % fewer iterations and 9 to 24 % less time a solve with its set-up on twelve symmetric positive definite operators; GMRES keeps MFEM's settings)", {'HIPPYMFEM_AD_WORKING_SET': ('8', 'HIPPYMFEM_HYPRE_SINGLE'), 'HIPPYMFEM_AMG_CG': ('relax_wt=1.8', 'HIPPYMFEM_HYPRE_DEVICE'), 'HIPPYMFEM_HESSIAN': 'quadrature', 'HIPPYMFEM_PRECISION': ('mixed', 'HIPPYMFEM_HYPRE_SINGLE')}), 'gpu-large': ("'gpu' and the solver settings of the weak-scaling series on Frontier to 4096 GPUs: BoomerAMG with l1-Jacobi weight 1.8 and six interpolation entries a row for the CG solvers (HIPPYMFEM_AMG_CG; GMRES keeps MFEM's settings, with which it converges on convection-dominated problems where that weight stalls it), in the single-precision solves the p-multigrid over up to seven meshes of a uniformly refined mesh (BoomerAMG where there are none) with its small levels in host memory, the prior's cycles over the meshes, and with a single-precision hypre the blocks of a linearization point in single precision; with a hypre built with tools/hypre-3.2.0-seqdevice.patch add seq_threshold=30000,redundant=1 to HIPPYMFEM_SINGLE_AMG", {'HIPPYMFEM_AD_WORKING_SET': ('8', 'HIPPYMFEM_HYPRE_SINGLE'), 'HIPPYMFEM_AMG_CG': 'relax_wt=1.8,pmax=6', 'HIPPYMFEM_HESSIAN': 'quadrature', 'HIPPYMFEM_PMG': '1', 'HIPPYMFEM_PMG_H': '7', 'HIPPYMFEM_PMG_H_HOST': '5000', 'HIPPYMFEM_PRECISION': ('mixed', 'HIPPYMFEM_HYPRE_SINGLE'), 'HIPPYMFEM_PRIOR_H': '7', 'HIPPYMFEM_SINGLE_AMG': 'pmax=8,interp=18', 'HIPPYMFEM_SINGLE_BLOCKS': ('1', 'HIPPYMFEM_HYPRE_SINGLE')})}

Named sets of defaults, by environment variable. A profile fills in what the environment leaves unset, so an explicit setting always wins: HIPPYMFEM_PROFILE=<name> before import hippymfem reaches every knob, the import-time ones included; hm.config.use_profile(name) afterwards sets the runtime ones. A value given as (value, needs) is used only where the environment variable needs is set (mixed precision only with a single-precision hypre named). What changes the discrete problem (a lumped prior mass) or belongs to a solver call (tolerances, Newton-CG parameters) is not in a profile: see the GPU guide’s “Recommended settings”.

hippymfem.config.EXPLICIT = {}

The environment variables of the knobs set through hippymfem.config in this process: a profile applied afterwards leaves them, and show reports them as set.

hippymfem.config.apply_profile_env(name=None, environ=None)

Fill in the environment variables of a profile (default: HIPPYMFEM_PROFILE) that environ (default os.environ) leaves unset or empty, and return them. import hippymfem calls it first, before any module reads its variables.

class hippymfem.config.Config

Bases: object

The knobs as attributes; see the module docstring. show() prints them.

property knobs

The knob descriptions, in display order.

as_dict(load=True)

{name: value}; with load=False the knobs whose module is not imported yet report "(unloaded)" instead of importing it (and JAX).

profiles()

{name: description} of the named sets of defaults (PROFILES).

use_profile(name)

Apply a profile after import hippymfem: each runtime knob it names that the environment leaves unset (or that another profile set), and that was not set through hippymfem.config, takes its value; an import-time knob is left as it is, with a warning, since it is read before. Returns {knob: value} of what was set.

show(file=None, load=True)

Print every knob: its value; where the value comes from (set through this object, profile <name>, env or default); when it is read; what it does; and its environment variable. Put the output in a bug report.