Skip to content

JSON Configuration file

The configuration file has to be in the JSON format (For the definition of the JSON format see json.org, RFC 8259 or ECMA-404 "The JSON Data Interchange Standard". ). The file has to be UTF-8 encoded. The following will describe the keys and their values processed by migraSIM. Additional key/value-pair does not raise an error. The symbol [number] will stand for a floating point or integer, the symbol [unit] for a string of characters.

The root level of the JSON-file consists of the following key/value-pairs:

migraSIM (string, required) Version of the current configuration file format, current value is 20210205.

migration modelling (object, required) Section describing the migration modelling scenario, see section migration modelling.

output (object, required) Controls the format and amount of output of the migraSIM-service, see section output.

For physical quantity a value/unit-pair (or short v/u-pair) is used in form of the json object 

{ "value": [number], "unit": "[unit]" }
is used. For example 23 °C is encoded as: 
{ "value": 23, "unit": "°C" }

migration modelling

The migration modelling object has the following keys and values:

name (string, required) A name of the scenario/simulation

change cycle (list of objects) Each object describes consecutive a time and temperature profile during the simulation. In combination with the "initial mass fraction"-key this can also be used, to simulate an exchange of food / water layer (see section change cycle).

matrix (object, required) Describes the layer of the matrix including the food / water (see section matrix).

migrant (object, required) Each object describes the properties of one migrant in the scenario (see section migrant).

change cycle

More then one change cycle is used for repeated use applictions.

temperature (v/u-pair, optional) The constant temperature during the time period of cycle.

start temperature (v/u-pair, optional) Start temperature during the time period of the cycle

end temperature (v/u-pair, optional) End temperature during the time period of the cycle

time (v/u-pair, optional) Duration of the cycle.

The two keys start temperature and end temperature must occur both or the temperature must occur alone. If start temperature and end temperature occur, then the temperature is recomputed every time step by adding the tendency

(end temperature - start temperature)/time * ∆t

where ∆t is the duration of a time step, this means the temperature is linearly interpolated between the start temperature and end temperature over the cycle time. In the case of temperature occur, the temperature is constant over the cycle.

There is another possibility to formulate a change cycle, if the temperature is constant over the time:

{
    "temperature": {
      "value": 23.0,
      "unit": "°C" 
    },
    "time": {
      "value": [1, 3, 3, 3],
      "unit": "d" 
    }
  }

matrix

name, (string, required) Name of the matrix

layer (list of objects, required) Description of the layers in the matrix (see following section matrix layer).

contact area (v/u-pair, required) contact area between the layers, e. g. the contact area between food contact material and food/simulant or product and drinking water.

matrix layer

name (string, required) Name of the layer, this name is used in the migrant-layer-object for matching the layers. This name must be unique in the matrix layer names.

id (string, optional) Identifier for the polymer

thickness (v/u-pair, required) The thickness of the layer

density (v/u-pair, optional) The density of the layer, if a polymer id is specified, the density is lookup for this id from migraBASE.

Piringer (object, optional) The Piringer-Parameters A'_P and τ of the layer as object 

{"APp": [number], "tau": [number]}
or as object 
{"compute": "glass transition temperature"}
if the glass transition temperature is given.

glass transition temperature (v/u-pair, optional) Glass transition temperature of the plastic used in the layer.

migrant

name (string, required) Name of the migrant

id (string, required) Id of the migrant

molar mass (v/u-pair, optional) molar mass of the migrant. If migrant id is specified, the molar mass is lookup for this id from migraBASE.

logPow (value, optional) octanol/water partition coefficient of the migrant as a object {"value": <value>}.

layer (list of objects, required) Each object describes the properties of the migrant in the layer (see migrant layer).

migrant layer

name (string, required) Name of the layer, must match a name of one layer in the matrix-object.

initial mass fraction(v/u-pair or list of v/u-pair, required) Initial mass for the change cycles. Each element of the list corresponds to one change cycles. The initial mass is reset to the defined value at the beginning of the cycle. Are there n initial mass fraction elements and m change cycles defined, and n is smaller than m, then only at the first n change cycles the values is reset, for the cycle n + 1 to m the simulation continues without resetting the mass fraction in the layer.

If there is one cycle with no contact to the food/water, then the "no contact" key word can be used.

 "initial mass fraction":
     {"value": [0.0, "no contact", 0.0, 0.0, 0.0, 0.0, "no contact", 0.0, 0.0, 0.0],
      "unit": "mg/kg"}
if in a change cycle the initial mass should not be change to a defined value (but in a later one), but the simulation shall continue with the simulated value, than the key word "keep" can be used.

 "initial mass fraction":
     {"value": [0.0, "keep", "keep", 0.0, "keep", "keep", 0.0, "keep", "keep"],
      "unit": "mg/kg"}

diffusion coefficient (v/u-pair or list of v/u-pair or object, required) diffusion coefficient of the migrant in the layer. Each element of the list corresponds to one change cycles. The diffusion coefficient is reset to the defined value for the cycle. Are there n diffusion coefficients elements and m change cycles defined, and n is smaller than m, then only at the first n change cycles the values is reset, for the cycle n + 1 to m the simulation continues without resetting the diffusion coefficients in the layer. For {"compute": "Piringer"} the diffusion coefficient is computed with the Piringer parameters of the layer, the molar mass of the migrant and the current temperature defined for the change cycle. For each time step the temperature and there fore also the diffusion coefficient is recomputed.

partition coefficient (v/u-pair or list of v/u-pair or object, required) Partition coefficient of the migrant in the layer. Each element of the list corresponds to one change cycles. The partition coefficient is reset to the defined value for the cycle. Are there n partition coefficients elements and m change cycles defined, and n is smaller than m, then only at the first n change cycles the values is reset, for the cycle n + 1 to m the simulation continues without resetting the partition coefficients in the layer. For {"compute": "logPow"} the partition coefficient is com- puted from the log linear correlation of the octanol/water- partition coefficient of the layer.

output

The output object configures the result of the simulation.

number output time steps (integer, optional) number of equidistantly spaced time steps for the mass fraction output

output interval of migrant mass (v/u-pair, optional) output interval of the migrant mass in the output file

output format (string or list of strings, optional) Each string can be "csv" for several comma sepa- rated values files or "hdf5" for one hdf5-file con- taining all outputs.

output fields (list, optional): 

    "output fields": ["mass fraction profile", "migration mass", "migration mass at change cycle",
                      "mass deviation", "log"]

  • If not specified all possible elements are in the result.
  • If specified only the elements of the list are in the result. Possible values are listed in the synopsis.

output of the migraSIM-service

The return value of the migraSIM-service is a JSON file.

csv There is a key creation time, which shows the time stamp, when the simulation was computed. And for each migrant there is a key with the name of the migrant from section migrant. For the csv-output the object of the migrant has the following keys:

mass fraction profile the profile of the mass fraction for the given output time steps

migration mass the evolution of the mass of the migrant during the migration per layer

migration mass at change cycle the mass of the migrant at the end of a change cycle.

log A log file of the migration simulation.

mass deviation < < to be done.> >

hdf5 For the hdf5-output there is on key hdf5_base64, with a hdf5 file encode in base64 for transportation and one key log for the log file of the simulation. The hdf5 file has the following data sets:

/layer names the names of the layers

/mass_fraction/mass fraction the mass fraction for each output time

/mass_fraction/spatial position the x coordinates

/mass_fraction/layer end position the x coordinate of the right end of the positions

/mass_fraction/output times the time steps of the output of the mass fraction

/migration_profile/migration profile the evolution of the mass of the migrant during the migration per layer

/migration_profile/time the time stamp of the evolution

/migration_profile/temperature the temperature at the time stamp

/mass_at_change_cycle/mass at change cycle the mass of the migrant at the end of a change cycle.

/mass_at_change_cycle/cycle time the time stamp of the change from the current cycle to the next.

/configuration the configuration passed to migraSIM

/information the creation time and the version of migraSIM

The units of the physical quantity are noted as data sets attributes.

Units

The following units can be used for the unit-keys.

physical quantity unit symbol description
time s second
h hour
d day
thickness cm centimetre
mm millimetre
μm micrometer, 1 μm = 1 · 10^(−6) Meters
area cm², cm2 square centimetre
diffusion coefficient cm²/s, cm2/s square centimetre per second
partition coefficient (g/ml)/(g/ml) this mean the partition coefficient for the concentration, not for the
mass fraction.
temperature °C, C degree Celsius
K Kelvin

Examples

You will get examples for the current file format from SAFE+ Algorithmics GmbH. You can get an template for the configuration file over the end point https://[migrasim-server]:8000/get_configuration_template of the REST-API.