armi.settings.setting module

System to handle basic configuration settings.

Notes

The type of each setting is derived from the type of the default value. When users set values to their settings, ARMI enforces these types with schema validation. This also allows for more complex schema validation for settings that are more complex dictionaries (e.g. XS, rx coeffs).

class armi.settings.setting.Option(option, settingName)

Bases: tuple

Create new instance of Option(option, settingName)

option

Alias for field number 0

settingName

Alias for field number 1

class armi.settings.setting.Default(value, settingName)

Bases: tuple

Create new instance of Default(value, settingName)

settingName

Alias for field number 1

value

Alias for field number 0

class armi.settings.setting.Setting(name, default, description, label=None, options=None, schema=None, enforcedOptions=False, subLabels=None, isEnvironment=False, oldNames: Optional[List[Tuple[str, Optional[date]]]] = None)

Bases: object

A particular setting.

Initialize a Setting object.

Parameters:

• name (str) – the setting’s name

• default (object) – The setting’s default value

• description (str) – The description of the setting

• label (str, optional) – the shorter description used for the ARMI GUI

• options (list, optional) – Legal values (useful in GUI drop-downs)

• schema (callable, optional) – A function that gets called with the configuration VALUES that build this setting. The callable will either raise an exception, safely modify/update, or leave unchanged the value. If left blank, a type check will be performed against the default.

• enforcedOptions (bool, optional) – Require that the value be one of the valid options.

• subLabels (tuple, optional) – The names of the fields in each tuple for a setting that accepts a list of tuples. For example, if a setting is a list of (assembly name, file name) tuples, the sublabels would be (“assembly name”, “file name”). This is needed for building GUI widgets to input such data.

• isEnvironment (bool, optional) – Whether this should be considered an “environment” setting. These can be used by the Case system to propagate environment options through command-line flags.

• oldNames (list of tuple, optional) – List of previous names that this setting used to have, along with optional expiration dates. These can aid in automatic migration of old inputs. When provided, if it is appears that the expiration date has passed, old names will result in errors, requiring to user to update their input by hand to use more current settings.

property underlyingType

Useful in categorizing settings, e.g. for GUI.

property containedType

The subtype for lists.

property default

property value

setValue(val)

Set value of a setting.

This validates it against its value schema on the way in.

Some setting values are custom serializable objects. Rather than writing them directly to YAML using YAML’s Python object-writing features, we prefer to use our own custom serializers on subclasses.

addOptions(options: List[Option])

Extend this Setting’s options with extra options.

addOption(option: Option)

Extend this Setting’s options with an extra option.

changeDefault(newDefault: Default)

Change the default of a setting, and also the current value.

dump()

Return a serializable version of this setting’s value.

Override to define custom deserializers for custom/compund settings.

revertToDefault()

Revert a setting back to its default.

Notes

Skips the property setter because default val should already be validated.

isDefault()

Returns a boolean based on whether or not the setting equals its default value.

It’s possible for a setting to change and not be reported as such when it is changed back to its default. That behavior seems acceptable.

property offDefault

Return True if the setting is not the default value for that setting.

getCustomAttributes()

Hack to work with settings writing system until old one is gone.

getDefaultAttributes()

Additional hack, residual from when settings system could write settings definitions.

This is only needed here due to the unit tests in test_settings.

class armi.settings.setting.FlagListSetting(name, default, description=None, label=None, oldNames: Optional[List[Tuple[str, Optional[date]]]] = None)

Bases: Setting

Subclass of Setting convert settings between flags and strings.

static schema(val) → List[Flags]

Return a list of Flags <armi.reactor.flags.Flags.

Raises:

• TypeError – When val is not a list.

• ValueError – When val is not an instance of str or Flags.

dump() → List[str]

Return a list of strings converted from the flag values.