Skip to content

Latest commit

 

History

History
128 lines (95 loc) · 5.54 KB

validation.rst

File metadata and controls

128 lines (95 loc) · 5.54 KB

IDS validation

The IDSs you fill should be consistent. To help you in validating that, IMAS-Python has a :py:meth:`~imas.ids_toplevel.IDSToplevel.validate` method that executes the following checks.

Validation checks

If you call this method and your IDS fails validation, IMAS-Python raises an error explaining the problem. See the following example:

>>> import imas
>>> core_profiles = imas.IDSFactory().core_profiles()
>>> core_profiles.validate()
imas.exception.ValidationError: Invalid value for ids_properties.homogeneous_time: -999999999

IMAS-Python also automatically validates an IDS every time you do a :py:meth:`~imas.db_entry.DBEntry.put` or :py:meth:`~imas.db_entry.DBEntry.put_slice`. To disable this feature, you must set the environment variable IMAS_AL_DISABLE_VALIDATE to 1.

.. seealso::

    API documentation: :py:meth:`IDSToplevel.validate() <imas.ids_toplevel.IDSToplevel.validate>`

Validate the time mode

The time mode of an IDS is stored in ids_properties.homogeneous_time. This property must be filled with a valid time mode (IDS_TIME_MODE_HOMOGENEOUS, IDS_TIME_MODE_HETEROGENEOUS or IDS_TIME_MODE_INDEPENDENT). When the time mode is independent, all time-dependent quantities must be empty.

Validate coordinates

If a quantity in your IDS has coordinates, then these coordinates must be filled. The size of your data must match the size of the coordinates:

.. todo:: link to DD docs

  1. Some dimensions must have a fixed size. This is indicated by the Data Dictionary as, for example, 1...3.

    For example, in the magnetics IDS, b_field_pol_probe(i1)/bandwidth_3db has 1...2 as coordinate 1. This means that, if you fill this data field, the first (and only) dimension of this field must be of size 2.

  2. If the coordinate is another quantity in the IDS, then that coordinate must be filled and have the same size as your data.

    For example, in the pf_active IDS, coil(i1)/current_limit_max is a two-dimensional quantity with coordinates coil(i1)/b_field_max and coil(i1)/temperature. This means that, if you fill this data field, their coordinate fields must be filled as well. The first dimension of current_limit_max must have the same size as b_field_max and the second dimension the same size as temperature. Expressed in Python code:

    numpy.shape(current_limit_max) == (len(b_field_max), len(temperature))

    Time coordinates are handled depending on the value of ids_properties/homogeneous_time:

    • When using IDS_TIME_MODE_HOMOGENEOUS, all time coordinates look at the root time node of the IDS.

    • When using IDS_TIME_MODE_HETEROGENOUS, all time coordinates look at the time path specified as coordinate by the Data Dictionary.

      For dynamic array of structures, the time coordinates is a FLT_0D inside the AoS (see, for example, profiles_1d in the core_profiles IDS). In such cases the time node must be set to something different than EMPTY_FLOAT. This is the only case in which values of the coordinates are verified, in all other cases only the sizes of coordinates are validated.

    Alternative coordinates

    Version 4 of the Data Dictionary introduces alternative coordinates. An example of this can be found in the core_profiles IDS in profiles_1d(itime)/grid/rho_tor_norm. Alternatives for this coordinate are:

    • profiles_1d(itime)/grid/rho_tor
    • profiles_1d(itime)/grid/psi
    • profiles_1d(itime)/grid/volume
    • profiles_1d(itime)/grid/area
    • profiles_1d(itime)/grid/surface
    • profiles_1d(itime)/grid/rho_pol_norm

    Multiple alternative coordinates may be filled (for example, an IDS might fill both the normalized and non-normalized toroidal flux coordinate). In that case, the size must be the same.

    When a quantity refers to this set of alternatives (for example profiles_1d(itime)/electrons/temperature), at least one of the alternative coordinates must be set and its size must match the size of the quantity.

  3. The Data Dictionary can indicate exclusive alternative coordinates. See for example the distribution(i1)/profiles_2d(itime)/density(:,:) quantity in the distributions IDS, which has as first coordinate distribution(i1)/profiles_2d(itime)/grid/r OR distribution(i1)/profiles_2d(itime)/grid/rho_tor_norm. This means that either r or rho_tor_norm can be used as coordinate.

    Validation works the same as explained in the previous point, except that exactly one of the alternative coordinate must be filled. Its size must, of course, still match the size of the data in the specified dimension.

  4. Some quantites indicate a coordinate must be the same size as another quantity through the property coordinateX_same_as. In this case, the other quantity is not a coordinate, but their data is related and must be of the same size.

    An example can be found in the edge_profiles IDS, quantity ggd(itime)/neutral(i1)/velocity(i2)/diamagnetic. This is a two-dimensional field for which the first coordinate must be the same as ggd(itime)/neutral(i1)/velocity(i2)/radial. When the diamagnetic velocity component is filled, the radial component must be filled as well, and have a matching size.