IDS API¶

public class ids_type¶

public static ids_type get(int expIdx, String idsFullName)¶

Read the contents of the an IDS into memory.

This method fetches the IDS in its entirety, with all time slices it may contain. See getSlice for reading a specific time slice.

Empty fields within the IDS in the Data Entry are returned with the default values indicated in Default values.

Parameters:

• expIdx (int) – Data entry context created with imas.open, imas.openEnv or imas.createEnv

• idsFullName (String) – name of the ids with optional occurrence number, e.g. "core_profiles" (for occurrence 0), "core_profiles/1" (for occurrence 1)

Returns:

The loaded IDS

Example:

// Import the Access Layer
import imasjava.imas;
import imasjava.wrapper.LowLevel;

public class load_ids {
    public static void main(String[] args) throws Exception {
        // Open the database entry by providing an IMAS URI
        int data_entry = imas.open(
            "imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3",
            LowLevel.OPEN_PULSE);

        // Load the core_profiles IDS, occurrence 0
        imas.core_profiles cp = imas.core_profiles.get(
            data_entry, "core_profiles");

        // Load the core_profiles IDS, occurrence 1
        imas.core_profiles cp1 = imas.core_profiles.get(
            data_entry, "core_profiles/1");
    }
}

public static ids_type getSample(int expIdx, String idsFullName, double tmin, double tmax, double[] dtime, int interpolMode)¶

Read the contents of an IDS over a specific time range into memory.

This method fetches an IDS with all time slices in a time range between tmin and tmax.

1. In case of no interpolation in the time range, interpolMode must be set to 0 and dtime = {}.

   This mode returns an IDS object with all constant/static data filled. The dynamic data is retrieved for the provided time range [tmin, tmax].

2. The method can interpolate time slices in the time range, if interpolMode is not set to 0 and dtime = {step} (double array of size equals 1) where ‘step’ is the constant time between two slices.

   This mode will generate an IDS with a homogeneous time vector [tmin, tmin + dtime, tmin + 2*dtime, ... up to tmax. The chosen interpolation method will have no effect on the time vector, but may have an impact on the other dynamic values. The returned IDS always has ids_properties.homogeneous_time = 1.

3. Interpolation of dynamic data on an explicit time base. This method is selected when dtime and interpolMode are provided. dtime must be a double[] of size larger than 1.

   This mode will generate an IDS with a homogeneous time vector equal to dtime. tmin and tmax are ignored in this mode. The chosen interpolation method will have no effect on the time vector, but may have an impact on the other dynamic values. The returned IDS always has ids_properties.homogeneous_time = 1.

Empty fields within the IDS in the Data Entry are returned with the default values indicated in Default values.

Parameters:

• expIdx (int) – Data entry context created with imas.open, imas.openEnv or imas.createEnv

• idsFullName (String) – name of the ids with optional occurrence number, e.g. "core_profiles" (for occurrence 0), "core_profiles/1" (for occurrence 1)

• tmin (double) – Lower bound of the requested time range

• tmax (double) – Upper bound of the requested time range, must be larger than or equal to tmin

• dtime (double[]) – Interval to use when interpolating, must be a std::vector<double> containing an explicit time base to interpolate.

• interpolMode –

  Interpolation method to use. Available options: - :const: CLOSEST_INTERP - :const: PREVIOUS_INTERP - :const: LINEAR_INTERP

  returns:

  The loaded IDS.

Example:

// Import the Access Layer
import imasjava.imas;
import imasjava.wrapper.LowLevel;

public class example_getSample_ids {
    public static void main(String[] args) throws Exception {
        // Open the database entry by providing an IMAS URI
        int data_entry = imas.open(
            "imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3",
            LowLevel.OPEN_PULSE);

        // Load the core_profiles IDS, occurrence 0
        double tmin = 3.0;
        double tmax = 8.0;

        double[] dtime = {};

        imas.core_profiles cp = imas.core_profiles.getSample(data_entry, "core_profiles", tmin, tmax, dtime, 0);

        System.out.println("Size of time range:" + cp.time.getDim());

        double[] dtime1 = {0.2};

        imas.core_profiles cp1 = imas.core_profiles.getSample(data_entry, "core_profiles", tmin, tmax, dtime1, 1);

        System.out.println("Size of time range:" + cp1.time.getDim());

        double[] dtime2 = {2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 6.0};

        imas.core_profiles cp2 = imas.core_profiles.getSample(data_entry, "core_profiles", tmin, tmax, dtime2, 2);

         System.out.println("Size of time range:" + cp2.time.getDim());
    }
}

public boolean isDefined()¶

Checks whether IDS was initialized or not.

This method returns true in case ids_properties field inside IDS is initialized and homogenous_time is set to either 0, or 1, or 2

Returns:

true in case IDS is already initialized, false otherwise

Example:

import java.io.*;
import imasjava.*;

class TestCoreProfilesEmpty {
    public static void main(String args[]) {

        double[] time = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0};

        // Get username
        String userName = System.getenv("USER");
        if (userName == null) {
            System.out.println("PANIC: $USER not found! Exiting...");
            System.exit(1);
        }

        // Get empty IDS
        try {
            int idx = imas.createEnv(13, 1, userName, "test", "3");

            imas.core_profiles ids = imas.core_profiles.get(idx, "core_profiles");
            System.out.println("Is defined: " + ids.isDefined());

            imas.close(idx);
        } catch (Exception exc) {
            System.out.println("Error: " + exc);
        }

        // Store IDS with a basic data, get it from the pulse file, and check
        // whether it is empty
        try {
            int idx = imas.createEnv(13, 1, userName, "test", "3");

            imas.core_profiles ids = new imas.core_profiles();

            ids.ids_properties.homogeneous_time = 1;
            ids.ids_properties.comment = "This is a test ids. User: " + userName;
            ids.time = new Vect1DDouble(time);

            ids.put(idx, "core_profiles", ids);
            imas.close(idx);

            idx = imas.openEnv(13, 1, userName, "test", "3");
            ids = imas.core_profiles.get(idx, "core_profiles");
            System.out.println("Is defined: " + ids.isDefined());

            imas.close(idx);

        } catch (Exception exc) {
            System.out.println("Error: " + exc);
        }
    }
}

public static ids_type getSlice(int pulseCtx, String idsFullName, double time, int interpolMode)¶

Read a single time slice from an IDS in this Database Entry.

This method fetches the IDS object with all constant/static data filled. The dynamic data is interpolated on the requested time slice. This means that the size of the time dimension in the returned data is 1.

Parameters:

• pulseCtx (int) – Data entry context created with imas.open, imas.openEnv or imas.createEnv

• idsFullName (String) – name of the ids with optional occurrence number, e.g. "core_profiles" (for occurrence 0), "core_profiles/1" (for occurrence 1)

• time (double) – Requested time slice

• interpolMode (int) – Interpolation method to use, see Load a single time slice of an IDS

Returns:

The loaded IDS

Example:

// Import the Access Layer
import imasjava.imas;
import imasjava.wrapper.LowLevel;

public class load_ids_slice {
    public static void main(String[] args) throws Exception {
        // Open the database entry by providing an IMAS URI
        int data_entry = imas.open(
            "imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3",
            LowLevel.OPEN_PULSE);

        // Retrieve the time slice just before t=370 of the core_profiles IDS
        imas.core_profiles cp = imas.core_profiles.getSlice(
            data_entry, "core_profiles", 370, LowLevel.PREVIOUS_INTERP);
    }
}

public static void put(int pulseCtx, String idsFullName, ids_type ids)¶

Write the contents of an IDS to the Database Entry.

The IDS is written entirely, with all time slices it may contain.

The IDS object can have none or many empty fields, empty fields are ignored and remain empty in the data entry. Some fields are required to be filled before calling this method, see Mandatory and recommended IDS attributes.

Caution

The put method deletes any previously existing data within the target IDS occurrence in the Database Entry.

Parameters:

• pulseCtx (int) – Data entry context created with imas.open, imas.openEnv or imas.createEnv

• idsFullName (String) – name of the ids with optional occurrence number, e.g. "core_profiles" (for occurrence 0), "core_profiles/1" (for occurrence 1)

• ids (ids_type) – IDS object to put

Example:

// Import the Access Layer
import imasjava.imas;
import imasjava.wrapper.LowLevel;

public class store_ids {
    public static void main(String[] args) throws Exception {
        // Create the database entry by providing an IMAS URI
        int data_entry = imas.open(
            "imas:hdf5?path=my-data", LowLevel.FORCE_CREATE_PULSE);

        // Create an empty pf_active IDS
        imas.pf_active pf_active = new imas.pf_active();
        // Set the mandatory ids_properties.homogeneous_time field
        pf_active.ids_properties.homogeneous_time = LowLevel.IDS_TIME_MODE_HOMOGENEOUS;
        // Continue filling the pf_active IDS here
        // ...

        // Store the pf_active IDS
        pf_active.put(data_entry, "pf_active", pf_active);

        // Alternatively, store the pf_active IDS as occurrence 1
        pf_active.put(data_entry, "pf_active/1", pf_active);
    }
}

public static void putSlice(int pulseCtx, String idsFullName, ids_type ids)¶

Append a time slice of the provided IDS to the Database Entry.

Time slices must be appended in strictly increasing time order, since the Access Layer is not reordering time arrays. Doing otherwise will result in non-monotonic time arrays, which will create confusion and make subsequent getSlice commands to fail.

Although being put progressively time slice by time slice, the final IDS must be compliant with the data dictionary. A typical error when constructing IDS variables time slice by time slice is to change the size of the IDS fields during the time loop, which is not allowed but for the children of an array of structure which has time as its coordinate.

The putSlice command is appending data, so does not modify previously existing data within the target IDS occurrence in the Data Entry.

It is possible possible to append several time slices to a node of the IDS in one putSlice call, however the user must ensure that the size of the time dimension of the node remains consistent with the size of its timebase.

Parameters:

• pulseCtx (int) – Data entry context created with imas.open, imas.openEnv or imas.createEnv

• idsFullName (String) – name of the ids with optional occurrence number, e.g. "core_profiles" (for occurrence 0), "core_profiles/1" (for occurrence 1)

• ids (ids_type) – IDS object to put

Example:

// Import the Access Layer
import imasjava.*;
import imasjava.wrapper.LowLevel;

public class store_ids_slice {
    public static void main(String[] args) throws Exception {
        // Create the database entry by providing an IMAS URI
        int data_entry = imas.open(
            "imas:hdf5?path=my-data", LowLevel.FORCE_CREATE_PULSE);

        // Create an empty core_profiles IDS
        imas.core_profiles core_profiles = new imas.core_profiles();
        // Set the mandatory ids_properties.homogeneous_time field
        core_profiles.ids_properties.homogeneous_time = LowLevel.IDS_TIME_MODE_HOMOGENEOUS;
        // Continue filling the core_profiles IDS with static values here
        // ...

        core_profiles.time = new Vect1DDouble(1);

        double t = 0.0;
        double t_stop = 60.0;
        double dt = 0.1;

        while (t < t_stop) {
            core_profiles.time.setElementAt(0, t);
            // Fill your time-dependent data in the core_profiles IDS here
            // ...

            // Append the current time slice to the data stored on disk
            core_profiles.putSlice(data_entry, "core_profiles", core_profiles);

            t += dt;
        }
    }
}

public byte[] serialize()¶

public byte[] serialize(int protocol)¶

Serialize the contents of this IDS into binary data.

There are currently two different serialization protocols. The ASCII protocol serializes the data though the ASCII backend. This is a simpler human readable protocol, but it’s also less efficient than the (newer) Flexbuffers protocol. The latter is the default and should be preferred.

The ID of the used serializer protocol is kept in the header of the serialized buffer, such that specifying the protocol is not necessary when deserializing.

Parameters:

• protocol (int) –

  Which serialization protocol to use. Available options are:

  • ASCII_SERIALIZER_PROTOCOL

  • FLEXBUFFERS_SERIALIZER_PROTOCOL

  • DEFAULT_SERIALIZER_PROTOCOL

Returns:

Binary representation of this IDS.

Example:

imas.ids_pf_active ids = new imas.ids_pf_active();
// populate the IDS
// ...
byte[] data = ids.serialize();

// move the binary data around, for example to another process using
// memory communication, then deserialize
imas.ids_pf_active ids2 = new imas.ids_pf_active();
ids2.deserialize(data);

public void deserialize(byte[] data)¶

Deserialize the provided binary data into an IDS.

Parameters:

• data (byte[]) – data representing a serialized IDS.

Example:

See serialize.

public void validate()¶

Validate the IDS coordinate consistency. The method should always be tested for exception/errors while it is being executed. A ValidationException can be raised if a coordinate inconsistency is found. Nothing occurs if the data are valids.

Example:

// Import the Access Layer
import imasjava.*;
import imasjava.wrapper.LowLevel;

public class validate_ids {
    public static void main(String[] args) {

        // Create an empty equilibrium IDS
        imas.equilibrium equilibrium = new imas.equilibrium();



        // |---> equilibrium is empty, -> raise of the ValidationException:
        // "ids_properties.homogeneous_time wrong value (-999999999)"
        try {
            equilibrium.validate()
   	}
	catch (ValidationException e) {
            System.err.println("Validation exception:");
            System.err.println(e.getMessage());
        } 



        // Minimal equilibrium ids (homogeneous_time = 0 + time not empty)
        equilibrium.ids_properties.homogeneous_time = 0; // (0 -> IDS_TIME_MODE_HOMOGENEOUS)
        equilibrium.time= new Vect1DDouble(20);
        try {
            equilibrium.validate()
        }
        catch (ValidationException e) { // not occured here
            System.err.println("Validation exception:");
            System.err.println(e.getMessage());
        }

    }
}