Cases

Cases define which data (e.g. experimental or equilibrium data) and which simulation results are used in a comparison. They serve as an entry point for the data and for the simulation driver including all relevant conditions and parameters. A minimally valid case requires the presence of a package.json file (and optionally a carmen.yml file) in the Project Directory.

Cases are defined in YAML by writing cases: and hitting enter. Cases are then given as an array, each one starting with one level of indentation (i.e. two blank spaces) followed by a - hyphen and enter. A case requires a title key, a data key referencing to a data resource, and a configuration key containing the configuration parameters that are bound to that data. The first key of the case definition is written by convention on the line below the hyphen with one additional level of indentation (i.e. two additional blank spaces) with respect to the hyphen. The configuration: field requires a driver key, an ouput key, and a parameters key. The name of each key is followed by a colon :, a blank space, and the value of the key.

The following example is an excerpt from a case definition in YAML format:

cases:
  -
    title: My first case
    data: ./path/to/file.csv
#   view:
#     label:
#       x: temperature (T/K)
#       y: mole fractions
    configuration:
      driver: detchem_stagnation
      output: ./mole_fractions
      parameters:
        # ...

The title: field defines the name of the case shown in CaRMeN's user interface. It is therefore important to give it a name which is quickly and unequivocally identifiable.

The data: field is given as a string referencing the file containing the experimental (or the equilibrium) data, starting always with a point . followed by a slash / and the path to the file.

The view: field under the cases: field is optional (written in this example as a comment for the sake of clarity) and it can be used to define the labels of the x and y axes on the plot shown by CaRMeN. If no view options are defined the axis will be labelled x and y, or differently, according to the case. For more information about CaRMeN's user interface see the chapter Description of the User Interface under the manual section of this documentation.

The driver: field defines the driver used by CaRMeN for simulating, in other words, it defines the code which will be used by CaRMeN's remote server to perform the calculations. For more information on drivers see the chapter Drivers under the reference section of this documentation.

The output: field defines the output of the driver by writing a point . followed by a slash / and the name of the desired output format. Which output options are available depends on the driver used.

The parameters: field contains the simulation parameters used by the driver for the simulation. Which parameters are allowed depends on the driver used.

The example shown above can be understood as follows:

Here a single case with the title My first case is defined. This case definition tells carmen to use the data in ./path/to/file.csv as a basis for a comparison with the result from the driver detchem_stagnation as mole_fractions when it is given the parameters under the parameters: field (omitted in the example for brevity).