OOPS 2D Tutorial: Adding Parameters

Any scientific code needs to be able to adjust parameters without recompiling. In some codes, adding new parameters or adjusting permissible inputs is often very difficult; at the bare minimum, you'll have to add a new parameter to a data structure, possibly with access functions, and modify a parser to read the parameter and guarantee that the requested value is valid. If you're working on a parallel code, these parameters also need to be broadcast to all the other processors. It's such an onerous process that a lot of very simple codes simply relegate all their parameters to command-line arguments.

Fortunately, OOPS-2D tries to be one of the more enlightened codes that makes adding parameters easy. Thanks to the genParams.py script, the hardest task is just writing a setup file. You can even set up your build procedure to run genParams.py whenever the code is compiled.

Note: readers familiar with parameters in OOPS can skip this tutorial. The process is identical.

Parameter Setup Scripts

OOPS-2D stores a list of all possible parameters, their acceptable values, and their defaults in a JSON setup script. A typical file looks something like the following:

{
  "Example":{
    "name":"Example",
    "id":3,
    "members":[
      {
        "name":"AnInteger",
        "type":"int",
        "min":0,
        "max":10,
        "default":3
      },
      {
        "name":"ADouble",
        "type":"double",
        "min":-1e6,
        "max":1e6,
        "default":1.0
      },
      {
        "name":"AnEnum",
        "type":"enum",
        "values":[
          "VALUE1",
          "VALUE2",
          "VALUE3"
        ],
        "default":"VALUE1"
      },
      {
        "name":"AString",
        "type":"string",
        "default":"This is a string"
      }
    ]
  }
}

The first layer creates a new object, "Example". This represents a single set of parameters (yes, you can have multiple sets in a single file). Every parameter object must define three variables: "name", which is a string that would qualify as a valid identifier in C++ (i.e., only letters, numbers, and underscores); "id", which is an integer that helps match a generated Parameters object with an appropriate ParamParser object; and "members", which is an array of objects, each defining a new parameter.