Difference between revisions of "Input syntax manual"

From Serpent Wiki
Jump to: navigation, search
(Branch (branch definition))
(coef (coefficient matrix definition))
Line 90: Line 90:
 
=== coef (coefficient matrix definition) ===
 
=== coef (coefficient matrix definition) ===
  
  '''coef''' ''NBU'' [ ''BU<sub>1</sub>'' ''BU<sub>2</sub>'' ... ]  
+
  '''coef''' ''NBU'' [ ''BU<sub>1</sub>'' ''BU<sub>2</sub>'' ... ]  
          [ ''NBR<sub>1</sub>'' ''BR<sub>1,1</sub>'' ''BR<sub>1,2</sub>'' ... ]
+
          [ ''NBR<sub>1</sub>'' ''BR<sub>1,1</sub>'' ''BR<sub>1,2</sub>'' ... ]
          [ ''NBR<sub>2</sub>'' ''BR<sub>2,1</sub>'' ''BR<sub>2,2</sub>'' ... ]
+
          [ ''NBR<sub>2</sub>'' ''BR<sub>2,1</sub>'' ''BR<sub>2,2</sub>'' ... ]
          ...
+
          ...
 
Defines the coefficient matrix for the automated burnup sequence. Input values:
 
Defines the coefficient matrix for the automated burnup sequence. Input values:
  

Revision as of 21:50, 21 February 2016

Serpent has no interactive user interface. All communication between the code and the user is handled through one or several input files and various output files.

The format of the input file is unrestricted. The file consists of white-space (space, tab or newline) separated words, containing alphanumeric characters(’a-z’, ’A-Z’, ’0-9’, ’.’, ’-’). If special characters or white spaces need to be used within the word (file names, etc.), the entire string must be enclosed within quotation marks.

The input file is divided into separate data blocks, denoted as cards. The file is processed one card at a time and there are no restrictions regarding the order in which the cards should be organized. The input cards are listed below. Additional options are followed by key word "set". All input cards and options are case-insensitive (note to developers: make it so). Each input card is delimited by the beginning of the next card. It is hence important that none of the parameter strings used within the card coincide with the card identifiers.

The percent-sign ('%') is used to define a comment line. Anything from this character to the end of the line is omitted when the input file is read. Unlike Serpent 1, hashtag ('#') can no longer be used to mark comment lines in Serpent 2 input. The alternative is to use C-style comment sections beginning with "/*" and ending with "*/". Everything between these delimiters is omitted, regardless of the number of newlines or special characters.

This page will contain the whole input syntax of Serpent 2, with links to more detailed descriptions where needed. For reference see also the Serpent 1 input manual.[1]


Input cards

NOTE: Serpent command words are in boldface and input parameters entered by the user in CAPITAL ITALIC. Optional input parameters are enclosed in [ square brackets ], and when the number of values is not fixed, the remaining values are marked with three dots (...).

Branch (branch definition)

branch NAME [ repm MAT1 MAT2 ]
            [ repu UNI1 UNI2 ]
            [ stp MAT DENS TEMP THERM1 SABL1 SABH1 THERM2 SABL2 SABH2 ... ]
            [ tra TGT TRANS ] 
            [ var VNAME VAL ]

Defines the variations invoked for a branch in the automated burnup sequence. Input values:

NAME  : branch name
MAT1  : name of the replaced material
MAT2  : name of the replacing material
UNI1  : name of the replaced universe
UNI2  : name of the replacing universe
MAT  : name of the material for which density and temperature are adjusted
DENS  : material density after adjustment (positive entries for atomic, negative entries for mass densities, or "sum" to use the sum of the constituent nuclide densities)
TEMP  : material temperature after adjustment, or -1 if no adjustment in temperature
THERMn  : n:th thermal scattering data associated with the material
SABLn  : name of the n:th S(\alpha,\beta) library for temperature below the given value
SABHn  : name of the n:th S(\alpha,\beta) library for temperature above the given value
TGT  : target universe, surface or cell
TRANS  : applied transformation
VNAME  : variable name
VAL  : variable value

Notes:

  • The branch name identifies the branch in the coefficient matrix of the coef card
  • The input parameters consist of a number variations, which are invoked when the branch is applied. A single branch card may inclued one or several variations.
  • The repm variation can be used to replace one material with another, for example, to change coolant boron concentration.
  • The repu variation can be used to replace one universe with another, for example, to replace empty control rod guide tubes with rodded tubes for control rod insertion in 2D geometries.
  • The stp variation can be used to change material density and temperature. The adjustment is made using the built-in Doppler-broadening preprocessor routine and tabular interpolation for S(\alpha,\beta) thermal scattering data.
  • The last three parameters of the stp entry are provided only if the material has thermal scattering libraries attached to it (see the therm card).
  • The tra variation can be used to move or rotate different parts of the geometry, for example, to adjust the position of control rods in 3D geometries.
  • Variables can be used to pass information into output file, which may be convenient for the post-processing of the data.
  • The branch card is used together with the coef card.
  • For more information, see detailed description on the automated burnup sequence.

cell (cell definition)

coef (coefficient matrix definition)

coef NBU [ BU1 BU2 ... ] 
         [ NBR1 BR1,1 BR1,2 ... ]
         [ NBR2 BR2,1 BR2,2 ... ]
         ...

Defines the coefficient matrix for the automated burnup sequence. Input values:

NBU  : number of burnup points
BUn  : burnup steps at which the branches are invoked
NBRm  : number branches in the m:th dimension of the burnup matrix
BRm,i  : name of the i:th branch in the m:th dimension

Notes:

  • The coef card creates a multi-dimensional coefficient matrix (of size NBR1 \times NBR2 \times NBR3 \times ... ). The automated burnup sequence performs a restart for each of the listed burnup points, and loops over the branch combinations defined by the coefficient matrix.
  • The coef card is used together with the branch card
  • For more information, see detailed description on automated burnup sequence.

det (detector definition)

div (divisor definition)

div <mat> [ sep <lvl> ] 
          [ subz <nz> <zmin> <zmax> ]
          [ subr <nr> <rmin> <rmax> ] 
          [ subs <ns> <s0> ]

Divides a material into a number of sub-zones. Input values:

<mat>  : name of the divided material
<lvl>  : geometry level at which the cell-wise division takes place (0 = no division, 1 = last level, 2 = 2nd last level, etc.)
<nz>  : number of axial zones
<zmin>  : minimum axial coordinate (cm)
<zmax>  : maximum axial coordinate (cm)
<nr>  : number of radial zones
<rmin>  : minimum radial coordinate (cm)
<rmax>  : maximum radial coordinate (cm)
<ns>  : number of angular sectors
<s0>  : zero position of angular division (degrees)

Notes:

  • The automated divisor feature can be used to sub-divide burnable materials into depletion zones, but the use is not limited to burnup mode.
  • Volumes of the divided materials must be set manually (see detailed description on the definition of material volumes).
  • Using automated instead of manual depletion zone division saves memory, which may become significant in very large burnup calculation problems (see detailed description on memory usage).
  • For more information, see detailed description on automated depletion zone division.

ifc (interface file)

 ifc <file> 

Links a multi-physics interface file to be used with the current input. Input values:

<file> : path to the multi-physics interface file

Notes:

include (read another input file)

include <file>

Reads another input file. Input values:

<file>  : name of the input file

Notes:

  • The include card can be used to simplify the structure of complicated inputs.
  • The input parser starts reading and processing the new file from the point where the input card is placed. Processing of the original file continues after the new file is completed.
  • The included file must contain complete input cards and and options, it cannot be used to read the values of another card.

mat (material definition)

mesh (mesh plot definition)

pin (pin geometry definition)

plot (geometry plot definition)

plot <type> <xpix> <ypix> [ <pos> <min1> <max1> <min2> <max2> ]

Produces a png-format geometry plot. Input values:

<type>  : defines the plot type (orientation and plotting of boundaries)
<xpix>  : horizontal image size in pixels
<ypix>  : vertical image size in pixels
<pos>  : position of plot plane
<min1>  : minimum horizontal coordinate of plotted region
<max1>  : maximum horizontal coordinate of plotted region
<min2>  : minimum vertical coordinate of plotted region
<max2>  : maximum vertical coordinate of plotted region

Notes:

  • The type parameter consists of one or two concatenated values ('AB'):
    1. The first value ('A') defines the plot plane (1 = yz, 2 = xz, 3 = xy).
    2. The second value ('B') defines which boundaries are plotted (0 = no boundaries, 1 = cell boundaries, 2 = material boundaries, 3 = both). If the second value in is not provided, material boundaries are plotted.
  • Each material plotted with different color. The colors are sampled randomly, unless defined using the rgb entry in the material card.
  • Void is plotted in black and special colors are used to plot geometry errors (red = overlap, green = undefined region).
  • The position parameter defines the location of the plot plane on the axis perpendicular to it (e.g. z-coordinate for xy-type plot).
  • The minimum and maximum coordinates define the boundaries of the plotted region (e.g. minimum and maximum x- and y-coordinates for xy-type plot). If these coordinates are not provided, the plot is extended to the maximum dimensions of the geometry.
  • The relative dimensions of image size in pixels should match that of the plotted region. Otherwise the image gets distorted.
  • Geometry plotter requires compiling the source code with GD Graphics libraries
  • Command line parameter '-plot' stops the execution after the geometry plots are prodused. Option '-qp' invokes a quick plot mode, which does not check for overlaps.
  • See practical examples.

surf (surface definition)

src (source definition)

tme (time binning definition)

tme 1 <nb> <lim_1> <lim_2> ...
tme 2 <nb> <tmin> <tmax>
tme 3 <nb> <tmin> <tmax>

Defines a time binning structure. The first entry sets the binning type (1 = arbitrary, 2 = uniform, 3 = log-uniform). Remaining values:

<nb>  : number of bins
<lim_n>  : upper time boundary in arbitrary binning
<tmin>  : minimum time boundary in uniform or log-uniform binning
<tmax>  : maximum time boundary in uniform or log-uniform binning

Notes:

Input options

Input options are used to set various calculation parameters that are not included in the main input cars. Each option is identified by key word "set". Optional values are enclosed within square brackets.

set arr

set arr <moden> [ <modeg> ]

Sets analog reaction rate calculation on or off. Input values:

<moden>  : mode for neutrons (0 = no reactions included, 1 = include only reactions that affect neutron balance, 2 = include all reactions)
<modeg>  : mode for photons (0 = no reactions included, 1 = include all reactions)

Notes:

  • Analog reaction rates are calculated by counting sampled events and printed in a separate output file.
  • See detailed description on the reaction rate output file.

set bc

set blockdt

set blockdt <mat_1> <mat_2> ...

Defines the list of materials where delta-tracking is never used. Input values:

<mat_n>  : material names

Notes:

  • This option is used to override selection of tracking mode based on the probability threshold (see set dt) in individual materials.
  • Use of delta-tracking can be forced in individual materials using set forcedt.
  • For more information on tracking modes, see the detailed description on delta- and surface-tracking.
  • Note to developers: should have different lists for neutrons and photons?

set ccmaxiter

set ccmaxiter <niter>

Sets the maximum number of coupled calculation iterations. Input values:

<niter>  : number of iterations.

Notes:

  • Default maximum number of iterations is 1 (no iteration).
  • The iteration is stopped when either the maximum number of iterations or the maximum active neutron population (set with set ccmaxpop) has been simulated.
  • See Coupled multi-physics calculations for further information.

set ccmaxpop

set ccmaxpop <pop>

Sets the maximum total live population to simulate in a coupled calculation. Input values:

<pop>  : total active population to simulate.

Notes:

  • Default maximum population is INFTY/1e6.
  • The iteration is stopped when either the maximum number of iterations (set with set ccmaxiter) or the maximum active neutron population has been simulated.
  • Only the population simulated during active cycles is included in this amount.
  • This is mostly useful if the neutron population per iteration is not constant.
  • See Coupled multi-physics calculations for further information.

set coefpara

set delnu

set delnu <opt>

Sets delayed neutron emission on or off. Input values:

<opt>  : option to switch delayed neutron emission on (1/yes) or off (0/no)

Notes:

  • Delayed neutron emission is on by default in neutron criticality source and off by default in external source simulation mode.

set depout

set depout <mode>

Controls which burnable material compositions are printed into the _dep.m output file in case of divided materials. Input values:

<mode>  : value indicating, which materials to output to the _dep.m file (1 = only partials, 2 = only parents, 3 = both)

Notes:

  • Default is 2 (only parents)

set dt

set dt <ntrsh> [ <gtrsh> ]

Sets probability threshold for delta-tracking. Input values:

<ntrsh>  : probability threshold for neutrons
<gtrsh>  : probability threshold for photons

Notes:

  • Serpent uses delta-tracking by default for both neutrons and photons, but switches to surface-tracking if the probability of sampling virtual collisions (ratio between material total cross section and the majorant) exceeds the given threshold.
  • Default probability threshold for both particle types is 0.9, i.e. delta-tracking is used if the ratio between total cross section and majorant is above 0.1.
  • set dt 1 means that delta-tracking is always used and set dt 0 that it is never used.
  • Use of delta-tracking can be enforced or blocked in individual materials using the set forcedt and set blockdt options
  • Integral reaction rates are scored using the collision estimator of neutron flux, which has a few adjustable parameters (see set minxs).
  • For more information on tracking modes, see the detailed description on delta- and surface-tracking.

set entr

set entr <nx> <ny> <nz> [ <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> ]

Defines the mesh structure used for calculating fission source entropy. Input values:

<nx>  : number of mesh cells in x-direction
<ny>  : number of mesh cells in y-direction
<nz>  : number of mesh cells in z-direction
<xmin>  : minimum mesh boundary in x-direction
<xmax>  : maximum mesh boundary in x-direction
<ymin>  : minimum mesh boundary in y-direction
<ymax>  : maximum mesh boundary in y-direction
<zmin>  : minimum mesh boundary in z-direction
<zmax>  : maximum mesh boundary in z-direction

Notes:

  • Shannon entropy is used to monitor fission source convergence by recording the distribution of source points on mesh.
  • The calculation is invoked by setting the generation history record option on (set his).
  • The default mesh size is 5x5x5, extending over the entire geometry.
  • Monitoring fission source convergence make sense only in criticality source mode.
  • For more information, see detailed description on fission source convergence.

set forcedt

set forcedt <mat_1> <mat_2> ...

Defines the list of materials where delta-tracking is always used. Input values:

<mat_n>  : material names

Notes:

  • This option is used to override selection of tracking mode based on the probability threshold (see set dt) in individual materials.
  • Use of delta-tracking can be blocked in individual materials using set blockdt.
  • For more information on tracking modes, see the detailed description on delta- and surface-tracking.
  • Note to developers: should have different lists for neutrons and photons?

set fsp

set fsp <opt> <nskip>

Sets fission source passing between two transport simulations in burnup or coupled calculation. The fission source at the end of one transport calculation is used as the initial source for the next transport calculation.

<opt>  : option to switch fission source passing on (1/yes) or off (0/no)
<nskip>  : number of inactive generations on subsequent steps

Notes:

  • Fission source passing is turned off by default.
  • Number of inactive generations is taken from set pop card on the first step and from set fsp on all later steps.

set gbuf

set gbuf <fac> [ <bnk> ]

Sets the size of photon buffer and event bank. Input values:

<fac>  : factor (> 1) defining the buffer size
<bnk>  : event bank size

Notes:

  • Photon buffer refers to pre-allocated memory block used to store photon particle data. This memory is needed for putting secondary photons in que, etc..
  • The buffer factor defines the buffer size relative to simulated batch size.
  • The event bank refers to pre-allocated memory block used to store history data on particle events. This bank is used only with certain special options, such as importance detectors and track plotter.
  • The default values depend on simulation mode, and there is no need to adjust the values unless the calculation terminates with an error.
  • Note to developers: event bank is now the same for both neutrons and photons.

set gcut

set gcut <gmax> 

Sets generation cut-off for neutrons. Input values:

<gmax>  : number of simulated generations before cut-off

Notes:

  • The generation cut-off can be used in neutron external source simulations, to limit the length of fission chains.
  • Applicable only to neutron external source simulation (invoked using set nps)
  • Generation or time cut-off (set tcut) is always needed for neutron external source simulations in super-critical systems.

set his

set his <opt> 

Sets batch history record on or off. Input values:

<his>  : option to switch batch history record on (1/yes) or off (0/no)

Notes:

  • When invoked, Serpent collects batch-wise data on keff, fission source entropy etc. and produces a separate output file.
  • Setting the history option also invokes the calculation of fission source (Shannon) entropy. The entropy mesh parameters can be adjusted using set entr.
  • See detailed description on the history output file.

set mcvol

set mcvol <np>

Runs the Monte Carlo volume-checker routine to set material volumes before running the transport simulation. Input values:

<np>  : number of points sampled in the geometry

Notes:

  • The Monte Carlo based volume calculation routine works by sampling random points in the geometry, and counting the number of hits in every material.
  • When invoked, all material volumes are overridden by the results given by the checker routine.
  • The volume checker can also be used to produce a separate input file for the volume entries (see detailed description on defining material volumes).

set memfrac

set memfrac <fraction>

Defines the fraction of total system memory Serpent can allocate to its use. If the fraction is exceeded, the simulation will abort. This is mainly to avert the use of swap-memory, which can make the system unresponsive. Input values:

<fraction>  : the fraction of system memory that Serpent is allowed to use (between 0 and 1)

Notes:

  • The default fraction is 0.8.
  • The fraction can also be set via a SERPENT_MEM_FRAC environmental variable.
  • Serpent tries to read the system total memory from the first line of the file /proc/meminfo

set minxs

set minxs <ln> [ <tn> <lg> <tg> ] 

Defines the minimum mean distance for scoring the collision flux estimator (CFE) for photons and neutrons. Input values:

<ln>  : minimum mean distance for scoring the CFE for neutrons
<tn>  : minimum mean time interval for scoring the CFE for neutrons
<lg>  : minimum mean distance for scoring the CFE for photons
<tg>  : minimum mean time interval for scoring the CFE for photons

Notes:

  • The use of delta-tracking necessitates the use of CFE for scoring the integral reaction rates. The scoring is based on both real and virtual collision to improve the statistics in low density regions (and short time intervals).
  • The minimum mean distance is the statistical mean-free-path (mfp) of collisions that contribute to the CFE. Collisions are more frequent if the physical mfp is shorter.
  • In time-dependent simulations it may be more convenient to define the minimum mean time between two collisions, to get sufficient statistics for short time bins.
  • The default minimum mean scoring distance is 100 cm for both neutrons and photons. Adjusting the distance affects both statistics and running time, but it should be noted that no studies have been performed on what the optimal value should be.
  • Only one criterion can be provided for each particle type. If distance is given, time must be set to -1 and vice versa.
  • For more information on tracking modes and CFE, see the detailed descriptions on delta- and surface-tracking and result estimators.

set mvol

set mvol
<mat_1> <zone_11> <vol_11>
<mat_1> <zone_12> <vol_12>
...
<mat_2> <zone_21> <vol_21>
...

Sets the volumes of material regions. Input values:

<mat_m>  : name of material m
<zone_mn>  : index of zone n in material m
<vol_mn>  : volume of zone n in material m

Notes:

set nbuf

set nbuf <fac> [ <bnk> ]

Sets the size of neutron buffer and event bank. Input values:

<fac>  : factor (> 1) defining the buffer size
<bnk>  : event bank size

Notes:

  • Neutron buffer refers to pre-allocated memory block used to store neutron particle data. This memory is needed for banking fission neutrons for the next generation and putting secondary neutrons in que.
  • The buffer factor defines the buffer size relative to simulated batch size.
  • The event bank refers to pre-allocated memory block used to store history data on particle events. This bank is used only with certain special options, such as importance detectors and track plotter.
  • The default values depend on simulation mode, and there is no need to adjust the values unless the calculation terminates with an error.
  • Note to developers: event bank is now the same for both neutrons and photons.

set nps

set nps <ppb> [ <btch> <tbi> ] 

Sets parameters for simulated particle population in external source mode. Input values:

<ppb>  : number of particles per batch
<btch>  : number of batches
<tbi>  : time binning for dynamic mode

Notes:

  • The simulation is run for a number batches using the given batch size.
  • Using the nps card sets the mode to external source simulation. Criticality source simulation for neutrons is invoked using set pop.
  • If time binning is provided, the simulation is run in the dynamic mode with sequential population control. The bin structure is defined using the tme card.
  • Running an external source simulation requires a source, defined by the src card. Source definition also sets the transported particle type.
  • Neutron external source simulations are limited to sub-critical systems, unless dynamic mode, time cut-off (set tcut) or generation cut-off (set gcut) is invoked.
  • Neutron external source simulations in multiplying systems may require adjusting the neutron buffer (set nbuf).
  • Delayed neutron emission is switched off by default in neutron external source simulation (for compatibility with MCNP). Delayed neutrons can be included with set delnu.

set outp

set outp <interval>

Sets the interval (in cycles) for writing simulation output to files. Input values:

<interval>  : number of cycles after which the output-files are updated

Notes:

  • Default value is 50.
  • Affects files such as _res.m, _det.m as well as mesh plots.

set pop

set pop <npg> <ngen> <nskip> [ <k0> <btch> ] 

Sets parameters for simulated neutron population in criticality source mode. Input values:

<npg>  : number of neutrons per generation
<ncyc>  : number of active generations
<nskip>  : number of inactive generations
<k0>  : initial guess for keff
<btch>  : batching interval

Notes:

  • The simulation is first run for a number of inactive generations to allow the fission source to converge. This is followed by a number of active generations, during which the results are collected. The statistics are divided in batches, and by default each generation forms its own batch.
  • Using the pop card sets the mode to criticality source simulation. External source simulation is invoked using set nps.
  • Convergence of fission source can be monitored using Shannon entropy (input parameters set his and set entr).
  • Initial guess for keff is 1.0 by default. Setting the value manually may get the simulation going if it terminates on the first generation because of poor initial guess. The value does not affect fission source convergence.
  • See detailed descriptions on fission source convergence and statistical effects of batching.

set relfactor

set relfactor <value> 

Sets the underrelaxation factor for the power relaxation used in coupled multi-physics calculations. Input values:

<value>  : underrelaxation factor

Notes:

  • Setting the underrelaxation factor to 0, disables power relaxation altogether. The power distribution written to the output-files will be unrelaxed and only based on the most recent iteration.

set savesrc

set savesrc <path> [<Pn> <Pp> <nx> <ny> <nz>]

Sets up the creation of an initial source to be used in a dynamic simulation with delayed neutron emission.

<path>  : The path of the source file to be created
<Pn>  : Proportion of tentative neutrons to save (default 1.0)
<Pp>  : Proportion of tentative precursors to save (default 1.0)
<nx>  : Precursor mesh size in x-direction (default 1)
<ny>  : Precursor mesh size in y-direction (default 1)
<nz>  : Precursor mesh size in z-direction (default 1)

Notes:

  • Four source files will be generated <path>.main, <path>.prec, <path>.live and <path>.precpoints
  • If used in criticality source simulation, the system should be critical and the values will correspond to steady state values
  • If used in a dynamic simulation, the values will correspond to end-of-simulation values
  • If you are getting a warning from function WriteSourceFile "P larger than 1", you should lower the <Pn> value.

set tcut

set tcut <tmax> 

Sets time cut-off for neutrons and photons. Input values:

<tmax>  : time limit for simulated particle histories (in seconds)

Notes:

  • The time cut-off can be used in both neutron and photon external source simulations, to limit the length of particle histories.
  • Time or generation cut-off (set gcut) is always needed for neutron external source simulations in super-critical systems.
  • Time cut-off is automatically set in the dynamic external source simulation mode.
  • Note to developers: this should take independent values for photons and neutrons

set ures

set ures <opt> [ <nuc_1> <nuc_2> ... ]

Sets unresolved resonance probability table sampling on or off. Input values:

<opt>  : option to switch probability table sampling on (1/yes) or off (0/no)
<nuc_n>  : list of nuclides to which the option is applied to.

Notes:

  • Probability table sampling is switched off by default
  • Note to developers: add description of dilution cut-off

set usym

References

  1. ^ Leppänen, J. "Serpent – a Continuous-energy Monte Carlo Reactor Physics Burnup Calculation Code." User manual, June 18, 2015.