Access Layer: from version 3 to version 4

This page describes the important API differences of the IMAS Access Layer version 4 (AL4), especially for users which have already experience with previous version 3 (AL3). 
This page is intended as a quick HOWTO, for more details on the AL4 usage please refer to the "AL user guide" (todo: link the user guide here when available from imas.iter.org).

Data Dictionary dependency

IMAS modules and versions are composed of both a Data Dictionary version (DD) and the Access Layer version (AL). Access Layer 4.0.0 was released the 29th of March 2019 for the 3.21.1 DD version. While in principle older DD version can be supported, for practical reasons no older DD are planned to be released with AL4. DD 3.21.0 is the last version supported by AL3, all more recent versions can only be released with AL4.

Below you will a section on main difference in high-level interface API. Then users API for each high-level language will be compared side by side comparison for AL3 and AL4. todo: add section on backends

1.1. Main discrepancies

Names of functions given hereafter might differ slightly in the language specific high-level interfaces, please refer to language specific sections below or to "Access Layer user's guide" for exact names and signatures, as well as for differences which are specific to a given language interface.

Reference to a data-entry now requires always to specify user, machine and version, as there is no proper default mechanism. This means that open(),create() functions are now deprecated, and only open_env() and create_env() remain in AL4.
Side effect of the change above, calling imasdb is not mandatory anymore (it was with AL3 for using either open(),create() or Kepler), but the script is still present in order to help users to create the local database layout (one time call per machine/version).
put_non_timed() function is now deprecated, as this feature was not used when not followed by at least one put_slice(). AL3 chain of put_non_timed()+put_slice() should be translated into a single call to put() where IDS contains only one slice of timed data. Note that this combined approach is valid in both AL3 and AL4, and that put_slice() has a well defined behavior only when the passed IDS contains one single slice of timed data.
The caching mechanism, as well as the flush(),discard() operations are deprecated. A new memory backend is introduced in AL4 in order to reduce IO costs of disk accesses when not necessary.
New API to select any available backend will be added soon, in the meantime it is possible to use the lowlevel API (if accessible from targeted language interface) to perform this selection (currently available backends are MDSplus, Memory and UDA).

MDSplus pulsefiles conversion

The MDSplus models (structure of the pulsefiles) have changed a lot between AL3 and AL4. Reading with AL4 a pulsefile written with AL3 or the other way around is not possible. Nevertheless a conversion script is provided with any AL4 release, so users can attempt to convert an AL3 generated pulse into a AL4 compatible one. This script is developed purely in MDSplus and will work only for pulsefiles with IDS in homogeneous_time and which are well formed. Usage, after having loaded one AL4 IMAS module (or imasenv <= 3.21.1) is as the following:

ualport.py <shot> <run> <oldDir> <newDir>
	<shot>   : shot number, or 'all' for converting all shots presents in <oldDir>
	<run>    : run number, or 'all' for converting all runs presents in <oldDir>
	<oldDir> : directory containing the source (AL3) pulsefile
	<newDir> : directory where will be stored the destination (converted to AL4) pulsefile

For sake of clarity, it is strongly advised that you use two separate directories (machine names for instance) to differenciate AL3 and AL4 pulses. For instance you can rename your test tokamak (or any other machine name) to test-AL3 and recreate an empty test where AL4 generated or converted pulsefiles will be stored:

mv ~/public/imasdb/test ~/public/imasdb/test-AL3
imasdb test
ualport.py 123 1 ~/public/imasdb/test-AL3/3/0 ~/public/imasdb/test/3/0

1.2. Fortran

bindings to lowlevel C/C++ is done explicitly through iso_c_bindings, without reallocating arrays when possible (for all non-character based quantities)
wrappers around lowlevel API are provided, allowing for instance to select a different backend

Operation	AL3	AL4	Remarks
creating a data-entry (MDSplus backend)	call imas_create(name,shot,run,shotref,runref,idx) call imas_create_env(name,shot,run,shotref,runref,& idx,user,machine,version)	call imas_create_env(name,shot,run,shotref,runref,& idx,user,machine,version)	Concept of default machine is deprecated Arguments `name,refshot,refrun` can have any (or empty) value, and are kept only for compatibility. A new unique data-entry selection routine will be added to the API, making this routine deprecated at term.
opening a data-entry (MDSplus backend)	call imas_open(name,shot,run,idx) call imas_open_env(name,shot,run,idx,& user,machine,version)	call imas_open_env(name,shot,run,idx,& user,machine,version)	Concept of default machine is deprecated Argument `name` can have any (or empty) value, and is kept only for compatibility. A new unique data-entry selection routine will be added to the API, making this routine deprecated at term.
writing the complete IDS	call ids_put(idx,idsname,ids)	`call ids_put(idx,idsname,ids)`
writing a single slice of an IDS	call ids_put_slice(idx,idsname,ids)	call ids_put_slice(idx,idsname,ids)
writing only non-timed data of an IDS	call ids_put_non_timed(idx,idsname,ids)		Deprecated, replaced by ids_put() on IDS containing only first slice data
reading the complete IDS	call ids_get(idx,idsname,ids)	call ids_get(idx,idsname,ids)
reading a single slice of an IDS	call ids_get_slice(idx,idsname,ids,time,interpol)	call ids_get_slice(idx,idsname,ids,time,interpol)	Paremeters are defined in `ual_defs` module for the different interpolation modes (to be used for `interpol` argument): `CLOSEST_INTERP,PREVIOUS_INTERP,LINEAR_INTERP`
copying an IDS or one of its substructure	call ids_copy(src,dest)	call ids_copy(src,dest)
deallocating an IDS or one if its substructure	call ids_deallocate(ids)	call ids_deallocate(ids) call ids_deallocate_struct(struct,c_data)	When deallocating a substructure of an IDS, one need to pass a logical argument indicating whether this structure has been obtained allocated in C (obtained from AL `get(),get_slice()`) or not. This check is performed automatically while deallocating an entire IDS
deleting an IDS from a data-entry	call ids_delete(idx,idsname,ids)	call ids_delete(idx,idsname,ids)
closing a data-entry	call imas_close(idx)	call imas_close(idx)

Page tree

1.1. Main discrepancies

1.2. Fortran

1.3. C++

1.4. Python

1.5. Matlab

1.6. Java

1.7. Lowlevel (C)