Running Bison

Bison uses GitLab for code management and distribution. Detailed instructions for checking out (also know as cloning), building and contributing to the code can be found in the Bison Workshop slides located in the Bison repository (bison/docs/workshop) or under the Getting Started section.

Running an Example Problem

When first starting out with Bison, we recommend starting with an example problem similar to the problem that you are trying to solve. Multiple examples can be found in the directories bison/examples/ and bison/assessment/. Additionally, step-by-step instructions for the common fuel rod geometries are given in the Examples & Tutorials section.

We recommend running the example problems to see how the code works. Explore the Bison code functionality by modifying input parameters to see how the run time, results and convergence behavior change. To demonstrate running Bison, consider the 2D-axisymmetric example problems. Do the following in your terminal:

cd ~/bison/examples/tensor_mechanics/2D-RZ_rodlet_10pellets
../../bison-opt -i 2Dtm_discrete_finiteStrain_action.i ## for serial processing

It is also possible to use multiple processors to run a Bison simulation.

mpiexec -n <procs> ../../bison-opt -i 2Dtm_discrete_finiteStrain_action.i ## where <procs> is the number of processors

Required Input and Mesh Files

Two input files are required as input when running Bison: an text input file and a mesh file.

The text input file commonly has "i" as its extension and contains a description of the variables, equations, boundary conditions, and material models associated with an analysis. The structure of the text input file is the main focus of our discussion here.

The mesh file is an ExodusII file (Schoof and Yarberry, 1996). (Athough MOOSE supports several mesh file formats, the ExodusII format is the one used in Bison.) This file commonly has "e" as its file extension. The mesh file may be generated using CUBIT (Sandia National Laboratories, 2008) or another meshing tool. A further option is a meshing script bundled with Bison; this script, dependent on CUBIT and suitable for LWR fuel rod meshes, is discussed in the section on the Meshing Script.

Additional Boundary Condition Files

Before running any problem, the power function, axial profile, mesh, and any functions needed for boundary conditions need to be generated.

Typically, a PiecewiseLinear function is used together with an external data file to specify a complex power history. This file has time and power specified in columns or rows, with the first row (or column) being the time (seconds) and the second row (or column) being power (W/m). The axial power profile, if present, is also input as a PiecewiseBilinearFile. Inclusion of these power function and axial profile files are shown in the 2D axisymmetric ten pellet example problem file:

  # Define functions to control power and boundary conditions
    type = PiecewiseLinear # reads and interpolates an input file containing rod average linear power vs time
    data_file = powerhistory.csv
    scale_factor = 1
  [./axial_peaking_factors] # reads and interpolates an input file containing the axial power profile vs time
    type = PiecewiseBilinear
    data_file = peakingfactors.csv
    scale_factor = 1
    axis = 1 # (0,1,2) => (x,y,z)
  [./pressure_ramp] # reads and interpolates input data defining amplitude curve for fill gas pressure
    type = PiecewiseLinear
    x = '-200 0'
    y = '0 1'
    type = CompositeFunction
    functions = 'power_history axial_peaking_factors'

Bison can read comma-separate value (csv) files with either Windows or UNIX-style line terminations. In some versions of Excel, you may need to select a Windows or MS-DOS csv option to avoid generating it with the old-style Mac line terminations. If a csv file is generated in Microsoft Excel on the Mac, you should not output it as a Macintosh formatted csv file, because the file will be generated with the line terminations used by Mac OS versions that predate the current UNIX-based Mac OS versions.

As an example of a PiecewiseBilinearFile, we'll look at the axial power profile used in this example Bison problem. The axial peaking factors are input as a table within the CSV file, with the top row being the axial location from the bottom of the rod and the left column as time.


Note that the top most row in this CSV file has one fewer entry than the remaining rows: this difference is the result of the first column indicating the time at which each row expriences the given peaking factor.

Connecting the Mesh and Input Files

If using a separately built mesh file, include the name of the mesh file in the input file

  # Import mesh file
  file = fine10_rz.e
  patch_update_strategy = auto
  patch_size = 10 # For contact algorithm
  partitioner = centroid
  centroid_partitioner_direction = y

The mesh can either be generated with the mesh script, or if you do not have CUBIT, you can generate a simple 2D-RZ axisymmetric mesh with smeared solid fuel pellets (single fuel column) with the SmearedPelletMesh in Bison. To generate a smeared mesh similar to the geometry used in the example problem we have been working with, use the mesh block:

  type = SmearedPelletMesh
  patch_size = 10
  patch_update_strategy = auto
  partitioner = centroid
  centroid_partitioner_direction = y
  dim = 2
  pellet_quantity = 10
  pellet_height = 0.01186
  pellet_outer_radius = 4.1e-3
  pellet_mesh_density = coarse
  clad_mesh_density = coarse
  clad_gap_width = 160.0e-6
  clad_thickness = 0.56e-3
  clad_bot_gap_height = 1.0e-3
  top_bot_clad_height = 2.24e-3
  clad_top_gap_height = 2.6e-2
  elem_type = QUAD8

Post Processing

Viewing and analyzing the results of a Bison simulation is a key component of successfully running a Bison simulation. Bison typically writes solution data to an ExodusII file. Data may also be written in other formats: a simple comma separated file giving global data being the most common.

Paraview Visual Post Processings

Several options exist for viewing ExodusII results files. These include commercial as well as open-source tools. One good choice is Paraview, which is open-source.

Paraview is available on a variety of platforms. It is capable of displaying node and element data in several ways. It will also produce line plots of global data or data from a particular node or element. A complete description of Paraview is not possible here, but a quick overview of using Paraview with Bison results is available in the Bison workshop material.

Peacock Graphical User Interface

It is worth noting that a graphical user interface (GUI) exists for all MOOSE-based applications. This GUI is named Peacock. Information about Peacock and how to set it up for use may be found on the MOOSE wiki page.

Peacock may be used to generate a text input file. It is also capable of submitting the analysis, and it provides basic post processing capabilities.

Additional Mesh Geometries

Although this discussion has focused only on 2D axisymmetric (2D-RZ) geometries, Bison simulations can also be run on 3D meshes and 1D meshes. The 3D geometry simulations are useful for examining the effect of localized defects on the fuel performance, while the 1D simulations use simplifying symmetry assumptions to produce faster running simulations. The Mesh Script is used to generate both 2D-RZ and 3D meshes.

1D Spherically Symmetric TRISO Mesh

The mesh class designed to create 1D spherically symmetric TRISO meshes accounts for the multiple layers in a pellet. The TRISO1DMesh documentation page includes more details on using the mesh.

Layered 1D (1.5D) Fuel Rod Mesh

The Layered 1D geometry (also known as 1.5D) in Bison is used to generate fast simulation results when is it not important to account for localized effects in the analysis. Read more about how the Layered 1D simulations in Bison are set up in our upcoming tutorials. The Layered1DMesh documentation page gives more details about the Layered 1D mesh generation.

The Layered 1D input files are constructed with the same tensor mechanics materials as the 2D-RZ simulation we previously ran. The main differences in the input files of these two types of the simulations are in the Mesh block and the calculation of the out of plane strain calculation.

To generate a Layered 1D smeared mesh similar to the geometry used in the 2D-RZ example problem we have been working with, use the mesh block:

  type = Layered1DMesh
  patch_update_strategy = auto
  partitioner = centroid
  centroid_partitioner_direction = y
  slices_per_block = 10
  clad_gap_width = 8.0e-5
  clad_thickness = 0.00056
  fuel_height = 0.1186
  plenum_height = 0.027

The settings for the out of plane strain calculations are discussed in the dedicated Layered 1D tutorial.


  1. L. Schoof and V. Yarberry. EXODUS II: A finite element data model. Technical Report SAND92-2137, Sandia National Laboratories, September 1996.[BibTeX]
  2. Sandia National Laboratories. CUBIT: geometry and mesh generation toolkit., 2008.[BibTeX]