Documentation Directives

This section describes all the documentation directives provided as extensions to the Sphinx documentation system.

To use these directives, the autodoc.sphinxext module should be added to extensions in your conf.py file. For example:

extensions = [
 'matplotlib.sphinxext.plot_directive',
 'sphinx.ext.mathjax',
 'sphinx.ext.autosectionlabel',
 'autodoc.sphinxext']

If using results generated by docgen, they should also be passed by setting autodoc_variables in conf.py:

from core.utilities import load_file

autodoc_variables = load_file('.results.pkl')

Quick directive reference
Directive	Short Description
template	Insert documentation elements based on the resolution of a template. Useful to treat repeated elements.
data_table	Display lists of data in a table.
plot_lines	Adds a plot of multiple one dimensional data sets.
plot_grid_data	Displays multiple data fields on a two dimensional grid.
model_slice	Add an image from a two dimensional slice through a target model element.
model_view	Insert a camera view of a three dimensional model as a projected image.
model_view_with_types	Radial model view with channel type labels.
model_view_with_target_types	Radial model view with loaded target type labels.
state_table	Adds a table listing the average model state parameters.
material_composition	Adds a table containing a specified material’s isotopic composition.
assembly_composition	Adds a table summarizing the fueled content of an assembly.
assembly_structure	Adds a table summarizing the structure of an assembly.
assembly_library	Adds a complete model documentation tree.
inventory_report	Produce a table with entries queried from an inventory

Variable tokens

To refer to a variable from autodoc_variables in your documentation, the standard bash like notation ${VARIABLE NAME} is used.

Note

Document names are not case sensitive, and spaces can also be replaced with either an underscore or dash, that is, ${My Variable}, ${my_variable} and ${MY-VARIABLE} al evaluate to the same token.

Simple variable referencing

To add a simple variable value to the documentation, the var role is used:

:var variable <,formatting>:

Extracts and formats a variable from the registered autodoc_variables. The first required argument is the variable name.

Note

When used with this role, variables can be specified with or without the variable token notation, that is ${MY VARIABLE} or just MY VARIABLE. However, for consistency with other directives, it is recommended that the token notation is used.

The optional arguments (separated in this case by a ,), are formatting statements, which depends on the data type:

For scalar real values, the single formatting argument determines how the value will be printed in the documentation. It can be standard python format specification related to floating point formatting. The following example shows how the print a value to 5 decimal places, and in scientific notation with three decimal places:
```
:var:`${MY VARIABLE}, {:.5f}`
:var:`${MY VARIABLE}, {:.3E}`
```
For dimensioned values, up to two formatting arguments are supported. The first being the target unit, and the second a standard format specification. For example, the following will cast the value to grams, and print it with one decimal place:
```
:var:`${MY VARIABLE}, g, {:.1f} grams`
```
For calendar date and time values, the format argument determines how the date (and/or time) will be displayed. It is any combination of datetime format tokens. For example, to print in day month then year format:
```
:var:`${MY VARIABLE}, %d %B %Y`
```

Note

When no additional formatting is given, the default python formatting (cast to string) will be used.

This role can be used within other directives, for example to include a variable in a table or figure caption.

When the variable being referenced is a simple container (e.g. a list, tuple or dict), then elements within the container can be extracted using the ${VARIABLE}[item] notation. For example, to retrieve the first element in the list ${MY_LIST}[0], or ${MY_DICT}[name], to get the value associated with the key name.

General elements

.. template::

Insert contents into the documents based on the resolution of a template.

This directive support the following options:

:engine: ({cheetah}): What template engine to use. Currently only the Cheetah engine is supported.

The directive body contains the template to resolve. This directive is especially useful if a number of repeated elements should be included, or to manage repeated elements within the body of other directives.

Example:

.. template::
   :engine: cheetah

   #for $a in [1, 2, 3]

   I'm repeating something for the $a'th time. See, I can even add directives:

   .. note::

      Remember to escape your variable tokens, e.g :var:`\${my_var_$a}`.

   #end for

Data visualization elements

.. data_table::

Display lists of data in a table.

This directive has no positional argument, and supports the following options:

:align: ({left center right}): How data should be aligned horizontally in the columns. The default is center.

The directive body has two sections. In the first, the table data is specified using the following format:

<Column Header 1>:
    data: <list>
    <option>: <value>
<Column Header 2>:
    data: <list>
    <option>: <value>
...

Each column header will be used verbatim in the text, and the number of entries here determine the number of columns in the produced table. The complete list of options under each header is:

data: The list of values that should be displayed in the column. This is the only reguired parameter.

unit: Base unit dimensioned data should be cast to.

fmt: A formatting statement, which determines how data will be printed in the table. If omitted, default formatting will be used.

The second part of the body is used to specify the table caption.

Example:

.. data_table::
   :align: center

   Cycle Progression:
      data: ${Days}
      unit: days
   Bank Positions:
      data: ${Bank Positions}
      fmt: '{:.2} %'
   U-235 Mass:
       data: ${U-235 Mass}
       unit: g
       fmt: {:.1} g

   Bank positions and burnup for :var:`Cycle Name`.

.. plot_lines::

Adds a plot of multiple one dimensional data sets. It extends the matplotlib .. plot:: directive, which is used in the background to render the data.

This directive has no positional arguments, but supports the following options:

:x_axis_label: (str): Label placed on the $x$ axis of the plot.

:x_axis_unit: (unit): Unit to which all $x$ values should be scaled.

:y_axis_label: (str): Label placed on the primary (left) $y$ axis of the plot.

:y_axis_unit: (unit): Unit to which all primary $y$ values should be scaled.

:y_axis_scale: ({log, linear}): Scaling of the primary $y$-axis. Default is linear.

:legend: (bool): Flag indicating that the legend should be included in the plot.

:legend_position: (str)

Where the legend should be placed. The following options are supported:

Option	Behavior
auto	Plot engine decides on best position within the plot axis area.
top	Legend is placed on the top of the plot area (outside axis)
bottom	Legend is placed at the bottom of the plot area (outside axis)
right	Legend is placed on the right hand side (outside axis)

The default value is auto.

Note

If you have a secondary axis, placing the legend on the right can potentially cause it to be clipped. In particular, this placement should not be used when the tight global option is set for savefig.bbox.

The body of this directive has two sections. The first is a data tree describing the data used in the line plots. It has the following format:

<First Line Label>:
      x:
      y:
      <other opts>
<Second Line Label>:
      x:
      y:
      <other opts>

Where the top entries are the line labels, and subsequent (indented) entries the data defining and formatting the line. The complete list of options are:

x: The $x$ coordinates of the scatter plot data. This is usually given as a variable token, which points to a list of values.

y: The $y$ coordinates of the scatter plot data. This is usually given as a variable token, which points to a list of values.

data: Provides the scatter plot data in a single tuple $(x, y)$. Can be used in instead of specifying x and y separately.

y_axis_unit (optional): Unit to which the data should be scaled. Only applicable for dimensioned data.

y_axis_label (optional): The label placed on the $y$ axis, if this data set requires a new $y$ axis.

line_style (optional): Style used when drawing the line between data points. Use None if only the data points should be shown.

marker (optional): Style used to denote data points. Use None if data points should not be marked. See matplotlib markers for all the available marker options.

sigma (optional): Number of standard deviations that should be shown for plots with error bars. The default value is 3.

Note

Unlike std, this is only used for y values with uncertainty.

average (optional): Set to True if a horizontal line denoting the average of the y values should be included.

std (optional): Adds a background block element that denotes the spread of data. The value here denotes how many standard deviations should be plotted.

outliers (optional): Use the specified method to remove outliers from the data set before plotting average and/or std. Options are:

iqr_test

Use the Inter Quantile Range test to remove outliers

zeta_test

Reject outliers based on their Zeta score, that is, data points larger than 3 sigma from mean will be removed.

The second section contains the resulting figure caption, and is optional.

Note

All $x$ values must have the same dimension.
A new $y$ axis will be created automatically if data added is of a different dimension than any existing $y$ axis. In this case, the y_axis_label should be specified for that line.
The line data tree and caption must be separated by an empty line.

Example:

.. plot_lines::
   :x_axis_label: Cycle Progression
   :x_axis_unit: days

   Critical Estimates:
      x: ${Cycle Days}
      y: ${Cycle Keff}
      line_style: None
      marker: +
      y_axis_label: $k_{eff}$
   U-235 Mass:
      x: ${Cycle Days}
      y: ${Cycle U-235}
      y_axis_unit: g
      y_axis_label: U-235 Mass

   Critical estimates and total U-235 mass for cycle :var:`Cycle Name`.

.. plot_grid_data:: <width> <height>

Displays multiple data fields on a two dimensional grid.

The directive accepts up to two (optional) arguments, which gives the pitches of the grid elements. If one value, the $x$ and $y$ pitch is assumed to be identical. Two values are interpreted as the $x$ and $y$ pitch respectively. If nothing is specified, a square pitch will be used.

The following options are supported:

:position_labels: ({labels_in_mesh, labels_on_axis, no_labels})

If and where the grid position labels should be placed. The behavior is summarized in the following table:

Option	Behavior
labels_in_mesh	Grid labels will be placed in the upper left corner of grid cells
labels_on_axis	Row and column labels will be placed in an extra column before and row above respectively
no_labels	Positions labels will not be displayed.

:fmt_labels: ({switch}): Indicate that row and column labels should be switched when adding them to the position cell. Only used when position_labels is specified as labels_in_mesh.

:show_grid: (bool): Indicate if the grid lines should be included in the plot.

:color_by: (str): Which data field (see below) should be used to color the grid elements. If not specified, scaled colors will not be shown.

Attention

It must be one of the scalar field labels specified in the directive body.

:show_scale: (bool): Flag indicating if the scaled color bar should be shown. Only applicable if color_by is set.

The body of this directive has two sections. The first is a tree giving the data used in the two dimensional plots. It has the following format:

<First Field Label>:
      data:
      <other opts>
<Second Field Label>:
      data:
      <other opts>

Where the top entries are the data labels, and subsequent (indented) entries the data defining and formatting the data. The complete list of options for each data field are:

data (labeledgrid): The two dimensional data field to plot. Usually a variable token pointing to a labeledgrid. Entries in the grid can be anything, but must be numerical values in order to be used for color coding. This is the only required parameter.
unit: To which unit dimensioned values in data should be scaled.
show_value (bool): Flag indicating if the contents of the data field should be added to the plot as text. If False (the default), the data can only be used to color the cells.
fmt (str): Formatting of displayed values. Only applicable if show_value is True.
font_size (int): Font size (in pts) applied when printing the data in the plot. Only used if show_value is True.
colormap (str): Custom colormap to use for creating a scaled color bar. Can be any matplotlib colormap. Only used if the color_by option is set to the current field.

The second paragraph of the body is used as the caption of the produced plot.

Example:

.. plot_grid_data:: 7.71 8.1
   :position_labels: labels_in_mesh
   :color_by: U-235 Mass
   :show_scale: True

   Assembly Names:
      data: ${Load Map}
      show_value: True
   U-235 Mass:
      data: ${BOC Masses}
      unit: g
      show_value: True
      fmt: {:.1f}

   Beginning of cycle masses for :var:`Cycle Name`.

Model visualization elements

Directives that inserts images based on model components into the documentation. They are extensions of the .. figure:: directive and therefore support all its options (e.g :scale:, :width:).

All these elements will require, as its first argument, a model.

.. model_slice:: model plane position

Add an image from a two dimensional slice through a target model element.

The directive takes three (required) positional arguments:

model: Either an assembly instance, an assembly base type name, or a complete core configuration.
plane: The coordinate plane used to cut the model. Either xy, xz or yz.
position: The position along the axis perpendicular to plane at which the cut should be calculated.

In addition, the following options are supported:

:image_name: (str): Specify the name of image file that will be created. If this option is not given, a unique (generic) name will be generated internally.

:frame: (length, length, length): The size of the image frame in model coordinates. This, together with center, is used to focus on a particular region in the model. If not specified, a frame large enough to fit the entire will be generated.

:center: (length, length, length): Where the view frame is centered. Only used if the view of the model should be limited, otherwise the model center of mass will be used.

:resolution: (int): Number of pixels per square centimeter. Affects the image quality and size.

:target_mode: (str): Use one of the connected sub codes to generate the image (provided plotting is supported for that code). If not specified, the built in plotter will be used.

:threads: (int): Number of processor threads that can be used when calculating the plot.

:force: (bool): Force the re-plotting of image, even if image file already exists. Use this if you made changes to the model.

The figure caption is entered in the body of the directive.

Example:

.. model_slice:: ${Model}  XY  0cm
   :image_name: my_model_slice.png
   :resolution: 16

   Slice in the :math:`xy` plane at :math:`z=0`.

.. model_view:: model

Insert a camera view of a three dimensional model as a projected image.

This directive requires one positional argument, which must resolve to a viewable model (either an assembly or configuration – see).

The following options are supported:

:image_name: (str): Specify the name of image file that will be created. If this option is not given, a unique (generic) name will be generated internally.

:core_only: (bool): Flag indicating that only the core component (if present) should be included in the view.

:background: (color): Color that will be used for the background canvas. If ‘White’ (the default) the background will be transparent in the generated image.

:direction:

The view direction. Currently the following options are supported:

Option

Description

bottom

View along $z$-axis from negative to positive

top

View along $z$-axis from positive to negative

left

View along $x$-axis from negative to positive

right

View along $x$-axis from positive to negative

front

View along $y$-axis from negative to positive

back

View along $y$-axis from positive to negative

The default value is top.

:focus: (length,length,length,length): Custom frame on which the camera should be focus. Specified as four corner values in the view $uv$-plane, $min_u,max_u,min_v,max_v$.

:opacity: (fraction or percentage): Level of opacity that should be applied to the entire model, with 0.0 being fully transparent.

:hide: (regex): A regex expression of part name(s) that should be hidden in the view. For example, setting this to ‘Adapter’ will hide all parts with names containing ‘Adapter’.

:highlight: (regex): A regex expression of part name(s) that should be highlighted in the view.

:resolution: (int): Number of pixels per square centimeter. Affects the image quality and size.

:force: (bool): Force the re-plotting of image, even if image file already exists. Use this if you made changes to the model.

The body of the directive contains two sections, the first is an optional tree like structure describing additional overlay elements that should be added to the model. It has the following format:

overlay_element_1:
     <options>: <value>
overlay_element_2:
     <options>: <value>

All the currently supported overlay elements are described in the following table

Element Name

Description

Options

channel_labels

Add core channel labels as overlay text.

position: Location of the labels within the channel bounding box. Any of the nine positions

top left

top center

top right

center left

center

center right

bottom left

bottom center

bottom right
font_size(int): Font size used when rendering text.
color: The color that should be used when rendering the text.
fmt: How labels should be formatted

channel_values

Add arbitrary data as overlay text.

data: A labeledgrid of values with the same labeling as that used in the core channels.
position: Location of the data within the channel bounding box. Same options as above.
color: The color that should be used when rendering the text.
font_size(int): Font size used when rendering text.
fmt: How data values should be rendered as text formatted.

response

Add a colored flux map.

data: Must point to a Response instance, a result file, or MCNP mesh tally output.
bin(int): Energy bin index that should be displayed in case the response contains multiple energy bins.

The image caption is given in the second part of the body.

For example, the following will generate a radial view with channel labels, and element masses:

.. model_view:: ${Model}
   :image_name: my_radial_view.png
   :direction: top
   :resolution: 25
   :width: 50%

   channel_labels:
      position: upper left
      font_size: 8
      color: black
   channel_values:
      data: ${BOC Masses}
      position: center
      font_size: 16
      color: red

   Model view with element masses.

The display elements are optional, and can be omitted. In this case, the directive body only contains the figure caption:

.. model_view:: ${Model}
   :image_name: my_axial_view.png
   :direction: front
   :resolution: 25
   :opacity: 50%
   :width: 50%

   My side view.

Attention

The difference between the .. model_slice:: and .. model_view:: directives, is that the former produces images by slicing the model, and the latter from positioning a camera in a three dimensional view. Thus, the view will not reveal all internal detail, but some approximation of this can be achieved by decreasing the opacity.

.. model_view_with_types:: model

This generates a radial model view with channel type labels, as well as a legend mapping these labels to assembly documentation (if present).

It supports all the options of model_view, with the following additional options:

:type_map: (str)

The model attribute that should be used to extract the channel contents. Available options are:

core_map: Usually only static (non loadable) elements.

load_map: Usually only loadable elements.

extract_load_grid: All channels and targets loaded.

Note

The extract_load_grid option is the most robust, as it will resolve the content of all the channels.

:font_size: (int): Size of rendered type labels on the image.

:font_color: (color): Color of rendered type labels on the image.

The body of this directive contains the image caption.

Example:

.. model_view_with_types:: ${Base_Model}
   :image_name: safari-config.png
   :type_map: extract_load_grid
   :resolution: 20
   :width: 75%
   :font_size: 64

   Core channel elements.

Attention

This directive only labels channels based on the top level assembly loaded. For type maps of loaded targets, use the model_view_with_target_types directive.

.. model_view_with_target_types:: model facility

Similar to model_view_with_types, except that the content of facility in each channel (if present) is labeled.

Accept all options from model_view_with_types.

Example:

.. model_view_with_target_types:: ${Base_Model} reflector-irradiation-channel
   :image_name: safari-reflector-load.png
   :type_map: extract_load_grid
   :resolution: 20
   :width: 75%
   :font_size: 64

   Reflector loading.

Model data elements

These directives adds tables of data from model elements.

.. state:: target

Adds a table listing the state parameters and their values as set in target, which can be a model, assembly or State instance.

It accepts the following options, which determine how dimensioned quantities will be displayed:

:temperature: (format): A format specifier which determines how all quantities with temperature dimensions will be formatted, e.g ‘degC, {:.1f} C’.

:density: (format): A format specifier which determines how all quantities with density dimensions will be formatted, e.g ‘kg/m/m/m, {:.1f} kg/m^3’.

:pressure: (format): A format specifier which determines how all quantities with pressure dimensions will be formatted, e.g ‘kPa, {:.1f} kPa’.

:velocity: (format): A format specifier which determines how all quantities with velocity dimensions will be formatted, e.g ‘mm/s, {:.1f} mm/s’.

:concentration: (format): A format specifier which determines how all concentration quantities (parts per) will be formatted, e.g ‘{:.1f} ppm’.

The table caption is given in the directive’s body.

Example:

.. state:: ${Model}
   :temperature: degC, {:.1} degC
   :density: g/cc, {:.3} g/cc
   :velocity: m/s, {:.2} m/s

   Average core state for cycle :var:`Cycle Name`.

.. material_composition:: material

Adds a table containing the material composition. The table has three columns: the isotope or element, its mass fraction, and number density.

The table caption is specified in the body of the directive.

Example:

.. material_composition:: ${UCO}

   Composition for the Uranium oxycarbide fuel matrix at 10 g/cc.

.. assembly_composition:: assembly

Adds a table summarizing the fueled content of an assembly.

The table caption is specified in the body of the directive.

Example:

.. assembly_composition:: ${LEU}

   Fuel contents of a fresh LEU assembly.

.. assembly_structure:: assembly

Adds a table summarizing the structure of an assembly. This depends on the design, but usually contains information like the number and dimensions of fueled elements, distance between elements (pitch) etc.

Note

This only gives meaningful information if the assembly is based on one of the built-in assembly macros.

The table caption is specified in the body of the directive.

Example:

.. assembly_structure:: ${LEU}

   Geometry of a LEU fuel assembly.

.. assembly_library:: <model_path>

Adds a complete documentation tree, describing all assembly types and the materials used.

This directive accepts one (optional) positional argument, which is the directory (relative to the reactor input set root) containing the model input files. If not specified, it defaults to ‘model’.

The following options are supported:

:exclude: (regex): A regex pattern of module names that should be excluded from the documentation set.

:skip_drawing_sheets: (bool): Flag indicating that drawing sheets should not be extracted from FreeCAD input.

:extract_materials: (bool): Flag indicating that heterogeneous material data should also be extracted. Defaults to True.

:subprocess: (bool): Flag indicating that a terminal subprocess should be used to query external python programs (such as FreeCAD), instead of calling them within the same interpreted session. The default is True.

Warning

Switching this to False might have some performance benefits, but incompatibilities between python libraries frequently cause unstable behavior.

:force: (bool): Flag indicating that assembly documentation input should be regenerated, even if the source module has not changed.

The body of the directive is used to indicate how the assembly and material index elements should be inserted in the document. The special tokens <assemblies> and <materials> are used to indicate were the respective documentation trees should be inserted. The rest of the body can have any text and or markup elements. See the examples below.

Note

The directive will dynamically create new source documents which will not be parsed when running sphinx the first time. Thus, the documentation will only be complete when parsed the second time.
Documentation input will be automatically regenerated if the assembly source scripts have changed.
New drawing sheets will only be extracted if the FreeCAD file was modified.
More information on how to prepare your model can be found in the presentation Quick overview of the model documentation mechanism and the video tutorials.

Example:

.. assembly_library::
   :exclude: (container)|(dummy)

   Assembly Library
   ----------------

   Description of all assembly types.

   .. note::

      All drawing dimensions are in millimeters.

   <assemblies>

   Material Library
   ----------------

   <materials>

Inventory elements

Directives that extract and display data form assembly inventories.

.. inventory_report:: inventory

Produce a table with entries queried from an inventory.

The positional argument is either a Inventory instance, or path to an inventory. In the latter case, if the path is not absolute, it is assumed to be relative to the current reactor root.

Note

All applications binds the inventory to the ${Inventory} token.

This directive supports the following options:

:at: (datetime): Default time at which inventory should be accessed. This can be overwritten by data elements in the table.

:start_date: (datetime): Optional start time. Used for delta and relative queries when generating table entries. For example, if at is the EOC time then this can be set to the BOC time in order to extract changes through the cycle.

:flt:: Filter the inventory entries that appear in the report. Either a list or labeledgrid of assembly names, or a general predicate accepting two arguments: the assembly name and AssemblyHistory instance.

:include_totals: (bool): Flag indicating that a row with totals should be added at the bottom of the table.

The table contents are specified in the first section of the directive’s body. It has the follow format:

<Column Header 1>:
    data:
    <options>
<Column Header 2>:
    data:
    <options>

Each column header can be any text, and will be displayed verbatim in the table. The column data and options are:

data: What data that should be extracted from the inventory entry. It can be any of the following:

name: the assembly name.

type: the assembly type name.

energy: the total energy delivered.

exposure: which will extract the exposure value (energy per mass).

heavy_metals: which will extract the total heavy metal mass.

Any isotope or element name, in which cases total masses will be extracted.

A custom function, which accepts a AssemblyHistory instance and returns the value of interest.

at: Overrides the at option to specify the time point where data should be extracted. Any datetime or the the string BOL (Beginning of Life).

since: Evaluates the difference in data from at to this value. Any datetime or the the string BOL (Beginning of Life). For example, if data is U-235, then setting this to BOL will yield the amount of U-235 depleted.

relative: Similar to since, except that the difference is expressed in relative terms (as a fraction).

unit: Specify the unit in which the data should be extracted.

fmt: Specify how data should be formatted.

The table caption is specified as the second paragraph of the directive body.

Example:

.. inventory_report:: ${Inventory}
   :at: ${BOC}
   :include_totals: True

   Assemblies:
      data: name
   Energy Delivered:
      data: energy
      unit: MW * hour
      fmt: '{:.1f} MWh'
   U-235 Mass:
      data: U-235
      unit: g
      fmt: '{:.1f} g'
   U-235 Consumed:
      data: U-235
      since: BOL
      unit: g
      fmt: '{:.1f} g'

   Beginning of cycle masses for :var:`${Cycle Name}`.