imas.ids_toplevel.IDSToplevel¶

class imas.ids_toplevel.IDSToplevel(parent: IDSFactory, structure_xml, lazy=False)¶

Bases: IDSStructure

This is any IDS Structure which has ids_properties as child node

At minimum, one should fill ids_properties/homogeneous_time IF a quantity is filled, the coordinates of that quantity must be filled as well

__init__(parent: IDSFactory, structure_xml, lazy=False)¶

Save backend_version and backend_xml and build translation layer.

Parameters:

parent: IDSFactory¶

Parent of self.

structure_xml¶

XML structure that defines this IDS toplevel.

lazy=False¶

Whether this toplevel is used for a lazy-loaded get() or get_slice()

Methods

__init__(parent, structure_xml[, lazy])	Save backend_version and backend_xml and build translation layer.
default_serializer_protocol()	Return the default serializer protocol.
deleteData([occurrence, db_entry])	Delete AL backend storage data.
deserialize(data)	Deserialize the data buffer into this IDS.
get([occurrence, db_entry])	Get data from AL backend storage format.
getSlice(time_requested, interpolation_method)	Get a slice from the backend.
iter_nonempty_(*[, accept_lazy])	Iterate over all child nodes with non-default value.
put([occurrence, db_entry])	Put this IDS to the backend.
putSlice([occurrence, db_entry])	Put a single slice into the backend.
serialize([protocol])	Serialize this IDS to a data buffer.
validate()	Validate the contents of this IDS.

Attributes

has_value	True if any of the children has a non-default value
metadata	Metadata of this IDS node

static default_serializer_protocol()¶

Return the default serializer protocol.

deleteData(occurrence: int = 0, db_entry: DBEntry | None = None) → None¶

Delete AL backend storage data.

This method exists for API compatibility with the IMAS python HLI. See DBEntry.delete_data.

deserialize(data: bytes) → None¶

Deserialize the data buffer into this IDS.

See serialize() for an example.

Parameters:

data: bytes¶

binary data created by serializing an IDS.

get(occurrence: int = 0, db_entry: DBEntry | None = None) → None¶

Get data from AL backend storage format.

This method exists for API compatibility with the IMAS python HLI. See DBEntry.get.

getSlice(time_requested: float, interpolation_method: int, occurrence: int = 0, db_entry: DBEntry | None = None) → None¶

Get a slice from the backend.

This method exists for API compatibility with the IMAS python HLI. See DBEntry.get_slice.

property has_value : bool¶

True if any of the children has a non-default value

iter_nonempty_(*, accept_lazy=False) → Generator[IDSBase, None, None]¶

Iterate over all child nodes with non-default value.

Note

The name ends with an underscore so it won’t clash with IDS child names.

Caution

This method works differently for lazy-loaded IDSs.

By default, an error is raised when calling this method for lazy loaded IDSs. You may set the keyword argument accept_lazy to True to iterate over all loaded child nodes with a non-default value. See below example for lazy-loaded IDSs.

Examples

iter_nonempty_ for fully loaded IDSs¶

>>> import imas.training
>>> entry = imas.training.get_training_db_entry()
>>> cp = entry.get("core_profiles")
>>> list(cp.iter_nonempty_())
[
    <IDSStructure (IDS:core_profiles, ids_properties)>,
    <IDSStructArray (IDS:core_profiles, profiles_1d with 3 items)>,
    <IDSNumericArray (IDS:core_profiles, time, FLT_1D)>
    numpy.ndarray([  3.98722186, 432.93759781, 792.        ])
]

iter_nonempty_ for lazy-loaded IDSs¶

>>> import imas.training
>>> entry = imas.training.get_training_db_entry()
>>> cp = entry.get("core_profiles", lazy=True)
>>> list(cp.iter_nonempty_())
RuntimeError: Iterating over non-empty nodes of a lazy loaded IDS will
skip nodes that are not loaded. Set accept_lazy=True to continue.
See the documentation for more information: [...]
>>> list(cp.iter_nonempty_(accept_lazy=True))
[]
>>> # An empty list because nothing is loaded. Load `time`:
>>> cp.time
<IDSNumericArray (IDS:core_profiles, time, FLT_1D)>
numpy.ndarray([  3.98722186, 432.93759781, 792.        ])
>>> list(cp.iter_nonempty_(accept_lazy=True))
[<IDSNumericArray (IDS:core_profiles, time, FLT_1D)>
numpy.ndarray([  3.98722186, 432.93759781, 792.        ])]

Keyword Arguments:

accept_lazy=False¶

Accept that this method will only yield loaded nodes of a lazy-loaded IDS. Non-empty nodes that have not been loaded from the backend are not iterated over. See detailed explanation above.

metadata : IDSMetadata¶

Metadata of this IDS node

put(occurrence: int = 0, db_entry: DBEntry | None = None) → None¶

Put this IDS to the backend.

This method exists for API compatibility with the IMAS python HLI. See DBEntry.put.

putSlice(occurrence: int = 0, db_entry: DBEntry | None = None) → None¶

Put a single slice into the backend.

This method exists for API compatibility with the IMAS python HLI. See DBEntry.put_slice.

serialize(protocol=None) → bytes¶

Serialize this IDS to a data buffer.

The data buffer can be deserialized from any Access Layer High-Level Interface that supports this.

Example:

Parameters:

protocol=None¶

Which serialization protocol to use. Uses DEFAULT_SERIALIZER_PROTOCOL when none specified. One of:

• ASCII_SERIALIZER_PROTOCOL

• FLEXBUFFERS_SERIALIZER_PROTOCOL

• DEFAULT_SERIALIZER_PROTOCOL

The flexbuffers serializer protocol is only available when using imas_core >= 5.3. It’s the default protocol when it is available.

Returns:

Data buffer that can be deserialized using deserialize().

validate()¶

Validate the contents of this IDS.

The following sanity checks are executed on this IDS:

• The IDS must have a valid time mode (ids_properties.homogeneous_time)

• For all non-empty quantities with coordinates:

  • If coordinates have an exact size (e.g. coordinate1 = 1…3), the size in that dimension must match this.

  • If coordinates refer to other elements (e.g. coordinate1 = time), the size in that dimension must be the same as the size of the referred quantity.

    Note that time is a special coordinate:

    • When using homogeneous time, the time coordinate is the /time node.

    • When using heterogeneous time, the time coordinate is the one specified by the coordinate. For dynamic Array of Structures, the time element is a FLT_0D inside the AoS (see profiles_1d in the core_profiles IDS). In such cases the time element must be set.

    • When using independent time mode, no time-dependent quantities may be set.

  • If a “same_as” coordinate is specified (e.g. coordinate2_same_as = r), the size in that dimension must be the same as the size in that dimension of the referred quantity.

If any check fails, a ValidationError is raised that describes the problem.

Example

>>> core_profiles = imas.IDSFactory().core_profiles()
>>> core_profiles.validate()  # Did not set homogeneous_time
[...]
imas.exception.ValidationError: Invalid value for ids_properties/homogeneous_time: IDSPrimitive("/core_profiles/ids_properties/homogeneous_time", -999999999)
>>> core_profiles.ids_properties.homogeneous_time = imas.ids_defs.IDS_TIME_MODE_HOMOGENEOUS
>>> core_profiles.validate()  # No error: IDS is valid
>>> core_profiles.profiles_1d.resize(1)
>>> core_profiles.validate()
[...]
imas.exception.CoordinateError: Dimension 1 of element profiles_1d has incorrect size 1. Expected size is 0 (size of coordinate time).
>>> core_profiles.time = [1]
>>> core_profiles.validate()  # No error: IDS is valid