Compiling with Machine Architecture Abstraction Support
OR/AND Process Mapping Support
_________________________________________________________

Machine Architecture Visualization Support

These tools are intended to allow CP2K to provide an overview of the
machine where it is running. Using this support it is possible observe
the machine hardware organization and how process/threads are placed
over the machine cores. Additionally, it is possible to set and get the
scheduling and memory policy used by processes/threads on the
machine. The memory policy is avaible only on NUMA machines.

In order to use these tools, it is necessary to have hwloc library
(http://www.open-mpi.org/projects/hwloc/) or libnuma
(ftp://oss.sgi.com/www/projects/libnuma/download/) installed one the
system. Both libraries are used in the Machine Architecture
Abstraction tools. However when this support is build with hwloc
much more information is provided about the machine and 
process/threads/memory placement. The libnuma library does not provide
 a graphic view of the machine.

To compile CP2K with Machine Architecture Visualization support, two
modifications must be made to the arch file. An example is provided in
arch/Linux-x86-64-ma.sopt. The necessary modifications are:

1) Add either -D__HWLOC or -D__LIBNUMA to the DFLAGS environmental
   variable.

2) Set the HWTOPO variable to yes

3) Set the HWLOC variable, e.g., set it to the base HWLOC directory.

4) Add libhwloc.so or libnuma.so to the LIBS variable. It is also
   possible to add the static version of such libraries to LIBS.

5) Add a CFLAGS variable and include the same DFLAGS used for FCFLAGS
   as well as the include path to the HWLOC headers (e.g.,
   $(HWLOC)/include).

Then, compile as normal.


Features
--------
To visualize the output generated by the Machine Architecture
Abstraction Support it is necessary to include the print keys in the
input file of CP2K.  Consult the GLOBAL/MACHINE_ARCH section of the
input file for available options.

By default threads and processes placement are shown only once at the
initialization of the application (when they are created). If you want
to verify threads and processes placement in other steps of the
applications, you can use the interface functions to change the
application source code and get the placement. The interface is in
src/cp_ma_interface.F

There is a default placement fro processes/threads/memory that is
used depending on the CP2K version. If you want to disable or test 
different ones, you can use the interface functions to change the
application source code and get the placement. The interface is in
src/cp_ma_interface.F

Note
-------
It is not possible to compile CP2K with both libraries at same
time. The Machine Architecture Visualization Support is built using
the same interface for both libraries.

_________________________________________________________

Process Mapping Support

These tools are intended to allow CP2K to better adapt itself on
large scale parallel machines. Using this support it is possible to
map processes to the machine nodes in order to improve the available
bandwidth. For this, classical and heuristic based strategies are 
provided within CP2K. 

In order to use these tools, it can be necessary the use of machine 
dependent libraries. For instance, on CRAY machines it is necessary to 
link with krca and rca. These libraries are necessary to extract the 
machine nodes interconnection information. On machines that do not provide
such support, interconnection is obtained using the time to access nodes.
This is done automatically by CP2K.

To compile CP2K with Process Mapping Support, two modifications must be
made to the arch file. An example is provided in arch/Linux-x86-64-mp.popt.
The necessary modifications are:

1) Add the target network. For example, -D__SEASTAR, -D__GEMINI, etc.

2) Set the HWTOPO variable to yes

3) Add the interconnection information libraries (e.g. rca) to LIBS

Then, compile as normal.

If you want to use a specific strategy modify the command line 
to run CP2K with -mpi-mapping X, where X=1...7
   Example: ./cp2k.popt -mpi-mapping X ...
