ETSF_IO library - documentation pages

Library documentation page Public API (modules) Low level API ETSF level API High level file API High level tools API Tutorials & examples Basics of file creation Sub-access on k points and spin Converter and validity checks Use MPI and split capabilities Mix ETSF and non-ETSF variables Simple read of wavefunctions Binary utility Merge files Scan file contents Check conformance

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:

• One appropriated for beginners who would like to know how to read and write some ETSF files using this library. See the tutorials pages. Several examples are explained step by step.
• The other is the description of all public routines that can be used. Their functions, their arguments and some examples are given, as much as the code itself when relevant.

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.

• Tutorial 5 is not focus on the low level API but it uses it in several areas. This tutorial shows how to write an ETSF file with additional non-ETSF variables. These variables are defined and written directly by using the low level API.

etsf_io (libetsf_io.a)

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

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:

• Tutorial 1 is intended to explain the basics and the philosophy of this library. It details the first steps required to create a density file, using high level routines (etsf_io_data_<action>). It shows how to use the pointers and the unformatted ones (used to map any shape arrays between the ETSF definition and the main program memory).
• Tutorial 2 introduced the group level routines and explain how to access only sub part of arrays. This sub access is possible when one array has a dimension on spin or k points. Then one can access data for one k point or spin at a time. This is controlled by some attributes in the concerned groups, called <short_var_name>__[spin|kpoint]_access. In this tutorial a wave-function file is created and the coefficients of wave-functions are written for one k point at a time.
• Tutorial 4 shows how to use the split definitions as defined in the specifications to handle MPI computations. This tutorial creates a density file with a paralelisation on z planes.
• Tutorial 5 shows how to use the etsf_io_<group_name>_put() methods in the context of a concurrent list of ETSF and non-ETSF variables.
• Tutorial 6 shows how to use the etsf_io_<group_name>_get() methods in the simpliest way, also reading possible split definitions.

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

• The merge routine can read several ETSF files and create a new one, copying all variables that are not splitted and merging those that have a split definition. If there is not enough input file to create a full unsplitted array, the new file will contains some new split informations resulting from the merge. This routine also copy headers and attributes, as for all none-ETSF variables and dimensions.
• The contents routine is used to get the specifications the file is matching and reasons why it fails on some.
• The check routine is used to validate the file on themes as defined in the specifications.

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

• A method to retrieve the names of the element in a crystallographic file, whatever variables are present in the read ETSF file.
• Two routines to handle the use_time_reversal_at_gamma attribute as defined in the 2.2 specifications.

The usage of these modules is illustrated by several tutorials:

• Tutorial 3 shows how to use high level modules etsf_io_file and etsf_io_tools to check the conformance of an input ETSF file on cristalographic specifications and then to read atomic coordinates and names to create a simple XYZ file.
• Previously presented Tutorial 2 has a line on how to write the use_time_reversal_at_gamma attribute (see Tutorial 6 for the read counterpart).

Attributes

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

• The units attribute is defined by default to "atomic units". When a file is read, all returned values are automatically converted to atomic units when required, thanks to the scale_to-atomic_units attribute. To get the true value from the file, one can give an optional argument to prevent to convert into atomic units, called use_atomic_units (logical).
• The k_dependent attribute is set to "yes" by default. When a variable with the k_dependent attribute is read, the value from the array is read except if the attribute is "no". Then the fallback value specified in the ETSF specifications is given.
• The symmorphic attribute is set to "no" automatically as soon as reduced_symmetry_translations is set to non zero values.
• The time reversal symmetry at Gamma attribute is not handled automatically by the libetsf_io.a library, but two routines (get and set) have been written in the etsf_io_tools module (see libetsf_io_utils.a). These routines check the validity of the presence of the attribute and can write or read its contents easily (see Tutorial 2 or Tutorial 6).

Manually maintained file, last edition 2007-08-09 by Damien Caliste.