Packages

In CaRMeN, all data (experimental data, equilibrium data, simulation results, chemical models, i.e. the combination of mechanism, thermodynamic data and possibly transport data) are organized in packages. A package can be viewed as a simple collection of files, along with metadata that adds context to them. The presence of a package.json file marks the enclosing directory as a package.

package.json files are written in JSON-format and define various things. If you are not familiar with the JSON-format see the chapter Data Structures in the manual section of this documentation. A minimally valid package.json file contains two keys: name and version. Configurations related to CaRMeN are grouped under a third key called carmen. Objects are defined in JSON by writing a left brace { and hitting enter. On the line below the left brace one level of indentation is inserted by writing two blank spaces followed by the first key. The names of keys are given as strings and are therefore surrounded by double quotes ". The name of each key is followed by a colon : and the value of the key. A blank space can be inserted after the colon for better readability.

Here is an example of a package.json file using the JSON-format:

{
  "name": "Donazzi 2008 10.1016/j.jcat.2008.02.009",
  "version": "0.0.0",
  "carmen": "carmen.yml"
}

The field "name": can be given any value as a string. It does not show up in CaRMeN's user interface but rather only serves the program to differentiate between multiple package.json files.

The field "version": serves to determine the compatibility of the file with the version of CaRMeN been used. Older file versions are so far compatible with newer versions of CaRMeN.

The field "carmen": contains all configurations related to CaRMeN, which are contained under three keys: "cases", "mixins" and "resources". This configuration parameters can be either directly written into the package.json file, using the JSON-format, or in an external file using a different format like YAML, by providing the path to the file as a string instead of the above mentioned keys. Because the YAML format is generally easier to read and write and also supports the use of comments, most packages use an external file in YAML format to define CaRMeN related parameters. If you are not familiar with the YAML-format see the chapter Data Structures in the manual section of this documentation.

Here is an example of a carmen.yml file using the YAML-format:

cases:
  -
    # ...

mixins:
  -
    # ...

resources:
  -
    # ...

An important advantage of the concept of packages is its non-intrusiveness and the resulting flexibility. No constraints are imposed on the way users organize their files. Hence, existing file structures and directory hierarchies can be used without modification. Only one package.json file must be created in each respective directory. The user may organize these files in any way, and may add as many files as needed to the package. Furthermore, there is no restriction about the formats of these files. In a package describing experimental data, for example, textual descriptions, PDFs, or even images could be provided in addition to the actual tabular data in order to let consumers of the package better understand the experimental setup, procedure, and background.