hila::input Class Reference

hila::input - Class for parsing runtime parameter files. More...

#include <input.h>

Classes
class	returntype
	returntype is a special class for resolving get("label") return type More...

Public Member Functions
bool	open (const std::string &fname, bool use_cmdline=true, bool exit_on_error=true)
	Open file that parameters are read from.
void	close ()
	Closes input parameter file.
void	quiet (bool really=true)
	Silence print output during file reading.
returntype	get (const std::string &key)
	Get next value in stack of read in input string from parameters file.
template<typename T >
bool	get_value (T &val, const std::string &label, bool bcast=true)
	Read input (alternative to get())
int	get_item (const std::string &label, const std::vector< std::string > &items, bool bcast=true)
	Identify item from a list.

Detailed Description

hila::input - Class for parsing runtime parameter files.

Input files consist normally of "key <value>" -pairs.

It is important to note that the data structure employed by the input class is not a dictionary, but technically a stack. This means that the values are read in sequentially, thus they must be in the file in the order they are read in.

In examples of other methods we will refer to the input object as f. Creating the input object is done with:

hila::input f("filename");   // initialization with filename opens the file for input

One can also initialize the input object without specifying the filename:

hila::input f;   // initialization with filename opens the file for input

in which case the hila::input::open method needs to be called separately.

Comment character '#': everything after # in input file is a comment to the end of the line.

NOTE: methods which broadcast to all nodes (default) must be called from all nodes synchronously. These include open(), get(), get_value() with bcast=true, get_item with bcast=true.

Thus:

if (hila::myrank() == 0) {
    double v = f.get("a value");
    ...
}

deadlocks (if there are more than 1 rank). Method f.get_value(v,"a value",false) can be used in this context.

Definition at line 52 of file input.h.

Member Function Documentation

close()

void hila::input::close

(

)

Closes input parameter file.

After f.close() the file can be reopened with f.open("file") and the stack is reset. File is also closed when variable "f" goes out of scope.

Definition at line 79 of file input.cpp.

get()

returntype hila::input::get ( const std::string &  key )

inline

Get next value in stack of read in input string from parameters file.

Use as

var = f.get("key");

reads in a key-value pair

key   <value(s)>

from the input file f, and returns the value of type of variable var. The value is broadcast to all MPI nodes. The method infers the type of the returned variable from the type of the assignment.

Key is an alphanumeric string, which may contain words separated by whitespace.

The get method simply traverses the parsed in stack of input values in the given parameters file. A functionality of the method is that the given argument key is skipped and the value that this key is assigned to is then fetched and returned.

Technically the key's can also be read in if no argument is given to get. The main functionality of the key argument is to book keep by the user that all parameters are read in. If the key that is wanting to be read doesn't exist, then get throws an error and the program is stopped.

With this logic one could construct a parameters file of only values:

value_1
value_2
.
.
.
value_n

and read in the values in a loop by simply calling hila::input::get() consecutively, but this is not advised.

The type of the value to be read in is inferred by the variable the value is fetched into. If the value cannot be casted into the variable, then the parser will throw an error and crash.

Types which the parser supports with examples

Multiple items are separated by commas, whitespace is not significant.

Any arithmetic type (ints/floats)

int i = f.get("number of cats");

matches " number of cats 5 "

Complex<float/double>

Complex<double> phase = f.get("complex phase");

matches "complex phase (0.4, 0.5)"

complex values are given in pairs within ( , )

std::string

std::string s = f.get("key");

matches "key <string value>" where string value is either

• sequence of non-whitespace chars, delimited by whitespace, eol, ',' or '#'.
• characters enclosed by quotes "..". These have to pair within the same line. Quote marks are removed.

CoordinateVector

CoordinateVector v;
v = f.get("lattice size");

matches "lattice size 32, 32, 32, 32" (if NDIM == 4).

Vector<T,int>

Vector<5,int> vec = f.get("initial vector")

matches "initial vector 1, 2, 3, 4, 5"

std::vector<T>

std::vector<double> dvec = f.get("vec");

matches "vec 3,4, 5.5, 7.8, 4" and returns a vector of double values. The numbers are read until they are not followed by a comma. If comma is the last non-whitespace character on the line, reading continues to the next line.

T is one of the other supported types.

NOTE: The parser will crash if during reading in a multi valued line (Vector, std::vector) the line ends with a ",". The parser will interpret that there is data on the next line to read in and will fail during the next get call.

Parameters

key	Parameter to be read in.

Returns

returntype Value corresponding to input key

Definition at line 269 of file input.h.

get_item()

int hila::input::get_item	(	const std::string &	label,
		const std::vector< std::string > &	items,
		bool	bcast = true
	)

Identify item from a list.

"items" contains the allowed entries. Return value is the index of the item found in input file.

If the value of the optional bool parameter broadcast is:

• true (default): the result is broadcast to all nodes and the program exits if no matches found.
• false: result is not broadcast, and if no match found returns -1.

Special item values:

• "%f" matches a float or double value
• "%i" matches an int or long
• "%s" matches any string value

If one of these is matched, it has to be read again with corresponding get() or get_value() -method. get_item doesn't progress the stack, so get() will fetch the next value which the item result corresponds to

Examples:

i = f.get_item("colour", {"red","green","blue"});

will return value 1 if f contains "colour green", and quits the program if none of the 3 alternatives are found.

double clover;
int i = f.get_item("c_sw", {"tree","perturbative","%f"} );
if (i == 2)
     clover = f.get();
else { ...

If file contains:

• c_sw perturbative get_item() returns 1
• c_sw 1.343 get_item() returns 2 and subsequent get() sets c_sw = 1.343
• c_sw abcd error message and quit

NOTE: "%s" matches anything. It should be the last item in the list. (The items are tested in order and first to match is returned.)

Parameters

label	key to match in parameters file
items	list of items to identify with
bcast	Default true, if true broadcast to all MPI ranks

Returns

int index of identified item in users defined list

Definition at line 302 of file input.cpp.

get_value()

template<typename T >

bool hila::input::get_value ( T &  val, const std::string &  label, bool  bcast = true  )

inline

Read input (alternative to get())

Val can be any value used in get()-method above. If broadcast==false, the value is not broadcast to other nodes. The return value is false if the value could not be read successfully, true otherwise. This method does not exit on error (but an error message may be printed) Example:

int i,j;
bool success;
success = get_value(i, "key", false);   // only node 0 gets i
success = get_value(j,"key2");          // all nodes get j

NOTE: if broadcast == false the return value is correct only on node 0.

Supported types same as for hila::input::get

Template Parameters

T

Parameters

val	variable to store gotten value in. Infers the type for the fetched value
label	key to fetch value for
bcast	default true. If true the value will be broadcasted to all nodes

Returns

true Returns true on success

false Returns false if return value is correct only on node 0.

Definition at line 302 of file input.h.

open()

bool hila::input::open	(	const std::string &	fname,
		bool	use_cmdline = true,
		bool	exit_on_error = true
	)

Open file that parameters are read from.

If input class is initialized with path to file that needs to be opened, then the file will be opened automatically, and this method does not need to be called.

If no argument is given then filename will be interperated as default input file name

In the case that use_cmdline is True and if no argument is given and filename is given with -i {alternative_file} cmdline argument then {alternative_file} will be the specified file to be opened.

Parameters

fname	Path to file that needs to be read
use_cmdline	Default True
exit_on_error	If true exit on error. Return value is passed to all MPI nodes. Default True

Returns

true

false

Definition at line 22 of file input.cpp.

quiet()

void hila::input::quiet ( bool  really = true )

inline

Silence print output during file reading.

f.quiet();      // don't print read items to hila::out
f.quiet(false); // re-enable printing

By default hila::input methods print everything read to hila::out0 for logging. f.quiet() disables this.

Parameters

really

Definition at line 112 of file input.h.

---

The documentation for this class was generated from the following files:

• input.h
• input.cpp