IDS API

ids_get()

out = ids_get(expIdx, IDSpath[, occurence])

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 ids_get_slice 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 – Data entry context created with imas_open_uri, imas_open_env, imas_open_env_backend, imas_create_env or imas_create_env_backend.

  • IDSpath – Name of the IDS to retrieve, e.g. ‘core_profiles’.

  • occurence – Which occurrence of the IDS to read. Defaults to 0.

Returns:

The loaded IDS.

ids_get_slice()

out = ids_get_slice(expIdx, IDSpath[, occurence], time, interp)

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:

  • expIdx – Data entry context created with imas_open_uri, imas_open_env, imas_open_env_backend, imas_create_env or imas_create_env_backend.

  • IDSpath – Name of the IDS to retrieve, e.g. ‘core_profiles’.

  • occurence – Which occurrence of the IDS to read. Defaults to 0.

  • time – Requested time slice.

  • interp – interpolation method. Allowed values are: CLOSEST_SAMPLE = 1, PREVIOUS_SAMPLE = 2 or INTERPOLATION = 3

Returns:

The loaded IDS.

ids_get_sample()

out = ids_get_sample(expIdx, IDSpath[, occurence], tmin, tmax, dtime, interp)

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, interp 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 interp is not set to 0 and dtime = [step] (double list 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 interp are provided. dtime must be a double list 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 default values.

Parameters:

  • expIdx – Data entry context created with imas_open_uri, imas_open_env, imas_open_env_backend, imas_create_env or imas_create_env_backend.

  • IDSpath – Name of the IDS to retrieve, e.g. ‘core_profiles’.

  • occurence – Which occurrence of the IDS to read. Defaults to 0.

  • tmin – Lower bound of the requested time range

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

  • dtime – Interval to use when interpolating, must be a list containing an explicit time base to interpolate.

  • interp – interpolation method. Allowed values are: CLOSEST_SAMPLE = 1, PREVIOUS_SAMPLE = 2 or INTERPOLATION = 3

Returns:

The loaded IDS.

ids_put()

ids_put(expIdx, IDSpath[, occurence], IDS)

Write the contents of an IDS into this 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 Default values.

Caution

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

Parameters:

  • expIdx – Data entry context created with imas_open_uri, imas_open_env, imas_open_env_backend, imas_create_env or imas_create_env_backend.

  • IDSpath – Name of the IDS to store, e.g. ‘core_profiles’.

  • occurence – Which occurrence of the IDS to read. Defaults to 0.

  • IDS – The IDS to store.

ids_put_slice()

ids_put_slice(expIdx, IDSpath[, occurence], 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 get_slice() 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 put_slice() 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 put_slice() 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:

  • expIdx – Data entry context created with imas_open_uri, imas_open_env, imas_open_env_backend, imas_create_env or imas_create_env_backend.

  • IDSpath – Name of the IDS to store, e.g. ‘core_profiles’.

  • occurence – Which occurrence of the IDS to read. Defaults to 0.

  • IDS – The IDS to store.

imas_serialize()

data = imas_serialize(ids, ids_name[, 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:

  • ids – IDS to serialize.

  • ids_name – Name of the ids.

  • protocol – Protocol type (default: DEFAULT_SERIALIZER_PROTOCOL)

Example

ids = ids_init('pf_active')
% populate the IDS
% ...
data = imas_serialize(ids, 'pf_active')

% move the binary data around, for example to another process using
% memory communication, then deserialize
pf_active2 = imas_deserialize(data, 'pf_active')
imas_deserialize()

ids = imas_deserialize(data, ids_name)

Deserialize the provided binary data into an IDS.

Parameters:

  • data – serialized data

  • ids_name – name of the ids

Returns:

Deserialized IDS

ids_init()

ids = ids_init(IDSname)

Generate an IDS of specified type with default field values.

Parameters:

IDSname – name of the IDS to generate.

Returns:

Empty IDS of the requested type.

NOTE: The array of structures in the resulting IDS will be empty. This is not as in ids_gen where they are all of size 1. Use ids_allocate to fill the array of structures.

See also: ids_allocate

ids_allocate()

ids_allocate(IDSname, AOSpath, size)

Allocate the desired array of structure to the requested size.

Parameters:

  • IDSname – The name of the IDS to modify.

  • AOSpath – Path to the desired array of structure in the IDS (‘/’ separated following DD convention)

  • size – Desired size.

Example

eq = ids_init('equilibrium');
eq.time_slice = ids_allocate('equilibrium','time_slice',5);
eq.time_slice{1}.profiles_2d = ...
    ids_allocate('equilibrium','time_slice/profiles_2d',1);

See also`` : ids_init``

ids_isdefined()

is_defined = ids_isdefined(ids)

Verifies if given IDS is ‘defined’ by checking if its field ids_properties.homogeneous_time is set to a valid value

Parameters:

ids – IDS to check.

Example

magnetics_ids = ids_gen('magnetics')
is_defined = ids_isdefined(magnetics_ids) %false
% set the ids_properties.homogeneous_time field
magnetics_ids.ids_properties.homogeneous_time = 1
is_defined = ids_isdefined(magnetics_ids) %true
ids_validate()

ids_validate(IDSname, IdsData)

Read the contents of the IDS and validate the consistency.

This method validate the IDS in its entirety. It can raise an error if the data are not consistent.

Parameters:

  • IDSname – Name of the IDS to validate, e.g. ‘core_profiles’.

  • IdsData – IDS structure data

Returns:

Nothing.