imaspy 0.1.1

Pythonic wrappers for the IMAS Access Layer

IMASPy

IMASPy is (yet another) pure-python library to handle arbitrarily nested data structures. IMASPy is designed for, but not necessarily bound to, interacting with Interface Data Structures (IDSs) as defined by the Integrated Modelling & Analysis Suite (IMAS) Data Model.

It provides:

• An easy-to-install and easy-to-get started package by
  • Not requiring an IMAS installation
  • Not strictly requiring matching a Data Dictionary (DD) version
• An pythonic alternative to the IMAS Python High Level Interface (HLI)
• Checking of correctness on assign time, instead of database write time
• Dynamically created in-memory pre-filled data trees from DD XML specifications

A word of caution

Development of this package continues under ITER contract at the ITER bitbucket. If you are interested in this development, contact the IMAS team on the IMAS user slack or open a JIRA issue

Documentation

Documentation is autogenerated from the source using Sphinx and can be found at the gitlab pages.

Getting Started

Clone the repository on your local machine. To set up SSH keys for GitLab, look here: https://docs.gitlab.com/ee/ssh/

git clone [e-mail]:klimex/imaspy.git # Using SSH keys
git clone https://gitlab.com/klimex/imaspy.git # Using username/password

Install IMASPy in developer mode with all the optional components it can find:

cd imaspy
pip install --user -e .[all]

For now, let's assume you have a Data Dictionary specification available, and managed to compile the AL.

# Initialize an empty IDS
import imaspy as imas
idsdef_dir = <path to IDSDef.xml>
idsdef = os.path.join(idsdef_dir, 'IDSDef.xml')
shot = 1234
run_in = 0
imas_entry = imas.ids(shot, run_in, xml_path=idsdef, verbosity=2)

We end up with a IDSRoot instance that is pre-filled with all defaults and data structures defined in the given DD XML. We could've not given xml_path to create an empty IDSRoot. No interaction with any LL-AL has happened yet!

Create a PulseFile. This creates an empty PulseFile with the specified backend. This will overwrite pulsefiles with the same path. This does need an access layer, IMASPy does not provide one out of the box currently.

from imas_entry._libs.imasdef import *
input_user_or_path = <path to pulsefiles, for example your username>
input_database = <database, for example 'iter' >
imas_entry.create_env_backend(input_user_or_path, input_database, '3', MDSPLUS_BACKEND)

Now that the pulse file exists, put some data in our Python structure:

ids = imas_entry.equilibrium
ids.ids_properties.homogeneous_time = 'special' #Whoops! This crashes, wrong type!
ids.ids_properties.homogeneous_time = IDS_TIME_MODE_HETEROGENEOUS # This field needs to be filled for all valid IDSs
ids.time = [0.1, 0.2, 0.3]
ids.time += 2 # Let's offset this by 2

No database interaction has happened yet. We need to explicitly send it to the MDSPLUS pulsefile:

ids.put() # This removes the pulsefile, and rebuilds it with our in-memory structure!

And now we can interact with the regular IMAS tools, for example to plot the structures with IMASViz.

Prerequisites

IMASPy is a standalone python package with optional dependencies. All needed python packages can be found in requirements.txt, and should all be publicly available. A simple pip install should take care of everything.

Being IMAS DD compatible

To check IMAS DD compatible, one needs the IDS definition XML file. This file can usually be found at $IMAS_PREFIX/include/IDSDef.xml on your IMAS-enabled system. Otherwise, they can be build from source from the ITER IMAS Core Data Dictionary repository.

Interacting with IMAS AL

Interaction with the IMAS AL is provided by Cython and Python wrappers provided by the Python High Level Interface. As Cython code, it needs to be compiled on your local system. First make sure you can access the ITER IMAS Access Layer repository using SSH ssh://[e-mail]/imas/access-layer.git. A copy of this repository will be cloned into src during build.

Get the prerequisites:

pip install numpy cython gitpython

Install in verbose mode. After installing, you should have a ual_x_x_x directory in your root. If not, something went wrong. Be sure to browse the verbose log or open a ticket.

pip install --user -e .[all] -v

Where does IMASPy live in IMAS ecosystem?

IMASPy tries to fill a slightly different niche than existing tools. It aims to be an alternative to Python HLI instead of a wrapper. It tries to be dynamic instead of pre-generated. Is hopes to be extendable instead of wrappable.

A small, biased, and wildly incomplete of some common IMAS tools, and where they live with respect to IMASPy.

classDiagram
  MDSPLUS_DATABASE .. LL_AL : puts
  MDSPLUS_DATABASE .. LL_AL : gets
  MDSPLUS_DATABASE .. LL_HDC : puts
  MDSPLUS_DATABASE .. LL_HDC : gets
  IMAS DD <.. PythonHLI: build dep
  IMAS DD <-- IMASPy:  runtime dep
  LL_HDC <-- HDC_python_bindings : calls
  LL_AL <-- Cython_HLI : calls
  Python_helpers <-- IMASPy: calls
  HDC_python_bindings <.. IMASPy: Could call

  Cython_HLI <-- Python_helpers : calls
  Python_helpers <-- Python HLI: calls

  IMASDD <..  IMASviz_codegen: build dep
  IMASviz_codegen <..  IMASviz: build dep

  PythonHLI <-- OMAS: calls
  OMAS <-- OMFIT: calls
  OMFIT <-- IMASgo : calls

  PythonHLI <-- pyAL: calls
  PythonHLI <-- JINTRAC_WORKFLOWS : calls
  pyAL <-- HnCD_WORKFLOWS : calls
  PythonHLI <-- HnCD_WORKFLOWS : calls
  PythonHLI <-- IMASviz: calls

Contributing

IMASPy is open for contributions! Please open a fork and create a merge request or request developer access to one of the maintainers.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

Inspired and bootstrapped by existing tools, notably the IMAS Python HLI, IMAS Python workflows, and OMAS.