GUI: nextnanomat
 Tool: nextnano++
 Tool: nextnano
 Tool: nextnano.QCL

 Download | SearchCopyright | News | Publications
 * password protected


nextnano≥ software


  IP: Manual




Input Parser Manual (Fortran 2003)


  • Fortran input parser
    This is a simple test example (Fortran 2003 code) of GŁnther Zandler's famous input parser that is used inside nextnano≥.
    Maybe you got already familiar with it and want to use it in your own code.

The given input parser reads and analyzes an input file according to predefined syntactical rules. It is written in Fortran 2003.
It has a unique psychological effect on any user: "No matter if it works or not - you will wonder why!"

The main idea is to realize a tool, which enables the user to write position independent (as far as possible) input files.
The input files can be changed without recompiling the parser.
The parser checks the input file for syntactical correctness, for the presence of required input and for correctness of the data types of the given variable values.

Any input must be given according to predefined syntactical rules. These rules utilize keywords and specifiers, defined in a file, currently named keywords.val. The name of this file is specified in module "parameters" in the parser source code. New keywords and specifiers can be added without the need of recompilation. The general syntax to define keywords and specifiers in keywords.val is as follows:


 specifier1 data type optional
 specifier2 data type optional


Limitations for keywords and specifiers: Special characters used to identify a keyword are defined in module parameters.

keyword Each keyword must start with a predefined special character. This special character is currently set to $ and is allowed only as the first character of a keyword. Otherwise, the keyword is an arbitrary string, containing no blanks and no "=" signs.
 specifier Arbitrary string, containing no blanks, no "$", and no "=" sign.
end_keyword Must match the starting keyword as follows: $key -> $end_key


data type

Each specifier has a fixed data type. This data type must be defined by a string in the keyword definition file at the position of >data type<.

String to define a data type for a specifier:  
single precision real
double precision real
character string
data type logical
array of integer values
array of single precision real values
array of double precision real values



Defines specifier to be optional input or required input

For the string optional one of the two logical values must be substituted. optional specifier is optional input (meaning .FALSE.)
required specifier is required input (meaning .TRUE.)

Note: The first specifier after the starting keyword must be required input!


Input file name

The input file name is specified due to the first entry sequence in file keywords.val.
This "must" look like (everything after the "!" is just comment and can be removed):

  ! only to specify input file name      !
$input_filename                        !   character   required  !
! end: only to specify input file name !

any keyword with valid syntax
the first string in this line is the name of the input file
corresponding end_keyword with valid syntax


Example for definitions in keywords.val

 xmin double optional   
 xmax double required  
 nodes integer  required  
 outfile character  required  
 infile character  required  
 optimize logical optional  CHOICE[.TRUE.,.FALSE.]
 strategies integer_array  required  
 steps real_array  required  
 accuracy double_array  required  


Note: The sum of all specifiers corresponding to one keyword is referred to as input sequence in the following.

In the input file, currently named (name is specified in keyword definition file keywords.val as described above), this would look like:

$cartesian_grid_x           ! You can write comments as in Fortran
 xmin       = 0.1           ! wherever you want.
 xmax       = 0.2           !
 nodes      = 11            ! Create 11 nodes from xmin to xmax.
 outfile    = output.dat
 strategies = 1 4 8
 accuracy   = 1.0D-3  1.0D-4  1.0D-5  1.0D-6  1.0D-9  1.0D-1
 optimize   = .TRUE.
 xmin       = 0.2           ! Acts as a separator for new input sequence.
 optimize   = .FALSE.
 xmax       = 0.4           !
 nodes      = 18            ! Create 18 nodes from xmin to xmax.
$end_cartesian_grid_x       ! This is the matching end keyword.


Note: The = sign after each specifier is required. You can use another special character instead of this. The special character used is defined in MODULE parameters. The number of input values for array valued specifiers is arbitrary (limited only by the memory of your computer). If the same specifier appears twice or more within one input sequence, the last value is used for single valued input. For array valued input, the additional values are added. However, for the separation specifiers (for a definition see below), this rule does not apply by definition.
You can define predefined options using the optional argument CHOICE e.g. CHOICE[.TRUE.,.FALSE.] or CHOICE[1 0 0,0 1 0,0 0 1].
If the nextnano3 executable is run with the option -debuglevel 1000, then the file keywords_nn3.xml is generated which includes all allowed keywords, specifiers and choices which are used by nextnanomat for its auto completion feature.



In the input file, the first specifier after the starting keyword must be the same as the first specifier after the starting keyword in the definition file keywords.val. Due to this limitation, this specifier can be used as a separator for a new input sequence within a start and end keyword structure. Each time, this specifier appears, the beginning of a new input sequence is assumed. These special specifiers are named separation specifiers. Otherwise, the ordering is arbitrary. Keywords and specifiers may be in the same line or spread over multiple input lines. Line breaks are allowed before and after any data value, the = signs and before and after keywords and specifiers. Blanks at the beginning of a line are not significant. For input of array type, the numbers must be separated by blanks.



Parser usage

To read and analyze the input file, one call to SUBROUTINE read_and_analyze_input is required. No argument list is required.


Data value extraction

To extract data for a given specifier, a generic subroutine get_data(....) is supplied.

SUBROUTINE get_data(keyword,new,specifier,cont,data,pres,line,last)

In the calling routine, two modules must be included by the USE statement:

 USE parameters, ONLY: Data_len
 USE generic_get_data
length specification for character variables keyword and specifier
interface to generic subroutine get_data(....)


Argument list

Input variables LOGICAL               :: new
LOGICAL               :: cont
CHARACTER(Data_len/3) :: keyword
CHARACTER(Data_len/3) :: specifier 


new .TRUE.  start new search for keyword
.FALSE. stay at actual keyword
At first entry in subroutine get_data new must be set to .TRUE.
cont .TRUE.  search for specifier in next input sequence
.FALSE. search in actual input sequence
keyword string, containing keyword to be searched for (maximum length 267/3)
specifier string, containing specifier, for which data value is requested (maximum length 267/3)



Informative output variables: INTEGER :: line
LOGICAL :: pres
LOGICAL :: last 
line line number in input file, where value was found.
pres .TRUE. if a value for actual specifier was found; .FALSE. otherwise
last .TRUE. if last input sequence for given keyword was read.


Generic output:
The variable data in the argument list is representative for one of the possible data type listed beneath for a generic call.

:: ival  
:: xsval single
:: loval  
:: xdval double
:: caval  
:: inarval  
:: xsarval single
:: xdarval double

  The generic argument must be of the same type as the data type of the requested specifier.