FRAMEWORK.txt

#Configuration file for Nek5000 framework developed at KTH
# Place for short description; doxygen style
/**
@defgroup toolbox  Toolbox
@ingroup framework

@brief Toolbox for Nek5000

@details 
This directory contains a number of tools used by toolbox developed at KTH. 
All the files are grouped by tasks and placed in a tree structure, where the parent directories (modules) 
perform some operations and can define tasks and interfaces that have to be provided by their 
sub-directories (sub-modules). This structure can be repeated recursively with sub-modules becoming
parent modules for the next level structures. The top level directories are related to the main services 
that have to be provided for toolboxes. An exemplary framework structure is presented in the figure.

@image html framework.png Examplary framework structure.

Modules can provide tools, [runtime parameters] (@ref parameter_list_page), memory structures (common blocks), 
define interfaces and perform some tasks.
The main goal is to simplify the development of the toolbox by defining simple tasks that could be used by a number of tools. 
At the same time, a clear definition of the inteface makes it possible to have the number of different implementations 
of the same or various tasks. A good example is the [time stepping tool] (@ref tstpr), which can be used for both 
[power iteration] (@ref pwit) and spectra calculation with the [Arnoldi algorithm] (@ref arna). In this case, 
the [time stepping] (@ref tstpr) module defines the interface of @a stepper_vsolve, while both 
[power iteration] (@ref pwit) and [Arnoldi algorithm] (@ref arna) sub-modules provide its implementation.

Each module has to contain:
- FRAMEWORK.txt -module description
- makefile_usr.inc - compilation rules
- source code
- optionally
   + example.par including corresponding runtime parameter section
   + example.usr including example of required user defined interfaces (modiffication required)
   + more detailed documentation
   + additional scripts required by the module

Dependences between modules are described in FRAMEWORK.txt, which is present in almost every directory.
It is a documentation file written in a form of doxygen C comment including:
- definition of group
- description of the module's purpose
- definition of the interface provided by the module
- list of required interfaces from submodules (module dependency)
- example of a module call
- list of provided runtime parameters
- list of requred runtime parameters (module dependency)
- example of a section in @a setup.par file

In addition there is a bash script @a toolbox_path.sh located at the top level directory of the toolbox.
It provides a set of the environment variables defining absolute paths of each of the modules in the toolbox containg
the code. These variables are later used in @a makefile_usr.inc to define compilation rules. It prevents copying 
the source files from the toll's directory to the compilation directory except those include files 
marked @a _template in the source code directory that require user modification.
*/