Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search

Using SHARP with ICE

This is a legacy tutorial and may contain outdated information.

This document is designed to outline the basic steps of setting up and using the SHARP plugins in ICE. There are three different tasks in ICE for the input generation, launching, and post-run analysis of SHARP data in ICE:

  • SHARP Model Builder - Using selected parameters, generates a set of input files necessary to launch the SHARP suite of multi-physics simulation codes.
  • SHARP Launcher - Initiates the SHARP codes to run on a local or remote system using the files generated from the SHARP Model Builder.
  • Reactor Analyzer - Provides post-simulation analysis tools for "quantities of interest" from the SHARP output.

Installation & Configuration

Follow the instructions in the Getting ICE article to download and install the latest version of ICE on your system. Pay special attention to the installation of HDF5 since the SHARP plugins require that library.


You should have SHARP installed on a machine, either locally or remotely.

Developer Instructions for SHARP Installations

If you are just using ICE to work with SHARP, you can skip this section.

In the future it will be possible to generate ICE I/O files directly from SHARP. If you are a developer or IT specialist who is configuring this capability, you need to install the ICE I/O libraries on the same machine where SHARP is installed. There is no easy way to do this since these are not distributed as a binary. You have to checkout the ICE trunk onto your machine and run the following instructions in your shell from the trunk directory:

mkdir nativeBuild
cd nativeBuild
cmake ..
make test
make install

If installing ICE I/O is too difficult, contact the ICE development team at ice-dev <at>

Data Configuration

ICE requires a data file for SHARP that contains a specification of the PROTEUS input parameters; contact the ICE development team for a copy of this file. After downloading it, create a directory named SHARP in the /home/{user}/ICEFiles/default directory on your local system, and place the ICEProteusInput.xml file here before launching ICE. You may also need to create the /ICEFiles/default directory as well if you have never launched ICE before.

On Windows, the directory strutcure is: C:\Users\{user}\ICEFiles\default\SHARP

Creating SHARP Input

After ICE is properly installed and configured, the first step in utilizing the SHARP plugins is using ICE to generate the appropriate input files for the SHARP simulations.

Getting Started

This tutorial will generate the SHARP input files for the SAHEX1 simplified single hexagonal assembly problem, outlined in the SHARP Assembly-Scale Multiphysics Demonstration Simulations Report.

Once you have downloaded and placed the XML file in the correct directory, go ahead and launch ICE. Once ICE opens, we must first create a SHARP Model Builder Item. To do this, click the green plus icon (+) located at the top of the left-hand column.

ICE CreateItem.png

This will launch a dialog prompting you to select a new Item to create. Find SHARP Model Builder in the Item list and select Finish.

Defining Input Parameters

A SHARP Model Builder containing a number of parameters will appear in the main workspace. These parameters are specific to the input required by PROTEUS and have a number of restrictions. The specifics of PROTEUS input are beyond the scope of this tutorial, but the table below provides a brief outline of the parameters used for the SAHEX1 problem. Since we prepared and placed a ICE-native input file in the /ICEFiles/default/SHARP/ directory ahead of time, you will find the parameters are already filled out with appropriate values.

ICE SHARPModelBuilderForm.png

Parameter Name Value Description
METHOD <name>
SN_TYPE <16 character name> Specifies the type of SN cubature to use
THETA_RESOLUTION <value> > 0 Specifies the resolution of the SN cubature. Valid numbers for a hex reflected geometry are 1, 3, 5, 7, 9, ...
PHI_RESOLUTION <value> > 0 Only needed for product cubatures to select the resolution to apply in the radial plane. Valid numbers for a hex reflected geometry are 2, 5, 8, 11, 14, 17, 20, 23, ...
SEGMENT_ANGLE <value> ≥ 0 The number of segments to attempt in the angular approximation
DEBUG_PRINT_LEVEL <integer> ≥ 0 Specify level of debug printing for entire routine
DEBUG_PRINT_SETUP <integer> ≥ 0 Specify level of debug printing of setup related operations
DEBUG_PRINT_FORMATION <value> in range [0, 10] This controls the debug printing during the tracking/matrix formation
DEBUG_PRINT_OUTER <value> in range [0, 10] This controls the debug printing during the outer iterations
THERMAL_POWER <value> Specifies the normalization power in watts
SCATTERING_ORDER <integer> ≥ 0 Indicates the Legendre expansion order of the scattering kernel
EIGENVALUE_GUESS <value> The guess for the initial eigenvalue
USE_TCHEBYCHEV_ACCEL YES, NO Indicates whether Tchebychev acceleration is used
TOLERANCE_EIGENVALUE <value> The maximum relative error to allow on the eigenvalue
TOLERANCE_FISSION <value> The maximum relative error to allow on the outer iterations for the flux
TOLERANCE_FLUX <value> The maximum relative error to allow on the inner iterations for the flux
ITERATIONS_FISSION <value> The maximum number of outer iterations
ITERATIONS_UPSCATTER <value> The maximum number of Gauss-Siedel 'upscatter' iterations
ITERATIONS_SCATTER <value> The maximum number of inner iterations per outer iteration
ITERATIONS_SYNTHETIC <value> The maximum number of Krylov iterations to allow for the synthetic diffusion solver
ITERATIONS_KRYLOV <value> The maximum number of Krylov iterations to allow in the iterative flux solver
SOURCEFILE_MESH <128 character pathname> Specifies the UNIX file path to a spatial geometry mesh file
SOURCEFILE_XS <128 character pathname> Specifies the UNIX file path to a cross section data file
SOURCEFILE_MATERIAL <128 character pathname> Specifies the UNIX file path to a material mapping file
EXPORT_FLUX YES, NO Indicates whether the scalar flux is to be exported in addition to primary reaction rates
EXPORT_FILE <128 character pathname> Specifies the flux file name designation of a HDF5 or pmo file to export the solution
BC_ALIAS <name name> Used to change a boundary surface name to VOID or REFLECTIVE at runtime.

Once you have entered all the required parameters, or have made any changes to the existing ones, save the SHARP Model Builder by clicking the floppy disk icon located in the toolbar at the top of the ICE workbench (or Ctrl+S / +S).

ICE SaveButton.png

Generating SHARP Input Files

The last step involved is actually generating the SHARP-specific input files. To do so, simply find the Process drop-down menu located in the top right-hand corner of your SHARP Model Builder tab. Select Write SHARP File from the drop-down menu, and press the Go! button. Doing this will launch a script in the background to convert your input parameters into a file format that SHARP can understand. This operation should take no more than a second or two, and the message "Done!" should appear near the top of the SHARP Model Builder tab when it is complete.

ICE WriteSHARPFile.png

This file will be created in your /home/{user}/ICEFiles/default directory and will have the filename sharp_neutronics_{num}.inp, where {num} is your model builder Item number (i.e. SHARP Model Builder 1, SHARP Model Builder 2, etc.). It's important to note, that if you have a previously generated SHARP input file in your default directory, generating another input file with the same Item number will overwrite your existing file without warning.

This completes the SHARP input generation task. The file generated will be used in the next step by the SHARP Launcher to run SHARP remotely. However, if you'd like to review your input file before launching SHARP, you can do so by opening the File > Open File... menu in ICE, and navigating to the sharp_neutronics_{num}.inp file. Once opened, you will be able to review the input file generated.

ICE SHARPInputFile.png

Launching SHARP Jobs

The process for launching SHARP from ICE is not entirely different from creating an input file. ICE abstracts activities in such a way that they are not so different mechanically, even if the information exchanged is significantly different.

Creating the Launcher

To begin, create a ICE job by clicking on the green plus icon (+) above the Item Selection column on the left-hand side.

ICE CreateItem.png

In the list that appears, select SHARP Launcher. Note that because of all of the different items supported, you may need to scroll down to the bottom of the list to find the SHARP Launcher.

ICE SHARPSelectLauncher.png

The main editor area of the workbench will change once you click OK. A form will appear that requires some information about the job that you would like to run.

ICE SHARPLauncherForm.png

Setting the Input File & Hostname

The first thing that you need to do is select the input file for SHARP, which is just the neutronics input file that you created in the last section. Start by clicking the box labelled Input File and select your SHARP neutronics *.inp file. Remember that the file you created in the previous section will be named sharp_neutronics_{num}.inp where {num} is the number of your model Item. In the case below, the model was number one and the input file is sharp_neutronics_1.inp.

ICE SHARPChooseInput.png

The next step is selecting the machine on which ICE will launch SHARP. This can be either locally or remotely in general, although for now the SHARP Launcher only works locally and with a remote machine at ORNL. This will change after further testing.

ICE SHARPChooseHost.png

Launching the Job

After selecting both the input file and the host machine, save the project by clicking the floppy disk icon (or Ctrl+S / +S). Use the drop-down menu in the upper right-hand corner to tell ICE to launch the SHARP job. Select the Launch the Job task from the drop-down menu and click the Go! button.

ICE SHARPLaunchJob.png

ICE will then launch SHARP on your host machine. If you are trying to launch on a remote machine, you may also be asked for login credentials.

Viewing Results

SHARP takes a while to run. You can view live streaming output from SHARP in ICE's console and, when the job is finished, you can click on the Output Files and Data tab to view the files. If you are running on a remote machine, ICE will try to download the output files from your job if they are less than 50 MB in size each.

ICE SHARPOutputAndConsole.png

SFR Extensions to ICE's Reactor Analyzer

In addition to input generation and job launch, ICE provides access to analysis tools and its own reactor-specific tool, the Reactor Analyzer. This is a tool geared for quick analysis of nuclear reactor and fuel simulation data. The Reactor Analyzer provides tools for analyzing "quantities of interest" (i.e. flux, temperature, velocity etc.) pulled from the data output by any code that writes to the ICE I/O data format using the ICE I/O library. This section details the capabilities offered by the Reactor Analyzer, including how to start the Reactor Analyzer plugin, how to open the ICE reactor files generated by a simulator, and how to use the different tools in the plugin.

Importing Data into ICE

Before you can explore data in ICE's Reactor Analyzer, you need data that is in the ICE I/O format. Contact the ICE development team for some sample files that can be used in the Reactor Analyzer. If you use these files or other files that did not come from a job that you launched, you must import them to ICE so that it knows about them. The import option is available under File > Import a File. It is also available on the toolbar via the button that looks like a blue arrow. Select any file you would like to import, and click Open. The files should now be imported into ICE.

ICE SHARPImportFiles.png

If you launch a simulation using ICE, it automatically imports the data that the Reactor Analyzer can use, if it is available, when the job is done. Once you get more comfortable using ICE, it's important to remember to always import your files before creating the Reactor Analyzer item that will use them. If you forget, just delete the old item and create a new one.

Starting the Reactor Analyzer

The next step is to open the Reactor Analyzer by creating a new ICE item and selecting the Reactor Analyzer from the Item Selector dialog that pops up.

ICE SelectReactorAnalyzer.png

The Reactor Analyzer is split into three pages, called "tabs," that you can select near the bottom of the item's editor:

  • The first page, labelled Reactor/Fuel Assembly, provides the options to load reactors from files you have imported into ICE. It also contains two reactor views for easy visual comparison between different components of a single reactor or from different reactors.
  • The second page, Analysis Configuration, allows you to perform data mining and numerical analysis on the data through a suite of tools that is compatible with the loaded reactor files. (Depending on your version of ICE, the tools available to you may be different than others.)
  • The last page, Analysis Artifacts, allows you to directly view the files generated from the analysis routines and their contents.

These pages will be covered in more detail below.

You can maximize the Reactor Analyzer within ICE by double-clicking on its tab. You can also minimize or restore the views that contain the Item Viewer, Resources, Console, Transformations, etc.

Loading an imported file in the Reactor Analyzer

On the Reactor/Fuel Assembly page in the Reactor Analyzer, you can select the reactor data files that you would like to analyze from among those that you have imported into ICE. In the section labeled Data Sources, you can select both the input and reference data via the two drop-down lists. These lists are populated from .h5 files imported into ICE. Once you have selected the files you would like to use, click on the Save icon in the top left of the ICE window. If the files are compatible with ICE, the 'Reactor Viewer's below will populate with the data from the files.

ICE SHARPChooseSources.png

You can minimize the Data Sources section to further increase the screen real estate available to the graphical reactor views.

Navigating the Reactor Views

In top top right of each Reactor Viewer, there is a drop-down list labelled Views. These lists allow you to select the view displayed within each Reactor Viewer, so you can simultaneously view, for example, the input reactor's core and selected fuel assembly, or an assembly from each of the input and reference reactors. The default initial view is the reactor 'Core View' of the input reactor.

ICE AnalysisViews.png

At the top of each Reactor Viewer will be a set of buttons and drop-down lists for that particular view type. These options are also available in a context menu, which you can open by right-clicking somewhere within the Reactor Viewer.

For each of the view types in the Reactor Viewer, there is a button called Save Image, which allows you to save the graphics displayed as a BMP, JPG, or PNG image. This makes it easy to share a discovery with colleagues and friends or to use the analysis image in a presentation.

Browsing the Reactor Core

In the Core View, you have a graphical representation of the assemblies in a reactor core. White or empty hexagons within the core do not have an assembly of the currently selected type, while shaded hexagons do have an assembly. For fuel assemblies, you can select the assembly that is displayed in the assembly view (described below) by left-clicking on one of the shaded components in reactor view.

ICE ReactorView.png

Core View commands:

  • Assembly Type: Shows only assemblies of the selected type in the core.
  • Fuel Assembly (default): Shows only fuel assemblies in the core.
  • Control Assembly: Shows only control assemblies in the core.
  • Reflector Assembly: Shows only reflector assemblies in the core.
  • Shield Assembly: Shows only shield assemblies in the core.
  • Test Assembly: Shows only test assemblies in the core.
  • Save Image: Exports the current reactor core image to a file on your computer.

Browsing the Assembly

The Pin Assembly View displays a graphical representation of a pin assembly. You can see the geometric properties of each pin in the assembly or browse specific data features from the reactor data file. You can select the feature displayed via the Data Feature drop-down, and if there is data available along the length of the pins, you can navigate that data with the slider and scale on the right of the view. You can select the pin that is displayed in the Pin View (described below) by left-clicking on one of the pins in the assembly graphic.

ICE AssemblyView.png

Pin Assembly View commands:

  • Display Type: Toggles the view of the currently selected pin assembly.
  • Geometry (default): Shows the geometry of the assembly.
  • State Point Data: Shows the data for a particular feature at each pin location.
  • Data Feature: Selects the currently displayed data feature. If no data is available, this will be disabled, and each pin will display 0.0 for the data.
  • Save Image: Exports the current assembly image to a file on your computer.

Examining the Pin

The Pin View is very similar to the Pin Assembly View but focuses on a single pin. It provides a closer look at the geometry and data for a particular pin in an assembly. Like the Pin Assembly View, there is also a slider and scale to the right for browsing data with values along the length of the pin. There are also plans to provide an axial view—or a lengthwise cross-section—of the pin to the right of the current Pin View. The Axial View will also be available for navigating the data like the slider and scale.

ICE PinView.png

Pin view commands:

  • Display Type: Toggles the view of the currently selected pin.
  • Geometry (default): Shows the geometry of the pin.
  • State Point Data: Shows the data for a particular feature of the pin.
  • Data Feature: Selects the currently displayed data feature. If no data is available, this will be disabled, and the pin will display 0.0 for the data.
  • Save Image: Exports the current pin image to a file on your computer.

Plotting Pin Data

The Plot Analysis View allows you to plot data from the reactor file for multiple pins. This makes it easier to compare data for specific pins in the assembly. To make it easier on the user to select multiple pins for graphical analysis, we created a custom dialog that displays the pin assembly. To open the dialog, click the Select Plotted Series button. Inside the dialog, you can select multiple pins to pull data from by clicking and dragging and using the SHIFT or CTRL keys.

ICE PlotView.png

Plot Analysis view commands:

  • Select Plotted Series: Opens a dialog used to select data from the pins.
  • Clear Plot: Removes all plotted data.
  • Data Feature: Selects the currently displayed data feature. If no data is available, this will be disabled.
  • Save Image: Exports the current plot image to a file on your computer.

Performing Data Mining Routines

In the Analysis Configuration tab, you can select from various pre-programmed strategies for mining or numerical analysis of the data. As of now, strategies are only available for LWRs, not SFRs. If there are strategies available for the reactor type of your input and reference files, then do the following to select and run them:

The two images below show the Analysis Configuration and the Analysis Artifacts tabs, respectively. These tabs can be used to select, modify, run, and review analysis tools available for the input and reference files.

ICE AnalysisConfiguration.png

In order to run an available strategy on the input and reference data in the Reactor Analyzer, you should

  1. Add a strategy.
    • Select the Analysis Configuration tab at the bottom of the main Reactor Analyzer View.
    • In the Analysis Configuration View, click on Add.
    • A dialog should appear with the available strategies. Select one and click OK.
  2. Modify the strategy.
    • In the Analysis Configuration View, click on a strategy.
    • The Global Analysis Options section appears to the right. You can use this section to modify the strategy if options are available.
  3. Run the strategy.
    • At the top right where it says Process, click on the drop-down list.
    • Select Generate Analysis Artifacts.
    • Click Go!
  1. Review the strategy results.
    • Select the Analysis Artifacts tab at the bottom of the main Reactor Analyzer View.
    • In the Resources View, select the file generated by the strategy. You can expand the list item to get the files details.
    • Click on the file to view the contents of it in the Reactor Analyzer.

The raw output can be viewed in the Analysis Artifacts tab.

ICE AnalysisArtifacts.png

When running the strategies, standard output will be directed to the Console View in ICE.

Plotting the Comparison Data

Some strategies can be plotted with the Plot Analysis View described above. If you switch back to the Reactor/Fuel Assembly tab in the Reactor Analyzer, you can open up Comparison > Plot View and plot the data generated from the strategy just as you would a typical reactor file.

The image below demonstrates the plotting capability for comparison data generated by data mining strategies using data taken from LWR simulations, not SFRs.

ICE ComparisonPlot.png

Known Issues

The SHARP plugins are not thoroughly tested... because they are brand new! There are some known issues that users should keep in mind while we fix them:

  • ICE can only launch on one remote machine in the latest release. Please check out a nightly build for the capability to specify the target host.
  • SHARP does not immediately generate output that can be viewed in ICE's Reactor Analyzer. While we were very successful in making the infrastructure to view data from SHARP, we have not yet finished the work required to automatically generate ICE's HDF5 file.
  • There is no way to cancel a SHARP job once it is launched without stopping ICE. The "kill switch issue" is a well known problem with ICE that is currently being addressed.
  • The 'Pin Assembly View' in the Reactor Analyzer does not display the duct.
  • The Pin View in the Reactor Analyzer does not display an axial view of the pin. There are plans to show a pin axial view, which will show the axial data or materials composing the pin and allow you to change the currently displayed data just like the current scale and slider widgets.

Ongoing Work

The ICE development team has several areas of ongoing work related to the SHARP plugins project:

  • At the time of writing this document, ICE's SHARP plugins currently support functionality for the PROTEUS neutronics simulation codes. The ICE development team intends to further extend SHARP functionality in ICE to include Nek5000 computational fluid dynamics codes, and DIABLO structural mechanics codes as well.
  • While the development of ICE's SHARP plugins is initially based upon a simplified single assembly test reactor, we plan to next upgrade this example to a 7-assembly reactor, and eventually a 199-assembly ABTR (Advanced Burner Test Reactor) designed by Argonne National Laboratory.
  • We are currently in the process of writing extensions to SHARP that will write the output directly to a ICE I/O file. This file will be recovered after ICE launches SHARP and available for immediate consumption in the Reactor Analyzer.
  • In the future, we plan to enhance the support of our light-water and sodium-cooled fast reactor packages, including reducing redundancy between the two where possible.

Back to the top