imas-data-dictionary 4.1.1
The Data Dictionary is the implementation of the Data Model of ITER's Integrated Modelling & Analysis Suite (IMAS)
Requires Python: >=3.8
Keywords: IMAS, Data Dictionary, IDS

# IMAS Data Dictionary

The Data Dictionary is the implementation of the Data Model of ITER's
Integrated Modelling & Analysis Suite (IMAS). It describes the
structuring and naming of data (as a set of Interface Data Structures
or IDSs) being used for both simulated and experimental data in a
machine agnostic manner.

[![PyPI][pypi-badge]][pypi-url]

[pypi-badge]: https://img.shields.io/pypi/v/imas-data-dictionary.svg
[pypi-url]: https://pypi.org/project/imas-data-dictionary/

## Installation

It's possible to install the Data Dictionary within a Python environment.

> Prerequisite : A Python interpreter is all you need

```sh
git clone git@github.com:iterorganization/IMAS-Data-Dictionary.git
cd IMAS-Data-Dictionary
pip install . [--user]
```

After the install, you will get a directory with the version/tag information
prefixed with `dd_` e.g. `dd_4.0.0`. It has an `include` directory with a few
XML files (`data_dictionary.xml` is the main source of information for the definition
of IDSs and `*_indentifier.xml` are listing common identifiers) and a `share`
directory with html documentation.

The package also installs the Data Dictionary XML files as package resources, making them accessible from Python code without needing to know their filesystem location.

### Accessing the Data Dictionary from Python

You can access the Data Dictionary directly from Python using the `importlib.resources` API:

```python
import importlib.resources
import xml.etree.ElementTree as ET

# Access the data_dictionary.xml file from the package resources
xml_path = importlib.resources.files("imas_data_dictionary.resources.schemas") / "data_dictionary.xml"

# Read the content
if xml_path.is_file():
    # Parse the XML content
    tree = ET.parse(xml_path)
    root = tree.getroot()

    # Now you can work with the ElementTree
    # For example, find all IDS elements:
    for ids in root.findall(".//IDS"):
        print(f"Found IDS: {ids.get('name')}")
```

Alternatively, use the provided `idsinfo` module for higher-level access:

```python
from imas_data_dictionary import idsinfo

# Create object of IDSInfo
obj_ids_info = idsinfo.IDSInfo()

# Get all IDS names
all_ids = obj_ids_info.get_ids_names()
print(all_ids)

# Get info about a specific IDS
info = obj_ids_info.get_ids_info("magnetics")
print(info)
```

### Documentation

The documentation is generated by Sphinx and is available [here](https://imas-data-dictionary.readthedocs.io/en/latest/). Note that for generating the `IDS Migration guide` section you will need `imas-python` installed as a prerequisite.

You can open the online documentation using the `dd_doc` command:

```bash
dd_doc
```

#### Legacy Local Documentation

You can also generate and install local HTML documentation with the following steps:

```bash
IMAS_BUILD_DOCS=1 pip install .
```

After installation, open the local legacy documentation using:

```bash
dd_doc --legacy
# or
dd_doc -l
```

This will open the locally installed HTML documentation in your default browser.

### `idsinfo` tool

The installation also provides a small utility script in Python which can be
used from the command line to obtain some information from the installed
Data Dictionary. Type `idsinfo -h` for more info on this tool's options.

## Collaboration

As it is generic and machine agnostic by design, the IMAS Data Model,
and by extension its implementation as the Data Dictionary, have the
potential to serve as a data standard for the fusion community. As
such, it benefits from the wide involvement of specialists and active
users and developers in the various areas being described. If you want
to contribute to the improvement of the Data Dictionary, either as a
developer, a specific system/area specialist or an occasional user
providing feedback, please see the [contributing guidelines](CONTRIBUTING.md).

## Legal

Copyright 2012-2025, ITER Organization, Route de Vinon-sur-Verdon, CS 90 046,
13067 St-Paul-lez-Durance Cedex, France.

This repository contains data schemas and software that are subject to different
licenses:

- The data schemas are licensed under the Creative Commons
  Attribution-Noderivatives 4.0 International License (CC-BY-ND 4.0) which permits
  use and distribution as long as appropriate credit is given to the original source,
  but does not permit adaptations, as the main goal of these schemas is to serve as
  a standard for the community.
  Details can be found in [LICENSE-CC-BY-ND](LICENSE-CC-BY-ND).

- The software is licensed under the LGPLv3 License which allows for extensive
  freedom in using, modifying, and distributing it, provided that the license terms
  are met.
  Details can be found in [LICENSE-LGPL](LICENSE-LGPL).