======================================================================
                                  EZFIO
======================================================================

Author: A. Scemama, LCPQ-IRSAMC, CNRS-Universite Paul Sabatier
scemama@irsamc.ups-tlse.fr

== About EZFIO ==

 EZFIO is the Easy Fortran I/O library. With EZFIO, your data is organized
in a file system inside a main directory. This main directory contains
subdirectories, which contain files. Each file corresponds to a data. For
atomic data the file is a plain text file, and for array data the file is a
gzipped text file.


== Building a library ==

Your EZFIO library is built according to the definitions given in the
files of the 'config' directory.  A configuration file can be, for example:
---

system
  title              character*(128)
  num_elec           integer            = system_num_alpha + system_num_beta
  num_alpha          integer
  num_beta           integer
                    
geometry
  num_atom           integer
  nuc_energy         double precision
  label              character*(32)   (geometry_num_atom)
  atomic_number      integer          (geometry_num_atom)
  charge             double precision (geometry_num_atom)
  coord              double precision (3,geometry_num_atom)

---

  A subdirectory is defined by its name at the beginning of a new line. The
data contained in this subdirectory is defined by the triplet
(name,type,dimension), leaving at least one white space at the beginning of the
line.
  If the dimension of an array is a data defined in the file, its name can be
used as <name of the subdirectory>_<name of the data>. For example, the
dimension '(geometry_num_atom)' uses the data 'num_atom' of subdirectory
'geometry'.
 A data can also be the result of a simple operation. In that case, the
simple operation is written after an '=' symbol (as for 'num_elec'). In
that case, the data is read_only.

Once your configuration file is ready, run 'make' and your library will be
built.

== Using the library ==

 In the following, we will call 'EZFIO file' the main directory containing the
EZFIO data.

Only one EZFIO file can be manipulated at a time. To select a file, use:
   character*(64) :: filename
   call ezfio_set_file(filename)
To get the name of the current used EZFIO file, use
   character*(64) :: filename
   call ezfio_get_filename(filename)

For each data, 3 subroutines are created.
<dir> is the name of the subdirectory which contains the data and
<data> is the name of the data.

* subroutine ezfio_has_<dir>_<data> (result)
sets result to .True. if the data exists in the EZFIO file, .False. otherwise.

* subroutine ezfio_set_<dir>_<data> (source)
writes the source data to the EZFIO file.

* subroutine ezfio_get_<dir>_<data> (destination)
reads the data from the EZFIO file to the destination.

For safety, a read-only attribute can be set to the file by
   call ezfio_set_read_only(.True.)
or inquired by
   logical :: is_read_only
   call ezfio_is_read_only(is_read_only)