Application Parameters

Input to any application is passed using a special object, which is referred to as the parameter set. These parameter objects contain simple data records (keyword value pairs), as well as methods (function calls) which are used to set more complicated input.

Creating an Application Parameter Set

There are currently two ways to obtain a parameter set for a specific application, as discussed in the following sections.

Using the global application parameters

Each application module (in the applications package), contains an instance of its own set of input parameters, which is immediately available upon a global import, as the symbol parameters:

from applications.target_app import *

parameters.project_name = 'my_name'

In this case, there is no need to manually construct the parameter set.

Attention

Although this method is still fully supported and is perfectly safe in most instances, it can potentially cause problems when importing one or more applications of the same type into other script. This is because, since parameters is global, it is overwritten by subsequent imports. Although rare, there are some applications (e.g docgen) that can combine input and output from multiple applications, in which case Creating a unique parameter set should be used.

Creating a unique parameter set

Instead of using the global parameters directly, a unique copy can be created as follows:

import applications.target_app as app

parameters = app.parameters()
parameters.project_name = 'my_name'

Note

When using this method, the copy need not be named parameters, since it is just another variable. For example,

app_param = app.parameters()

is also perfectly legal. In order to distinguish between different application parameter set, this approach will be used throughout this manual.

General Parameters

Although each application has a slightly different interface, they all share a common set of parameters, which sets and customizes the underlying model, determines where input will be generated, set options that will be passed to the target analysis code, and customize how the application should be launched. These are described further in the following sections.

Note

In the following app_param denote an instance of the application’s parameter set, instantiated through the mechanism described in Creating a unique parameter set.

General application parameters.
Category	Parameters
Model setup	`app_param.model` `app_param.time_stamp`
Input generation	`app_param.config_file` `app_param.target_mode` `app_param.project_name` `app_param.working_directory`
Execution	`app_param.executable` `app_param.arguments` `app_param.host_directory` `app_param.use_rsync` `app_param.threads` `app_param.nodes` `app_param.walltime` `app_param.queue`
Numerics	`app_param.particles` `app_param.source_iteration` `app_param.max_iteration` `app_param.max_feedback_iteration` `app_param.convergence_criteria` `app_param.error_tolerance` `app_param.bank_search`
Physics	`app_param.doppler_broadening` `app_param.use_stochastic_mixing` `app_param.cross_section_library` `app_param.decay_data_library` `app_param.fission_product_yields` `app_param.thermal_hydraulic_feedback` `app_param.thermal_hydraulic_options`

app_param.model : ModelBuilder 

The model that your application will use. This is a large sub section which contains all data related to building and customizing the model. See Building Core Configurations.

The recommended method is to start with a predefined model. For instance,

from .configurations.my_configuration import model

app_param.model = model

This avoids cluttering the application script with model specific input. You can however modify the model, for instance

parameters.model.set_banks(core.control.fully_extracted())

will fully extract all the banks for this particular application.

Since some applications will use a simplified or heavily customized model, by default the app_param.model is an empty ModelBuilder instance, allowing you to construct the model in the script. See Building Core Configurations.

app_param.time_stamp : datetime : The real model date and time which this input or application is attached to. This parameter is required when certain model elements (model.load_map, etc), should be deduced from the facility loading data base. See the model.facility_manager parameter, and the Facility Management application mode for additional information.

app_param.config_file : filepath 

Host configuration file. The configuration file configures target modes for the application’s intended execution host (local or remote). Thus, it affects both input generation and application launch. If nothing is specified, the system configuration file is used, and the local host is assumed. See Configuring Hosts for details on customizing configuration files.

This parameter is most frequently set on the command line, but when specifying it in the script make sure to pass the full path to the configuration file.

app_param.target_mode : string = 'SERPENT': Specify for which underlying code input should be generated. This must either be a build-in mode, or a mode configured in the app_param.config_file.

app_param.project_name : string : Input project name. This parameter is used as a basis to name files generated by the system. It is highly recommended that you set this parameter to something that uniquely identifies the project.

Changed in version 1.2: If the value is not explicitly specified, it will default to to the input script name.

app_param.input_file_name : string : Name of the input file the project will write to. Defaults to app_param.project_name with the extension .i.

app_param.working_directory : directory 

Sets the working directory for your application. In particular, all input, output and data files will be written to this directory. It is usually specified relative to the script:

parameters.working_directory = core.utilities.path_relative_to(__file__, 'my_working_directory')

Note

A sub directory will be created under app_param.working_directory for each target code, so this parameter is app_param.target_mode independent.

Changed in version 1.2: If the value is not explicitly specified, it will default to a full caps version of the input script (module) name, in the same directory as the script.

app_param.executable : string : Full path to target executable. Defaults to the value specified in app_param.config_file.

Attention

Since this parameter is specific to the execution host, it is better to use the values derived from your configuration file. Otherwise, your script will not be portable.

app_param.arguments : string : Optional argument string that will be passed to the executable.

app_param.host_directory : directory : Run directory on the remote machine. The default host directory is <directory>/project_name/<timestamp> where directory is the base remote directory is specified in the configuration file , and timestamp is the current date and time at launch.

Note

This parameter is only used when the execution host differs from the local host.

app_param.use_rsync : bool = False

Use the rsync protocol to copy files to and from a remote host. This can significantly speed up the transfer of files to a remote host. .. attention:

This mode is not supported on Windows.

app_param.threads : integer = 1: Number of threads (cores) application should use. This parameter applies to any machine with multiple cores.

app_param.nodes : integer = 1: Number of compute nodes application should use. This parameter is only applicable to a machine or server that has MPI configured.

app_param.walltime : float : Maximum run time (in hours) allocated for the application. Only applicable when the target host is a cluster.

Note

If this parameter is not specified, the default value for the specified queue will be used. This value is set by the system administrator, and for large clusters can be quite restrictive. It is therefore recommended that, if the cluster implements a wall time cutoff, you manually specify this parameter.

app_param.queue : string : Job queue application should be launched to. Only applicable when the target host uses a job management system. Defaults to the value specified in app_param.config_file.

app_param.source_iteration : integer = 50: Number of source convergence cycles. The way in which this parameter is used depends on the target code, but is always related to convergence (at a fixed state) of the fission source. For instance, in Monte Carlo simulations, it is mapped to the inactive cycle input, while in MGRAC it affects the number of inner and outer iterations.

app_param.max_iteration : integer = 100: General parameter specifying the maximum iterations.

app_param.max_feedback_iteration : integer = 75: The maximum number of cross section update iterations, used when resolving temperature and other non-linear feedback effects.

app_param.particles : integer = 16000: Number of source particles per iteration step.

app_param.convergence_criteria : float = 1.0E-5: Iteration convergence criteria. Used to determine iteration stopping criteria were applicable.

app_param.error_tolerance : float = 1.0E-5: General error tolerance parameter.

app_param.bank_search : bool or float = False

Set up bank critical searches. It can be switched on by setting it to True, or by passing the target \(k_{eff}\). Once switched on, the following sub-parameters can be set:

bank_search.target_keff : float = 1.00: The target effective multiplication factor (\(k_{eff}\)).

bank_search.banks : list [string] : List of bank names that can be searched. If not specified, all banks will be searched.

bank_search.continue_on_failure : bool = False: Flag indicating that the simulation should continue even when the search iteration fails to reach the app_param.bank_search.target_keff.

app_param.doppler_broadening : bool = True: Use (automatic) Doppler resonance broadening if available.

app_param.use_stochastic_mixing : bool = False

For target codes that does not support automatic app_param.doppler_broadening, or does not use libraries that support temperature interpolation, this technique can be used to better capture temperature effects in materials.

Although its use can be customized per target mode, it is typically implemented as follows:

For each isotope in the material composition, let \(T_l < T < T_u\) denote the temperatures closest to the target temperature \(T\) at which cross section libraries are available.

Then, when writing the material composition, two entries are created for the isotope, one pointing to the library at \(T_l\), with density scaled by

\[w_l = \frac{T_u - T}{T_u-T_l},\]

and another pointing to the library at \(T_u\), with density scaled by \(w_u = 1 - w_l\).

This will effectively model a linear interpolation between these two libraries.

Attention

If this flag is not switched on, the isotope library with temperature closest to the target temperature will be used. Thus, it is recommended that this mechanism is used if the temperature steps between subsequent libraries are large.

app_param.cross_section_library : filepath : Path to cross section library or directory file. Defaults to the value specified in app_param.config_file.

Attention

Since this parameter is specific to the execution host, it is better to use the values derived from your configuration file. Otherwise, your script will not be portable.

app_param.decay_data_library : filepath : Path to additional decay data if applicable. Defaults to the value specified in app_param.config_file.

Attention

Since this parameter is specific to the execution host, it is better to use the values derived from your configuration file. Otherwise, your script will not be portable.

app_param.fission_product_yields : filepath : Path to additional fission product yield data if applicable. Defaults to the value specified in app_param.config_file.

Attention

Since this parameter is specific to the execution host, it is better to use the values derived from your configuration file. Otherwise, your script will not be portable.

app_param.thermal_hydraulic_feedback : bool or tuple (state) = False

Switch thermal-hydraulic feedback on or off. Instead of passing True, which will switch on all feedback effects, individual effects can be switched on by passing a tuple of state tags. For example, to switch on only doppler feedback:

app_param.thermal_hydraulic_feedback = state_param.fuel_temperature,

and to switch on doppler and moderator temperature feedback,

app_param.thermal_hydraulic_feedback = state_param.fuel_temperature, state_param.moderator_temperature

app_param.thermal_hydraulic_options

Extra options that are used when app_param.thermal_hydraulic_feedback is active.

app_param.calculate_hot_channel : bool = False: Also include a hot channel estimate in the calculation. The definition of a coolant channel, depends on the assembly design.

app_param.heat_transfer_correlation : string : When performing heat transfer calculations for feedback within the target code, use the selected correlation

app_param.safety_correlation : string : When estimating the distance to the relevant operating temperature limit within the target code, use the selected correlation

Note

Target codes will only make use of these parameters if it makes sense to them, for instance, a nodal diffusion code will ignore the app_param.particles parameter.

Activating documentation input

The generation of a document associated with the current application is activated by calling:

app_param.doc_parameters(): This will setup, and return a docgen parameter set. The