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 PROTEUS with ICE

This is a legacy tutorial and may contain outdated information.

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 ICE team by sending an email to the appropriate mailing list, or by filing a bug report.

Getting Started

This document is designed to outline the basic steps of setting up and using the PROTEUS plugins in ICE. There are two different tasks for the input generation and launching of PROTEUS within ICE:

  • PROTEUS Model Builder - Using selected parameters, generates a set of input files necessary to launch the PROTEUS neutronics codes.
  • PROTEUS Launcher - Initiates the PROTEUS codes to run on a local or remote system using the files generated from the PROTEUS Model Builder.

Installation and 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 SHARP plugins require that library.


You should have PROTEUS installed on a machine. The plugins are currently only configured to run PROTEUS on an ORNL machine. See "Known Issues" below.

You need to install the ICE I/O libraries on the same machine where PROTEUS is installed. There is no easy way to do this since they are not distributed as a binary. You have to checkout the ICE 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 ICE I/O is too difficult, contact the ICE Dev team.

Lastly, to utilize the PROTEUS plugins, ICE requires a data file that contains a specification of the PROTEUS input parameters; download this from the ICE project here. After downloading it, create a directory named PROTEUS_Model_Builder in the /home/<user>/ICEFiles/default/ directory on your local system, and place the NiCEProteusInput.xml file here before launching ICE. If you have never launched ICE on your system before, you will also have to create the ICEFiles/default directory as well.

On Windows, the directory structure is different: C:\Users\<user>\ICEFiles\default\PROTEUS_Model_Builder

Creating Input

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

This tutorial will generate the PROTEUS 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. An empty workspace will appear.


To begin, we must first create a PROTEUS Model Builder item; click on the green plus icon (+) located at the top of the left-hand column.


This will launch a dialog prompting you to select a task (or Item) to create. Find PROTEUS Model Builder in the Item Selector list (you may need to scroll down) and select OK.


Defining input parameters

A PROTEUS 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 is 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 an ICE-native input file in the ICEFiles/default/PROTEUS_Model_Builder/ directory ahead of time, you will find the parameters are already filled out with appropriate values.


Name Value Description
METHOD <none>
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 PROTUES Model Builder project by clicking the floppy disk icon located in the top left-hand corner of ICE.

Generating PROTEUS input files

The last step involved before launching PROTEUS is actually generating the PROTEUS-specific input files. To do so, simply find the Process drop-down menu located in the top right-hand corner of your PROTEUS Model Builder tab. Select Write PROTEUS 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 PROTEUS can understand. This operation should take no more than a second or two, and the message "Done!" should appear near the top of the PROTEUS Model Builder tab when it is complete.


This file will be created in your /home/<user>/ICEFiles/default/ directory and will have the file name proteus_neutronics_<num>.inp, where <num> is your model builder Item number (i.e. PROTEUS Model Builder 1, PROTEUS Model Builder 2, etc.). It's important to note that if you have a previously generated PROTEUS 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 PROTEUS input generation task. The file generated will be used in the next step by the PROTEUS Launcher to run PROTEUS remotely. However, if you'd like to review your input file before launching PROTEUS, you can do so by opening the File > Open File... menu in ICE, and navigating to the proteus_neutronics_<num>.inp file. Once opened, you will be able to review the input file generated.


Launching PROTEUS Jobs

The process for launching PROTEUS from within 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

Assuming you just generated a PROTEUS-specific input file, you already have ICE running. If not, launch ICE and wait until an empty workspace appears.


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


In the list that appears, select PROTEUS 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 PROTEUS 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 PROTEUS, which is just the neutronics input file that you created in the previous section. Start by clicking the box labelled Input File and select your PROTEUS neutronics *.inp file. Remember that the file you created in the previous section will be named proteus_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 proteus_neutronics_1.inp.

ICE SHARPChooseInput.png

The next step is selecting the machine on which ICE will launch PROTEUS. This can be either locally or remotely in general, although for now the PROTEUS 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 Save floppy disk button in the upper left-hand corner. Use the drop-down menu in the upper right-hand corner to tell ICE to launch the PROTEUS job. Select the Launch the Job task from the drop-down menu and click the Go! button.


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


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

Known Issues

The PROTEUS 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:

  • PROTEUS 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 PROTEUS, we have not yet finished the work required to automatically generate ICE's HDF5 file
  • There is no way to cancel a PROTEUS job once it is launched without stopping ICE; "the kill switch issue" is a well known problem with ICE that is currently being addressed

Back to the top