1. High Level Interfaces and their API (Application Programming Interface)

There are currently 5 High Level Interfaces (HLIs) available from the following programming languages:

• Fortran
• C++
• Java
• Python
• Matlab

Only Python and Matlab provide user interactive session for accessing IMAS data.

The HLI API covers all available Access Layer features:

• creating a so-called new IMAS Data Entry
• opening an existing IMAS Data Entry
• reading data of an IDS from an existing Data Entry
• writing data from an IDS to a Data Entry
• deleting an IDS from an existing Data Entry
• closing a Data Entry

A Data Entry is an IMAS concept for designating a pulse experiment  with given shot and run number located in some database (see below).

Methods exposed by High Level Interfaces:

• —Operations on data base entry
  • —CREATE
  • —OPEN
  • —DELETE
  • —CLOSE
• —Operations on IDSes  - AL operates at the IDS level (with some exceptions) providing only methods for “atomic” operations such as:
  • —PUT
  • —GET
  • —PUT_SLICE
  • —GET_SLICE

In this tutorial, we will illustrate the use of the HLI API using 2 use-cases:

• in the first use-case 1, we will create a new pulse file and we will store a new 'magnetics' IDS and populate this IDS with some dynamic (1D) data read from an existing WEST pulse file
• in a second use-case 2, we will create a 'camera_visible' IDS and we will append new frames to this IDS which will be written to the previously created pulse file

1.1. HLI API (Ludovic)

For this tutorial, we will use the Python HLI. Documentation of all others HLIs is available in the User guide available from this page: https://confluence.iter.org/display/IMP/Integrated+Modelling+Home+Page

1.1.1. Using get() and put() operations (use-case 1)

For use-case 1, we will:

1. create a new pulse file
2. open and read some (realistic) dynamic data read from an existing 'magnetics' IDS contained in a WEST pulse file (using open() and get() operation of the Access Layer)
   1. these data will be appended to a new 'magnetics' IDS
3. write the new magnetics IDS to the new pulse file created at step 1
4. close the two pulse files
5. check the content of the pulse file. For this purpose we will:
   • open the newly created pulse file
   • read the new magnetics IDS
   • display the dynamic data which has beed added in the IDS

1.1.1.1. Creating a new pulse file

Creating a new Data Entry using the MDS+ backend consists in creating a new pulse file on disk.  Therefore, you need to have write permissions for the database specified in the create() command.

So, let's first create a new database belonging to the current user.

From a new shell, execute the following command:

module load IMAS
imasdb data_access_tutorial

The following code will create a new MDS+ pulse file for shot=15000, run=1 in the 'data_access_tutorial' database of the current user:

import imas
import getpass
from imas import imasdef
#creates the Data Entry object 'data_entry' associated to the pulse file with shot=15000, run=1, belonging to database 'pcss_tutorial' of the current user, using the MDS+ backend
data_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, 'data_access_tutorial, 15000, 1, user_name=getpass.getuser())
#creates the pulse file associated to the Data Entry object 'data_entry' previously created
data_entry.create()

Execution of the code above will create the pulse file at location ~/public/imasdb/data_access_tutorial/3/0:

$ ls -alh ~/public/imasdb/data_access_tutorial/3/0
total 78M
drwxrwsr-x 2 fleuryl fleuryl 4.0K Aug 31 10:09 .
drwxrwsr-x 12 fleuryl fleuryl 4.0K Aug 31 10:09 ..
-rw-rw-r-- 1 fleuryl fleuryl 42M Aug 31 10:09 ids_150000001.characteristics
-rw-rw-r-- 1 fleuryl fleuryl 37 Aug 31 10:09 ids_150000001.datafile
-rw-rw-r-- 1 fleuryl fleuryl 36M Aug 31 10:09 ids_150000001.tree

1.1.1.2. Opening and reading some (realistic) dynamic data read from an existing 'magnetics' IDS contained in a WEST pulse file

The following code opens and reads a 'magnetics' IDS from WEST shot=54178, run=0 in the 'west' database of user 'g2lfleur':

#
#opens the Data Entry object 'data_entry' associated to the pulse file with shot=54178, run=0, belonging to database 'west' of user 'g2lfleur', using the MDS+ backend
west_data_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, 'west, 54178, 0, user_name='g2lfleur')
#opens the pulse file associated to the Data Entry object 'data_entry' previously created
west_data_entry.open()
#reads the 'magnetics" IDS
west_data_entry.magnetics.get()

#copy the data of the first flux_loop to the new 'magnetics' IDS of the previously created data_entry
data_entry.magnetics.flux_loop

1.1.2. Using putSlice()/getSlice() operations (use-case 2)

In this tutorial, in order to illustrate the use of getSlice() and putSlice() operations, we will:

1. open the previous created pulse file
2. write10 images (10 frames) to a new 'camera_visible' IDS using the putSlice() operation
3. close the pulse file
4. read few time slices to check the content of the file, using the getSlice() operation

IDSs are data containers described by the IMAS Data Dictionary. IDSs represent either a Diagnostics (like the 'bolometer' IDS), or a System (like the 'camera_ir'), or a concept like the 'equilibrium' IDS representing the plasma equilibrium.

In order to write IDS data to the pulse file, we will first use the put() operation which writes all static (non time dependent) and dynamic data from an IDS. 

Let's add a 'magnetics' IDS to the pulse file previously created.

The first part of the code below is opening a data_entry (see 2.2.1.2.), then a magnetics IDS is created and written to the data_entry using the put() operation:

import imas
import getpass
import numpy as np
from imas import imasdef
#creates the Data Entry object 'data_entry' associated  to the pulse file with shot=15000, run=1, belonging to database 'data_access_tutorial' of the current user, using the MDS+ backend
data_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, 'data_access_tutorial, 15000, 1, user_name=getpass.getuser())
#opens the pulse file associated to the Data Entry object 'data_entry' previously created
data_entry.open() 

magnetics_ids = imas.magnetics() #creating a 'magnetics' IDS
magnetics_ids.ids_properties.homogeneous_time=1 #setting the homogneous time to 1
magnetics_ids.ids_properties.comment='IDS created for testing the IMAS Data Access layer'
magnetics_ids.time=np.array([0]) #the time(vector) basis must be not empty, otherwise an error will occur at runtime
data_entry.put(magnetics_ids, 0) #writing magnetics data to the data_entry associated to the pulse file. The second argument 0 is the so-called IDS occurrence.
data_entry.close()

1.1.3. delete_data