Background

Introduction

The Rapyds platform is the component of the OSCAR-5 system that provides an interface between the reactor data model and specific simulation tools/codes.

An appropriate simulation solver is chosen depending on the application such as flux calculations, core-follow or reload design as demonstrated in the schematic of the OSCAR-5 system in the Introduction. As an example, a core-follow calculation may be performed with either the MGRAC or Serpent reactor physics solvers. Rapyds generates the input required by the chosen simulation tool, for the application at hand from the code-independent reactor model.

This training manual will guide developers in coupling new simulation tools and applications to Rapyds. It is prerequisite that the reader be familiar with the OSCAR-5 System Overview as well as the OSCAR-5 Usage Training Documentation before proceeding to the rest of this guide.

Back to the specific topic of this training manual, the vehicle for establishing the connection between Rapyds and an external codes is found in the Rapyds Application Framework, which is depicted in application_frame. This training manual will describe the Application Framework, and demonstrate its use at the hand of a simple example.

We begin by introducing the UML Class diagrams for the Rapyds Application Framework and Rapyds Data Model.

Tip

UML class diagrams are in themselves complex constructs, which indicate how data elements in the system relate to each other. Various type of association between elements can be indicated, such as inheritance (triangle: is a), aggregation (open diamond: combines into complex object), composition (solid diamond: highly dependant relationship) and multiplicity (one-to-many, many-to-many) can be indicated in such diagrams. A deep understanding is not required at this point.

The diagrams below likely appear too detailed and unreadable, but are rendered in high resolution, and clicking upon them would allow deeper investigation of the detail. This is however not needed at this stage.

Note

Classes are grouped together in the UML diagrams into modules (black boxes with titles). These modules map directly onto Rapyds source code modules found in the directory structure of Rapyds. Where multiple boxes are shown within a larger box, the larger box would map onto a Python package in Rapyds (separate folder)

../_images/application_framework_all.svg — UML model of Rapyds Application Framework

Of course the application framework has to act upon a data model, which stores the actual reactor specifications in various classes, with their associated members and attributes. This part of the system is termed the Rapyds Data Model, and is depicted in data_frame

../_images/data_model.svg — UML model of Rapyds Data Model

These figures contain a large amount of detail, most of which are not critical to cover at this stage. However, do note the major groups of classes, and their basic interaction with other class groups, as terminology from this diagram will be introduced and used in this manual.

Overview of the Rapyds Data Model

The Data Classes (from data_frame) describe the reactor. The full detail of the data model is not the focus of this manual, but an introduction is provided here for the sake of completeness. Note that many of the statements below represent a “reading” of the diagram, meaning the sentence can be deduced from the relationships described in the diagram.

Selected element relationships in the Rapyds Data Model
CATEGORY	MODULES/CLASSES	ASSOCIATIONS
General Classes	Notable Base Classes	Some important Rapyds base classes on which other elements build their behaviour
	`Parameter_Pack`	the base class manages the way classes collect data and generically controls the way that class properties are set throughout the system.
	`Input_template`	the base class defines the basic behaviour for any class which has a string representation, and potentially should be written out at some point to an input file for a code. This concept and terminology is related to the Cheetah template engine which Rapyds uses to write out input files. In Cheetah the `TemplatedMetaData` class must be a parent to any data class which is associated with an `Input_template`.
	`Component`	the base class of all reactor geometric components

Reactor Data Elements	Materials	the set of classes which allow for the specification of homogeneous isotopic content needed to fill the reactor geometry. Looking at the UML diagram, we may note that:
	`Isotope`	The `Isotope` class is the container for data handling and behaviour of isotopes and elements.
	`Mixture`	a `Mixture` is comprised of a set of `Isotopes`
	`Material`	A `Material` inherits (is a) `mixture`, which additionally has a name, a color, a temperature and a library.
		A `Material` is also a `Parameter_pack`, so has a set of associated properties to set.
		A `Material` has a MaterialTemplate (relation), which is an `input_template`, so can have string representation (such as when you write the material element out to an input file for a specific code)
	Assemblies	the set of classes which allow for the specification of geometric components of the reactor assemblies
	`Assembly`	An `Assembly` is a `Component`, and has an `Input_Template`, which means its representation can be written to file.
		An `Assembly` aggregates a number of `states`, which in-turn is comprised of a number of `state parameters`. We can think of fuel temperature for example.
		An `Assembly` has a `Transformation` which defines its placement and orientation in the reactor.
		An `Assembly` is an aggregation of `Cells`, which themselves are `PhysicalRegions` from the external `csg` package.
		An `Assembly_Container` is an aggregation of multiple instances of `Assembly`, either in the form of an Hexagonal Grid, Cartesian Grid or Unstructured grid.
		An `Assembly` has a `Burn Bundle` (in Rapyds this is an overlay mesh) which defines the depletable region in the assembly.
		An `Assembly` is a `Facility`, meaning something can be loaded into it’s cells, even another `Assembly`.
		Many specialisation of `Assembly` exist in Rapyds, such as `PlateAssembly`, `PinAssembly`, `PrismaticElement`, `DispersedParticles` etc. These classes essentially act as Macros which generate the `Assembly` structure, based on some specified parameters.
	Burn Bundles	The set of classes providing an independent material mesh structure for tracking burnable or activation region materials. This is an overlay mesh on top of the assembly geometry.
	`Burn Bundles`	A collection of `FuelBundles`, which is of a certain layout (typically Array structure).
		`FuelBundles` each have a `DepletionMesh`
		`DepletionMesh` is made up of a collection of `FueledPrimitive`, which can be of pin, plate, particle, etc.
		For changes due to activation or burnup, fluxes are typically calculated on the `DepletionMesh`, and relevant volumes are calculated by intersecting the `DepletionMesh` with the `cells` of the assembly.
		There are options for certain complex/large geometries to redistribute the `Burn bundle` back to the geometry (track materials on `cells` level), although the default behaviour is for a separate overlay approach.
	Reactor Core	Set of classes which combine assemblies (or components) into a reactor core
	`Lattice`	Set of classes which allow various forms of 2D lattice-based combinations of components to be created, such as `SquareLattice` or `HexagonalLattice`. These are also used for lattice based constructions within Assemblies (e.g. pin or plate lattices)
		A `Lattice` is itself a `AssemblyContainer`, which is in-turn also a `Component`
		All lattices have an associated Template Class, to allow the lattice to written to the underlying codes.
	`ReactorCore`	The `ReactorCore` specialises the concept of a `Lattice` and extends it to capture the behaviour of a reactor core, by adding e.g. concepts such as control rods and their movement
	`Reactor`	The `Reactor` contains the concept of a `pool`, in which a space exists for the core lattice.``Reactor`` then combines the `ReactorCore` and the `pool`.
		The `Reactor` class includes the concept of the boundary conditions to the system.
		The `Reactor` has an associated `InputTemplate` which allows the full geometric model to be written out (recursively calling other templates)

Although this table may seem rather obscure, it represent a direct reading of the UML diagram, and is presented here as example of how to interpret such a diagram. It further assist in introducing some terminology which will be of interest later in this training manual.

Overview of the Application Framework

The Application Classes (from application_frame) describe the interaction of Rapyds with external codes. Again, the full detail of the application framework is not the focus of this manual, but an introduction is provided here primarily to define some basic concepts and terminology.

Selected element relationships in the Rapyds ApplicationFramework
CATEGORY	MODULES/CLASSES	ASSOCIATIONS
Application	Application Classes	Classes associated with a Rapyds application, which is a reactor analysis task at a code independent level
	`ApplicationFramework`	The base application class, not often instantiated, but specialised into `Application`, `ApplicationChains` and `MultiApplication`
		An `ApplicationFramework` has an associated set of `ApplicationParameters`, which are themselves a `ParameterPack`
		An `ApplicationFramework` has an associated `DirectoryManager`, which managers the folder structure for the specific application.
		An `ApplicationFramework` has an associated `ResultsSummary`, which keeps the primary results from the application after execution.
	`Application`	A single standalone analysis application. A single code execution, with one primary input file
	`Multi-Application`	Multiple independent analysis applications. Multiple input files to multiple codes all spawned simultaneously.
	`ApplicationChain`	Multiple sequenced analysis applications. Multiple input files to multiple codes all spawned sequentially.
Project	Project Classes	Classes associated with a Rapyds project, which essentially puts together all elements to generate an input file for a calculation
	`Project`	The base project class, identifying the `ProjectResources`, `ProjectParameters` and output file names
	`ProjectParameters`	Is a `ParameterPack`, and collects all parameters needed to produce an input file, such as the model itself, the intended target code and configuration file for setting up the run.
	`ProjectResources`	Collects the various elements (materials, surfaces, assemblies, …) of the input data
	`ResourceLayoutTemplate`	Is an `InputTemplate` used to define how the application specific input structure
	`ExecutionTemplate`	Is an `InputTemplate` used to define how the application should be run.
	`Recipe`	An abstract class overriden per application to define how the generic output parameters to extract after the code run is complete.

A large number of additional classes, beyond what is in the above UML diagrams or tables, exist in the Rapyds system, and can be inspected in the Rapyds system itself. For now however, we are more interested in the process of coupling a new external physics or engineering solver code to the Rapyds system, and seeing how to interact with the identified Rapyds classes to accomplsh this goal. The next section provides an introduction to this process, after which we will together go through such an example.

Introduction to Code Coupling

Coupling codes to the Rapyds platform requires work to be performed from four different perspectives. These are:

Work done as the Rapyds developer (RD). This step is not always needed, and depends on whether the application and Rapyds data elements needed for this work under consideration as yet exists in Rapyds at a code independent level. This step requires adaptation to existing, or creation of new Rapyds classes. For example, Rapyds already has an application for a critical case type calculation, so if you simply wanted to add another code capable of doing this, this step can most likely be skipped.

Work done as the Plugin developer (PD). The Plugin is the connection between Rapyds and the external code, and contains primarily two components. Firstly, the template class which creates the input file/s for the external code, and Secondly the Recipe, which parses the output file from the external code. This role typically requires in-depth knowledge of the input and output files of the external code.

Work done as the External code developer (ED). The External code itself often may change or have updates made to it. This work may not be applicable if the external code you are intending to couple is outside of your control, or sufficiently featured for the task at-hand.

Work done as the Rapyds end-user (RU), meaning that a Rapyds input file must be created and the newly coupled code must be run to fulfil the intended purpose. This could include various modes of interaction with the Rapyds application, including generating the input for the external code, running the code, or post-processing the output.

Tip

Take note of these different roles discussed here, as the remainder of this manual will build on this separation of activities, and approach the problem from these four perspectives.