Difference between revisions of "FDF - Flexible Data Format"

From ESL
Jump to navigation Jump to search
m (Category Libraries (not Library))
Line 81: Line 81:
[[Category: ESL entries]]
[[Category: ESL entries]]
[[Category: Software]]
[[Category: Software]]
[[Category: Library]]
[[Category: Libraries]]
[[Category: I/O]]
[[Category: I/O]]

Revision as of 12:03, 4 August 2014

FDF (Flexible Data Format) is an input file parser that offers an easy, transferable and practical way for a Fortran program to read its input. It is text (ASCII) based, and conceived for small data (input parameters). Every input piece of data is introduced in a line of an input file (which can be standard input) by writing a name-value pair, that is, a name characterising the data, and its value. If the latter corresponds to a physical magnitude, the units can also be specified after the value. Names can be long and should be descriptive of the value it corresponds to. FDF blocks are used to input structured data, in which case, the program using FDF reads the inside of the block.

From the programming point of view, FDF allows for any data to be retrieved whenever, from any part of the code, and in any order.

If a piece of data is sought by FDF by is not found in the input file, FDF will return a default value, as set up in the call to the FDF routine.


Here we explain the way it works on an example. Consider the following input file:

lattice_constant  5.5 Ang      # LatticeConstant == lattice_constant
NumberOfSpecies  2             # Order of labels is irrelevant
%block ChemicalSpeciesLabel
 1  8  O      # Species index, atomic number, species label
 2  1  H
%endblock ChemicalSpeciesLabel

spin.polarized                 # T==true==yes==blank

It illustrates typical input, including different features, such as comments. Empty lines do not matter, neither do the number of spaces (or positioning) between name and value.

Names are case-insensitive, and allow the introducing "-", "_" or "." in them for clarity without their being considered.

The position of any input pair is irrelevant.

Here is an example of source code that would read that input using the FDF library:

  use fdf
  type(block_fdf)            :: bfdf
  type(parsed_line), pointer :: pline

  ns       = fdf_get('NumberOfSpecies',0)   ! fdf_get(label,default[,units])
  latconst = fdf_get('LatticeConstant',0.0_dp,'Bohr')
  spinpol  = fdf_get('SpinPolarized',.false.)

  found = fdf_block('ChemicalSpeciesLabel',bfdf) ! read block into bfdf struct
  if (.not.found) stop "Block ChemicalSpeciesLabel not found"
  do is = 1,ns                         ! loop on species
    found = fdf_bline(bfdf,pline)      ! read one line into pline structure
    label(is) = fdf_bnames(pline,1)    ! first name in line
    z(is) = fdf_bintegers(pline,2)     ! second integer in line