3.1. General Case Setup

Some guidelines for setting up a new case apply to all configurations independent of the particular CFD solver and whether the case is simple or very complex. As mentioned several times before, the primary JSON file is mandatory and controls most of the settings of a run configuration.

This master JSON file points to several other files, such as meshes, template input files, or a list of input conditions. In addition, users may wish to define some of the settings in a Python script instead of typing them out in JSON. This enables the use of loops, etc., and also it provides input settings that are dependent on conditions.

Two of the sections of the JSON file, particularly "DataBook" and "Report" can be filled in after getting the cases running. The other sections of the JSON file are generally required to be configured correctly before starting a case. The most important section for determining the basic structure of a run setup is the "RunMatrix" section.

3.1.1. Matrix Setup

The first step is to pick the list of run matrix variables, which is a list set in RunMatrix ‣ Keys. For example, this could be as simple as ["mach", "alpha"] for a simple run matrix, or there could be may more variables such as fin deflection angles or thrust settings. Common variables such as "mach", "alpha", "beta", etc. do not need definitions, but special variables such as thrust settings need to have further explanation in the RunMatrix ‣ Definitions section.

In addition, there are three other pre-declared variable types that do not directly impact any CFD input settings. These variables are "config", which sets the name of the group folder; "Label", which appends an extra string to the end of the run folder name; and "tag", which does not affect either folder name but can be used to store other markers. For example, consider the following run matrix CSV file:

# mach, alpha, config, Label, tag
2.50, 2.0, hi-q, ,
2.50, 2.0, hi-q, b,
2.50, 2.0, lo-q, ,

The folder names for these three cases are below:

hi-q/m2.50a2.0
hi-q/m2.50a2.0_b
lo-q/m2.50a2.0

Quite often the "Label" key is used to redo cases that failed on the first attempt but users can also use for other purposes, such as denoting different grid resolutions, etc.

As hinted above, another file that is needed independently of which particular solver is being used is the run matrix file. This is a simple comma-separated or white-space-separated file where each row is a separate CFD case, and each column is a separate variable. Note: commas are recommended over spaces because space-separated values don’t work properly with empty columns.

We generally recommend leaving two spaces at the start of each row so that marking a case as completed (PASS) doesn’t mess with the alignment. The run matrix file shown above with the first two cases marked as PASs would look like the following.

# mach, alpha, config, Label, tag
p 2.50, 2.0, hi-q, ,
p 2.50, 2.0, hi-q, b,
  2.50, 2.0, lo-q, ,

3.1.2. Pre-run JSON Setup

Most of the sections of the JSON file other than Report, DataBook, and RunControl ‣ Archive affect the way the CFD solver is run, and thus they should generally be determined before starting the first case.

For each version of the code, the RunControl section contains some key parameters. For example, RunControl ‣ PhaseSequence and RunControl ‣ PhaseIters are mandatory. Some of the other RunControl parameters are very dependent on which solver is being used, for example command-line options to flowCart (for Cart3D) nodet (for FUN3D).

Users should take special consideration of the Config section prior to starting the actual runs. This section can be used to request certain outputs from a solver, and it is important that the solver is reporting all the needed information. It is possible to have the template input files (such as input.cntl for Cart3D) already set up to request the right outputs, but if the user is relying on the convenience of pyCart to request the information, Config is the section to do it. Most commonly, this description refers to asking for iterative force and moment histories, but other parameters such as point sensors are occasionally set here, too.

3.1.3. Mesh Files and Other Templates

There are certain pointers to mesh files in each version of the JSON file, and each code needs several other template input files as well. Most of these input files have default templates provided in $CAPE/templates/, but some files like OVERFLOW’s overflow.inp namelist depend on the number of grids and cannot be reduced to a global default template.

Below is a list of the required or semi-required input templates for each solver.

  • Cart3D

    • input.cntl: Main Cart3D input file (global template provided)

    • aero.csh: Cart3D adaptation script (global template provided)

  • FUN3D

    • fun3d.nml: Template namelist (global template provided)

    • pyfun.mapbc: Sets boundary condition for each surface in mesh

  • OVERFLOW

    • overflow.inp: Template input namelist

3.1.4. Data Book Setup

The DataBook ‣ Components parameter sets the list of data components that are considered final post-processing data products from the run. With no other specifications, a “Component” is assumed to be a force and moment ("Type": "FM") taken from an iterative history. The exception is Cart3D, where the default type is "Force" since users must separately request forces and moments in that particular solver.

However, there are other data book types. The following example requests iterative force and moments on the components called "left_wing" and "right_wing", a line load on "fuselage", and a protuberance patch load taken from the final surface solution on the "cockpit". There is also an FM component called "wings" in which pyCart adds the two wings’ forces together for each iteration.

"DataBook": {
    "Components": ["left_wing", "right_wing", "fuselage",
        "cockpit", "wings"],
    "fuselage": {
        "Type": "LineLoad",
        "CompID": "fuselage"
    },
    "cockpit": {
        "Type": "TriqFM",
        "MapTri": "inputs/cockpit.patch.uh3d",
        "Patches": ["front", "left", "top", "right", "back"]
    }
    "wings": {
        "Type": "FM",
        "CompID": ["left_wing", "right_wing"]
    }
}

Because this is a pure post-processing step, these parameters can be filled in after starting or even finishing some of the cases. Other DataBook parameters, such as DataBook ‣ nStats and DataBook ‣ nFirst are also important; see the appropriate subsection of the JSON settings description for more information.

Collecting the data into a database, which is kept in a separate folder outside the run folders (so that the run folders can be deleted when appropriate without affecting the databases), is performed via several commands:

Type

Command

"FM"

pycart --fm

"LineLoad"

pycart --ll

"TriqFM"

pycart --triqfm

"TriqPoint"

pycart --pt

3.1.5. Case Disposition and Archiving

Once a case has been marked as PASS using a p in the first column of the run matrix file, it can be archived. (Note: cases marked with the p but that have not run the appropriate number of iterations or are still running have the status PASS* and will not be archived.) Archiving a case is performed using a command that conforms to the following template.

$ pycart -I 140 --archive

This will save some of the important files to a backup location and also delete files if requested. It can be useful for keeping below file size and file count quotas while running large databases.

The --clean command performs a subset of the --archive actions and can be run at any time. Any files identified in the RunControl ‣ Archive ‣ ProgressDeleteFiles as noncritical files will be deleted at any time this --clean command is run.

The command

$ pycart -I 140 --skeleton

performs even more cleanup tasks. Users may distinguish between --archive and --skeleton for various tasks of post-processing. Typically it is useful to leave the solution folder in such a state that all necessary post-processing can still be performed after --archive has been run, but the remaining files after --skeleton are only sufficient for pycart -c to report the correct number of iterations run.