Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Using PROTEUS with ICE
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.
Contents
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.
Prerequisites
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 |
| 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 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.
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.
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