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
- writing data from an IDS to a Data Entry
- reading data of an IDS from an existing 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 with given shot and run numbers located in some database (see below).
The methods exposed by HLIs are:
- —Operations on data base entry:
- —CREATE
- —OPEN
- —CLOSE
- —Operations on IDSs:
- —PUT
- —GET
- —PUT_SLICE
- —GET_SLICE
- —DELETE
In this tutorial, we will describe each method of the HLI API (section 1.1. HLI API).
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. HLI API (Ludovic)
1.1.1. create
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
Now, 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.2. open
The following code opens the existing MDS+ pulse file created previously for shot=15000, run=1, from 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 '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()
The pulse file is opened, however no data have been yet fetched from the pulse file.
1.1.3. put/close
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 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 homogeneous time (mandatory) 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 if homogeneous_time==1 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. #close the pulse file associated to the 'data_entry' object data_entry.close()
1.1.4. get/close
Let'read the 'magnetics' IDS previously created in 1.1.3.
import imas
import getpass
import numpy as np
from imas import imasdef
#opens 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()
#reads the 'magnetics' IDS from the data_entry object previously opened
data_entry.get('magnetics', 0) #The second argument 0 is the so-called IDS occurrence.
#close the pulse file associated to the 'data_entry' object
data_entry.close()
#print some IDS attributes
print('homogeneous_time = ', magnetics_ids.ids_properties.homogeneous_time)
print('comment = ', magnetics_ids.ids_properties.comment)
$ python get.py homogeneous_time = 1 comment = IDS created for testing the IMAS Data Access layer