armi.settings.setting module

System to handle basic configuration settings.

Notes

Rather than having subclases for each setting type, we simply derive the type based on the type of the default, and we enforce it with schema validation. This also allows for more complex schema validation for settings that are more complex dictionaries (e.g. XS, rx coeffs, etc.).

One reason for complexity of the previous settings implementation was good interoperability with the GUI widgets.

We originally thought putting settings definitions in XML files would help with future internationalization. This is not the case. Internationalization will likely be added later with string interpolators given the desire to internationalize, which is nicely compatible with this code-based re-implementation.

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=None, label=None, options=None, schema=None, enforcedOptions=False, subLabels=None, isEnvironment=False, oldNames: Optional[List[Tuple[str, Optional[datetime.date]]]] = None)

Bases: object

A particular setting.

Setting objects hold all associated information of a setting in ARMI and should typically be accessed through the Settings class methods rather than directly. The exception being the SettingAdapter class designed for additional GUI related functionality.

Setting subclasses can implement custom load and dump methods that can enable serialization (to/from dicts) of custom objects. When you set a setting’s value, the value will be unserialized into the custom object and when you call dump, it will be serialized. Just accessing the value will return the actual object in this case.

Initialize a Setting object.

Parameters

• name (str) – the setting’s name

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

• description (str, optional) – 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[armi.settings.setting.Option])

Extend this Setting’s options with extra options.

addOption(option: armi.settings.setting.Option)

Extend this Setting’s options with an extra option.

changeDefault(newDefault: armi.settings.setting.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[datetime.date]]]] = None)

Bases: armi.settings.setting.Setting

Subclass of Setting convert settings between flags and strings.

Initialize a Setting object.

Parameters

• name (str) – the setting’s name

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

• description (str, optional) – 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.

static schema(val) → List[armi.reactor.flags.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.