armi.cases.suiteBuilder module

Contains classes that build case suites from perturbing inputs.

The general use case is to create a SuiteBuilder with a base Case, use addDegreeOfFreedom() to adjust inputs according to the supplied arguments, and finally use .buildSuite to generate inputs. The case suite can then be discovered, submitted, and analyzed using the standard CaseSuite objects.

This module contains a variety of InputModifier objects as well, which are examples of how you can modify inputs for parameter sweeping. Power-users will generally make their own Modifiers that are design-specific.

armi.cases.suiteBuilder.getInputModifiers(cls)

class armi.cases.suiteBuilder.SuiteBuilder(baseCase)

Bases: object

Class for constructing a CaseSuite from combinations of modifications on base inputs.

Variables:

• baseCase (armi.cases.case.Case) – A Case object to perturb

• modifierSets (list(tuple(InputModifier))) – Contains a list of tuples of InputModifier instances. A single case is constructed by running a series (the tuple) of InputModifiers on the case.

Notes

This is public such that someone could pop an item out of the list if it is known to not work, or be unnecessary.

addDegreeOfFreedom(inputModifiers)

Add a degree of freedom to the SweepBuilder.

The exact application of this is dependent on a subclass.

Parameters:

inputModifiers (list(callable(Settings, Blueprints, SystemLayoutInput))) – A list of callable objects with the signature (Settings, Blueprints, SystemLayoutInput). When these objects are called they should perturb the settings, blueprints, and/or geometry by some amount determined by their construction.

addModifierSet(inputModifierSet: List)

Add a single input modifier set to the suite.

Used to add modifications that are not necessarily another degree of freedom.

buildSuite(namingFunc=None)

Builds a CaseSuite based on the modifierSets contained in the SuiteBuilder.

For each sequence of modifications, this creates a new Case from the baseCase, and runs the sequence of modifications on the new Case’s inputs. The modified Case is then added to a CaseSuite. The resulting CaseSuite is returned.

Parameters:

namingFunc (callable(index, case, tuple(InputModifier)), (optional)) –

Function used to name each case. It is supplied with the index (int), the case (Case), and a tuple of InputModifiers used to edit the case. This should be enough information for someone to derive a meaningful name.

The function should return a string specifying the path of the Settings, this allows the user to specify the directories where each case will be run.

If not supplied the path will be ./case-suite/<0000>/<title>-<0000>, where <0000> is the four-digit case index, and <title> is the baseCase.title.

Raises:

RuntimeError – When order of modifications is deemed to be invalid.

Returns:

caseSuite – Derived from the baseCase and modifications.

Return type:

CaseSuite

class armi.cases.suiteBuilder.FullFactorialSuiteBuilder(baseCase)

Bases: SuiteBuilder

Builds a suite that has every combination of each modifier.

addDegreeOfFreedom(inputModifiers)

Add a degree of freedom to the SuiteBuilder.

Creates the Cartesian product of the inputModifiers supplied and those already applied.

For example:

class SettingModifier(InputModifier):

    def __init__(self, settingName, value):
        self.settingName = settingName
        self.value = value

    def __call__(self, cs, bp, geom):
        cs = cs.modified(newSettings={self.settingName: self.value})
        return cs, bp, geom

builder = FullFactorialSuiteBuilder(someCase)
builder.addDegreeOfFreedom(SettingModifier('settingName1', value) for value in (1,2))
builder.addDegreeOfFreedom(SettingModifier('settingName2', value) for value in (3,4,5))

would result in 6 cases:

Index	settingName1	settingName2
0	1	3
1	2	3
2	1	4
3	2	4
4	1	5
5	2	5

See also

SuiteBuilder.addDegreeOfFreedom

class armi.cases.suiteBuilder.FullFactorialSuiteBuilderNoisy(baseCase, noiseFraction)

Bases: FullFactorialSuiteBuilder

Adds a bit of noise to each independent variable to avoid duplicates.

This can be useful in some statistical postprocessors.

Warning

Use with caution. This is part of ongoing research.

addDegreeOfFreedom(inputModifiers)

class armi.cases.suiteBuilder.SeparateEffectsSuiteBuilder(baseCase)

Bases: SuiteBuilder

Varies each degree of freedom in isolation.

addDegreeOfFreedom(inputModifiers)

Add a degree of freedom to the SuiteBuilder.

Adds a case for each modifier supplied.

For example:

class SettingModifier(InputModifier):

    def __init__(self, settingName, value):
        self.settingName = settingName
        self.value = value

    def __call__(self, cs, bp, geom):
        cs = cs.modified(newSettings={self.settignName: self.value})
        return cs, bp, geom

builder = SeparateEffectsSuiteBuilder(someCase)
builder.addDegreeOfFreedom(SettingModifier('settingName1', value) for value in (1,2))
builder.addDegreeOfFreedom(SettingModifier('settingName2', value) for value in (3,4,5))

would result in 5 cases:

Index	settingName1	settingName2
0	1	default
1	2	default
2	default	3
3	default	4
4	default	5

See also

SuiteBuilder.addDegreeOfFreedom

class armi.cases.suiteBuilder.LatinHyperCubeSuiteBuilder(baseCase, size)

Bases: SuiteBuilder

Implements a Latin Hypercube Sampling suite builder.

This method is used to provide a more efficient sampling of the design space. LHS more efficiently samples the space evenly across dimensions compared to random sampling. It requires fewer points than a full factorial since it samples quasi-randomly into nonoverlapping partitions. It is recommended to use a surrogate model with the sampled data to get the full benefit.

Variables:

modifierSets (An array of InputModifiers specifying input parameters.) –

addDegreeOfFreedom(inputModifiers)

Add a degree of freedom to the SuiteBuilder.

Unlike other types of suite builders, only one instance of a modifier class should be added. This is because the Latin Hypercube Sampling will automatically perturb the values and produce modifier sets internally. A settings modfier class passed to this method need include bounds by which the LHS algorithm can perturb the input parameters.

For example:

class InputParameterModifier(SamplingInputModifier):

    def __init__(
        self,
        name: str,
        pararmType: str, # either 'continuous' or 'discrete'
        bounds: Optional[Tuple, List]
    ):
        super().__init__(name, paramType, bounds)

    def __call__(self, cs, bp, geom):
        ...

If the modifier is discrete then bounds specifies a list of options the values can take. If continuous, then bounds specifies a range of values.

buildSuite(namingFunc=None)

Builds a CaseSuite based on the modifierSets contained in the SuiteBuilder.

For each sequence of modifications, this creates a new Case from the baseCase, and runs the sequence of modifications on the new Case’s inputs. The modified Case is then added to a CaseSuite. The resulting CaseSuite is returned.

Parameters:

namingFunc (callable(index, case, tuple(InputModifier)), (optional)) –

Function used to name each case. It is supplied with the index (int), the case (Case), and a tuple of InputModifiers used to edit the case. This should be enough information for someone to derive a meaningful name.

The function should return a string specifying the path of the Settings, this allows the user to specify the directories where each case will be run.

If not supplied the path will be ./case-suite/<0000>/<title>-<0000>, where <0000> is the four-digit case index, and <title> is the baseCase.title.

Raises:

RuntimeError – When order of modifications is deemed to be invalid.

Returns:

caseSuite – Derived from the baseCase and modifications.

Return type:

CaseSuite