What is it?

ETSF_IO is a library build on top of NetCDF that gives easy access to files conforming to the ETSF specifications (see the ETSF specification page). NetCDF files are binary files with key-values access, optimized to store large volume of data. The ETSF specifications define all key-value pairs that are normalized for a file containing informations of an electronic calculation.

License

The library and all its contents (source files and documentation files) is released under the Lesser General Public License as it can be found in the COPYING file of the distribution.

Contents of this documentation

The documentation of the library is made of two parts:

The libraries

ETSF_IO is shipped with several libraries. These libraries gives from low-level access to high-level routines on ETSF files. Each library contains one or several modules, as described below.

etsf_io_low_level (libetsf_io_low_level.a)

The library is made of one unique module. This is a wrapper around NetCDF calls to be able to do in one call what requires several NetCDF calls, such as get the id of a variable, check its shape and dimensions definition and read it. This module is not specific to the ETSF specifications and can be used as a stand-alone library to easily handle NetCDF files.

etsf_io (libetsf_io.a)

It is also made of one unique module, called etsf_io, containing specific routines to the ETSF specifications.

Beware that the library built on that module includes the etsf_io_low_level module. This means that linking with libetsf_io.a implies linking with etsf_io_low_level.

This module is the core of ETSF_IO. All variables from the specifications have been gathered into structured called group (see the etsf_groups page and related ones).

For each group, one can define a file with these variables using methods with a name like etsf_io_<group_name>_def(). This will alocate the disk space required to store all the variables of the group. Then, to write data, methods called etsf_io_<group_name>_put() are available. For reading actions, the routines are suffixed with get instead of put. To access several groups at one time a high level routine has been created and is called etsf_io_data_<action>.

There are four tutorials to learn how to use this module:

etsf_io_file & etsf_io_tools (libetsf_io_utils.a)

This library contains two modules, etsf_io_file which is dedicated to high level actions on ETSF files (merge, check...) and etsf_io_tools which implements some not mandatory routines but convenient to handle data from ETSF files (get element names...).

etsf_io_file is a not mandatory high level module. It contains several routines to do complex action on ETSF files (see the API page):

etsf_io_tools is a not mandatory high level module. It contains some tools to do common high-level actions on ETSF data (see the API page):

The usage of these modules is illustrated by several tutorials:

Attributes

The support for attributes as defined in the specifications is transparent for the user of the library: