View source for Creating MARMOT Input Files with ICE


== Getting Started ==

This document is designed to outline the basic steps of setting up and using the MARMOT plugins in ICE. There are two different tasks for the input generation and launching of MARMOT within ICE:
*'''MOOSE Model Builder''' - Generates a set of input files necessary to launch a MARMOT job.
*'''MARMOT Launcher''' - Initiates the MARMOT codes to run on a local or remote system using the files generated from the ''MOOSE Model Builder''.

=== Prerequisites ===

You should have the MOOSE environment installed, either your local machine or on a remote machine.

You will also need MARMOT installed on a machine, either your local machine or a remote machine.

Generating MOOSE-specific input files in ICE requires YAML files to be downloaded ahead of time. We cannot provide these files for you, so you will have to generate them from MOOSE or request them from the MOOSE team. Navigate to the /moose/trunk/marmot directory and use the command:

<code>./marmot-opt --yaml; marmot.yaml</code>

to generate the file.

Open marmot.yaml and check if it starts with

<code>**START YAML FILE</code>

and/or ends with

<code>**END YAML FILE</code>

If these two lines are in the file, remove them, because they are not valid YAML.

Create a directory named MOOSE in your local file system in one of the following directories:

On Linux, use: /home/<user>/ICEFiles/default/

On Mac OS X, use: /Users/<user>/ICEFiles/default/

On Windows, use: C:\Users\<user>\ICEFiles\default\

=== Installation and Configuration ===

Place the all of the MOOSE YAML files (marmot.yaml and any others) in the MOOSE directory before launching ICE. If you have never launched ICE on your system before, you will also have to create the ICEFiles/default directory.

== Creating Input ==

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

This tutorial will demonstrate the general procedure for generating MARMOT input in ICE.

To begin, launch ICE (if it isn't already running), and you should be presented with an empty workbench.

[[File:EmptyNiCEWorkspace.png|1500px]]

We must first create a ''MOOSE Model Builder'' item. ICE provides three options for creating new items (all highlighted in red below). The user may click on the green plus icon (+) located near the top-right corner of the ''Item Viewer'', click on the ''New Item'' button in the main ICE toolbar, or choose ''File > Create an Item''.

[[File:CreateNewItemOptions.png]]

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

[[File:SelectMOOSEModelBuilder.png]]

=== Defining and modifying input parameters ===

A MOOSE Model Builder will appear in the main workspace, and the ''Input Data -- Tree View'' will be activated in the left-hand column. If any YAML files for MOOSE-based application exist in the ICEFiles/default/MOOSE/ directory, they will appear in the main workbench window.

[[File:MOOSEModelBuilderForm.png]]

Under the MOOSE Model Builder form, select ''MARMOT'' from the available MOOSE-based applications.

[[File:SelectMARMOTApp.png]]

Next, save the form by clicking the floppy disk ''Save'' button in the toolbar, or pressing Ctrl+S on your keyboard.

[[File:SaveButton.png]]

You can now begin adding specifics to your MARMOT input model. For example, to add constraints to your MARMOT model, select ''Constraints'' in the ''Input Data'' -- Tree View column on the left, and click the the ''Add Child'' button above. This will prompt you with a list of constraints to select from. Simply choose the one you would like to add, and click ''OK''. In this example, we're beginning by adding an EqualValueConstraint.

[[File:SelectConstraintAddChild.png]]

[[File:AddConstraintsDialog.png]]

Once a child (an ''EqualValueConstraint'' in this case) is added to the tree view, you can edit its parameters. In this example, expand the Constraints node to reveal the EqualValueConstraint that was just added.

[[File:ExpandConstraints.png]]

Select the Pump component by clicking its name, and a number of Pump-specific parameters will be displayed in the ''Properties'' view. You can now edit the parameters as you see fit. (If for any reason you cannot see the Properties view, you can reveal it by navigating from the main ICE toolbar at the top: ''Window > Show View > Other... > General > Properties''. You can then drag the Properties view around to anywhere in the workbench that is convenient for you.)

[[File:ConstraintEditPropsView.png]]

Continue adding children to the tree view and editing parameters in the same manner until you have created a satisfactory plant model.


=== Generating MARMOT input files ===

The last step involved before launching a MARMOT job is actually generating the input files based on the model just created.

First, use the ''Output File Name'' field to specify the name of your MARMOT file. Apply the name by clicking the floppy-disk Save button mentioned earlier.

Next, you must select which nodes in our MARMOT model tree you'd like to be written into an input file. To do so, go through the tree and select the nodes you'd like to use by clicking the checkbox next to its name. Note: You only need to select the top-level nodes (i.e. Bounds, CoupledProblems, Debug, EoS, etc.); the children will be automatically added.

Lastly, find the ''Process'' drop-down menu located in the top right-hand corner of your ''MOOSE Model Builder'' tab. Select ''Write MOOSE 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 MARMOT can understand. This operation should take no more than a second or two, and the message "Done!" should appear near the top of the ''MOOSE Model Builder'' tab when it is complete.

[[File:MOOSEWriteFile.png]]

This file will be created in your /home/<user>/ICEFiles/default/ directory and will have the file name you specified. It's important to note that if you have a previously generated MARMOT input file in your default directory, generating another input file with the same name will overwrite your existing file without warning.

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

== Launching a MARMOT job ==

Once you've generated appropriate input files, launching MARMOT is a relatively simple task.

To get started, click the green "+" button once more to create a new ICE Item. Select Marmot Launcher from the menu and click ''OK''. 

A form will appear in the main ICE workbench area. This form contains the information necessary for launching a MARMOT problem.

[[File:MARMOTLauncherWorkbench.png]]

=== Setting the input file and host ===

The first piece of necessary information is to specify an input file.

If you are using an input file that was created elsewhere, it must be in your /home/<user>/ICEFiles/default/ directory ''prior'' to creating the MARMOT Launcher Item or you will need to import it. To do this, click "File->Import File" and pick the file that you want to import. It will appear in the list of input files in the MARMOT launcher.

[[File:ImportButton.png]]

From the ''Input File'' drop-down menu, select an appropriate MARMOT file. 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.

The next step is to specify on which machine MARMOT will be run, 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 /trunk/marmot/ directory of the machine's MARMOT installation. If you are launching on a remote machine, also be sure that you have appropriate privileges for the MARMOT install directory.

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

[[File:ParallelExecution.png]]

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 MARMOT ===

Once the input file and host is specified, apply your settings by clicking the floppy disk Save button.

If you make any subsequent changes to the MARMOT 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.

[[File:LaunchJob.png]]

== Visualizing Output ==

'''This section requires VisIt 2.8, which may or may not be released at press time. Contact the NiCE team if you need a pre-release copy.'''

The output produced by a MARMOT job can be visually analyzed in ICE by utilizing the ''Visualization'' perspective. Select ''Window > Perspective > Other...'' from the menu bar at the top of the ICE workbench. From the resulting dialog, select ''Visualization'' and press OK.

[[File:PerspectiveDialogViz.png]]

An empty ''Visualization'' perspective will replace the existing ICE perspective in the workbench.

[[File:VizPerspective.png|1500px]]

Rendering in ICE's ''Visualization'' perspective is executed through a connection to the external visualization software application, VisIt. To establish this connection, click Launch VisIt near the upper-right corner of the ICE workbench.

[[File:LaunchVisItButton.png]]

A dialog for connecting to VisIt will appear. This dialog allows the user to start a new instance of VisIt on their local machine or a remote machine. The dialog additionally allows the user to connect to an already running instance of VisIt. Select a connection option and enter the appropriate parameters before clicking "OK".

[[File:VisItLaunchDialog.png]]

If the connection to VisIt is successful, a ''Visualization Editor'' will be opened in the main workbench area. Click the ''Open File'' button from the ''Visualization File Viewer'' in the right-hand column of the workbench.

[[File:OpenVizFile.png]]

A dialog for exploring the local file system will appear. Navigate to and select the .e file produced by the MARMOT job execution. ('''Note''': This may require adjusting the file extension filter in the dialog to get the file to appear.) After dismissing the file dialog, ensure that the file is selected in the ''Visualization File Viewer''. Click the ''Add Plot'' button in the ''Plot Viewer'' on the left-hand side of the workbench.

[[File:AddPlotButton.png]]

A dialog for selecting plots to add to the ''Plot Viewer'' will appear. Check any number of plots to add and click ''OK''.

[[File:AddPlotDialog.png]]

To display a plot in the ''Visualization'' Editor, select the plot in the ''Plot Viewer''. Click and drag on the image to manipulate its orientation.