Multi-physics interface
The multi-physics interface is a set of routines, as well as input/output formats intended for easily bringing in detailed temperature and density fields to Serpent and at the same time automatically producing power distributions to be used in coupled codes.
Contents
- 1 List of multi-physics interface filetypes
- 2 Usage instructions
- 3 Point-average interface (type 1)
- 4 Regular mesh based interface (type 2)
- 5 User defined functional dependence (type 3)
- 6 Tetrahedral mesh interface (type 4)
- 7 Fuel behavior interface (types 5 and 6)
- 8 Unstructured mesh based interface (type 7)
- 9 Unstructured mesh based interface with multiple materials (type 8)
- 10 Unstructured mesh based interface and geometry definition (type 9)
- 11 Output
- 12 Examples
List of multi-physics interface filetypes
| Type | Name | Notes |
|---|---|---|
| 1 | Point-average | For interpolation of point-wise data |
| 2 | Regular mesh | For data on a regular cartesian or hexagonal mesh |
| 3 | Functional dependence | User defined functional dependence can be defined on source code level |
| 4 | Tetrahedral mesh type | Use interface type 7 instead. |
| 5 | Fuel behavior interface (piecewise constant) | For coupling with fuel performance/behavior codes with 1.5 dimensional (z,r) coordinate system. |
| 6 | Fuel behavior interface (radial interpolation) | For coupling with fuel performance/behavior codes with 1.5 dimensional (z,r) coordinate system. |
| 7 | Unstructured mesh | Based on OpenFOAM file format. |
| 8 | Unstructured mesh with many materials | Based on OpenFOAM file format. |
| 9 | Unstructured mesh based geometry + interface. | Based on OpenFOAM file format. Also creates the mesh based geometry. |
Usage instructions
The interface is linked to the main input file with the command
ifc FILE
where FILE is the path to the interface definition file. The descriptions for the interface definition files of the different interface types are given below. Multiple interfaces can be linked to a single input e.g. for bringing in temperature/density data for multiple materials.
Point-average interface (type 1)
The point-average interface is a way to bring in temperatures and densities for a single material in a number of discrete points in the geometry. During neutron transport Serpent will calculate the temperature and density in an interaction point as an average of the values of nearby interface points.
Input syntax
The input syntax for the interface file is
TYPE MAT OUT OUTFILE NZ ZMIN ZMAX NR DIM RAD EXP NP X1 Y1 Z1 DENS1 T1 X2 Y2 Z2 DENS2 T2 ...
The first line contains three parameters:
| TYPE | : the interface type (1 for point-average inteface) |
| MAT | : the name of the material that the data is given for. |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the second line contains parameters for the fission power output. If the output flag is not set the second line is emitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
| NZ | : is the number of axial bins for pin-wise power distributions |
| ZMIN | : is the minimum axial coordinate of the power distribution. |
| ZMAX | : is the maximum axial coordinate of the power distribution. |
| NR | : gives the number of radial bins in the power distribution. The radial bins are of equal volume. |
The third line contains:
| DIM | : The dimension of the distribution (1 = z-dependence only, 2 = x- and y-dependence, 3 = x-, y- and z-dependence). |
| RAD | : The exclusion radius, beyond which the points are not included in the average. |
| EXP | : The exponent for the averaging process. |
If the exclusion radius RAD is too small, some parts of the region may not be properly covered. If the radius is large, more CPU time is required for calculating the average. Setting the exponent EXP to 1 means that the average is based on distance, EXP = 2 means square distance, and so on.
The fourth line gives the number of points NP to be given and the remaining lines give the data in each of the points: If DIM = 1, only Zi is given, if DIM = 2, only Xi and Yi are given). Parameter DENSi is the material density at the point (negative values for mass density, positive values for atomic density) and Ti is the temperature.
Output
Regular mesh based interface (type 2)
The regular mesh based interface is a way to bring in temperatures and densities on a regular cartesian or hexagonal mesh. The format has a wide variety of uses such as bringing in information from nodal codes, channel/subchannel codes etc.
Input syntax
The input syntax for the interface file is
TYPE MAT OUT OUTFILE NZ ZMIN ZMAX NR MESHTYPE NX XMIN XMAX NY YMIN YMAX NZ ZMIN ZMAX [Cartesian mesh] X0 Y0 PITCH ZMIN ZMAX NX NY NZ [Hexagonal mesh] DENS1 T1 DENS2 T2 ...
The first line contains three parameters:
| TYPE | : the interface type (1 for point-average inteface) |
| MAT | : the name of the material that the data is given for. |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the second line contains parameters for the fission power output. If the output flag is not set the second line is emitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
| NZ | : is the number of axial bins for pin-wise power distributions |
| ZMIN | : is the minimum axial coordinate of the power distribution. |
| ZMAX | : is the maximum axial coordinate of the power distribution. |
| NR | : gives the number of radial bins in the power distribution. The radial bins are of equal volume. |
The third line contains basic information about the regular mesh: MESHTYPE is an integer indicating the type of the mesh (1 = cartesian, 4 = x-type hexagonal, 5 = y-type hexagonal). The format of the next line depends on the mesh type:
- For the cartesian mesh the next line consists of three triplets of values indicating the number of bins as well as the minimum and maximum coordinates in each of the coordinate directions.
- For the hexagonal mesh the next line contains 8 values: The coordinates for mesh centerpoint, mesh pitch, the axial limits of the mesh and the number of nodes in each of the coordinate directions.
Finally NX*NY*NZ pairs of values indicating the density and temperature in each of the cells follow. The ordering of the cells is such that the x-index increases first, then the y-index and finally the z-index.
Output
User defined functional dependence (type 3)
The user defined functional dependence interface allows the user to pass a number of arbitrary input parameters to Serpent, that are passed to subroutine userdf.c, along with local coordinates. The subroutine can be modified to include any kind of functional distribution. The interface file has almost no error tolerance, so be sure that all required values are entered and in the correct order.
Input syntax
The input syntax for the interface file is
TYPE MAT OUT OUTFILE NZ ZMIN ZMAX NR NP P1 P2 ...
The first line contains three parameters:
| TYPE | : the interface type (1 for point-average inteface) |
| MAT | : the name of the material that the data is given for. |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the second line contains parameters for the fission power output. If the output flag is not set the second line is emitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
| NZ | : is the number of axial bins for pin-wise power distributions |
| ZMIN | : is the minimum axial coordinate of the power distribution. |
| ZMAX | : is the maximum axial coordinate of the power distribution. |
| NR | : gives the number of radial bins in the power distribution. The radial bins are of equal volume. |
After the output parameters, the number of parameters to be read from the file NP is indicated followed by NP arbitrary parameters (integers or floating point numbers).
Output
Tetrahedral mesh interface (type 4)
The tetrahedral mesh interface has been replaced with the OpenFOAM-based interface format, which offers the same functionality with some additional benefits.
Fuel behavior interface (types 5 and 6)
The fuel behavior interface is designed for bringing in temperature and radial expansion data from fuel behavior / fuel performance codes using the traditional "1.5 dimensional" (z,r) coordinate system.
Input syntax
TYPE OUTFILE NPIN PINUNIp1 NZp1 ZMINp1 ZMAXp1 NAp1 AMINp1 AMAXp1 NRp1 RMINp1 RMAXp1 NZp1 ZMINp1 ZMAXp1 NAp1 AMINp1 AMAXp1 NRp1 RMINp1 RMAXp1 EMINp1 EMAXp1 NZp1 ZMINz1 ZMAXz1 NAz1 AMINa1 AMAXa1 NRa1 RCOLDr1 RHOTr1 Tr1 RCOLDr2 RHOTr2 Tr2 ... AMINa2 AMAXa2 NRa2 RCOLDr1 RHOTr1 Tr1 RCOLDr2 RHOTr2 Tr2 ... ... ZMINz2 ZMAXz2 NAz2 AMINa1 AMAXa1 NRa1 RCOLDr1 RHOTr1 Tr1 RCOLDr2 RHOTr2 Tr2 ... AMINa2 AMAXa2 NRa2 RCOLDr1 RHOTr1 Tr1 RCOLDr2 RHOTr2 Tr2 ... ... ... PINUNIp2 NZp2 ZMINp2 ZMAXp2 NAp2 AMINp2 AMAXp2 NRp2 RMINp2 RMAXp2 NZp2 ZMINp2 ZMAXp2 NAp2 AMINp2 AMAXp2 NRp2 RMINp2 RMAXp2 EMINp2 EMAXp2 NZp2 ... ... ... ...
Parameter TYPE is set to 5 or 6 for fuel behavior interface. Type 5 indicates a temperature step profile in the radial direction whereas type 6 corresponds to interpolation of temperatures in the radial direction between the radial nodes. OUTFILE is the filename where output is written and NPIN is the number of fuel pins described in this interface.
After this header line, NPIN fuel pin descriptions follow.
Fuel pin description
First the pin name for which the temperatures are applied is given
PINUNIpi
this should correspond to the name in the pin-definition. After that come the output meshings for power and flux in axial, angular and radial directions
NZpi ZMINpi ZMAXpi NApi AMINpi AMAXpi NRpi RMINpi RMAXpi NZpi ZMINpi ZMAXpi NApi AMINpi AMAXpi NRpi RMINpi RMAXpi EMINpi EMAXpi
This sets up tallies for power and flux: NZ axial bins between ZMIN and ZMAX, NA angular bins between AMIN and AMAX (degrees), and NR radial bins (of equal area) between RMIN and RMAX. The detector intended for tallying the local fast flux also has energy limits EMIN and EMAX.
After these two output lines comes the number of axial temperature profiles that will be given for the pin:
NZpi
This is followed by NZpi axial zone descriptions
Axial zone description
Each of the axial zone descriptions starts with the limits of the axial zone as well as the number of angular subzones for this axial region
ZMIN1zi ZMAX1zi NAzi
After this, NAzi angular zone descriptions follow.
Angular zone description
Each of the angular zone descriptions starts with the limits of the angular zone as well as the number of radial nodes to be read for the temperature distribution
AMIN1ai AMAX1ai NRai
Finally, the information at NRai radial nodes is given for that correspond to the current angular zone of the current axial zone of the current pin:
RCOLDr1 RHOTr1 Tr1 RCOLDr2 RHOTr2 Tr2 ...
Three values are given for each radial node: RCOLDri the radial position of the node in cold (Serpent input) coordinates, RHOTri the radial position of the node in hot (to be used for neutron tracking) coordinates and Tri temperature at this radial node. If RCOLDri and RHOTri are equal the geometry is not deformed for the neutron tracking. If the interface type is 5, Ti is the temperature used between RHOTr(i-1) and RHOTri giving a step profile. If the interface type is set to 6, linear interpolation is used between the radial nodes.
After the list of NR radial nodes, come the limits of the next angular zone (if available) followed by the radial nodes for that zone etc. After all of the angular zones have been defined come the limits for the next axial zone and its first angular zone etc. After all of the axial zones of the pin have been defined comes the pin-universe for the next pin etc.
Special cases
Axially segmented fuel rods
The pin-definitions in Serpent are essentially one-dimensional, which means that fuel rods that consist of axial segments have to be defined as a combination of multiple pin-definitions (or without the use of pin-definitions, but the interface only works with pin-definitions).
The fuel behavior interface can be used for rods consisting of multiple pin-definitions, but all of the pin definitions have to be linked to the interface. Instead of giving a single pin-universe name
PINUNI
in the interface file, a negative number indicating the number of pin-definitions to be linked should be given followed by the pin-universe names
-NUNI PINUNI1 PINUNI2 ... PINUNINUNI
Consider, for example a fuel rod filled consisting of a lower undoped fuel part, an intermediate segment with gadolinia-doped fuel and an upper undoped fuel part. This kind of a fuel rod can be modeled by creating two pin-definitions
pin p1nogd fuel 0.60579 void 0.62103 Zirc 0.71501 cool
for the undoped part and
pin p1yesgd fuelgd 0.60579 void 0.62103 Zirc 0.71501 cool
for the doped part. The three dimensional rod can be created by defining the limiting horizontal surfaces (here surf z1 and surf z2) and filling the pin-definitions into the correct axial levels of a new universe:
cell cp1l p1combined fill p1nogd -z1 cell cp1m p1combined fill p1yesgd z1 -z2 cell cp1h p1combined fill p1nogd z2
Now the universe p1combined can be used for example in a lattice, producing a three dimensional representation of the fuel rod. The interface file associated with this rod would then link both of the pin-definitions to the temperature field:
TYPE OUTFILE NPIN -2 p1nogd p1yesgd NZ ZMIN ZMAX NA AMIN AMAX NR RMIN RMAX NZ ZMIN ZMAX NA AMIN AMAX NR RMIN RMAX EMIN EMAX ...
Non-uniform output binning
The output binning defined by the
NZ ZMIN ZMAX NA AMIN AMAX NR RMIN RMAX
line is normally of equal volume. If an arbitrary binning is to be used instead, a negative value can be given for the number of bins, followed by NBIN+1 bin boundaries instead of BINMIN and BINMAX. For example:
NZ ZMIN ZMAX NA AMIN AMAX -3 0.0 0.1 0.4 0.5
will define three radial bins, where the first bin is from 0.0 cm to 0.1 cm, the second one from 0.1 cm to 0.4 cm and the third bin from 0.4 cm to 0.5 cm. The practice is the same for each of the directions (axial, angular or radial).
Output
Unstructured mesh based interface (type 7)
The unstructured mesh based interface has been designed to bring in solutions from solvers based on unstructured meshes (e.g. many finite volume or finite element codes).
The unstructured mesh based interface format is based on a point-face-cell hierarchy, where the user gives a number of points (vertices) that can be combined into a set of planar faces, which make up a set of closed convex cells. Since the interface file format is based on the OpenFOAM file format, OpenFOAM mesh- and field-files should be natively supported.
Input syntax
TYPE MAT OUT OUTFILE RHO0 T0 MESH_SPLIT MESH_DIM SZ1 SZ2 ... SZMESH_DIM POINTS_FILE FACES_FILE OWNER_FILE NEIGHBOUR_FILE DENSITY_FILE DM TEMPERATURE_FILE TM MAPPING_FILE
The first line contains some basic information about the interface:
| TYPE | : the interface type (7 for unstructured mesh based interface) |
| MAT | : the name of the material that the data is given for. |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the second line contains the path to the output file. If the output flag is not set the second line is emitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
The next line contains the nominal density and temperature for the interface:
| RHO0 | : Nominal density to be used for the interface |
| T0 | : Nominal temperature to be used for the interface |
The fourth line contains information about the adaptive search mesh:
| MESH_SPLIT | : Splitting criterion for the adaptive search mesh (maximum number of geometry cells in search mesh cell) |
| MESH_DIM | : number of levels in the adaptive search mesh |
| SZi | : Size of the search mesh at level i |
After the options for the search mesh come the file paths:
| POINTS_FILE | : Path to the unstructured mesh points file |
| FACES_FILE | : Path to the unstructured mesh faces file |
| OWNER_FILE | : Path to the unstructured mesh owner file |
| NEIGHBOUR_FILE | : Path to the unstructured mesh neighbour file |
| DENSITY_FILE | : Path to the unstructured mesh density file or -1 if the nominal density is to be used. |
| DM | : Flag indicating the type of values in the density file (1 = given value is the cell density) |
| TEMPERATURE_FILE | : Path to the unstructured mesh temperature file or -1 if the nominal temperature is to be used |
| TM | : Flag indicating the type of values in the temperature file (1 = given value is the cell temperature, 2 = given value is incremented to the nominal temperature) |
| MAPPING_FILE | : Path to the power output mapping file or -1 (-1 maps each cell to a separate power tally bin) If the output flag is not set, this line can be omitted. |
Output
Examples
Unstructured mesh based interface with multiple materials (type 8)
The unstructured mesh based interface has been designed to bring in solutions from solvers based on unstructured meshes (e.g. many finite volume or finite element codes). This variant of the interface supports temperature and density fields spanning multiple materials as long as the material in each of the mesh cells can be identified. The type 8 interface is used to only bring in the temperature and density fields.
The unstructured mesh based interface format is based on a point-face-cell hierarchy, where the user gives a number of points (vertices) that can be combined into a set of planar faces, which make up a set of closed convex cells. Since the interface file format is based on the OpenFOAM file format, OpenFOAM mesh- and field-files should be natively supported.
Input syntax
TYPE MAT OUT OUTFILE RHO0 T0 MESH_SPLIT MESH_DIM SZ1 SZ2 ... SZMESH_DIM POINTS_FILE FACES_FILE OWNER_FILE NEIGHBOUR_FILE MATERIALS_FILE DENSITY_FILE DM TEMPERATURE_FILE TM MAPPING_FILE
The first line contains some basic information about the interface:
| TYPE | : the interface type (8 to only bring in the solution fields) |
| MAT | : the name of any of the materials that the data is given for. |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the second line contains the path to the output file. If the output flag is not set the second line is emitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
The next line contains the nominal density and temperature for the interface:
| RHO0 | : Nominal density to be used for the interface |
| T0 | : Nominal temperature to be used for the interface |
The fourth line contains information about the adaptive search mesh:
| MESH_SPLIT | : Splitting criterion for the adaptive search mesh (maximum number of geometry cells in search mesh cell) |
| MESH_DIM | : number of levels in the adaptive search mesh |
| SZi | : Size of the search mesh at level i |
After the options for the search mesh come the file paths:
| POINTS_FILE | : Path to the unstructured mesh points file |
| FACES_FILE | : Path to the unstructured mesh faces file |
| OWNER_FILE | : Path to the unstructured mesh owner file |
| NEIGHBOUR_FILE | : Path to the unstructured mesh neighbour file |
| MATERIALS_FILE | : Path to the unstructured mesh material file |
| DENSITY_FILE | : Path to the unstructured mesh density file or -1 if the nominal density is to be used. |
| DM | : Flag indicating the type of values in the density file (1 = given value is the cell density) |
| TEMPERATURE_FILE | : Path to the unstructured mesh temperature file or -1 if the nominal temperature is to be used |
| TM | : Flag indicating the type of values in the temperature file (1 = given value is the cell temperature, 2 = given value is incremented to the nominal temperature) |
| MAPPING_FILE | : Path to the power output mapping file or -1 (-1 maps each cell to a separate power tally bin) If the output flag is not set, this line can be omitted. |
Output
Examples
Unstructured mesh based interface and geometry definition (type 9)
The unstructured mesh based interface has been designed to bring in solutions from solvers based on unstructured meshes (e.g. many finite volume or finite element codes). This variant of the interface supports temperature and density fields spanning multiple materials as long as the material in each of the mesh cells can be identified. The type 9 interface will also create a geometry universe and geometry cells based on the mesh definition and has to be linked to the main input using the solid 3 input card and not the ifc card like the other interfaces.
The unstructured mesh based interface format is based on a point-face-cell hierarchy, where the user gives a number of points (vertices) that can be combined into a set of planar faces, which make up a set of closed convex cells. Since the interface file format is based on the OpenFOAM file format, OpenFOAM mesh- and field-files should be natively supported.
Input syntax
TYPE UNI BG_UNI OUT OUTFILE RHO0 T0 MESH_SPLIT MESH_DIM SZ1 SZ2 ... SZMESH_DIM POINTS_FILE FACES_FILE OWNER_FILE NEIGHBOUR_FILE MATERIALS_FILE DENSITY_FILE DM TEMPERATURE_FILE TM MAPPING_FILE
The first line contains some basic information about the interface:
| TYPE | : the interface type (9 to also create the geometry) |
| UNI | : universe name for the irregular geometry |
| BGUNI | : name of the background universe filling all undefined space |
| OUT | : the output flag (1/0). If the flag is not set, the second line is omitted. |
If the output flag is set, the next parameter contains the path to the output file. If the output flag is not set the next parameter should be omitted. The parameters for the output are:
| OUTFILE | : determines the file name to which the output is printed |
The next line contains the nominal density and temperature for the interface:
| RHO0 | : Nominal density to be used for the interface |
| T0 | : Nominal temperature to be used for the interface |
The fourth line contains information about the adaptive search mesh:
| MESH_SPLIT | : Splitting criterion for the adaptive search mesh (maximum number of geometry cells in search mesh cell) |
| MESH_DIM | : number of levels in the adaptive search mesh |
| SZi | : Size of the search mesh at level i |
After the options for the search mesh come the file paths:
| POINTS_FILE | : Path to the unstructured mesh points file |
| FACES_FILE | : Path to the unstructured mesh faces file |
| OWNER_FILE | : Path to the unstructured mesh owner file |
| NEIGHBOUR_FILE | : Path to the unstructured mesh neighbour file |
| MATERIALS_FILE | : Path to the unstructured mesh material file |
| DENSITY_FILE | : Path to the unstructured mesh density file or -1 if the nominal density is to be used. |
| DM | : Flag indicating the type of values in the density file (1 = given value is the cell density) |
| TEMPERATURE_FILE | : Path to the unstructured mesh temperature file or -1 if the nominal temperature is to be used |
| TM | : Flag indicating the type of values in the temperature file (1 = given value is the cell temperature, 2 = given value is incremented to the nominal temperature) |
| MAPPING_FILE | : Path to the power output mapping file or -1 (-1 maps each cell to a separate power tally bin) If the output flag is not set, this line can be omitted. |
