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 creating a new class object for that IDS, for example IdsNs::IDS::core_profiles() creates an empty core_profiles IDS. This initializes all items in the IDS to their Default values.

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty core_profiles IDS
    IdsNs::IDS::core_profiles empty_core_profiles;
    // This outputs -999999999 (default INT_0D value)
    std::cout << empty_core_profiles.ids_properties.homogeneous_time << std::endl;

    // Create an empty equilibrium IDS
    IdsNs::IDS::equilibrium empty_equilibrium;
    // This outputs 0 (default size of array of structure)
    std::cout << empty_equilibrium.time_slice.size() << std::endl;

    return 0;
}

Create a copy of an IDS¶

You can create a copy of another IDS by putting it to the memory backend and getting it again.

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty core_profiles IDS
    IdsNs::IDS::core_profiles core_profiles;
    core_profiles.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    core_profiles.time.resize(2);
    core_profiles.profiles_1d.resize(2);
    for (int i = 0; i < 2; i++) {
        core_profiles.time(i) = i + 1.0;
        core_profiles.profiles_1d(i).grid.rho_tor_norm.resize(5);
        core_profiles.profiles_1d(i).j_total.resize(5);
        for (int j = 0; j < 5; j++) {
            core_profiles.profiles_1d(i).grid.rho_tor_norm(j) = 0.25 * j;
            core_profiles.profiles_1d(i).j_total(j) = 0.25 * j + i;
        }
    }

    // Create a new IDS
    IdsNs::IDS::core_profiles core_profiles_copy;
    // Create memory backend Data Entry and associate the core_profiles IDSs
    IdsNs::IDS ids;
    ids.open("imas:memory?path=/", FORCE_CREATE_PULSE);
    core_profiles.setPulseCtx(ids.getPulseCtx());
    core_profiles_copy.setPulseCtx(ids.getPulseCtx());
    // Copy the IDS through the memory backend
    core_profiles.put();
    core_profiles_copy.get();

    // Adjust some data
    core_profiles_copy.profiles_1d(0).j_total *= 2.0;

    // Verify that we didn't change the original IDS
    // -> [ 0 0.5 1 1.5 2 ]
    std::cout << core_profiles_copy.profiles_1d(0).j_total << std::endl;
    // -> [ 0 0.25 0.5 0.75 1 ]
    std::cout << core_profiles.profiles_1d(0).j_total << std::endl;

    return 0;
}

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 C++ an IDS is automatically deallocated when it falls outside scope.

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    { // Enter a new scope
        // Create an empty magnetics IDS
        IdsNs::IDS::magnetics magnetics;
        // Use the IDS ...

        // We are done with the IDS, it will be cleaned up when exiting the
        // scope where it is declared:
    }
    // The magnetics IDS is cleaned up now

    return 0;
}

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 C++ they are implemented as a class. You can address child nodes as data members, see the code sample below.

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty core_profiles IDS
    IdsNs::IDS::core_profiles core_profiles;
    // core_profiles/ids_properties is a structure, which has multiple child
    // nodes. One of the child nodes is homogeneous time:
    std::cout << core_profiles.ids_properties.homogeneous_time << std::endl;
    // Since we created an empty IDS, this will output "-999999999": the default
    // value for integers.

    return 0;
}

Array of structures¶

Array of structure nodes in an IDS are one-dimensional arrays, containing structure nodes. In C++ they are implemented as a a Blitz++ Array of structures. The default value (for example, when creating a new IDS) for these nodes is an empty Blitz++ Array (node.size() == 0).

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty core_profiles IDS
    IdsNs::IDS::core_profiles core_profiles;
    // core_profiles/profiles_1d is an array of structures
    std::cout << core_profiles.profiles_1d.size() << std::endl;  // -> 0
    // It currently has no elements, so let's add one
    core_profiles.profiles_1d.resize(1);
    std::cout << core_profiles.profiles_1d.size() << std::endl;  // -> 1
    // Use parentheses 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 empty data array):
    std::cout << core_profiles.profiles_1d(0).t_i_average << std::endl;
    // -> (0,-1)
    //    [ ]

    return 0;
}

Resizing an array of structures¶

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

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty interferometer IDS
    IdsNs::IDS::interferometer interferometer;

    // interferometer/channel is an array of structures, add some data
    interferometer.channel.resize(1);
    std::cout << interferometer.channel.size() << std::endl; // -> 1
    interferometer.channel(0).name = "test";

    // Resize again. This will destroy the data that we just stored!
    interferometer.channel.resize(2);
    std::cout << interferometer.channel(0).name << std::endl; // -> <empty>
    interferometer.channel(0).name = "test";
    interferometer.channel(1).name = "test2";

    // Resize, preserving existing data
    interferometer.channel.resizeAndPreserve(3);
    std::cout << interferometer.channel(0).name << std::endl; // -> test
    std::cout << interferometer.channel(1).name << std::endl; // -> test2
    std::cout << interferometer.channel(2).name << std::endl; // -> <empty>

    return 0;
}

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.

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    // Create an empty core_profiles IDS
    IdsNs::IDS::core_profiles core_profiles;
    // core_profiles/time is a FLT_1D data node:
    std::cout << core_profiles.time << std::endl;
    // -> (0,-1)
    //    [ ]
    // We can assign values to it:
    core_profiles.time.resize(3);
    core_profiles.time = 0.5, 1.0, 1.5;
    std::cout << core_profiles.time << std::endl;
    // -> (0,2)
    //    [ 0.5 1 1.5 ]

    return 0;
}

Data types¶

The following data types exist:

• Textual data (std::string)

• Whole numbers (int)

• Floating point numbers (double)

• Complex floating point numbers (std::complex<double>)

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 (1D Blitz++ Array of std::string)

• Whole numbers: 1-3 dimensions (N-dimensional Blitz++ Array of int)

• Floating point numbers: 1-6 dimensions (N-dimensional Blitz++ Array of double)

• Complex floating point numbers: 1-6 dimensions (N-dimensional Blitz++ Array of std::complex<double>)

Default values¶

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

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 (not implemented yet for C++) 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:

// Include the Access Layer
#include "ALClasses.h"
#include <iostream>


int main(int argc, char *argv[]) {
    { // Enter a new scope
        // Create an empty magnetics IDS
        IdsNs::IDS::magnetics magnetics;
        // Fill the IDS ...

        try
        {
            magnetics.validate();
        }
        catch (IdsNs::ValidationException ve)
        {
            std::cout << ve.what() << std::endl;
        }
    }

    return 0;
}

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.

Blitz++¶

Blitz++ is a multi-dimensional array library for C++. The Access Layer uses Blitz++ Arrays for all dimensional nodes (Array of structures and Data nodes of 1 or more dimensions).

See the Blitz++ documentation for the (API) documentation for Blitz++ Array.