Use Interface Data Structures¶

The Interface Data Structures (IDSs) are the main way to interact with IMAS data. An IDS is a tree-like structure with one root element (the IDS) and several branches with data at the leave nodes.

Many types of IDSs exist: check out the documentation of the Data Dictionary for a complete overview.

Creating IDSs¶

IDSs can be created in multiple ways:

1. Load an IDS from disk

2. Create an empty IDS

3. Create a copy of an IDS

Create an empty IDS¶

You can create an empty instance of an IDS by calling ids_init(), for example ids_init('core_profiles') creates an empty core_profiles IDS. This initializes all items in the IDS to their Default values.

% Create an empty core_profiles IDS
core_profiles = ids_init('core_profiles')
disp(core_profiles.ids_properties.homogeneous_time)  % -> -999999999 (default INT_0D value)

% Create an empty equilibrium IDS
equilibrium = ids_init('equilibrium')
disp(length(equilibrium.time_slice))  % -> 0 (default size of array of structure)

Create a copy of an IDS¶

You can create a copy of another IDS by assigning it to a new variable.

% Create an empty core_profiles IDS, and fill with some data
core_profiles = ids_init('core_profiles')
core_profiles.ids_properties.homogeneous_time = 1
core_profiles.time = [1, 2]
core_profiles.profiles_1d = ids_allocate('core_profiles', 'profiles_1d', 2)
for i = 1:2
    core_profiles.profiles_1d{i}.grid.rho_tor_norm = 0:.25:1
    core_profiles.profiles_1d{i}.j_total = (0:.25:1) + i
end

% Copy the IDS
core_profiles_copy = core_profiles

% Adjust some data
core_profiles_copy.profiles_1d{1}.j_total = ...
    2 * core_profiles_copy.profiles_1d{1}.j_total

% Verify that we didn't change the original IDS
% ->     2.0000    2.5000    3.0000    3.5000    4.0000
disp(core_profiles_copy.profiles_1d{1}.j_total)
% ->     1.0000    1.2500    1.5000    1.7500    2.0000
disp(core_profiles.profiles_1d{1}.j_total)

Deallocate an IDS¶

If you no longer need an IDS, you can deallocate it so it releases the (memory) resources in use by the data. In MATLAB you can do this by clearing the IDS variable.

% Create an empty magnetics IDS
magnetics = ids_init('magnetics')

% Use the IDS ...

% We are done with the IDS, clear it
clear magnetics

Mandatory and recommended IDS attributes¶

Some attributes in an IDS are mandatory or recommended to always fill. Below list provides a short overview:

1. ids_properties/homogeneous_time [mandatory]: see Time coordinates and time handling.

2. ids_properties/comment [recommended]: a comment describing the content of this IDS.

3. ids_properties/provider [recommended]: name of the person in charge of producing this data.

4. ids_properties/creation_date [recommended]: date at which this data has been produced, recommended to use the ISO 8601 YYYY-MM-DD format.

Understanding the IDS structure¶

An IDS is a tree structure. You can think of it similar as a directory structure with files: the IDS is the root “directory”, and inside it you can find “subdirectories” and “files” with data.

We will use the general Computer Science terminology for tree structures and call these “files” and “directories” of our IDSs nodes. IDSs can have a limited number of different types of nodes:

1. Structure: think of these as the directories of your file system. Structures contain one or more child nodes (files and subdirectories). Child nodes can be of any node type again.

2. Array of structures: this is an array of structures (see previous point).

3. Data: this is a data element. Like files on your file system these nodes contain the actual data stored in the IDS.

Structure¶

Structure nodes in an IDS are a container for other nodes. In MATLAB they are implemented as a structure. You can address child nodes as structure fields, see the code sample below.

% Create an empty core_profiles IDS
core_profiles = ids_init('core_profiles')

% core_profiles/ids_properties is a structure, which has multiple child
% nodes. One of the child nodes is homogeneous time:
disp(core_profiles.ids_properties.homogeneous_time)
% Since we created an empty IDS, this will output '-999999999': the default
% value for integers.

Array of structures¶

Array of structure nodes in an IDS are one-dimensional arrays, containing structure nodes. In MATLAB they are implemented as a cell array. The default value (for example, when creating a new IDS) for these nodes is an empty cell array.

% Create an empty core_profiles IDS
core_profiles = ids_init('core_profiles')

% core_profiles/profiles_1d is an array of structures
disp(core_profiles.profiles_1d)  % -> <empty>
% It currently has no elements, so let's allocate one
core_profiles.profiles_1d = ids_allocate('core_profiles', 'profiles_1d', 1)
disp(core_profiles.profiles_1d) % -> {1x1 struct}

% Use cell array indexation to get a specific structure from the array,
% then we can address child nodes as usual (for example, the average ion
% temperature, which is an unallocated data array):
disp(core_profiles.profiles_1d{1}.t_i_average)  % -> <empty>

Resizing an array of structures¶

You can resize an array of structures with ids_allocate(). After calling this, the array of structures will have n elements.

% Create an empty interferometer IDS
interferometer = ids_init('interferometer')

% interferometer/channel is an array of structures, add some data
interferometer.channel = ids_allocate('interferometer', 'channel', 1)
disp(length(interferometer.channel))  % -> 1
interferometer.channel{1}.name = 'test'

% resize, this will destroy the data that we just stored
interferometer.channel = ids_allocate('interferometer', 'channel', 2)
disp(interferometer.channel{1}.name)  % -> <empty>
interferometer.channel{1}.name = 'test'
interferometer.channel{2}.name = 'test2'

% Resize, preserving existing data
interferometer.channel = [
    interferometer.channel;
    ids_allocate('interferometer', 'channel', 1)
]

disp(interferometer.channel{1}.name)  % -> test
disp(interferometer.channel{2}.name)  % -> test2
disp(interferometer.channel{3}.name)  % -> <empty>

Data¶

Data nodes in an IDS contain numerical or textual data. The data type and dimensions of a node are defined in the Data Dictionary.

% Create an empty core_profiles IDS
core_profiles = ids_init('core_profiles')

% core_profiles/time is a FLT_1D data node
% We can assign values to it:
core_profiles.time = [0.5, 1.0, 1.5]
disp(core_profiles.time) % ->     0.5000    1.0000    1.5000

Data types¶

The following data types exist:

• Textual data (char array)

• Whole numbers (int)

• Floating point numbers (double)

• Complex floating point numbers (double (with complex attribute))

Data nodes can be 0-dimensional, which means that the node accepts a single value of the specified type. Multi-dimensional data nodes also exist:

• Textual data: at most 1 dimension (cell array of char)

• Whole numbers: 1-3 dimensions (array of int)

• Floating point numbers: 1-6 dimensions (array of double)

• Complex floating point numbers: 1-6 dimensions (array of double (with complex attribute))

Default values¶

The default values for data fields (for example when creating an empty IDS) are indicated in the following table.

Time coordinates and time handling¶

Some quantities (and array of structures) are time dependent. In the Data Dictionary documentation this is indicated by a coordinate that refers to a time quantity.

This time-dependent coordinate is treated specially in the access layer, and it depends on the value of ids_properties/homogeneous_time. There are three valid values for this property:

1. IDS_TIME_MODE_HETEROGENEOUS (=0): time-dependent quantities in the IDS may have different time coordinates. The time coordinates are stored as indicated by the path in the documentation. This is known as heterogeneous time.

2. IDS_TIME_MODE_HOMOGENEOUS (=1): All time-dependent quantities in this IDS use the same time coordinate. This is known as homogeneous time. This time coordinate is located in the root of the IDS, for example core_profiles/time. The paths time paths indicated in the documentation are unused in this case.

3. IDS_TIME_MODE_INDEPENDENT (=2): The IDS stores no time-dependent data.

IDS validation¶

The IDSs you fill should be consistent. To help you in validating that, the Access Layer provides a validation method (ids_validate()) that executes the following checks.

If you call this method and your IDS fails validation, the Access Layer throws an error explaining the problem. See the following example:

% Open the database entry by providing an IMAS URI
data_entry = imas_open( ...
    'imas:mdsplus?user=public;shot=131024;run=41;database=ITER;version=3')

% Load an ids as example, here: the core_profiles IDS, occurrence 0
cp = ids_get(data_entry, 'core_profiles')

% Validate the coordinates of core_profiles
ids_validate('core_profiles', cp)

The Access Layer automatically validates an IDS every time you do a put or put_slice. To disable this feature, you must set the environment variable IMAS_AL_DISABLE_VALIDATE to 1.

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 IDS_TIME_MODE_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:

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.

   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_HETEROGENEOUS, 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 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.