Using SHARP with NiCE

The capabilities in this document are brand new and while we assert that they work, that may not be the case on all systems for all users. Problems should be reported directly to the NiCE team by sending an email to the project list, niceproject-development@lists.sourceforge.net, or following the instructions to report bugs at niceproject.sourceforge.net.

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

• 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.

Table of Contents

• Installation and Configuration
  • Prerequisites
  • Developer steps for SHARP installations
  • Data configuration
• Creating Input
  • Getting started
  • Defining input parameters
  • Generating SHARP input files
• Launching SHARP Jobs
  • Creating the launcher
  • Setting the input file and hostname
  • Launching the job
  • Viewing results
• SFR Extensions to NiCE's Reactor Analyzer
  • Importing data into NiCE
  • Starting the Reactor Analyzer
  • Loading an imported file in the Reactor Analyzer
  • Navigating the reactor views
  • Browsing the reactor core
  • Browsing the assembly
  • Examining the pin
  • Plotting pin data
  • Performing data mining routines
  • Plotting the comparison data
• Known Issues
• Ongoing Work

Installation and Configuration

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

Prerequisites

You should have SHARP installed on a machine.

Developer steps for SHARP installations

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

In the future it will be possible to generate NiCE I/O files directly from SHARP. If you are a developer or IT specialist who is configuring this capability, you need to install the NiCE 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 NiCE trunk onto your machine using SVN and run the following instructions in your shell from the trunk directory:

mkdir nativeBuild
cd nativeBuild
cmake ..
make
make test
make install

If installing NiCE I/O is too difficult, contact the NiCE Dev team.

Data configuration

NiCE requires a data file for SHARP that contains a specification of the PROTEUS input parameters. You need to download this from the NiCE project here. After downloading it, create a directory named SHARP in the /home/<user>/NiCEFiles/default/ directory on your local system, and place the NiCEProteusInput.xml file here before launching NiCE. You may need to create this directory if you have never launched NiCE before.

On Windows the directory structure is different: C:\Users\<user>\NiCEFiles\default\SHARP

Creating Input

After NiCE is properly installed and configured, the first step in utilizing the SHARP plugins is using NiCE 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 NiCE. Once NiCE opens, we must first create a SHARP Model Builder Item. To do this, click on the icon depicting a window with a plus sign, located at the top of the left-hand column. This will launch a dialog prompting you to select a new item to create. Find SHARP Model Builder in the Item list and select OK.

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 NiCE-native input file in the NiCEFiles/default/SHARP/ directory ahead of time, you will find the parameters are already filled out with appropriate values.

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
SN2ND_COMPUTES_DENSITY	YES, NO
BASIC_BWO	YES, NO
P_MULTIGRID_ORDER	<value>
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 project by clicking the floppy disk icon located in the top left-hand corner of NiCE.

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 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.

This file will be created in your /home/<user>/NiCEFiles/default/ directory and will have the file name 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 NiCE, and navigating to the sharp_neutronics_<num>.inp file. Once opened, you will be able to review the input file generated.

Launching SHARP Jobs

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

Creating the launcher

You can launch SHARP jobs in NiCE as soon as it opens and displays the empty workbench.

You can create a NiCE job by clicking on the green plus icon (+) above the Item Selection column on the left-hand side.

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.

The central "editor" area of the workbench will change once you click OK on the Item Selection menu. It will display a form that requires some information about the job that you would like to run.

Setting the input file and 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.

The next step is selecting the machine on which NiCE 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.

Launching the job

After selecting both the input file and the host machine, save the project by clicking the Save floppy disk button in the upper left-hand corner. Use the drop-down menu in the upper right-hand corner to tell NiCE to launch the SHARP job. Select the Launch the Job task from the drop-down menu and click the Go! button.

NiCE will immediately launch SHARP on the local machine when you click the OK button. If you are trying to launch on a remote machine, NiCE will ask for your credentials on that machine.

Input your username on the remote machine and enter your password. Hit OK and NiCE will attempt to push the job on the remote machine.

Viewing results

SHARP takes a while to run. You can view live streaming output from SHARP in NiCE'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, NiCE will try to download the output files from your job if they are less than 20MB in size each.

SFR Extensions to NiCE's Reactor Analyzer

In addition to input generation and job launch, NiCE 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 pulled from the data output by any code that writes to the NiCE I/O data format using the NiCE 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 NiCE reactor files generated by a simulator, and how to use the different tools in the plugin.

Importing data into NiCE

Before you can explore data in NiCE's Reactor Analyzer, you need data that is in the NiCE I/O format. Sample data files are available at here. If you use these files or other files that did not come from a job that you launched, you must import them to NiCE 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 NiCE.

If you launch a simulation using NiCE, 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 NiCE, 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 NiCE item and selecting the Reactor Analyzer from the Item Selector dialog that pops up.

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 NiCE. 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 NiCE, 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.

Tip: You can maximize the Reactor Analyzer within NiCE 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 NiCE. 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 NiCE. Once you have selected the files you would like to use, click on the Save icon in the top left of the NiCE window. If the files are compatible with NiCE, the Reactor Viewers below will populate with the data from the files.

Tip: 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.

Tip: 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.

Tip: 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.

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.

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.

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.

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.

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

1. Add a strategy.

2. Select the Analysis Configuration tab at the bottom of the main Reactor Analyzer View.

3. In the Analysis Configuration View, click on Add.

4. A dialog should appear with the available strategies. Select one and click OK.

5. Modify the strategy.

6. In the Analysis Configuration View, click on a strategy.

7. The Global Analysis Options section appears to the right. You can use this section to modify the strategy if options are available.

8. Run the strategy.

9. At the top right where it says Process, click on the drop-down list.

10. Select Generate Analysis Artifacts.

11. Click Go!

12. Review the strategy results.

13. Select the Analysis Artifacts tab at the bottom of the main Reactor Analyzer view.

14. In the NiCE Resources View, select the file generated by the strategy. You can expand the list item to get the files details.
15. 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.

Tip: When running the strategies, standard output will be directed to the Console View in NiCE.

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.

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:

• NiCE 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 NiCE'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 NiCE's HDF5 file.
• There is no way to cancel a SHARP job once it is launched without stopping NiCE. The "kill switch issue" is a well known problem with NiCE 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 NiCE development team has several areas of ongoing work related to the SHARP plugins project:

• At the time of writing this document, NiCE's SHARP plugins currently support functionality for the PROTEUS neutronics simulation codes. The NiCE development team intends to further extend SHARP functionality in NiCE to include Nek5000 computational fluid dynamics codes, and DIABLO structural mechanics codes as well.
• While the development of NiCE'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 NiCE I/O file. This file will be recovered after NiCE 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.