imas.ids_convert.convert_ids¶

imas.ids_convert.convert_ids(toplevel: IDSToplevel, version: str | None, *, deepcopy: bool = False, provenance_origin_uri: str = '', xml_path: str | None = None, factory: IDSFactory | None = None, target: IDSToplevel | None = None) → IDSToplevel¶

Convert an IDS to the specified data dictionary version.

Newer data dictionary versions may introduce non-backwards-compatible (NBC) changes. For example, the global_quantities.power_from_plasma quantity in the wall IDS was renamed in DD version 3.31.0 to global_quantities.power_incident. When converting from a version older than 3.31.0 to a version that is newer than that, this method will migrate the data.

By default, this method performs a shallow copy of numerical data. All multi-dimensional numpy arrays from the returned IDS share their data with the original IDS. When performing in-place operations on numpy arrays, the data will be changed in both IDSs! If this is not desired, you may set the deepcopy keyword argument to True.

See also

Conversion of IDSs between DD versions.

Parameters:

toplevel: IDSToplevel¶

The IDS element to convert.

version: str | None¶

The data dictionary version to convert to, for example “3.38.0”. Must be None when using xml_path or factory.

Keyword Arguments:

deepcopy: bool = False¶

When True, performs a deep copy of all data. When False (default), numpy arrays are not copied and the converted IDS shares the same underlying data buffers.

provenance_origin_uri: str = ''¶

When nonempty, add an entry in the provenance data in ids_properties to indicate that this IDS has been converted, and it was originally stored at the given uri.

xml_path: str | None = None¶

Path to a data dictionary XML file that should be used instead of the released data dictionary version specified by version.

factory: IDSFactory | None = None¶

Existing IDSFactory to use for as target version.

target: IDSToplevel | None = None¶

Use this IDSToplevel as target toplevel instead of creating one.