Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Using Nek5000 with ICE"

(Creating the Launcher)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
<div style="border-style:dashed;border-width:2px;border-color:black;text-align:center;font-size:24px;font-weight:bold;color:red;">This is a legacy tutorial and may contain outdated information.</div>
 +
 
This document is designed to outline the basic steps of setting up and using the Nek5000 plugins in ICE. There are two different tasks for the input generation and launching of Nek5000 within ICE:  
 
This document is designed to outline the basic steps of setting up and using the Nek5000 plugins in ICE. There are two different tasks for the input generation and launching of Nek5000 within ICE:  
  
Line 18: Line 20:
 
=== Prerequisites ===
 
=== Prerequisites ===
  
You should have [https://nek5000.mcs.anl.gov/index.php/GETNEK Nek5000 installed] on a machine, either your local machine or a remote machine.  
+
You should have [https://nek5000.mcs.anl.gov/download/ Nek5000 installed] on a machine, either your local machine or a remote machine. ICE should work with either the current version or legacy repo, but only the legacy version includes the example problems which ICE will run.  
  
 
Additionally, ICE's support for input creation is limited to loading and modifying existing ''two-dimensional'' problems. This means that ICE requires a <tt>*.rea</tt> example file from Nek5000 to get the information it needs to generate input. Below is a list of <tt>*.rea</tt> files that have been tested with ICE:
 
Additionally, ICE's support for input creation is limited to loading and modifying existing ''two-dimensional'' problems. This means that ICE requires a <tt>*.rea</tt> example file from Nek5000 to get the information it needs to generate input. Below is a list of <tt>*.rea</tt> files that have been tested with ICE:
Line 31: Line 33:
 
* <tt>v2d.rea</tt>
 
* <tt>v2d.rea</tt>
  
These files can be found in the <code>/nek5/examples</code> directory of a Nek5000 installation, or downloaded individually from the [https://svn.mcs.anl.gov/repos/nek5/examples/ Nek5000 SVN repository]. Once you've obtained a <tt>*.rea</tt> file, create a directory named <tt>Nek5000_Model_Builder</tt> in your local file system in one of the following directories:
+
These files can be found in the <code>/nek5/examples</code> directory of the legacy Nek5000 installation, or downloaded individually from the [https://svn.mcs.anl.gov/repos/nek5/examples/ Nek5000 SVN repository]. Once you've obtained a <tt>*.rea</tt> file, create a directory named <tt>Nek5000_Model_Builder</tt> in your local file system your workspace's itemDB folder.
  
On Linux: <code>/home/{user}/ICEFiles/default/</code><br>
+
Place the <tt>*.rea</tt> file here before launching ICE. If you have never launched ICE on your system before, you will also have to open it to create a workspace and place the file in the new itemDB folder which ICE will automatically create inside the workspace.
On Mac: <code>/Users/{user}/ICEFiles/default/</code><br>
+
On Windows: <code>C:\Users\{user}\ICEFiles\default\</code><br>
+
  
Place the <tt>*.rea</tt> file here before launching ICE. If you have never launched ICE on your system before, you will also have to create the <code>/ICEFiles/default</code> directory. In the following tutorial, we'll be modifying the <tt>conj_ht.rea</tt> problem.
+
In the following tutorial, we'll be modifying the <tt>conj_ht.rea</tt> problem.
 +
 
 +
== Building Nek ==
 +
 
 +
ICE will require that you have already built Nek5000 for your sample problem on the machine which will run the job. To do this, first find the example code you wish to run. They are located in the <tt>/examples</tt> folder of the legacy repo, and most be downloaded from [https://svn.mcs.anl.gov/repos/nek5/examples/ the repo] and placed in an <tt>/examples</tt> folder inside the current repo. Next find the makenek script. In the current repo, this is located at <tt>bin/makenek</tt> and in the legacy repo it is at <tt>trunk/nek/makenek</tt>. Copy it into the folder of the example problem you wish to use and run <code>./makenek problemName</code>, where problemName is the name of the <tt>.usr</tt> file in the directory. For example, to run the conj_ht problem you will need to copy makenek into <tt>/examples/conj_ht</tt> and run <code>./makenek conj_ht</code>.
 +
 
 +
If everything was done correctly, this will produce an executable named nek5000.  
  
 
== Creating a Nek5000 <tt>*.rea</tt> Input File ==
 
== Creating a Nek5000 <tt>*.rea</tt> Input File ==
  
Once ICE is properly installed and you have placed the <tt>*.rea</tt> file (<tt>conj_ht.rea</tt> in this example) in your <code>/ICEFiles/default/Nek5000_Model_Builder</code> directory, you can begin creating input for Nek5000.  
+
Once ICE is properly installed and you have placed the <tt>*.rea</tt> file (<tt>conj_ht.rea</tt> in this example) in your <code>itemDB/Nek5000_Model_Builder</code> directory, you can begin creating input for Nek5000.  
  
 
To begin, launch ICE (if it isn't already running), and you should be presented with an empty workbench.  
 
To begin, launch ICE (if it isn't already running), and you should be presented with an empty workbench.  
Line 47: Line 53:
 
[[File:ICE_EmptyWorkbench.png|625px]]  
 
[[File:ICE_EmptyWorkbench.png|625px]]  
  
The first step to generate Nek5000 input is to create a ''Nek5000 Model Builder'' Item; click on the green plus icon ('''<span style="color:green;">+</span>''') located at the top of the left-hand column.  
+
The first step to generate Nek5000 input is to create a ''Nek5000 Model Builder'' Item; switch to the ICE perspective by clicking on the ''Open Perspective'' button and selecting ICE, then (click on the green plus icon ('''<span style="color:green;">+</span>''') located at the top of the left-hand column.  
  
 
[[File:ICE_CreateItem.png]]  
 
[[File:ICE_CreateItem.png]]  
Line 53: Line 59:
 
This will launch a dialog prompting you to select a task (or ''Item'') to create. Find ''Nek5000 Model Builder'' in the ''Item Selector'' list (you may need to scroll down) and select ''Finish''.  
 
This will launch a dialog prompting you to select a task (or ''Item'') to create. Find ''Nek5000 Model Builder'' in the ''Item Selector'' list (you may need to scroll down) and select ''Finish''.  
  
[[File:ICE_NekModelBuilderItem.png]]  
+
[[File:ICE_NekModelBuilderItem.png|400px]]  
  
 
=== Defining Input Parameters ===
 
=== Defining Input Parameters ===
  
A ''Nek5000 Model Builder'' form containing a number of tabs (near the bottom) with parameter input boxes will appear in the ICE workbench. These parameters are specific to the input required by Nek5000 and have a number of restrictions associated to them. The specifics of Nek5000 input is beyond the scope of this tutorial. However, the list below provides links to more detailed information about each parameter. Since we prepared and placed the <tt>conj_ht.rea</tt> file in the <code>/ICEFiles/default/Nek5000_Model_Builder</code> directory ahead of time, you will find the parameters are already filled out with appropriate values. For some parameters, hovering over the name will display additional information about it.  
+
A ''Nek5000 Model Builder'' form containing a number of tabs (near the bottom) with parameter input boxes will appear in the ICE workbench. These parameters are specific to the input required by Nek5000 and have a number of restrictions associated to them. The specifics of Nek5000 input is beyond the scope of this tutorial. However, the list below provides links to more detailed information about each parameter. Since we prepared and placed the <tt>conj_ht.rea</tt> file in the <code>itemDB/Nek5000_Model_Builder</code> directory ahead of time, you will find the parameters are already filled out with appropriate values. For some parameters, hovering over the name will display additional information about it.  
  
 
'''Input specification by section''':  
 
'''Input specification by section''':  
Line 76: Line 82:
 
[[File:ICE_SaveButton.png]]
 
[[File:ICE_SaveButton.png]]
  
Clicking on the last tab in the ''Nek5000 Model Builder'' form will open the ''Mesh Editor'' with the current mesh for this problem displayed. More information on editing the mesh is available in [[ICE Editing Meshes|Editing Meshes]].
+
Clicking on the last tab in the ''Nek5000 Model Builder'' form will open the ''Mesh Editor'' with the current mesh for this problem displayed. More information on editing the mesh is available in [[Editing Meshes|Editing Meshes]].
  
 
=== Generating Nek5000 Input Files ===
 
=== Generating Nek5000 Input Files ===
Line 84: Line 90:
 
[[File:ICE_WriteNekInput.png]]  
 
[[File:ICE_WriteNekInput.png]]  
  
This file will be created in your <code>/home/user/ICEFiles/default</code> directory and will have the file name <tt>Nek5000_Model_Builder_{num}.rea</tt>, where <tt>{num}</tt> is your model builder Item number (i.e. ''Nek5000 Model Builder'' '''''1''''', ''Nek5000 Model Builder'' '''''2''''', etc.). It's important to note, that if you have a previously generated Nek5000 input file in your default directory, generating another input file with the same Item number will overwrite your existing file without warning.  
+
This file will be created in your <code>itemDB</code> directory and will have the file name <tt>Nek5000_Model_Builder_{num}.rea</tt>, where <tt>{num}</tt> is your model builder Item number (i.e. ''Nek5000 Model Builder'' '''''1''''', ''Nek5000 Model Builder'' '''''2''''', etc.). It's important to note, that if you have a previously generated Nek5000 input file in your default directory, generating another input file with the same Item number will overwrite your existing file without warning.  
  
 
This concludes the Nek5000 input file generation; the <tt>*.rea</tt> input file created here will be used to launch Nek5000 in the next section. If you would like to review the generated input file before moving onto the next step, you can do so by selecting the ''File > Open File...'' menu in ICE, and navigating to your <tt>Nek5000_Model_Builder_{num}.rea</tt> file. This will display the input file in your ICE workbench. You may make modifications and save changes to the <tt>*.rea</tt> file from within ICE, however, this is not recommended for users unfamiliar with Nek5000.  
 
This concludes the Nek5000 input file generation; the <tt>*.rea</tt> input file created here will be used to launch Nek5000 in the next section. If you would like to review the generated input file before moving onto the next step, you can do so by selecting the ''File > Open File...'' menu in ICE, and navigating to your <tt>Nek5000_Model_Builder_{num}.rea</tt> file. This will display the input file in your ICE workbench. You may make modifications and save changes to the <tt>*.rea</tt> file from within ICE, however, this is not recommended for users unfamiliar with Nek5000.  
Line 154: Line 160:
 
</div>
 
</div>
  
[[File:ICE_Nek5000AvailableExecutables.png]]
+
[[File:ICE_NekAvailableExecutables.png]]
  
 
Lastly, select the machine on which ICE will launch Nek5000; this can be either local or remote. You can add or remove hosts from the table to suit your needs.  
 
Lastly, select the machine on which ICE will launch Nek5000; this can be either local or remote. You can add or remove hosts from the table to suit your needs.  
  
[[File:ICE_Nek5000HostSelection.png]]
+
[[File:ICE_NekHostSelection.png]]
  
 
=== Launching the Job ===
 
=== Launching the Job ===
Line 166: Line 172:
 
== Viewing Results ==
 
== Viewing Results ==
  
You can view the results of the Nek5000 run by clicking on the ''Output Files and Data'' tab at the bottom of the ''Nek5000 Job Launcher'' form (and just above the streaming text console). If Nek5000 ran successfully, you should see the information that it writes to standard out in a text editor.  
+
You can view the results of the Nek5000 run by clicking on the ''Output Files and Data'' tab at the bottom of the ''Nek5000 Job Launcher''. If Nek5000 ran successfully, you should be able to view the results by double-clicking the ''Nek5000 Launcher Standard Output'' resource. To visualize the .nek5000 data files, you must [[ICE_Embedded_Visualizations|set up a connection to VisIt]] before double clicking on the file to open it.
 
+
[[File:ICE_NekResults.png]]  
+
  
 
== Known Issues ==
 
== Known Issues ==

Latest revision as of 11:03, 31 January 2017

This is a legacy tutorial and may contain outdated information.

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

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

Background

Part of our work in the 2013 fiscal year included a detailed analysis of Nek5000's existing graphical input generator, PreNek. We worked closely with the Nek5000 team to determine how it works and discover any painful points related to its use. The ICE and Nek5000 teams decided that the best course of action was to slowly reproduce the capabilities that exist in PreNek in ICE during the 2014 fiscal year, focusing on usability first, and inclusion of advanced features second. The goal is to produce a tool that will allow users to work with all of Nek5000's examples and, eventually, allow users to create entirely new Nek5000 problems from scratch.

We started by creating a new set of tools in ICE that can read and write Nek5000's .rea files. The first example that we targeted was Nek's conjugate heat transfer example, conj_ht, which includes a number of different options, a mesh, and some boundary conditions. ICE will support more examples in the very near future.

Getting Started

Installation & Configuration

Follow the instructions in the Getting ICE article to download and install the latest version of ICE on your system.

Prerequisites

You should have Nek5000 installed on a machine, either your local machine or a remote machine. ICE should work with either the current version or legacy repo, but only the legacy version includes the example problems which ICE will run.

Additionally, ICE's support for input creation is limited to loading and modifying existing two-dimensional problems. This means that ICE requires a *.rea example file from Nek5000 to get the information it needs to generate input. Below is a list of *.rea files that have been tested with ICE:

  • conj_ht.rea
  • eddy_uv.rea
  • kov.rea
  • ray_dd.rea
  • ray_dn.rea
  • ray_nn.rea
  • shear4.rea
  • v2d.rea

These files can be found in the /nek5/examples directory of the legacy Nek5000 installation, or downloaded individually from the Nek5000 SVN repository. Once you've obtained a *.rea file, create a directory named Nek5000_Model_Builder in your local file system your workspace's itemDB folder.

Place the *.rea file here before launching ICE. If you have never launched ICE on your system before, you will also have to open it to create a workspace and place the file in the new itemDB folder which ICE will automatically create inside the workspace.

In the following tutorial, we'll be modifying the conj_ht.rea problem.

Building Nek

ICE will require that you have already built Nek5000 for your sample problem on the machine which will run the job. To do this, first find the example code you wish to run. They are located in the /examples folder of the legacy repo, and most be downloaded from the repo and placed in an /examples folder inside the current repo. Next find the makenek script. In the current repo, this is located at bin/makenek and in the legacy repo it is at trunk/nek/makenek. Copy it into the folder of the example problem you wish to use and run ./makenek problemName, where problemName is the name of the .usr file in the directory. For example, to run the conj_ht problem you will need to copy makenek into /examples/conj_ht and run ./makenek conj_ht.

If everything was done correctly, this will produce an executable named nek5000.

Creating a Nek5000 *.rea Input File

Once ICE is properly installed and you have placed the *.rea file (conj_ht.rea in this example) in your itemDB/Nek5000_Model_Builder directory, you can begin creating input for Nek5000.

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

ICE EmptyWorkbench.png

The first step to generate Nek5000 input is to create a Nek5000 Model Builder Item; switch to the ICE perspective by clicking on the Open Perspective button and selecting ICE, then (click on the green plus icon (+) located at the top of the left-hand column.

ICE CreateItem.png

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

ICE NekModelBuilderItem.png

Defining Input Parameters

A Nek5000 Model Builder form containing a number of tabs (near the bottom) with parameter input boxes will appear in the ICE workbench. These parameters are specific to the input required by Nek5000 and have a number of restrictions associated to them. The specifics of Nek5000 input is beyond the scope of this tutorial. However, the list below provides links to more detailed information about each parameter. Since we prepared and placed the conj_ht.rea file in the itemDB/Nek5000_Model_Builder directory ahead of time, you will find the parameters are already filled out with appropriate values. For some parameters, hovering over the name will display additional information about it.

Input specification by section:

ICE NekModelBuilderForm.png

Once you have entered all the required parameters (or have made any changes to the existing ones), save the Nek5000 Model Builder project by clicking the floppy disk icon located in the top left-hand corner of ICE (or Ctrl+S/+S).

ICE SaveButton.png

Clicking on the last tab in the Nek5000 Model Builder form will open the Mesh Editor with the current mesh for this problem displayed. More information on editing the mesh is available in Editing Meshes.

Generating Nek5000 Input Files

The last step in creating input is to actually generate the *.rea file that will be used to launch Nek5000 in the next section. To do this, select the Process drop-down menu located in the upper right corner of your Nek5000 Model Builder window, select Write Nek5000 input, and click Go!. This will convert the parameters entered on your Nek5000 Model Builder form into a text-based format that is compatible with Nek5000; this process should only take a few seconds at most. The phrase "Done!" should appear next to the title of your Nek5000 Model Builder workspace.

ICE WriteNekInput.png

This file will be created in your itemDB directory and will have the file name Nek5000_Model_Builder_{num}.rea, where {num} is your model builder Item number (i.e. Nek5000 Model Builder 1, Nek5000 Model Builder 2, etc.). It's important to note, that if you have a previously generated Nek5000 input file in your default directory, generating another input file with the same Item number will overwrite your existing file without warning.

This concludes the Nek5000 input file generation; the *.rea input file created here will be used to launch Nek5000 in the next section. If you would like to review the generated input file before moving onto the next step, you can do so by selecting the File > Open File... menu in ICE, and navigating to your Nek5000_Model_Builder_{num}.rea file. This will display the input file in your ICE workbench. You may make modifications and save changes to the *.rea file from within ICE, however, this is not recommended for users unfamiliar with Nek5000.

ICE NekReaInputFile.png

Launching a Nek5000 Problem

The process for launching Nek5000 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

To begin creating a job launcher, click on the green plus icon (+) at the top of the Item Viewer list.

ICE CreateItem.png

In the list that appears, select Nek5000 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 Nek5000 Launcher.

ICE NekLauncherSelection.png

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.

ICE NekLauncher.png

Setting the Input File and Hostname

The first thing that you need to do is select the input file for Nek5000, which is the input file that you created in the previous section. Start by clicking the box labelled Input File and select your Nek5000 neutronics *.rea file. Remember that the file you created in the previous section will be named Nek5000_Model_Builder_{num}.rea where {num} is the number of your model Item. In the case of our example, the model was number 1 and the input file is Nek5000_Model_Builder_1.rea.

ICE NekInputSelection.png

Next, select a problem from the list of Available Executables upon which your input file is based. In this example, we would chose conj_ht. Currently, the list of Nek5000 examples supported in ICE for launching is limited to the following:

  • 2d_eigtest
  • 3dbox
  • axi
  • blasius
  • conj_ht
  • cyl_restart
  • eddy
  • eddy_psi_omega
  • expansions
  • ext_cyl
  • fs_2
  • fs_hydro
  • hemi
  • kov_st_state
  • kovasznay
  • lowMach_test
  • mhd
  • moab
  • moab_conjht
  • os7000
  • peris
  • pipe
  • rayleigh
  • robin
  • shear4
  • solid
  • strat
  • taylor
  • thermal_io
  • timing
  • turbChannel
  • turbJet
  • var_vis
  • vortex
  • vortex2

ICE NekAvailableExecutables.png

Lastly, select the machine on which ICE will launch Nek5000; this can be either local or remote. You can add or remove hosts from the table to suit your needs.

ICE NekHostSelection.png

Launching the Job

After selecting both the input file and the host machine, save the project by clicking the floppy disk icon in the upper left-hand corner (or Ctrl+S / +S). Next, use the drop-down menu in the upper right-hand corner to tell ICE to launch the Nek5000 job. Select the Launch the Job task from the drop-down menu and click the Go! button. ICE will then launch Nek5000 on your host machine when you click the OK button. If you are launching on a remote machine, ICE will ask for your credentials on that machine.

Viewing Results

You can view the results of the Nek5000 run by clicking on the Output Files and Data tab at the bottom of the Nek5000 Job Launcher. If Nek5000 ran successfully, you should be able to view the results by double-clicking the Nek5000 Launcher Standard Output resource. To visualize the .nek5000 data files, you must set up a connection to VisIt before double clicking on the file to open it.

Known Issues

  • ICE only supports 2 dimensional examples for input creation currently. We plan to increase the pool of available examples to choose from, and eventually allow the user to define their own custom problems.
  • When using a predefined example like conj_ht, any sections of the original *.rea file with a predefined number of lines in a particular section will remain that length for now, i.e. conj_ht has 6 lines of Output Field Specification data, and thus the user is not able to add or remove any more than that. This also extends to sections with 0 lines initially defined, meaning they will remain empty.
  • Similar to the previous bullet point, if the number of passive scalars (NPSCAL, p23) is initially set to 0 in a particular example, even if the user changes this value in the Parameters section, the problem will launch with no Passive Scalar Data defined.
  • The conj_ht example initializes with 96 elements (64 thermal, 32 fluid), and allows a maximum of 4100 total elements. It's very unlikely a user will create more than 4100 elements by hand for this example, however if they do, they will likely encounter errors when running Nek5000 because ICE does not yet rewrite the Nek's SIZE file.

Back to the top