1.  DBEntry

1.1. Class structure:

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

• 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 

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

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

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

1.4.2. Put IDS

def put(self, ids, occurrence = 0)

1.4.3. IDS putSlice

def put_slice(self, ids, occurrence = 0)

1.4.4. GetSlice IDS

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

1.5. Any other method is needed to ba added to DBEntry class?

def delete(self, ids_name, occurrence=0):

2. IDS superclass

IDSBase  - Parent class for all classes representing particular IDSes. 

2.1. Class  methods (aka "static")

def get_ids(cls, ids_name):

3. IDS class

3.1. Class  methods (aka "static")

def get_max_occurrences(cls):

def read_time_mode(self, ctx):

def read_time(self, ctx):

3.2. IDS storing / reading

DBEntry  is used to provide explicitly context to methods. This parameter is optional to keep 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):

3.3. Additional methods

def copy_values(self, ids):

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

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

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

3.4. "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

  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()

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

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

db_entry.put(ids)

db_entry.close()

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

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

ids.put(db_entry = db_entry)
db_entry.close()

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

ids = pf_active()


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

5. Importing IDS classes

Suggested method:

import imas
ids_wall = imas.wall()

It is also possible to write:

import imas
from imas.wall import wall
ids_wall = wall()

or

import imas
ids_wall = imas.wall.wall()

6. IDS names

ids = db_entry.get('pf_active')

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

It can be implemented using enum or class attribute

6.1. Enum

class IDSName(enum): 

     EQUILIBRIUM = 'equilibrium'

     WALL = 'wall' 

etc etc

from ids_names import IDSName

ids = db_entry.get(IDSName.WALL)

6.2. Given IDS class attribute

e.g. Wall.__name__

ids = db_entry.get(Wall.__name__)