Submitting DataSets to CollisionDB

Data may be submitted to the CollisionDB database using the format described below. Please contact fusion-data@iaea.org for more information about providing datasets.

Submitted text files should be in UTF-8 encoded, plain text format with metadata specified as the following key=value pairs. Some general principles:

• Blank lines are ignored;
• Comment lines which are indicated by a # as the first character, are also ignored;
• Each key=value pair, including comments, must be on a single line;
• No whitespace around the = symbol is allowed;
• Strings are enclosed in ordinary double quote characters, " (no word-processing "smart quotes");
• If a DOI is not provided, then the metadata fields author, affiliation and email must be completed;
• Unless specified, the total cross section for a process is assumed;
• For heavy particle collision cross sections, the energy frame must be specified as one of com (centre-of-mass frame) or target (target frame, i.e. the "lab" frame).

In the below, compulsory metadata is indicated by shaded entries.

Basic Metadata

• authors: name of the authors or contacts, in the case of unpublished data or data without a DOI. Example:
  authors="I. Ziaeian, K. Tőkési"
• affiliation: name of the university / institute in the case of unpublished data. Please include the city and country. Example:
  affiliation="Institute for Nuclear Research (ATOMKI), Debrecen, Hungary"
• email: contact email address for correspondence in the case of unpublished data. Example:
  email="fusion-data@iaea.org"
• comment: any one-line descriptive comment. Example:
  comment="Interaction of Be4+ and Ground State H Atom—Classical Treatment of the Collision"
• method: one of these pre-defined abbreviations identifying the computational method used, or one of: "experiment", "semi-empirical" or "estimate". Example:
  method="CCC"
• doi: the single or comma-separated list of DOIs identifying the publication(s) (if any) describing the work. Enclose values in square brackets, [...]. Examples:
  doi=["https://doi.org/10.3390/atoms8020027"]
doi=["https://doi.org/10.3390/atoms8020027", "https://doi.org/10.3390/atoms8020027”]
• data_type: the type of data, one of "cross section", "differential cross section" or "rate coefficient". Example:
  data_type="cross section"
• frame: (mandatory only for heavy particle collision cross sections) the energy frame of reference, one of "com" or "target" for centre-of-mass and target (i.e. "lab") frames, respectively. Example:
  frame="target"
• threshold: the threshold energy (in eV) for the transition. Should be a number, without units. Example:
  threshold=5.4
• uncertainty: the uncertainty associated with the data, as a relative value in percent (include the % symbol). Additional per-data point uncertainties may be specified in the data table itself (see below). Example:
  uncertainty=10.0%
• columns: an explanation of the numeric data columns as a list of strings of the form: "<name>, <units>". The first column in the data table is expected to be the energy, temperature or angle coordinate, depending on the data type; all subsequent columns must have the same units as the second entry in this list. Example:
  columns=["E, keV/u", "sigma, cm2"] for cross sections;
  columns=["T, eV", "rate, cm3.s-1"] for rate coefficients.
• reaction: a string identifying the collisional process in the form A + B -> C + D, where A, B, etc. are "stateful species", designed to be parseable by the pyvalem Python package. A brief introduction is given here. Examples:
  reaction="Be+4 + H 1s -> Be+3 + H+"
reaction="e- + H2 X(1SIGMA+g); v=0 -> e- + H2 C(1PIu); v=0"
  
• process_types: a list of three-letter codes describing the process; for process type abbreviations, please see Plasma Processes Classification. Enclose in square brackets. Examples:
  process_types=["EEX"]
process_types=["HDE", "HDS"]
• data_from_fit: (only for data provided with fit coefficients). data_from_fit should be set to false if the numerical data is from the original source (theoretical calculations or measurements) or set to true if the provided tabulated data are derived from a fitting function (see below).

Data

Data are presented in a table of columns of values, delimited by whitespace.

• The table header line should contain column names, which (for two-column tables) must match the entries in the columns metadata key-value pair;
• Numeric values must be provided in machine-readable format as integers, decimal numbers, or floating point values in E notation (e.g. 1.4e-17, not 1.4 × 10^-17 or variants);
• Missing values are indicated by a single asterisk, *;
• Blank and comment lines are allowed within the data table and are ignored (and not stored in the database);
• Where uncertainties on a single data point are given, they follow a colon, :;
• A single uncertainty value indicates symmetric uncertainties, asymmetric uncertainties are given as a comma-separated pair of values;
• Please provide data on a suitable grid of energy / temperature / angle values. The grid value spacing does not have to be constant;
• Please provide data with a suitable precision (more than three decimal places are rarely justified).

Example:

E           sigma
1.250E+01   1.088E-03            # no uncertainty value
1.550E+01   *                    # missing data point
1.229E+01   1.4e-18:5e-19        # symmetric uncertainty, 1.4e-18 ± 5e-19
1.229E+01   1.4e-18:5e-19,8e-19  # asymmetric uncertainty, 1.4e-18 (-5e-19, +8e-19)

An example template file for two-column data is provided here: xy_template1.txt.

Data may also be provided in a table with more than two columns, where each column following the first one contains data for a separate reaction. This is often useful where calculations are carried out for several different reactant or product states in a process. In this case, the reaction metadata key-value pair must indicate a wildcard, (*), into which the column headings will be interpolated to form the full collisional process "reaction".

Example:

...
columns=["E, keV/u", "sigma, 10^-16 cm2"]
reaction="Be+4 + H 1s -> Be+3 (*) + H+"
...
E        n=1       n=2       n=3
20       3.79E-3   1.05E+0   1.75E+2
100      *         2.93E-1   8.39E-1
500      3.68E-3   3.69E-3   1.63E-3

This table is understood to provide the cross sections for three processes, on the same energy grid for the formation of Be³⁺ in each of the states n=1, n=2 and n=3. That is, the above data are for the "reactions":
Be⁴⁺ + H 1s → Be³⁺ n=1 + H⁺
Be⁴⁺ + H 1s → Be³⁺ n=2 + H⁺
Be⁴⁺ + H 1s → Be³⁺ n=3 + H⁺

An example template file for multiple-column data is provided here: xy_template2.txt.

Fitting Coefficients

The fitting coefficients along with numerical data (either from the original source or derived from the fit function) can be provided in JSON format in the fit block of metadata, in which the following names may be defined:

• "coeffs": A JSON object providing values for named coefficients. The coefficient names must be valid Python identifiers. Example:
  "coeffs": {"A1": 0.085, "A2": -0.004, "I": 5.39}
• "func": the name of the fitting function. We can define the fitting function in the Python library if all relevant information is provided to us, or an account can be set up for data providers to store their own fit functions.
• "Elo": the lower limit of the energy range for the fit function to be valid.
• "Ehi": the upper limit of the energy range for the fit function to be valid.
• "data_type": if different from the fitted or original data, e.g. where fitted functions represent collision strengths but numerical fitted / original data provided are cross sections.
• "comment": a single-line comment, specific to the fitting function or its use.
• "source_dois": provide a single DOI string or a list of DOIs (as above) only if different from the primary DOI.
• "fit_precision": the uncertainty of fit, as a percentage.

An example template file for fitted data is provided here: fit_template.txt.