Commit 8aa0d9ac authored by Batson Iii, John's avatar Batson Iii, John
Browse files

mavric rst

parent 47bf3682
......@@ -372,6 +372,216 @@ quantity—constant. FW-CADIS uses the solution of a forward
discrete-ordinates calculation to properly weight the adjoint source.
After that, the standard CADIS approach is used.
MAVRIC Implementation of CADIS
With MAVRIC, as with other shielding codes, the user defines the problem as a set of physical models—the material compositions, the geometry, the source, and the detectors (locations and response functions)—as well as some mathematical parameters on how to solve the problem (number of histories, etc.). For the variance reduction portion of MAVRIC, the only additional inputs required are (1) the mesh planes to use in the discrete-ordinates calculation(s) and (2) the adjoint source description—basically the location and the response of each tally to optimize in the forward Monte Carlo calculation. MAVRIC takes this information and constructs a Denovo adjoint problem. (The adjoint source is weighted by a Denovo forward flux or response estimate for FW-CADIS applications.) MAVRIC then uses the CADIS methodology: it combines the adjoint flux from the Denovo calculation with the source description and creates the importance map (weight window targets) and the mesh-based biased source. Monaco is then run using the CADIS biased source distribution and the weight window targets.
Denovo is a parallel three-dimensional SN code that is used to generate adjoint (and, for FW-CADIS, forward) scalar fluxes for the CADIS methods in MAVRIC. For use in MAVRIC/CADIS, it is highly desirable that the SN code be fast, positive, and robust. The phase-space shape of the forward and adjoint fluxes, as opposed to a highly accurate solution, is the most important quality for Monte Carlo weight-window generation. Accordingly, Denovo provides a step-characteristics spatial differencing option that produces positive scalar fluxes as long as the source (volume plus in-scatter) is positive. Denovo uses an orthogonal, nonuniform mesh that is ideal for CADIS applications because of the speed and robustness of calculations on this mesh type.
Denovo uses the highly robust GMRES (Generalized Minimum Residual) Krylov method to solve the SN equations in each group. GMRES has been shown to be more robust and efficient than traditional source (fixed-point) iteration. The in-group discrete SN equations are defined as
.. math::
:label: mavric-16
\mathbf{L}\psi = \mathbf{\text{MS}}\phi + q
where **L** is the differential transport operator, **M** is the
moment-to-discrete operator, **S** is the matrix of scattering
cross-section moments, *q* is the external and in-scatter source,
:math:`\phi` is the vector of angular flux moments, and :math:`\psi` is
the vector of angular fluxes at discrete angles. Applying the operator
**D**, where :math:`\phi = \mathbf{D}\psi`, and rearranging terms casts
the in-group equations in the form of a traditional linear system,
:math:`\mathbf{A}x = b`,
.. math::
:label: mavric-17
\left( \mathbf{I} - \mathbf{D}\mathbf{L}^{- 1}\mathbf{\text{MS}} \right) = \mathbf{D}\mathbf{L}^{- 1}q .
The operation :math:`\mathbf{L}^{- 1}\nu`, where :math:`\nu` is an
iteration vector, is performed using a traditional wave-front solve
(transport sweep). The parallel implementation of the Denovo wave-front
solver uses the well-known Koch-Baker-Alcouffe (KBA) algorithm, which is
a two-dimensional block‑spatial decomposition of a three-dimensional
orthogonal mesh :cite:`baker_sn_1998`. The Trilinos package is used for the GMRES
implementation :cite:`willenbring_trilinos_2003` Denovo stores the mesh-based scalar fluxes in a
double precision binary file (*.dff) called a Denovo flux file. Past
versions of SCALE/Denovo used the TORT :cite:`rhoades_tort_1997` \*.varscl file format
(DOORS package :cite:`rhoades_doors_1998`), but this was limited to single precision. Since
the rest of the MAVRIC sequence has not yet been parallelized, Denovo is
currently used only in serial mode within MAVRIC.
The forward Monte Carlo transport is performed using Monaco, a
fixed-source, shielding code that uses the SCALE General Geometry
Package (SGGP, the same as used by the criticality code KENO-VI) and the
standard SCALE material information processor. Monaco can use either MG
or CE cross section libraries. Monaco was originally based on the MORSE
Monte Carlo code but has been extensively modified to modernize the
coding, incorporate more flexibility in terms of sources/tallies, and
read a user-friendly block/keyword style input.
Much of the input to MAVRIC is the same as Monaco. More details can be
found in the Monaco chapter of the SCALE manual.
Running MAVRIC
The objective of a SCALE sequence is to execute several codes, passing
the output from one to the input of the next, in order to perform some
analysis—things that users typically had to do in the past. MAVRIC does
this for difficult shielding problems by running approximate
discrete-ordinates calculations, constructing an importance map and
biased source for one or more tallies that the user wants to optimize in
the Monte Carlo calculation, and then using those in a forward Monaco
Monte Carlo calculation. MAVRIC also prepares the forward and adjoint
cross sections when needed. The steps of a MAVRIC sequence are listed in
:numref:`Mavric-sequence`. The user can instruct MAVRIC to run this whole sequence of
steps or just some subset of the steps—in order to verify the
intermediate steps or to reuse previously calculated quantities in a new
The MAVRIC sequence can be stopped after key points by using the
“parm= *parameter* ” operator on the “=mavric” command line, which is
the first line of the input file. The various parameters are listed in
Table :numref:`mavric-param`. These parameters allow the user to perform checks and make
changes to the importance map calculation before the actual Monte Carlo
calculation in Monaco.
MAVRIC also allows the sequence to start at several different points. If
an importance map and biased source have already been computed, they can
be used directly. If the adjoint scalar fluxes are known, they can
quickly be used to create the importance map and biased source and then
begin the forward Monte Carlo. All of the different combinations of
starting MAVRIC with some previously calculated quantities are listed in
the following section detailing the input options.
When using MG cross-section libraries that do not have flux-to-dose-rate
conversion factors, use “parm=nodose” to prevent the cross section
processing codes from trying to move these values into the working
MAVRIC creates many files that use the base problem name from the output
file. For an output file called “c:\path1\path2\\\ *outputName*.out” or
“/home/path1/path2/ *outputName*.inp”, spaces in the output name will
cause trouble and should not be used.
.. list-table:: Steps in the MAVRIC sequence
:name: Mavric-sequence
:widths: 100 100
:header-rows: 0
:align: center
* - **Cross section calculation**
- XSProc is used to calculate the forward cross sections for Monaco
* - **Forward Denovo (optional)**
* - Cross section calculation
- XSProc is used to calculate the forward cross sections for Denovo
* - Forward flux calculation
- Denovo calculates the estimate of the forward flux
* - **Adjoint Denovo (optional)**
* - Cross section calculation
- XSProc is used to calculate the adjoint cross sections for Denovo
* - Adjoint flux calculation
- Denovo calculates the estimate of the adjoint flux
* - **CADIS (optional)**
- The scalar flux file from Denovo is then used to create the biased source distribution and transport weight windows
* - **Monte Carlo calculation**
- Monaco uses the biased source distribution and transport weight windows to calculate the various tallies
.. list-table:: Parameters for the MAVRIC command line (“parm=…”)
:name: mavric-param
:widths: 50 50
:header-rows: 1
:align: center
* - Parameter
- MAVRIC will stop after
* - check
- input checking
* - forinp
- Forward Denovo input construction (makes ``xkba_b.inp`` in the tmp area)
* - forward
- The forward Denovo calculation
* - adjinp
- Adjoint Denovo input construction (makes ``xkba_b.inp`` in the tmp area)
* - adjoint
- The adjoint Denovo calculation
* - impmap
- Calculation of importance map and biased source
MAVRIC input
The input file for MAVRIC consists of three lines of text (“=mavric”
command line with optional parameters, the problem title, and SCALE
cross section library name) and then several blocks, with each block
starting with “read xxxx” and ending with “end xxxx”. There are three
required blocks and nine optional blocks. Material and geometry blocks
must be listed first and in the specified order. Other blocks may be
listed in any order.
Blocks (must be in this order):
- Composition – (required) SCALE standard composition, list of materials used in the problem
- Celldata – SCALE resonance self-shielding
- Geometry – (required) SCALE general geometry description
- Array – optional addition to the above geometry description
- Volume – optional calculation or listing of region volumes
- Plot – create 2D slices of the SGGP geometry
Other Blocks (any order, following the blocks listed above):
- Definitions – defines locations, response functions, and grid geometries used by other blocks
- Sources – (required) description of the particle source spatial, energy, and directional distributions
- Tallies – description of what to calculate: point detector tallies, region tallies, or mesh tallies
- Parameters – how to perform the simulation (random number seed, how many histories, etc.)
- Biasing – data for reducing the variance of the simulation
- ImportanceMap – instructions for creating an importance map based on a discrete-ordinates calculation
The material blocks (Composition and Celldata) and the physical model
blocks (Geometry, Array, Volume, and Plot) follow the standard SCALE
format. See the other SCALE references as noted in the following
sections for details. The Biasing block and ImportanceMap block cannot
both be used.
For the other six blocks, scalar variables are set by “keyword=value”,
fixed-length arrays are set with “keyword value\ :sub:`1` ...
value\ :sub:`N`\ ”, variable-length arrays are set with “keyword
value\ :sub:`1` ... value\ :sub:`N` end”, and some text and filenames
are read in as quoted strings. Single keywords to set options are also
used in some instances. The indention, comment lines, and
upper/lowercase shown in this document are not required— they are used
in the examples only for clarity. Except for strings in quotes (like
filenames), SCALE is case insensitive.
After all input blocks are listed, a single line with “end data” should be listed.
A final “end” should also be listed, to signify the end of all MAVRIC input.
Nine of the blocks are the same input blocks used by the functional module Monaco,
with a few extra keywords only for use with MAVRIC. These extra keywords are highlighted here,
without relisting all of the standard Monaco keywords for those blocks.
See :numref:`input-format` for an overview of MAVRIC input file structure.
Composition block
......@@ -383,7 +593,7 @@ the SCALE manual. The Standard Composition Library chapter lists the
different cross section libraries and the names of standard materials.
An example is as follows:
.. code:: rest
read composition
......@@ -406,10 +616,11 @@ present in both libraries.
:widths: 30 30
:header-rows: 1
:align: center
:name: input-format
* - input file
- Comment
* - ::
* - .. code:: rest
Some title for this problem
......@@ -452,7 +663,7 @@ present in both libraries.
end importanceMap
end data
- ::
- .. code:: rest
name of sequence
......@@ -496,5 +707,255 @@ present in both libraries.
end of all blocks
end of MAVRIC input
SGGP geometry blocks
MAVRIC uses the functional module Monaco for the forward Monte Carlo calculation. Monaco tracks particles through the physical geometry described by the SGGP input blocks as well as through the mesh importance map and any mesh tallies, which are defined in the global coordinates and overlay the physical geometry. Because Monaco must track through all of these geometries at the same time, users should not use the reflective boundary capability in the SGGP geometry.
For more details on each SGGP Geometry block, see the following sections of the KENO-VI chapter of the SCALE Manual.
Geometry – *Geometry Data*
Array – *Array Data*
Volume – *Volume Data*
Plot – *Plot Data*
Other blocks shared with Monaco
The definitions, sources, tallies, and biasing blocks are all the same
as Monaco. They are all fully described in the Monaco chapter of the
SCALE Manual.
Definitions – *Definitions Block*
Sources – *Sources Block*
Tallies – *Tallies Block*
Biasing – *Biasing Block*
In the parameters block, there are several extra keywords compared to
Monaco (see the *Parameter Block* section of the Monaco chapter) which
are used when the cross section library used in the importance
calculations is different from the library used in the final forward
Monaco Monte Carlo calculation. The library listed at the beginning of
the MAVRIC input file will be used for the importance calculations
(forward and adjoint Denovo calculation, formation of the importance
map, and biased sources). To use a different MG library in the final
Monaco simulation, use the keyword “library=” with the cross section
library name in quotes. A cross section library for Monaco will be made
using csas-mg. If there are any extra parameters to use (“parm=” in the
“=csas-mg” line of the csas-mg input), they can be passed along using
the keyword “parmString=” with the extra information in quotes. For
example, the following input file would use a coarse-group library for
the importance calculations and a fine-group library for the final
Monaco, each with CENTRM processing.
.. code:: rest
=mavric parm=centrm
read parameters
library=”v7-200n47g” parmString=”centrm”
end parameters
end data
To use a CE cross section in the final Monaco step, use the keyword “ceLibrary=” with the cross section library name in quotes. When using the “library=” or “ceLibrary=” keywords, they should precede the “neutron”, “photon”, “noNeutron”, and “noPhoton” keywords. :numref:`extra-keywords` summarizes all of the keywords in the MAVRIC parameter block.
When using two different cross section libraries, be sure that the responses and distributions are defined in ways that do not depend on the cross section library. For example, any response that is just a list of n values (corresponding to a cross section library of n groups) needs to have the group energies specifically listed so that it can be evaluated properly on the other group structure.
.. csv-table:: Extra keywords for the parameters block
:file: csv-tables/table4.1.04.csv
:header-rows: 1
:name: extra-keywords
Importance map block
The importance map block is the “heart and soul” of MAVRIC. This block lists the parameters for creating an importance map and biased source from one (adjoint) or two (forward, followed by adjoint) Denovo discrete-ordinates calculations. Without an importance map block, MAVRIC can be used to run Monaco and use its conventional types of variance reduction. If both the importance map and biasing blocks are specified, only the importance map block will be used. There are a variety of ways to use the importance map block, as explained in the subsections below. Keywords for this block are summarized at the end of this section, in
Constructing a mesh for the S\ :sub:`N` calculation
All of the uses of the importance map block that run the
discrete-ordinates code require the use of a grid geometry that overlays
the physical geometry. Grid geometries are defined in the definitions
block of the MAVRIC input. The extent and level of detail needed in a
grid geometry are discussed in the following paragraphs.
When using S\ :sub:`N` methods alone for solving radiation transport in
shielding problems, a good rule of thumb is to use mesh cell sizes on
the order of a meanfree path of the particle. For complex shielding
problems, this could lead to an extremely large number of mesh cells,
especially when considering the size of the meanfree path of the lowest
energy neutrons and photons in common shielding materials.
In MAVRIC, the goal is to use the S\ :sub:`N` calculation for a quick
approximate solution. Accuracy is not paramount—just getting an idea of
the overall shape of the true importance map will help accelerate the
convergence of the forward Monte Carlo calculation. The more accurate
the importance map, the better the forward Monte Carlo acceleration will
be. At some point there is a time trade-off when the computational time
for calculating the importance map followed by the Monte Carlo
calculation exceeds that of a standard analog Monte Carlo calculation.
Large numbers of mesh cells, coming from using very small mesh sizes,
for S\ :sub:`N` calculations also use a great deal of computer memory.
Because the deterministic solution(s) for CADIS and FW-CADIS can have
moderate fidelity and still provide variance reduction parameters that
substantially accelerate the Monte Carlo solution, mesh cell sizes in
MAVRIC applications can be larger than what most S\ :sub:`N` practioners
would typically use. The use of relatively coarse mesh reduces memory
requirements and the run time of the deterministic solution(s). Some
general guidelines to keep in mind when creating a mesh for the
importance map/biased source are:
- The true source regions should be included in the mesh with mesh
planes at their boundaries.
- For point or very small sources, place them in the center of a mesh
cell, not on the mesh planes.
- Any region of the geometry where particles could eventually
contribute to the tallies (the “important” areas) should be included
in the mesh.
- Point adjoint sources (corresponding to point detector locations) in
standard CADIS calculations do not have to be included inside the
mesh. For FW-CADIS, they must be in the mesh and should be located at
a mesh cell center, not on any of the mesh planes.
- Volumetric adjoint sources should be included in the mesh with mesh
planes at their boundaries.
- Mesh planes should be placed at significant material boundaries.
- Neighboring cell sizes should not be drastically different.
- Smaller cell sizes should be used where the adjoint flux is changing
rapidly, for example, toward the surfaces of adjoint sources and
shields (rather than their interiors).
Another aspect to keep in mind is that the source in the forward Monaco
Monte Carlo calculation will be a biased, mesh-based source. Source
particles will be selected by first sampling which mesh cell to use and
then sampling a position uniformly within that mesh cell that meets the
user criteria of “unit=”, “region=”, or “mixture=” if specified. The
mesh should have enough resolution that the mesh source will be an
accurate representation of the true source.
The geometry for the Denovo calculation is specified using the keyword
“gridGeometryID=” and the identification number of a grid geometry that
was defined in the definitions block. The material assigned to each
voxel of the mesh is determined by testing the center point in the SGGP
geometry (unless the macro-material option is used – see below).
Macromaterials for S\ :sub:`N` geometries
Part of the advantage of the CADIS method is that the adjoint
discrete-ordinates calculation only needs to be approximate in order to
form a reasonable importance map and biased source. This usually means
that the mesh used is much coarser than the mesh that would be used if
the problem were to be solved only with a discrete-ordinates code. This
coarse mesh may miss significant details (especially curves) in the
geometry and produce a less-than-optimal importance map.
In order to get more accurate solutions from a coarse-mesh
discrete-ordinates calculation, Denovo can represent the material in
each voxel of the mesh as a volume-weighted mixture of the real
materials, called macromaterials, in the problem. When constructing the
Denovo input, the Denovo EigenValue Calculation (DEVC, see section SECTIONREFERENCE)
sequence can estimate the volume fraction occupied by each real
material in each voxel by a sampling method. The user can specify
parameters for how to sample the geometry. Note that finer sampling
makes more accurate estimates of the material fraction but requires more
setup time to create the Denovo input. Users should understand how the
macromaterials are sampled and consider that when constructing a mesh
grid. This is especially important for geometries that contain arrays.
Careful consideration should be given when overlaying a mesh on a
geometry that contains arrays of arrays.
Because the list of macromaterials could become large, the user can also
specify a tolerance for how close two different macromaterials can be to
be considered the same, thereby reducing the total number of
macromaterials. The macromaterial tolerance, “``mmTolerance=``”, is used for
creating a different macromaterial from the ones already created by
looking at the infinity norm between two macromaterials.
The number of macromaterials does not appreciably impact Denovo run time
or memory requirements.
Two different sampling methods are available—point testing :cite:`ibrahim_improving_2009` with
the keyword ``mmPointTest`` and ray tracing :cite:`johnson_fast_2013` with the keyword
Ray Tracing
This method estimates the volume of different materials in the Denovo mesh grid elements by tracing rays through the SGGP geometry and computing the average track lengths through the each material. Rays are traced in all three dimensions to better estimate the volume fractions of materials within each voxel. The mmSubCell parameter controls how many rays to trace in each voxel in each dimension. For example, if mmSubCell= n, then when tracing rays in the z dimension, each column of voxels uses a set of n×n rays starting uniformly spaced in the x and y dimensions. With rays being cast from all three orthogonal directions, a total of 3n2 rays are used to sample each voxel. One can think of subcells as an equally spaced sub-mesh with a single ray positioned at each center. The number of subcells in each direction, and hence the number of rays, can be explicitly given with mmSubCells ny nz nx nz nx ny end keyword for rays parallel to the x axis, y axis, and z axis.
:numref:`ray-positions` shows different subcell configurations (in two dimensions) for a given voxel.
.. _ray-positions:
.. figure:: figs/fig4.1.01_rayTrace6.png
:width: 500
:align: center
Ray positions within a voxel with different mmSubCells parameters.
Ray tracing is a more robust method compared to the simple point testing
method used in previous versions of SCALE/MAVRIC; however, it requires
more memory than point testing. Ray tracing gives more accurate
estimates of volume fractions because track lengths across a voxel give
more information than a series of test points. Ray tracing is also much
faster than point testing because the particle tracking routines are
optimized for quickly determining lists of materials and distance along
a given ray.
Ray tracing operates on the grid geometry supplied by the user and
shoots rays in all three directions starting from the lower bounds of
the mesh grid. An example of an arbitrary assembly geometry is shown in
:numref:`geom-model`. A ray consists of a number of steps that each correspond
to crossing a material boundary along the path of the ray. Ratios of
each step’s length to the voxel length in the ray’s direction determine
the material volume fraction of that step in that voxel, and summation
of the same material volume fractions gives the material volume fraction
of that material in that voxel. Ray tracing through a single voxel that
contains a fuel pin is illustrated in Figure 4.1.3.
.. _geom-model:
.. figure:: figs/fig4.1.02_kenoDenovo.png
:width: 600
:align: center
Geometry model (left) and the Denovo representation (right) of an assembly using macromaterials determined by ray tracing.
.. bibliography:: /bibs/mavric.bib
.. bibliography:: /bibs/mavric.bib
......@@ -18,9 +18,12 @@
# -- Project information -----------------------------------------------------
project = 'SCALE test documentation'
copyright = '2020, John Batson'
copyright = '2020, SCALE developers'
author = 'John Batson'
pygments_style = "default"
highlight_language = "python"
# The full version, including alpha/beta/rc tags
release = '0.0.1'
......@@ -59,3 +62,7 @@ html_theme = 'sphinx_rtd_theme'
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_css_files = [
......@@ -8,6 +8,6 @@ Welcome to SCALE test documentation!
.. toctree::
:maxdepth: 2
:caption: Contents:
:caption: Radiation Shielding
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment