6.1. "How-to"

This section provides step-by-step how-to instructions on the following topics:

6.1.1. Submit Multiple Runs

To submit multiple runs:

  • From UI: The new UI (2023 R2 and newer) changes don't allow the preparation and submission of multiple jobs at once

  • From CLI: It is possible to prepare and submit multiple jobs from CLI via scripting. Create a script containing one line per run, specifying the directory (-prep_dir MyDir00X) where the run should be prepared, and the run (-run Run00X) to prepare.

For example, on a windows machine:

run_forte.bat CLI -project MyProject.ftsim --prepare -prep_dir MyDir001 -run Run_001 –submit –mpi_args Xx

run_forte.bat CLI -project MyProject.ftsim --prepare -prep_dir MyDir002 -run Run_002 –submit –mpi_args Xx

Where "Xx" indicates the desired number of cores.

Similarly, on a linux machine use forte.sh instead of run_forte.bat.

Additionally, the "--wait" option must be added if you want the command to wait until the job is finished before returning. Otherwise, if you put multiple lines in a bat or shell script invoking the run, the runs will all get submitted simultaneously in the background.

6.1.2. Restart Runs with a Reduced Mesh Resolution

When doing a restart in Forte, the volume mesh is already defined in the restart file. So, essentially the restarted simulation is based on the same mesh saved in the restart file.

If you'd like to have reduced mesh resolution in the restarted simulation, you could relax the mesh refinement controls in the .ftsim project. The restarted simulation will pick them up and apply them when the first mesh update happens. In simulations with moving boundary or SAM controls, mesh updates happen pretty frequently, and the first mesh update won't be too far from the restart point.

Note that, however, the restriction of doing a restart is that the global mesh size has to be the same. The current workflow in the mesh library is to recreate exactly the mesh from a previous cycle upon restart. The reason is that all the meshes rely on the root octree created at the beginning of a run, based on the original global mesh size. (As you know, Forte uses an Octree data structure to construct mesh.) There is not a clear path to change the global mesh size within our current restart framework.

If you must change the global mesh size when restarting, there is a workaround:

You could first save the spatially resolved data (.ftres) at the restart point. Make sure to save variables like pressure, temperature, velocity, turbulence quantities, and all the fluid compositions as mass fractions. Then, in the new project using a different global mesh size, choose Spatially Varying (instead of Constant) for the above variables in the initial conditions. The UI allows you to import data from the .ftres file. In this way, you are initializing the new simulation with the spatially resolved data at the restart point.

Interpolation will be made from the old solutions to the new mesh. The simulation won't use the restart file (.ftrst) but will be a new simulation with the initial conditions defined by the interpolated data. The following provides more detailed information about this workaround:

In this workaround, a new simulation will be done without using the restart file (.ftrst), while initializing the flow field using the spatially resolved solutions (.ftres) saved at the restart point. In this new simulation, a different global mesh size can be used.

Initialization is done at Initial Conditions > Default Initialization. Usually, constant inputs are specified for Composition, Temperature, Pressure, Turbulence, and Velocity. In this workaround, Spatially Varying will be chosen instead of Constant for each, as seen in Figure 6.1: Default Initialization panel specifying Spatially Varying composition.

Figure 6.1: Default Initialization panel specifying Spatially Varying composition

Default Initialization panel specifying Spatially Varying composition

After Spatially Varying is selected for each parameter, select Create new... to create an initial conditions (IC) table. This opens an IC table editor:

Figure 6.2: IC table editor panel

IC table editor panel

Click Import, select the source file as the .ftres solution file. You will see a group of FORTE Symbol—this is the list of variables that Forte can read to initialize the corresponding variables, and a group of Import Symbol—this is the list of variables available from the imported .ftres solution.

Find a relevant variable from the FORTE Symbol list and its corresponding one in the Import Symbol list and click Add Mapping. In Figure 6.3: IC table Import panel, the mapping of Pressure has been added (leave the import unit as the CGS unit, by default) and the variable Temperature has been selected in both lists to add mapping for it. You can also click Run Auto-Map to let the software automatically identify the corresponding variables and add the mapping for you.

Figure 6.3: IC table Import panel

IC table Import panel

In this workaround, for a successful initialization using the IC table, the following variables saved in the .ftres solution will be needed:

  • X (saved by default)

  • Y (saved by default)

  • Z (saved by default)

  • Velocity_X

  • Velocity_Y

  • Velocity_Z

  • Pressure

  • Temperature

  • Mass_Fraction_ID728 (this is the one-component gas species in your simulation)

  • TKE (turbulent kinetic energy, needed for a turbulence simulation)

  • TED (turbulent kinetic energy dissipation rate, needed for a turbulence simulation)

After establishing mapping for all of them, click OK and wait a few seconds. The IC table is automatically generated based on the data in the .ftres solution:

Figure 6.4: Generated IC table

Generated IC table

Give this IC table a name and save it. It can be accessed by the IC Tables icon in the Libraries ribbon group, as seen in Figure 6.5: IC Tables icon and Spatially Varying initialization option.

Now, back to the Initial Conditions > Default Initialization panel. If you have set up the IC table, and it contains the relevant data, you can select Spatially Varying for the variables of interest. As mentioned, to set up the simulation to effectively do a restart, you will need select Spatially Varying for all the parameters on this panel, such as Composition, Temperature, Pressure, Turbulence, and Velocity. In Figure 6.5: IC Tables icon and Spatially Varying initialization option, Temperature is set as Spatially Varying as an example.

Figure 6.5: IC Tables icon and Spatially Varying initialization option

IC Tables icon and Spatially Varying initialization option

There are two more things to be careful about when using the workaround:

  1. When a .ftres solution is imported as IC table, there are two data sets:

    mesh_****::CellSolution

    mesh_****::VertexSolution

    Figure 6.6: IC table Import data sets

    IC table Import data sets

    The cell solution data set contains all the cell-centered variables such as pressure, temperature, composition and turbulence quantities.

    The vertex solution data set contains the vertex-based variables such as velocities.

    There are x- y- and z- coordinates in each data set.

    Therefore, two IC tables must be created in this workaround. One is based on the cell solution and is used to initialize pressure, temperature, composition and turbulence quantities. The other is based on the vertex solution and is used to initialize velocities.

  2. When a .ftres solution is imported to initialize the flow field, it is important to make sure that the locations of the moving boundaries at the moment of that solution are the same as those defined in the Forte project when the new simulation starts. This requirement is important for problems with moving boundaries. If it is not met, then the mapping could fail and become meaningless. This is actually a big restriction in this workaround.

    Using a different global mesh size upon a restart is not what is encouraged. The trouble caused by going through the workaround might outweigh its benefits. If the goal is to change mesh resolution upon the restart, the best way is to adjust the mesh refinement settings except the global mesh size.

6.1.3. Keep Old Restart Files

If the Interval Based Restart option is used, only the most recent restart file is kept. When the simulation creates a new restart file, it will always erase the old one.

However, you can set User Defined Restart Points, and these restart files won't be erased.

Also, any time during the simulation, you can write a blank file named SAVE_RESTART into the working directory. The simulation will detect it and write a restart file in the next time step and remove the blank file. This restart file is also kept always.