Welcome to a programmer documentation of numbox tools. The documentation follows the code structure of the library.

• compilation - basic settings of compilation scripts for waf build system
• env - settings of environment parameters and third party libraries
• benchmarks - description how the library is tested and how to create a test for a new functionality
• src - description of the library source code

For compilation python-based framework waf is used. The compilation process has two phases: configuration and compilation. The former configures persistent data and checks available headers and libraries. The latter builds the library into the build directory. It is mandatory to re-run the configuration process after any change of environment. The following commands build all modules if require libraries are available:

$ ./waf configure
$ ./waf

A detailed description of the waf tool is provided at the link above. Hence, we provide only brief description here.

• the tool is fully distributed with the numbox library at the compressed form (file waf at the root directory)
• only a python interpreter is required to run the waf tool
• the tool is configured by wscript files (mainly) by the following three functions:
  • options - settings of configuration options (use ./waf -h to list all available options)
  • configure - settings of the configuration process (compilers, third party libraries, etc.)
  • build - building of the source files into libraries and executables

The main configuration file is located at the root directory. It provides the following additional functions:

• show - print the current configuration
• env - print the current waf environment settings
• link_cxx - try to compile a simple cpp file with a given list of headers and libraries. If all tests pass, the function adds a given library specification into the waf environment (you can check it by ./waf env). The function has the following parameters (examples of usage can be seen in src/wrappers directories)
  • root - root directory searched for includes and libraries
  • use - list of dependencies
  • name - name of checked library
  • header_name - list of headers
  • fragment - cpp code that check validity of the library (size of int etc.)
  • libs - list of libraries

Some numbox functionality is dependent on third party libraries. Wrappers of there libraries are located in src/wrappers directories. Each wrapper with a corresponding compilation script should assure that

• it is possible to build numbox without a particular third party library
• third party library headers are included only within a particular wrapper
• third party library is build with a required data types (e.g., integers have required size)
• third party library provides a required functionality (e.g., support parallel environment)
• calling not-linked third party library ends with an error
• wrappers resolve a potential conflict of more third party libraries

Particular wrappers are described in more detail here

Built libraries and executables are located in the build directory. This directory should be added into the system paths or library can be installed via ./waf install. Before running the library, one should also set the following variables according to the number of CPU cores per compute node (CPUs) and number of MPI processes processed per node (PPN):

• OMP_NUM_THREADS - should be set to CPUs/PPN
• SOLVER_NUM_THREADS - should be set to CPUs/PPN
• PAR_NUM_THREADS - should be set to CPUs/PPN

It is possible to set above environment variables at once using the following script in the root directory:

$ . env/threading.default ${CPUS/PPN}

Directory env also contains scripts for loading modules on IT4I clusters. These scripts should be used for loading tested modules on a particular cluster.

The benchmarks directory contains a basic set of examples for integrity testing of both mesio and espreso libraries. All tests are executed daily for the 'master' branch and if all tests pass, the branch is published to the 'release' repository on github. Hence, the github repository always contains a checked version. Detailed description of benchmarks can be found here.

The source code of the library is written in C++. Parallelization of the library is based on the MPI interface, OpenMP for threading, and asynchronous output is performed by POSIX threads.

The source code is divided into several directories. Please, follow the link to a separate page with a precise description.

• basic utilities accessible through the library
  • basis - basic containers and utilities
  • config - configuration of the library via ecf files and its reader
  • esinfo - globally accessible information (MPI, environment, logger, configuration, stepping)
• mesh pre/post-processing routines (main sources of the mesio library)
  • input - the core of the mesio tool
    • parsers - description of parsers for available mesh database formats
    • builders - description of massive parallel mesh builder
  • mesh - stored mesh information and manipulations
  • output - storing the results into output database and monitoring reports
• physical engines
  • math - vector and matrix manipulation routines
  • physics - physical matrices builder and solvers
    • kernels - physical matrices builders
    • solvers - physical matrices solver
    • system - generalization for different linear solvers (direct solver, FETI)
• FETI linear solver
  • feti - the core of the espreso library
• Other
  • app - the source code of executables
  • api - ESPRESO API description
  • wrappers - third party libraries wrappers