Settings#

Module pianistpy.settings

The numerical settings of a computation: the default settings, the quick settings, and single fields changed by an expert.

A user passes a Settings object to a computation, for example pp.solve(component, settings=pp.Settings(quick=True)). The default settings and the quick settings are the two tested settings levels: the package states the accuracy of each level from its test suite. The quick settings use fewer nodes and rows than the default settings and hold every check of a result to the same bounds, \(10^{-6}\), \(10^{-4}\) and \(10^{-2}\). The manual’s settings tables list every field with its value at each level.

class pianistpy.settings.Field(default, doc, quick=None)#

One numerical setting: its value at each settings level and a description of what the setting controls.

Parameters:

default (bool, int, float or str) – The field’s value in the default settings. The type of default is the type every value of the field must have.
doc (str) – A description of what the field controls, as the manual’s settings tables print it.
quick (bool, int, float or str, optional) – The field’s value in the quick settings. Default: None, which means the quick settings use the value default.

See also

Settings: The settings of a computation.
FIELDS: Every field of every group.

Examples

>>> field = FIELDS["sampling"]["n_nodes"]
>>> field.value("default"), field.value("quick")
(2048, 512)

value(level)#

Return the field’s value at a settings level.

Parameters:: level ({"default", "quick"}) – The settings level.
Returns:: value – The field’s value in the quick settings if level is "quick" and the field has a quick value; the field’s value in the default settings otherwise.
Return type:: bool, int, float or str

class pianistpy.settings.Settings(quick=False, write_anyway=False, check_rows=False, **overrides)#

The numerical settings of a computation.

A Settings object starts from one of the two tested settings levels, the default settings or the quick settings, and may change single fields of a group. A result records its settings; a result made with a changed field records that its settings are not a tested settings level and lists each changed field.

Parameters:

quick (bool, optional) – Whether the settings start from the quick settings. Default: False, which means the settings start from the default settings.
write_anyway (bool, optional) – Whether a computation returns a result whose own check is above \(10^{-2}\) instead of raising AccuracyError. The returned result’s validation report has the band "refused", and an AccuracyWarning is issued in place of the error. A model that is not a physical equilibrium raises UnphysicalModelError whatever the value of write_anyway. Default: False, which means a result above \(10^{-2}\) raises AccuracyError.
check_rows (bool, optional) – Whether a gradient through a LosTable recomputes each line-of-sight velocity distribution the gradient reads and compares the recomputed distribution with the stored distribution. A recomputed distribution must equal the stored distribution bit for bit, and a JAX copy of the distribution’s computation (the twin that carries the derivative) must agree with the stored distribution to \(10^{-12}\) of the distribution’s largest value; otherwise the gradient raises ResultError. The gradient’s value is the same with and without the comparison; the comparison computes each distribution read a second time. Default: False, which means no distribution is recomputed.
**overrides (mapping) – For each group to change (inversion, truncation, sampling, observables or losvd), a mapping from field name to new value. The manual’s settings tables list every field. Default: no override, which means every field has its value at the settings level.

Variables:

level ({"default", "quick"}) – The settings level the settings start from.
write_anyway (bool) – Whether a result above \(10^{-2}\) is returned instead of raising AccuracyError.
check_rows (bool) – Whether a gradient through a LosTable recomputes and compares each distribution the gradient reads.
overrides (mapping) – For each changed group, the changed fields and their values. Read only.
is_tested_level (bool) – Whether no field is changed from the settings level.

Raises:

InputError – If write_anyway or check_rows is not a bool.
InputError – If a keyword of overrides is not a group name.
InputError – If a field of an override is not a field of the override’s group.
InputError – If an override’s value does not have the type of the field’s default value (an int is accepted for a float field).
InputError – If a number override is zero or negative, except a field whose name starts with log10_ and the value 0 of innermost_read_radius and outer_mass_share.

See also

FIELDS: Every field of every group with its value at each level.
LEVELS: The names of the two tested settings levels.

Examples

>>> Settings().level
'default'
>>> Settings(quick=True).is_tested_level
True
>>> Settings(inversion={"n_nodes": 256}).is_tested_level
False
>>> Settings(inversion={"n_nodes": 256}).inversion["n_nodes"]
256
>>> Settings().truncation["ode_rtol"]
1e-11

property level: str#: The settings level the settings start from, "default" or "quick".

property write_anyway: bool#: Whether a result above \(10^{-2}\) is returned instead of raising AccuracyError.

property check_rows: bool#: Whether a gradient through a LosTable recomputes and compares each distribution the gradient reads.

property overrides: Mapping[str, Mapping[str, Any]]#: For each changed group, the changed fields and their values.

property is_tested_level: bool#: Whether no field is changed from the settings level.

group(name)#

Return the value in force of every field of one group.

Parameters:: name ({"inversion", "truncation", "sampling", "observables", "losvd"}) – The group’s name.
Returns:: values – Each field of the group mapped to the field’s override if the settings change the field, and to the field’s value at the settings level otherwise. Read only.
Return type:: mapping
Raises:: InputError – If name is not a group name.

See also

resolved: The values in force of every group.

Examples

>>> Settings(quick=True).group("sampling")["n_nodes"]
512

property inversion: Mapping[str, Any]#: The values in force of the group inversion.

property truncation: Mapping[str, Any]#: The values in force of the group truncation.

property sampling: Mapping[str, Any]#: The values in force of the group sampling.

property observables: Mapping[str, Any]#: The values in force of the group observables.

property losvd: Mapping[str, Any]#: The values in force of the group losvd.

resolved()#

Return the value in force of every field of every group.

Returns:: values – Each group name mapped to a dictionary of the group’s fields and their values in force.
Return type:: dict

See also

group: The values in force of one group.

Examples

>>> sorted(Settings().resolved())
['inversion', 'losvd', 'observables', 'sampling', 'truncation']

to_dict()#

Return the settings as the dictionary written to result files.

Returns:: record – The entries of numerical ("level" and "overrides"), and "write_anyway": True and "check_rows": True if the settings set those options.
Return type:: dict

See also

from_dict: The settings built from the dictionary.
numerical: The entries that determine a result’s values.

Examples

>>> Settings(quick=True, write_anyway=True).to_dict()
{'level': 'quick', 'overrides': {}, 'write_anyway': True}

numerical()#

Return the settings that determine a result’s values: the settings level and the overrides.

A result’s identity is computed from this dictionary, so that two results computed with the same level and overrides share an identity whatever their write_anyway and check_rows.

Returns:: record – The entries "level" and "overrides" (each changed group mapped to its changed fields and their values).
Return type:: dict

Examples

>>> Settings(inversion={"n_nodes": 256}).numerical()
{'level': 'default', 'overrides': {'inversion': {'n_nodes': 256}}}

classmethod from_dict(record)#

Build settings from the dictionary that to_dict writes.

Parameters:

record (mapping) – A dictionary in the form to_dict returns. A missing "level" entry is read from the entry "tier", the entry’s former name, and else as "default".

Returns:

settings – The settings the dictionary describes.

Return type:

Settings

Raises:

InputError – If the dictionary’s settings level is not one of LEVELS.
InputError – If an override in the dictionary is not accepted by Settings.

See also

to_dict: The dictionary form of settings.

Examples

>>> settings = Settings(sampling={"n_rows_max": 1000})
>>> Settings.from_dict(settings.to_dict()) == settings
True