ROLLO Input File Setup

The ROLLO input file is in JSON format. For each input file, the user must define four sections:

Control Variables
Evaluators
Constraints
Algorithm

Control Variables

Control variables are parameters the genetic algorithm will vary. For each control variable, the user must specify its minimum and maximum values. The user may define any number of control variables. The control_variables section of the ROLLO input file looks like this:

"control_variables": {
  "variable1": {"min": 0.0, "max": 10.0},
  "variable2": {"min": -1.0, "max": 0.0}
}

This demonstrates that control variables, variable1 and variable2, will be varied from 0 to 10 and -1 to 0, respectively. For example, in traditional reactor design, a control variable might be fuel enrichment.

Variable names must be strings. The following table describes each variable’s input parameter sub-requirements:

Input Parameter	Type	Description	Mandatory?
`min`	float	minimum value	yes
`max`	float	max value	yes

Evaluators

Evaluators are the nuclear software ROLLO utilizes to calculate the objective and constraint values. ROLLO is nuclear-software agnostic, and does not have any nuclear software dependencies. Thus the user may use any nuclear software as an evaluator, and it is also up to the user to ensure that the nuclear software and their corresponding executables are correctly installed. In a ROLLO input file, a user may define any number of evaluators.

For each evaluator, there are mandatory and optional input parameters. These input parameters are outlined in the following table:

Input Parameter	Type	Description	Mandatory?
`order`	int	evaluator’s operational order compared to other evaluators (indexed by 0)	yes
`inputs`	list of str	control variables to be placed into the input file template	yes
`input_script`	2-element list (containing str)	1st element: executable to run input script, 2nd element: input script template	yes
`outputs`	list of str	output variables that the evaluator will return to the genetic algorithm	yes
`output_script`	2-element list (containing str)	1st element: executable to run output script, 2nd element: output script template	no
`execute`	list of 2-element lists (containing str)	enables users to run other executables or files beyond the input and output scripts. 1st element: executable to run file, 2nd element: file to run	no

The evaluators section of the ROLLO input file looks like this:

"evaluators": {
  "evaluator_1": {
    "order": 0,
    "inputs": ["variable1", "variable2"],
    "input_script": ["python", "input_script.py"],
    "execute": [["exe1", "exe1_inp.py"], ["exe2", "exe2_inp.py"]],
    "outputs": ["output1", "output2"],
    "output_script": ["python", "output_script.py"]
    }
  }

Evaluators: Input File Templating

ROLLO utilizes Jinja2 templating to insert control variables values into the input_script. Users must include each evaluator’s input file template in the same directory as the ROLLO input file. Users must also ensure the template variables correspond to the inputs defined in the corresponding evaluator’s section in the ROLLO input file.

The following code snippets show the template and templated input scripts; once the input_script is templated, {{variable1}} and {{variable2}} will be replaced with values selected by ROLLO’s genetic algorithm.

Template

variable1 = {{variable1}}
variable1 = {{variable1}}

Templated

variable1 = 3.212
variable1 = -0.765

Evaluators: Returning Output Parameters

ROLLO uses two methods to return an output variable to the genetic algorithm. First, ROLLO will automatically return the input parameter’s value if the output parameter is also an input parameter. Second, the user may include an output script that returns the desired output parameter. The output_script must include a line that prints a dictionary containing the output parameters’ names and their corresponding value as key-value pairs:

output1_val = # some logic
output2_val = # some logic

print({"output1":output1_val, "output2":output2_val})

Constraints

The user can define constraints on any output parameter. Any individual that does not meet the defined constraints is removed from the population, encouraging the proliferation of individuals that meet the constraints. For each constrained parameter, the user lists the operator and constrained_val.

The constraints section of the ROLLO input file with two constraints looks like this:

"constraints": {
  "output1": {"operator": [">=", "<"], "constrained_val": [1.0, 1.5]},
  "output2": {"operator": ["<"], "constrained_val": [1000]}
    }

The constraints are 1.0 >= output1 > 1.5 and output2 < 1000.

The following table describes each constrained variable’s sub-requirements:

Input Parameter	Type	Description	Mandatory?
`operator`	list of str	operators for constraint	yes
`constrained_val`	list of floats	values to constrain (corresponds to operator list)	yes

Algorithm

In the algorithm section, users define the simulation’s general settings and the genetic algorithm’s hyperparameters. The algorithm section’s input parameters are outlined in the following table:

Input Parameter	Type	Description	Mandatory?	Default
`optimized_variable`	list of str	variables to be optimized	yes	n/a
`objective`	list of str	string options include: min or max. each objective corresponds to a variable in `optimized_variable`	yes	n/a
`pop_size`	int	population size	yes	n/a
`generations`	int	number of generations	yes	n/a
`parallel`	str	options include: none, multiprocessing, job control	yes	none
`keep_files`	str	options include: none, only_final, all	yes	none
`mutation_probability`	float	individual’s mutation probability (must be between 0 and 1)	no	0.23
`mating_probability`	float	individual’s mating probability (must be between 0 and 1)	no	0.47
`selection_operator`	dict	options described in sections below	no	{“operator”: ”selTournament”, ”tournsize”: 5}
`mutation_operator`	dict	options described in sections below	no	{“operator”: “mutPolynomialBounded”, “eta”: 0.23, “indpb”: 0.23}
`mating_operator`	dict	options described in sections below	no	{“operator”: “cxBlend”, “alpha”: 0.46}

The following sub-sections describe the selection, mutation, and mating operators available and their corresponding hyperparameters.

Selection Operators

There are three options for selection operator: selTournament, selBest, and selNSGA2. In tournament selection (selTournament), a user-defined number of individuals play in a tournament, and the best individual proceeds to the next population. The tournament repeats until all the population’s spots are filled. In best selection (selBest), the operator selects a user-defined number of best individuals, and copies are made to keep the population size constant. In NSGA-II selection (selNSGA2), the elitist operator selects the best individuals from the combination of parent and offspring populations. NSGA-II selection works well for multi-objective optimization.

Selection Operators	Hyperparameters	Description	Type
`selTournament`	`tournsize`	no. of individuals in each tournament	int
`selBest`	n/a	n/a	n/a
`selNSGA2`	n/a	n/a	n/a

Mutation Operators

There is one option for mutation operator: mutPolynomialBounded. Polynomial bounded mutation (mutPolynomialBounded) mutates each individual based on a polynomial distribution. The user also defines the crowding degree of the mutation, eta (a big eta will produce a mutant resembling its parent, while a small eta will produce the opposite).

Mutation Operators	Hyperparameters	Description	Type
`mutPolynomialBounded`	`eta` `indpb`	crowding degree of the mutation independent probability for each attribute to be mutated	float (btwn 0 and 1) float (btwn 0 and 1)

Mutation Operators

Hyperparameters

Description

Type

mutPolynomialBounded

eta

indpb

crowding degree of the mutation

independent probability for each attribute to be mutated

float (btwn 0 and 1)

Mating Operators

There are three options for mating operators: cxOnePoint, cxUniform, and cxBlend. In the single-point crossover (cxOnePoint), the operator randomly selects two individuals from the population and a site along the individual’s definition. For example, if the individual is a list, the operator randomly chooses an element in the list as the cross-site. Then, the attributes on the cross site’s right side are exchanged between the two individuals, creating two new offspring individuals. In a uniform crossover (cxUniform), the user defines an independent exchange probability for each individual’s attribute. In blend crossover (cxBlend), the operator creates two offspring (O) individuals based on a linear combination of two-parent (P) individuals using the following equations:

\(O_1 = P_1 - \alpha(P_1-P_2)\) \(O_2 = P_2 + \alpha(P_1-P_2)\)

where:

\(\alpha =\) Extent of the interval in which the new values can be drawn for each attribute on both side of the parents’ attributes (user-defined)

Mating Operators	Hyperparameters	Description	Type
`cxOnePoint`	n/a	n/a	n/a
`cxUniform`	`indpb`	independent probability for each attribute to be exchanged	float (btwn 0 and 1)
`cxBlend`	`alpha`	Extent of the interval that the new values can be drawn for each attribute on both sides of the parents’ attributes	float (btwn 0 and 1)

ROLLO v1.0 documentation

ROLLO Input File Setup

Contents