Introduced changes should work in parallel with existing API (unless it proves impossible)

'Old' methods and classes will be marked as deprecated  


1.  DBEntry

1.1. Class structure:

Class keeps information about one, particular  database entry (eg. pulse-file, HDC container, SQL-database, etc etc)

Class structure siagram


  • DBEntry class represents data accessible through Access Layer 
  • HDCEntry , SQLEntry  are examples of classes that represents IMAS data entry accessible via other mechanisms than AL (if they will be implemented in future)
  • IMASEntry a parent class for all XXXEntry classes. It will be implemented in future if any other mechanism of accessing data than AL will be used. Could be empty...  

THIS PAGE FOCUSES ON DESIGN OF DB_ENTRY AND IDS CLASSES ONLY!

1.2. Definition (constructor)

DB Entry  is defined by:

  • backend_id - MDSPLUS_BACKEND, MEMORY_BACKEND, ASCII_BACKEND - mandatory -   
  • db name - eg. test   - mandatory 
  • shot - mandatory
  • run - mandatory
  • user name - eg. g2bpalak  -  optional  (if None  → $USER)
  • data version - e.g. 3 - optional - currently not used,  we should keep it as it will point us to a proper dir in imasdb structure, when we develop versions 4,5, etc  - if None → $IMAS_VERSION 
DBEntry constructor
def __init__(self, backend_id, db_name, shot, run, user_name = None, data_version = None)
	if user_name is None:
		user_name = $USER

	if data_version is None:
		data_version = $IMAS_VERSION


Additional "URI-based" constructor will be added in future...

1.3. Create/open/close

All parameters that defines DBEntry  are set in constructor, so create, open, close will have no mandatory arguments

DBEntry create/open/close
def create(self, options = None)
def open(self, options = None)
def close(self, options = None)

options - additional options (backend specific)

1.4. DBEntry methods for IDS storing /reading

1.4.1. Get IDS

IDS GET
def get(self, ids_name, occurrence = 0) # ids_name (e.g. 'equilibrium', IDSName.EQUILIBRIUM, wall.__name__ (see below)) 

1.4.2. Put IDS

IDS PUT
def put(self, ids, occurrence = 0)

1.4.3. IDS put slice

IDS PUT
def put_slice(self, ids, occurrence = 0)

1.4.4. IDS get slice 

IDS GET
def get_slice(self, ids_name, time_requested, interpolation_method, occurrence=0): # idsName (e.g. 'equilibrium')
	return ids

1.4.5. Partial Get

def partial_get(self, ids_name, data_path, occurrence = 0, db_entry = None):


2. IDS superclass

IDSBase  - Parent class for all classes representing particular IDSes. For internal use only - it should not be called by users.

3. IDS class

Backward compatibility

Backward compatibility, understood as possibility of using 'old' and 'new' approach at the same time is kept:

(plus) All 'old' scripts will work - no modifications needed 

(minus) Currently all methods use context kept in IDS that was a reason of many problems. New API is designed to overcome this issue. Keeping compatibility means that methods still have to be able to use context stored in IDS that is error prone.

(minus) All unwanted, messy methods operating on context stored (setCtx, etc)  must be kept 


Compatibility can be also ensured by introducing new names of methods - putSlice  vs put_slice 

3.1. IDS storing / reading

To provide database context user has to pass explicitly DBEntry object to all methods responsible for saving / reading data. This parameter should be mandatory but has to be kept optional to ensure backward compatibility....


def put(self, occurrence=0, db_entry=None):

def get(self, occurrence=0, db_entry=None):

def putSlice(self, occurrence=0, db_entry=None):

def getSlice(self, time_requested, interpolation_method, occurrence=0, db_entry=None):

def partialGet(self, dataPath, occurrence=0, db_entry = None):

3.2. "Messy" methods

... that are not in line with proposed design but they must be kept to ensure backward compatibility.

def setPulseCtx(self, ctx):
def getPulseCtx(self):


4. Examples

4.1. Backward compatibility

PUTGET
  import imas

  imasEnv = imas.ids(1111, 1111)
  imasEnv.create_env(user, db_name, dd_version)  
    
  # Mandatory property
  imasEnv.pf_active.ids_properties.homogeneous_time = 2

  imasEnv.pf_active.put()
        
  imasEnv.close()
import imas

imasEnv = imas.ids(1111, 1111)
imasEnv.open_env(user, db_name, dd_version)  




imasEnv.pf_active.get()
  
imasEnv.close()


4.2. Storing/reading data via db_entry methods

PUTGET
import imas
from imas import imasdef

db_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, db_name, 2222, 2222)
db_entry.create()  
    
ids = imas.pf_active()
# Mandatory property
ids.ids_properties.homogeneous_time = 2

db_entry.put(ids)

db_entry.close()
import imas
from imas import imasdef

db_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, db_name, 2222, 2222)
db_entry.open()  





ids = db_entry.get('pf_active')

db_entry.close()

4.3. Storing/reading data via ids methods

PUTGET
import imas
from imas import imasdef

db_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, db_name, 3333, 3333)
db_entry.create()  
    
ids = imas.pf_active()
ids.ids_properties.homogeneous_time = 2

ids.put(db_entry = db_entry)
db_entry.close()
import imas
from imas import imasdef

db_entry = imas.DBEntry(imasdef.MDSPLUS_BACKEND, db_name, 3333, 3333)
db_entry.create()  

ids = imas.pf_active()


ids.get(db_entry = db_entry)
db_entry.close()



To avoid any mistakes, typos, argument describing IDS should not be a string (ida name - 'equilibrium', 'wall' etc) but a constant pre-defined value.

Suggested methods of specifying IDS name are:

  • Using IDSName enumerator
    • example:  ids = db_entry.get(IDSName.WALL.value)  (IDSName should be imported "from ids_names import IDSName ")
  • Using IDS class attribute
    • example: ids = db_entry.get(Wall.__name__) 

Acknowledgement

This work has been carried out within the framework of the EUROfusion Consortium and has received funding from the Euratom research and training programme 2014-2018 under grant agreement No 633053.The scientific work is published for the realization of the international project co-financed by Polish Ministry of Science and Higher Education in 2019 and 2020 from financial resources of the program entitled "PMW"; Agreement No. 5040/H2020/Euratom/2019/2 and 5142/H2020-Euratom/2020/2”.