$Id: README,v 1.3 2010-05-18 06:09:09 kmura Exp $
==========================================================================
Geant4 MPI Interface
Author:
Koichi Murakami (KEK) / Koichi.Murakami@kek.jp
==========================================================================
About the interface
===================
G4MPI is a native interface with MPI libraries. The directory contains
a Geant4 UI library and a couple of parallelized examples.
Using this interface, users applications can be parllelized with
different MPI compliant libraries, such as OpenMPI, LAM/MPI, MPICH2,
and so on.
System Requirements:
-------------------
* Platform
- Linux (32bit/64bit)
- MacOS (Tiger)
* MPI implementation
- Open MPI (1.4.2)
http://www.open-mpi.org/
- LAM/MPI (7.1.3) (development is terminated. maintenance only)
http://www.lam-mpi.org/
- MPICH2 (1.2.1p1)
http://www.mcs.anl.gov/research/projects/mpich2/
* Optional
- ROOT for histogramming/analysis
G4MPI UI library
----------------
G4MPI UI library is provided in the "mpi_interface" directory.
Start with building the G4MPI UI library according to the instruction
in the directory.
How to make parallel applications:
----------------------------------
* An example of a main program:
#include "G4MPImanager.hh"
#include "G4MPIsession.hh"
int main(int argc,char** argv)
{
// At first, G4MPImanager/G4MPIsession should be created.
G4MPImanager* g4MPI= new G4MPImanager(argc,argv);
// MPI session (G4MPIsession) instead of G4UIterminal
G4MPIsession* session= g4MPI-> GetMPIsession();
// user application setting
G4RunManager* runManager= new G4RunManager();
// ....
// After user application setting, just start a MPI session.
// MPIsession treats both interactive and batch modes.
session-> SessionStart();
// Finally, terminate the program
delete g4MPI;
delete runManager;
}
* Notes about session shell:
LAM/MPI users can use "G4tcsh" as an interactive session shell.
For other users (Open MPI/MPICH2), plese use G4csh (default).
In case of OpenMPI, LD_LIBRARY_PATH for OpenMPI runtime libraries
should be set at run time. Alternatively, you can add this path
to the dynamic linker configuration using `ldconfig`.
(needs sys-admin authorization)
How to use:
-----------
* MPI runtime rnvironment
1. Make hosts/cluster configuration of your MPI environment.
2. Launch MPI runtime environment, typically executing
lamboot (LAM) / mpdboot (MPICH2).
* How to run
For example,
> mpiexec -n # <your application>
Instead, "mpirun" command is more convenient for LAM users.
MPI G4UI commands:
------------------
G4UI commands handling the G4MPI interface are placed in /mpi/.
Command directory path : /mpi/
Guidance :
MPI control commands
Sub-directories :
Commands :
verbose * Set verbose level.
status * Show mpi status.
execute * Execute a macro file. (=/control/execute)
beamOn * Start a parallel run w/ thread.
.beamOn * Start a parallel run w/o thread.
masterWeight * Set weight for master node.
wait * Wait until beamOn-s on all nodes are done. (batch mode only)
showSeeds * Show seeds of MPI nodes.
setMasterSeed * Set a master seed for the seed generator.
setSeed * Set a seed for a specified node.
* Notes:
While "/run/beamOn" and "/mpi/beamOn" commands invoke beam-on in background,
so you can input UI commands even while event processing.
The original "/control/execute" and "/run/beamOn" are overwritten
with "/mpi/execute" and "/mpi/beamOn" commands respectively,
customized for the MPI interface.
Examples
========
There are a couple of examples for Geant4 MPI applications.
In some cases, you need to set some additional environment variables
for running examples:
- G4LEVELGAMMADATA : directory path for the data of
"low energy electromagnetic processes".
For running ROOT applications,
- ROOTSYS : root path of the ROOT package
- LD_LIBRARY_PATH : add ROOT library path, such as $(ROOTSYS)/lib/root
[exMPI01]
A simple application.
* Geometry : chamber / calorimeter
* Primary : particle gun (200 MeV electron as default)
* Physics List : standard EM
- Particles are transported in a geometry without any scoring.
- Learn how to parallelize your G4 session.
[exMPI02] (ROOT application)
An example of dosimetry in a water phantom.
* Geometry : water phantom
* Primary : particle gun (200 MeV proton as default)
* Physics List : QGSP_BIC
- Score dose distribution in a water phantom.
- Learn how to paralleize your applications.
- Create a ROOT file containing histograms in each node.
* treat multiple outputs properly:
each slave node generate a ROOT file, whose file name should
be different from each other.
Gabriele Cosmo