The JetStream Project Manager (JSPM) is a tool designed to help run and manage large volumes of flow solve cases.
About JSPM
Let's say you have implemented a new feature and you want to check how it affects a flow solve. You could set up a case and run it, and that would give you data for, well, one case. It might be more useful to run multiple cases for different geometries, grids, Mach numbers, angle of attack, Re, or other parameters. But, it generally takes a long time to set up these cases, and post-processing can be very time-consuming as well. The JSPM can help with that, by automatically setting up cases for different Mach numbers and AoA. It will also auto-generate submit scripts, so you can run it on any system that it is set up for. Furthermore, it will generate a set of Utility Scripts to help you set up, run, and manage your cases. Since these scripts can be placed in your project or home directory, you no longer have to worry about scratch purging deleting your data. Lastly, and the primary motivation for the development of this program, is that it provides easy version control when transferring cases between HPC systems, since input files and submit scripts can now be generated from a single template file.
Using JSPM
JSPM is distributed with Jetstream. Simply go into ~/jetstream/js_prj_mgr and run ./install. It will then prompt you for some questions about what to call the project, where to install, what Mach numbers to use, etc. When it asks you what grid to use, this is just what it will use as the default. You will can still choose a different grid when you actually set the cases up. If you mess up and want to restart, just hit Ctrl+C to exit then rerun the installer. When you rerun, you can still specify the same project name and install directories again, it will simply over-write the existing directories (though it will always prompt you first if the directory exists).
Organization
Once the install file has finished running, there will be several new directories. One will be in your scratch directory and is pretty uninteresting - it just contains a bunch of subdirectories that will eventually hold your cases. The second directory is the 'command centre' which can be installed anywhere (the /project directory is a good choice). This directory will contain a set of Utility Scripts which are used for all your case-running needs. This directory will also be used to house some files from completed cases for post-processing. You may also choose to install a third directory. This is a 'gdat' or General Data directory which can be used to permanently store data from cases.
Using the Utility Scripts
Setting up the input file template
The first thing you will need to do is set up a new case. You will have to decide on a name for the case. For example, if it is a case to test an ILUt preconditioner with ptc, you might call it ptc_ilut. You will need to create a template input file for your new case. In the directory where the utility scripts are installed, go to /file_templates/input and create a new directory called ptc_ilut and create an input file in there called input.param. So, the full path to this file will be ./file_templates/input/ptc_ilut/input.param. This file is a template input file, which looks just like a regular input file except that it does not need to include the Mach number, AoA, output file name, or grid file name as these will be filled in automatically. Note that if your file does contain these, they will be over-written. To see a sample input file template, one has been created automatically called ./file_templates/input/sample/input.param.
Making new cases withmake_new_case
You can now run the case by either typing './make_new_case case_name', or just './make_new_case' and then giving it the name of the case when prompted. For example, for the case called 'sample' that has already been set up, you can create these cases by typing './make_new_case sample'. This will set up several subdirectories and edit some other scripts to help you run the new case. When this is complete, the script will prompt you if you want to generate the submit scripts and input files. See the sections on make_submit and make_input below for details. Note that you can always run these scripts manually at a later time if you choose not to run them now.
Generating submit scripts with make_submit
Typing './make_submit case_name' will generate submit scripts for all your cases from the submit script contained in ./file_templates/xxxSubmit. If you want to edit this template file, feel free to do so, Note however that this template file does not contain the case name. Do not add this in, as it will be generated automatically from your project name and case name.
Generating the input files withmake_input
Typing './make_input case_name' will generate input files for your case. Before running this, you need to make a template input file. See above for details.
Running cases withrun
To run cases for mach number Ma and angle of attack AoA, type './run case_name Ma AoA '. This allows some flexibility in what cases to run and when. You can also type 'all' for either Ma or AoA or both. So, to run all cases for case 'ptc' at AoA=4, type './run ptc all 4'. To send all 'ptc' cases to the queue at once, just type './run ptc all all' or simply './run ptc'.
Cleaning cases withclean
The clean script will move the his, solv, screen, and (if it exists) gdat file to your command centre and remove all unnecessary files from scratch directory. So, if you need the .q file for plotting, make sure to copy this file manually to a safe place before running this script. To perform cleaning, type '/clean case_name Ma AoA', where 'all' can again be used for Ma or AoA or both, and './clean case_name' will clean the entire case.
Editing existing cases
If you want to change all input files or submit scripts at once, the best way to do that is by simply editing the input file template or submit script template and rerunning make_input or make_submit as appropriate, which will over-write the existing files with the new templates. However, if you want to edit only a subset of these files, you can use ed_line or add_line scripts. Unlike the other utility scripts, these scripts need to be open with a text editor and manually edited to use them. However, if you really want to run some cases under different parameters, consider setting up a new case for them.
Post-processing with make_gdat and save_gdat (optional)
The gdat files are new to Jetstream and are designed to hold post-processing data for plotting or other analysis. Currently, they contain data regarding CPU time, linear iterations, and preconditioner updates. Running './make_gdat case_name' will go through these files and fill out new files titled 'linits', 'prec', and 'time' which contain this information for all Ma and AoA in a single file. You can also run './make_gdat all' to update all gdat files at once. Note that these files should not be regarded as permanent, since they can be over-written by running the script again. When you want to save this data permanently, type './save_gdat', which will save the gdat info for all cases for which it has been generated and places it in your gdat directory, wherever you chose to set that up.
Despite the long description here, the JSPM is designed to be flexible but fast and easy to use. This program will be included in the Jetstream distribution in March 2013.
About JSPM
Let's say you have implemented a new feature and you want to check how it affects a flow solve. You could set up a case and run it, and that would give you data for, well, one case. It might be more useful to run multiple cases for different geometries, grids, Mach numbers, angle of attack, Re, or other parameters. But, it generally takes a long time to set up these cases, and post-processing can be very time-consuming as well. The JSPM can help with that, by automatically setting up cases for different Mach numbers and AoA. It will also auto-generate submit scripts, so you can run it on any system that it is set up for. Furthermore, it will generate a set of Utility Scripts to help you set up, run, and manage your cases. Since these scripts can be placed in your project or home directory, you no longer have to worry about scratch purging deleting your data. Lastly, and the primary motivation for the development of this program, is that it provides easy version control when transferring cases between HPC systems, since input files and submit scripts can now be generated from a single template file.
Using JSPM
JSPM is distributed with Jetstream. Simply go into ~/jetstream/js_prj_mgr and run ./install. It will then prompt you for some questions about what to call the project, where to install, what Mach numbers to use, etc. When it asks you what grid to use, this is just what it will use as the default. You will can still choose a different grid when you actually set the cases up. If you mess up and want to restart, just hit Ctrl+C to exit then rerun the installer. When you rerun, you can still specify the same project name and install directories again, it will simply over-write the existing directories (though it will always prompt you first if the directory exists).
Organization
Once the install file has finished running, there will be several new directories. One will be in your scratch directory and is pretty uninteresting - it just contains a bunch of subdirectories that will eventually hold your cases. The second directory is the 'command centre' which can be installed anywhere (the /project directory is a good choice). This directory will contain a set of Utility Scripts which are used for all your case-running needs. This directory will also be used to house some files from completed cases for post-processing. You may also choose to install a third directory. This is a 'gdat' or General Data directory which can be used to permanently store data from cases.
Using the Utility Scripts
Setting up the input file template
The first thing you will need to do is set up a new case. You will have to decide on a name for the case. For example, if it is a case to test an ILUt preconditioner with ptc, you might call it ptc_ilut. You will need to create a template input file for your new case. In the directory where the utility scripts are installed, go to /file_templates/input and create a new directory called ptc_ilut and create an input file in there called input.param. So, the full path to this file will be ./file_templates/input/ptc_ilut/input.param. This file is a template input file, which looks just like a regular input file except that it does not need to include the Mach number, AoA, output file name, or grid file name as these will be filled in automatically. Note that if your file does contain these, they will be over-written. To see a sample input file template, one has been created automatically called ./file_templates/input/sample/input.param.Making new cases with make_new_case
You can now run the case by either typing './make_new_case case_name', or just './make_new_case' and then giving it the name of the case when prompted. For example, for the case called 'sample' that has already been set up, you can create these cases by typing './make_new_case sample'. This will set up several subdirectories and edit some other scripts to help you run the new case. When this is complete, the script will prompt you if you want to generate the submit scripts and input files. See the sections on make_submit and make_input below for details. Note that you can always run these scripts manually at a later time if you choose not to run them now.Generating submit scripts with make_submit
Typing './make_submit case_name' will generate submit scripts for all your cases from the submit script contained in ./file_templates/xxxSubmit. If you want to edit this template file, feel free to do so, Note however that this template file does not contain the case name. Do not add this in, as it will be generated automatically from your project name and case name.Generating the input files with make_input
Typing './make_input case_name' will generate input files for your case. Before running this, you need to make a template input file. See above for details.Running cases with run
To run cases for mach number Ma and angle of attack AoA, type './run case_name Ma AoA '. This allows some flexibility in what cases to run and when. You can also type 'all' for either Ma or AoA or both. So, to run all cases for case 'ptc' at AoA=4, type './run ptc all 4'. To send all 'ptc' cases to the queue at once, just type './run ptc all all' or simply './run ptc'.Cleaning cases with clean
The clean script will move the his, solv, screen, and (if it exists) gdat file to your command centre and remove all unnecessary files from scratch directory. So, if you need the .q file for plotting, make sure to copy this file manually to a safe place before running this script. To perform cleaning, type '/clean case_name Ma AoA', where 'all' can again be used for Ma or AoA or both, and './clean case_name' will clean the entire case.Editing existing cases
If you want to change all input files or submit scripts at once, the best way to do that is by simply editing the input file template or submit script template and rerunning make_input or make_submit as appropriate, which will over-write the existing files with the new templates. However, if you want to edit only a subset of these files, you can use ed_line or add_line scripts. Unlike the other utility scripts, these scripts need to be open with a text editor and manually edited to use them. However, if you really want to run some cases under different parameters, consider setting up a new case for them.Post-processing with make_gdat and save_gdat (optional)
The gdat files are new to Jetstream and are designed to hold post-processing data for plotting or other analysis. Currently, they contain data regarding CPU time, linear iterations, and preconditioner updates. Running './make_gdat case_name' will go through these files and fill out new files titled 'linits', 'prec', and 'time' which contain this information for all Ma and AoA in a single file. You can also run './make_gdat all' to update all gdat files at once. Note that these files should not be regarded as permanent, since they can be over-written by running the script again. When you want to save this data permanently, type './save_gdat', which will save the gdat info for all cases for which it has been generated and places it in your gdat directory, wherever you chose to set that up.Despite the long description here, the JSPM is designed to be flexible but fast and easy to use. This program will be included in the Jetstream distribution in March 2013.
Last edited: David Brown, March 2013