5.2. Control Files for pyFun (pyFun.json)

This section describes the JSON files that provide the master control to the pyFun package. The file format, JSON, stands for “JavaScript Object Notation,” which is a standard file format but relatively recent. There is one extension for pyCart JSON files, which is that comments are allowed, using either // (preferred) or # as the comment character. Newer versions of vi or vim recognize this file format for syntax highlighting, as do some other text editors, and setting the highlight mode to javascript is a useful way to convince other programs to provide useful syntax highlighting.

Creating JSON files is very similar to creating a text file that contains a single Python dict, with a few differences.

  1. Only double quotes are allowed; single quotes are not valid string characters.

  2. Each key name must be a string; syntax like {1: "a"} is not valid.

  3. True and false are denoted true, false, and null instead of

    the Python standard True, False, and None.

  4. The only available types are int, float, unicode, bool, list, and dict.

  5. Other JSON files can be imported using JSONFile(othersettings.json).

The pyFun control file, which by default is called pyFun.json but can also have other names, is split into several sections. Most aspects of the control file have defaults that will go into effect if the user does not specify that option, but several entries are required. The user can also customize these defaults by editing the file $CAPE/pyfun/options/pyFun.default.json, where $CAPE is the path to the Cape root directory. Many of the settings are common to all solvers, and their description can be found in the Cape JSON section.

The master settings file is loaded in one of two ways: a command-line call to the script pyfun or loading an instance of the cape.pyfun.cntl.Cntl class. In both cases, the default name of the file is pyFun.json, but it is possible to use other file names. The following two examples show the status of the run matrix; the first load the inputs from pyFun.json, and the second loads the inputs from run/poweron.json.

$ pyfun -c
$ pyfun -f run/poweron.json -c

Within a Python script, the settings can be loaded with the following code.

import cape.pyfun

# Loads pyFun.json
c1 = cape.pyfun.Cntl()
# Loads run/poweron.json
c2 = cape.pyfun.Cntl('run/poweron.json')

The location from which either of these two methods is called (i.e., the current working directory) is remembered as the root directory for the run. Locations of other files are relative to this directory.

The following is a nearly minimal pyFun control file that is presented to show the major parts of the file.

{
    // Stand-alone options
    "ShellCmds": [],

    // Settings for creating PBS scripts, if applicable
    "PBS": {},

    // Primary settings for running Cart3D
    "RunControl": {
        // Overall control of mode and number of iterations
        "InputSeq": [0, 1],
        "IterSeq": [0, 1500],
        "qsub": false
    },

    // Settings to define the initial mesh
    "Mesh": {},

    // Settings to define component names, reference points, etc.
    "Config": {},

    // Settings for the output functional for adaptation
    "Functional": {},

    // Settings for folder management and archiving
    "Management": {},

    // Describe what forces and moments to record in the data book.
    "DataBook": {},

    // Describe reports to create to summarize results
    "Report": JSONFile("Report.json"),

    // Mandatory definition of run matrix.
    "RunMatrix": {
        // This method points to a file that contains run conditions.
        "File": "RunMatrix.csv",
        // It is mandatory to define what the input variables are.
        "Keys": ["Mach", "alpha", "beta"],
        "GroupPrefix": "poweroff",
        "GroupMesh": false
    }
}

For more information on these options see the following sections, and the documentation for the module cape.pyfun.options also provides descriptions of how the options are used.