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)
DBEntry
class represents data accessible through Access LayerHDCEntry
, 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 (ifNone
→ $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
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:
All 'old' scripts will work - no modifications needed
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.
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
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.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
PUT | GET |
---|---|
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
PUT | GET |
---|---|
import imas 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 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
PUT | GET |
---|---|
import imas 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 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() |
5. 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
5.1. Enum
class IDSName(enum):
EQUILIBRIUM = 'equilibrium'
WALL = 'wall'
class IDSName(enum): AMNS_DATA = 'amns_data' ...... WAVES = 'waves'
from ids_names import IDSName ids = db_entry.get(IDSName.WALL.value)
It is not enough to call IDSName.WALL
to get string value of enumerator. Because of Python enumerator implementation, one has to call IDSName.WALL.value
to get 'wall'
string.
5.2. Given IDS class attribute
e.g. Wall.__name__
ids = db_entry.get(Wall.__name__)