/usr/share/doc/libetsf-io-doc/index.html is in libetsf-io-doc 1.0.3-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="./robodoc.css" type="text/css" />
<title>ETSF_IO library</title>
</head>
<body>
<div id="logo">
<a name="robo_top_of_doc">ETSF_IO library - documentation pages</a>
</div> <!-- logo -->
<div id="navigation">
<a href="#top">Library documentation page</a>
<a href="robo_modules.html">Public API (modules)</a>
<a class="level2" href="low_level/etsf_io_low_level_f90.html">Low level API</a>
<a class="level2" href="group_level/etsf_io_f90.html">ETSF level API</a>
<a class="level2" href="utils/etsf_io_file_f90.html">High level file API</a>
<a class="level2" href="utils/etsf_io_tools_f90.html">High level tools API</a>
<a href="tutorials/index.html">Tutorials & examples</a>
<a class="level2" href="tutorials/create_a_crystal_den_file_f90.html">Basics of file creation</a>
<a class="level2" href="tutorials/read_write_sub_access_f90.html">Sub-access on k points and spin</a>
<a class="level2" href="tutorials/convert_to_xyz_f90.html">Converter and validity checks</a>
<a class="level2" href="tutorials/MPI_output_of_a_density_f90.html">Use MPI and split capabilities</a>
<a class="level2" href="tutorials/mix_ETSF_and_non_ETSF_f90.html">Mix ETSF and non-ETSF variables</a>
<a class="level2" href="tutorials/read_a_file_f90.html">Simple read of wavefunctions</a>
<a href="utils/binary.html">Binary utility</a>
<a class="level2" href="utils/binary.html#merge">Merge files</a>
<a class="level2" href="utils/binary.html#content">Scan file contents</a>
<a class="level2" href="utils/binary.html#check">Check conformance</a>
</div> <!-- navigation -->
<div id="content">
<h1>What is it?</h1>
<p>ETSF_IO is a library build on top of NetCDF that gives easy access to files
conforming to the ETSF specifications (see <a
href="http://www.etsf.eu/fileformats">the ETSF specification page</a>).
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.</p>
<h1>License</h1>
<p>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 <a href="../../COPYING">COPYING file</a> of the distribution.</p>
<h1>Contents of this documentation</h1>
<p>The documentation of the library is made of two parts:</p>
<ul>
<li>One appropriated for beginners who would like to know how to read and write some ETSF files using this library. See the <a href="tutorials/index.html">tutorials pages</a>. Several examples are explained step by step.</li>
<li>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.</li>
</ul>
<h2>The libraries</h2>
<p>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.</p>
<h3>etsf_io_low_level (<em>libetsf_io_low_level.a</em>)</h3>
<p>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.</p>
<ul>
<li><a href="tutorials/mix_ETSF_and_non_ETSF_f90.html">Tutorial 5</a> 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.</li>
</ul>
<h3>etsf_io (<em>libetsf_io.a</em>)</h3>
<p>It is also made of one unique module, called <code>etsf_io</code>, containing specific routines to the ETSF specifications.</p>
<div class="warning">Beware that the library built on that module includes the etsf_io_low_level module. This means that linking with <code>libetsf_io.a</code> implies linking with etsf_io_low_level.</div>
<p>This module is the core of ETSF_IO. All variables from the specifications have been gathered into structured called <em>group</em> (see the etsf_groups <a href="group_level/etsf_io_f90.html#robo7">page</a> and related ones).</p>
<p>For each group, one can define a file with these variables using methods with a name like <code>etsf_io_<group_name>_def()</code>. This will alocate the disk space required to store all the variables of the group. Then, to write data, methods called <code>etsf_io_<group_name>_put()</code> 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 <code>etsf_io_data_<action></code>.</p>
<p>There are four tutorials to learn how to use this module:</p>
<ul>
<li><a href="tutorials/create_a_crystal_den_file_f90.html">Tutorial 1</a> 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 (<code>etsf_io_data_<action></code>). 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).</li>
<li><a href="tutorials/read_write_sub_access_f90.html">Tutorial 2</a> 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 <code><short_var_name>__[spin|kpoint]_access</code>. In this tutorial a wave-function file is created and the coefficients of wave-functions are written for one k point at a time.</li>
<li><a href="tutorials/MPI_output_of_a_density_f90.html">Tutorial 4</a> 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.</li>
<li><a href="tutorials/mix_ETSF_and_non_ETSF_f90.html">Tutorial 5</a> shows how to use the <code>etsf_io_<group_name>_put()</code> methods in the context of a concurrent list of ETSF and non-ETSF variables.</li>
<li><a href="tutorials/read_a_file_f90.html">Tutorial 6</a>
shows how to use the <code>etsf_io_<group_name>_get()</code>
methods in the simpliest way, also reading possible split definitions.</li>
</ul>
<h3>etsf_io_file & etsf_io_tools (<em>libetsf_io_utils.a</em>)</h3>
<p>This library contains two modules, <code>etsf_io_file</code> which is dedicated to high level actions on ETSF files (merge, check...) and <code>etsf_io_tools</code> which implements some not mandatory routines but convenient to handle data from ETSF files (get element names...).</p>
<p><b>etsf_io_file</b> is a not mandatory high level module. It contains several routines to do complex action on ETSF files (see the API <a href="utils/etsf_io_file_f90.html">page</a>):</p>
<ul>
<li>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.</li>
<li>The contents routine is used to get the specifications the file is matching and reasons why it fails on some.</li>
<li>The check routine is used to validate the file on themes as defined in the specifications.</li>
</ul>
<p><b>etsf_io_tools</b> is a not mandatory high level module. It contains some tools to do common high-level actions on ETSF data (see the API <a href="utils/etsf_io_tools_f90.html">page</a>):</p>
<ul>
<li>A method to retrieve the names of the element in a crystallographic file, whatever variables are present in the read ETSF file.</li>
<li>Two routines to handle the <i>use_time_reversal_at_gamma</i>
attribute as defined in the 2.2 specifications.</li>
</ul>
<p>The usage of these modules is illustrated by several tutorials:</p>
<ul>
<li><a href="convert_to_xyz_f90.html">Tutorial 3</a> shows how to use high level modules <a href="../utils/etsf_io_file_f90.html">etsf_io_file</a> and <a href="../utils/etsf_io_tools_f90.html">etsf_io_tools</a> 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.</li>
<li>Previously presented <a
href="tutorials/read_write_sub_access_f90.html">Tutorial 2</a> has a
line on how to write the <i>use_time_reversal_at_gamma</i> attribute
(see <a href="tutorials/read_a_file_f90.html">Tutorial 6</a> for the
read counterpart).</li>
</ul>
<h2>Attributes</h2>
<p>The support for attributes as defined in the specifications is transparent for the user of the library:</p>
<ul>
<li>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 <em>use_atomic_units</em> (logical).</li>
<li>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.</li>
<li>The symmorphic attribute is set to "no" automatically as soon as reduced_symmetry_translations is set to non zero values.</li>
<li>The time reversal symmetry at Gamma attribute is not handled
automatically by the <code>libetsf_io.a</code> library, but two routines
(get and set) have been written in the etsf_io_tools module (see
<code>libetsf_io_utils.a</code>). These routines check the validity of
the presence of the attribute and can write or read its contents
easily (see <a
href="tutorials/read_write_sub_access_f90.html">Tutorial 2</a> or <a href="tutorials/read_a_file_f90.html">Tutorial 6</a>).</li>
</ul>
</div> <!-- content -->
<div id="footer">
<p>Manually maintained file, last edition 2007-08-09 by Damien Caliste.</p>
</div> <!-- footer -->
</body>
</html>
|