Using MOOSE with ICE
- 1 Introduction
- 2 Installation and Configuration
- 3 Generating YAML and Action Syntax Files
- 4 Creating Input
- 5 Launching a MOOSE Job
- 6 FAQ (Frequently Asked Questions)
- 7 Visualizing Output
This document is designed to outline the basic steps of setting up and using the MOOSE plug-ins in ICE. ICE currently supports four MOOSE-based applications: MARMOT, BISON, RELAP-7 and RAVEN. Although this tutorial was created with BISON in mind, the steps for using ICE with MARMOT, RELAP-7 and RAVEN are the same.
There are two different tasks for the input generation and launching of MOOSE products within ICE:
- MOOSE Model Builder - Generates a custom input file necessary to launch a MARMOT, BISON, RELAP-7 or RAVEN job.
- MOOSE Launcher - Initiates the MARMOT, BISON, RELAP-7 or RAVEN codes to run on a local or remote system using the files generated from the MOOSE Model Builder. Also includes the option to run a custom MOOSE-based application.
Any problems should be reported directly to the ICE team by sending an email to the project list,
ice-dev <at> eclipse.org, or following the instructions to report bugs on our Bugzilla.
Installation and Configuration
Follow the instructions in the Getting ICE article to download and install the latest version of ICE on your system.
You should have the MOOSE environment installed, either your local or remote machine. Instructions for installing MOOSE can be found here.
Additionally, you should have MARMOT, BISON, RELAP-7 or RAVEN compiled and ready to run. Contact the development teams of these projects on the rules and regulations for obtaining these codes.
ICE supports numerous plugins from different areas of science, and as a result it can sometimes be difficult for new users to make sense of all the different windows, panels and tabs in the workbench. To address this issue for MOOSE users, ICE now includes a MOOSE Perspective which pares down UI components to only those that are necessary for MOOSE-based plugins.
To access the MOOSE Perspective, use the the ICE toolbar at the top and navigate to:
Window > Open Perspective > Other...
Select MOOSE in the window that pops up and click OK. Alternatively, you can also access the same pop-up menu by clicking the Open Perspective button in the upper right-hand corner of the ICE workbench.
Once the MOOSE Perspective opens, you should notice the workbench now contains fewer UI components, and resembles something like this:
While it's not necessary to switch to the MOOSE Perspective to use MOOSE-based plugins, it has been included for convenience.
Generating YAML and Action Syntax Files
Like any MOOSE-based GUI, ICE relies on generated YAML and action syntax files to specify the rules of creating input files. To simplify this task, ICE includes a utility that will generate these files (either locally or remotely), clean them up, and place them in the appropriate local directory for ICE to use. All that is required of the user is to specify where and on which machine their MOOSE codes are installed.
This task must be completed at least once for every installation of ICE before the MOOSE Model Builder can be used. It's also a good idea to periodically re-run this utility to keep ICE's YAML and action syntax files in sync with any updates to your MOOSE-based codes.
To use this utility, begin by clicking the document-like button in the ICE toolbar:
This will prompt a wizard to pop up requiring a few pieces of information:
This can be a local or remote machine.
- Execution Path
Enter the fully-qualified path to the "herd" directory of your machine's MOOSE installation. For example, if I have BISON on a machine with the following structure:
/home/user/trunk/bison/bison-optI would set the execution path in ICE to be:
/home/user/trunkIf you are launching on a remote machine, also be sure that you have appropriate privileges for the execution path.
- Login Credentials
Your username and password (if required) on the host machine.
Once you have filled out the information, click Finish. This will launch a script on your designated machine that checks which MOOSE-based codes you have installed, generates the appropriate files, removes any extraneous header/footer text, and places them in your
/home/<user>/ICEFiles/default/MOOSE directory where ICE can reference them later.
To create an input file for a MOOSE problem, there are two ways you can get started: creating an input file from scratch, or importing an already existing file to modify.
Creating an Item
If you'd like to start from scratch, begin by clicking the green "+" button in the Item Viewer, located on the left-hand side of the ICE workbench.
This will prompt a window to pop up; select the MOOSE Model Builder Item, and click Finish.
Alternatively, if you'd like to import an already existing *.i file to modify, click the yellow item import arrow located at the top of the ICE workbench.
A wizard will pop up prompting you to specify two things: the *.i file you'd like to import from your filesystem, and what kind of Item you'd like to import it into.
Use the Browse... button to select your input file, and set the item type to MOOSE Model Builder. Click Finish when you're done and ICE will import the file data.
Regardless of how you decide to begin creating your input file, once the MOOSE Model Builder loads, you will see a workbench that looks like the following. Make note of the three tabs highlighted: the Tree View, Mesh and Properties tabs, as we'll be using them quite a bit in the following section.
Constructing the Tree
Before be begin constructing our problem, the first order of business is to specify which MOOSE application we're defining a problem for. Using the radio buttons in the main MOOSE Model Builder tab, select one of the options; in this example, we'll be creating a BISON problem.
Once you've made a selection, it must be applied by saving the form. Save by clicking the floppy-disk save icon (or ⌘+S / Ctrl+S).
At this point, a fully loaded set of blocks should appear in the Tree View. If you imported your data from an already existing file, you'll notice the data has been loaded into any blocks that are checked off. If you started from scratch, none of the blocks will be checked off yet.
We're now ready to begin using the Tree View to add, delete and modify blocks.
Expanding and Collapsing Subblocks
If you imported data from an already existing input file, you will likely notice some block names with a small arrow next to them. This indicates that the block contains subblock structures beneath it. To access these subblocks, simply click the small arrow and the subblocks will expand. Clicking this arrow again will collapse the subblocks.
Adding and Deleting Blocks
If you'd like to add a subblock, first select the parent block you'd like to add it to. Next, click the green "+" button located at the top right-hand corner of the Tree View. Alternatively, you can also right-click the parent block, and select Add Child from the context menu that appears.
Doing this will prompt a pop-up dialog to appear. This dialog contains a list of all possible subblocks that can be added, according to rules outlined in the YAML files generated earlier. Each block that appears in the list has its own unique set of parameters, with the exception of BlankBlocks, which are—as their name suggests—blocks that are totally devoid of any data.
Once you've selected a subblock to add, click OK, and it will be added in the Tree View. Use the arrow next to the parent block to expand/collapse the list of subblocks.
Similarly, to delete a block, select the particular block you'd like to remove, and click the red "x" button located at the top right-hand corner of the Tree View. You can also delete a block by right-clicking on it and selecting Delete Child from the pop-up context menu.
If the red "x" button is greyed-out for a particular block, this means that deletion has been disabled. This is true for all top-level blocks.
To rename a block, right-click on the block in question and select Rename from the context menu that appears. If the renaming option is greyed-out from the context menu, this means that renaming has been disabled for this block. Once again, this is true for all top-level blocks.
Each block has a set of parameters associated to it. The default list of parameters for each block is drawn from the YAML file that was generated earlier. To add, remove or modify parameters associated to a block, first select a block from the Tree View. A table of parameters will then appear in the Properties tab referenced earlier.
The parameters table displays a parameter name, value and the option for an in-line comment, which can all be edited directly in this table. When written out to file, each parameter will be written to one line in the form:
name = value # comment
Additional parameters can be added by clicking the "+" button to the right of the parameter table; parameters can be similarly deleted by clicking the "-" icon.
Next to each parameter row, you'll also notice an Enabled checkbox. Toggling this option on means that the parameter associated to it will be written out normally in the file created. Toggling this option off will cause the entire line to be commented out, and thus, won't be used during the problem runtime.
Note that if you created a MOOSE Model Builder by importing data from an already existing input file, ICE automatically parses any in-line comments or commented out lines (non-sensitive to leading whitespaces). This will be reflected in the Enabled and Comment columns of the parameters table.
Lastly, some blocks contain a special type parameter, such as the Executioner block, which affects the list of parameters associated to the block. In these special instances, an additional drop-down menu will appear in the Property tab, above the parameters table.
By setting the type of the block ICE automatically repopulates the parameter table according to the rules defined by the YAML specification.
Viewing the Mesh File
If your MOOSE problem uses a mesh file, it can be viewed in an interactive embedded VisIt client. More information about how to correctly configure a VisIt session in ICE can be found in the documentation on embedded VisIt visualizations in ICE.
To begin, make sure your Mesh block contains a parameter named file by clicking on the Mesh block in the MOOSE tree and examining its parameters in the Properties View. The file parameter should be set to the name of a *.e file located in your
/home/<user>/ICEFiles/default directory. You can either manually place the mesh file in that folder or import it using the import button in ICE's main toolbar. If you need to add a file parameter, do so now, and then save the form by clicking the floppy-disk save icon (or ⌘+S / Ctrl+S).
When you save the MOOSE Model, ICE will attempt to load the file specified by the Mesh block's file parameter as a Resource. To view the mesh, open the MOOSE Model Builder's Mesh tab, then double-click the mesh file Resource in the Resources View. If the file can be read by one of ICE's Visualization Services, e.g., VisIt, the first available mesh in the file will be opened in the Mesh tab's Resource Page.
For more information about embedded visualizations like this or about ICE Resources and Resource Pages, please see the documentation on embedded visualizations in ICE.
Viewing the 3D Plant (RELAP-7 only)
For RELAP-7 problems, ICE includes an interactive 3D Plant View to visualize the physical representation of the problem. To access the Plant View, click the Plant View tab located at the bottom of the main MOOSE Model Builder panel.
This view draws data from the Components block in the Tree View; if you have valid components in the Components block, then they should begin rendering now. Before we go on, there are a few things to note about using the Plant View. First, only components that are currently enabled in the Tree View (i.e. have a checkmark) are rendered. This way, components can easily be turned on and off without having to delete them entirely. And secondly, the Plant View updates in real time; any changes that you make to components in the Tree View will be reflected immediately such as adding, removing, re-positioning or re-orienting components.
Once your plant components have rendered, you can move around the 3D space by using the arrow buttons in the toolbar above the viewing window (hover over the button for a description of what it does), or by using the following keyboard controls:
* The camera viewing-angle can also be pivoted by left-clicking and dragging
Lastly, the Plant View has 3 other tools located in the toolbar above the 3D viewing window, to the left of the movement/rotation buttons.
- Wireframe - Clicking this will toggle the plant's wireframe on and off; this allows you see how the meshes for the rendering engine are constructed.
In certain cases, this may be useful for verifying the plant model before running a simulation. For instance, pipe components in RELAP-7 have a property called "n_elems" representing the number of cylindrical cross-section slices along the pipe's length. By switching to wireframe mode, the user can see the same number of cylindrical sections stacked together that represent the pipe's physical construction.
- Camera Orientation - You can re-orient the rendering engine's default camera view by clicking on the Camera Orientation button. The default orientation—YZ—is the standard <i, j, k> physics orientation with the Y axis increasing to the right, the Z axis increasing upwards, and the camera looking at the YZ-plane along the positive X axis.
In the same "Camera Orientation" menu, we provide two alternative default orientations: the XY orientation shows the XY-plane from along the positive Z axis, and the ZX orientation shows the ZX-plane from along the positive Y axis. Selecting Reset to current default will snap the camera back to the origin view should you ever get lost.
- (Camera Icon - Save Image) - Clicking this will prompt a pop-up window to save a .png image of the current Plant View to your local filesystem.
Creating the File
Once you have edited your blocks and associated parameters to your liking, the last step is to write them to file.
Any top-level block in the Tree View with a checkmark next to it will be written to file, and any top-level blocks without a checkmark will not. Similarly, any sub-blocks with a checkmark will also written to file, however, any sub-blocks without a checkmark will still be written to file but commented out. Ensure that you've correctly checked/unchecked all the necessary blocks. Save your work by clicking the floppy-disk save icon (or ⌘+S / Ctrl+S).
In the main MOOSE Model Builder tab, specify the name of the file you'd like to write in the Output File Name field. Next, in the top right-hand corner, set the Process drop-down menu to "Write MOOSE File", and click the Go! button.
This will write the contents of your Tree View to the specified filename, and will be placed in your
/ICEFiles/default directory. If you wish to review the file before moving onto the next section, you can do so by using the ICE toolbar and navigating to:
File > Open File...
Launching a MOOSE Job
Once you've generated appropriate input files, launching a MOOSE job is a relatively simple task.
To get started, click the green "+" button in the Item Viewer once more to create a new ICE Item.
Select MOOSE Launcher from the menu that pops up and click Finish.
A form will appear in the main ICE workbench area. This form contains the information necessary for launching a MOOSE problem.
Selecting the Input File(s)
From the Input File(s) drop-down menu, select an appropriate MOOSE input file. This drop-down menu displays all *.i files that were in the
/ICEFiles/default directory at the time the MOOSE Launcher was created. If you created your own input file in the previous step using the MOOSE Model Builder, this file should appear in the list of available files.
If you'd like to use an input file not found in this list, click the Browse... button; a file browser will pop up for you to locate the file you'd like to use. Once you've selected a file, it will be imported into the
At this time, the MOOSE Launcher will scan the *.i file for any references to additional files, such as a mesh, peaking factors, power history, etc. If any additional file dependencies are found, the MOOSE Launcher will dynamically render additional file entries for your to set in the same manner.
Selecting the MOOSE Product
You will need to indicate which MOOSE-based application you'd like to run. From the list of Available Executables, simply select one of the available applications.
If you'd like to launch a custom MOOSE application not listed, you also have the option of doing so. Select Custom executable name from the drop-down menu, and enter your application's name in the text field that appears.
If we were to use the above example, ICE would attempt to launch an executable called
PUMA-opt (and not
puma-opt). To learn more about creating your own custom MOOSE-based applications, read about Developing MOOSE Applications with ICE.
Specifying a Hostmachine
From here, the next step is to tell ICE which machine your MOOSE code will be run on, either locally or remotely. A list of hosts used at ORNL is displayed by default, however, additional hosts can be added by clicking the "+" button to the right of the Hosts table.
When adding hosts, set the Execution Path to the "herd" directory of the machine's MOOSE installation. For example, if I'm launching BISON on a machine with the follow structure:
I would set the execution path in ICE to be:
If you are launching on a remote machine, also be sure that you have appropriate privileges for the execution path.
Setting Parallel Execution (Optional)
Optionally, if you'd like to take advantage of parallel processing, you may specify the number of MPI process and/or Intel Thread Building Block (TBB) threads.
To use multiple MPI processes, change the marked field to an integer value anywhere between 1 and 10000. Note that
mpirun must be specified in the host machine's
PATH variable. If you choose not to change this field, the default value of 1 MPI process is used.
To use multiple TBB threads, change the marked field to an integer value anywhere between 1 and 256. Note that the host machine must have Intel TBB support. If you choose not to change this field, the default value of 1 TBB thread is used.
Launching the Problem
Once the input file(s), host, and any parallel execution options are specified, save your settings. If you make any subsequent changes to the MOOSE Launcher form, you will have to re-apply them by saving the form in the same way.
Lastly, use the Process menu in the upper right-hand corner; select the Launch the Job task from the drop-down menu and click the Go! button.
Depending on your host machine's configuration, you may be prompted for login credentials.
You should shortly begin seeing the standard console output in ICE as your problem begins to solve.
FAQ (Frequently Asked Questions)
An FAQ for MOOSE users can be found here. If you have any additional questions that are not addressed in this document, email our project development list at
ice-dev <at> eclipse.org.
Once your problem has successfully solved, ICE will automatically add any files and post-processing data produced—such as CSV, Exodus, etc.—to the Resources View (your original input files are also added for your convenience). Data listed in the Resources View can be visualized on a Resource Page via embedded plotting views. To learn more about viewing post-processing files and how to set up embedded visualizations, see our Embedded Visualizations tutorial.
Alternatively, if you'd prefer to not use embedded visualizations, files can also be manually viewed using the Visualization Perspective tools. See our Visualizing Output tutorial for instructions.