source: ThirdParty/mpqc_open/src/bin/mpqc/mpqcrunning.dox@ 482400e

/** \page mpqcrunning Running MPQC

This chapter explains how to run MPQC in a variety of environments.

The first two sections give general information on running MPQC:

<ul>
  <li> \ref mpqccomline
  <li> \ref mpqcenv
</ul>

The final sections given specific information on running MPQC in
different environments:

<ul>
  <li> \ref mpqcshmem
  <li> \ref mpqcpthr
  <li> \ref mpqcmpi
  <li> \ref mpqcmp2
  <li> \ref mpqcmp2r12
  <li> \ref mpqccca
</ul>

\section mpqccomline Command Line Options

  MPQC can be given options followed by an optional input file
name.  If the input file name is not given, it will default to
"mpqc.in".  The following command line options are recognized:

<dl>

  <dt><tt>-o</tt><dd>Gives the name of the output file.  The default is the
                console.

  <dt><tt>-i</tt><dd>Convert a simple input file to an object oriented
                input file and write the result to the ouput.  No
                calculations are done.

  <dt><tt>-messagegrp</tt><dd>A ParsedKeyVal specification of a MessageGrp
                object.  The default depends on how MPQC was compiled.

  <dt><tt>-memorygrp</tt><dd>A ParsedKeyVal specification of a MemoryGrp
                object.  The default depends on how MPQC was compiled.

  <dt><tt>-threadgrp</tt><dd>A ParsedKeyVal specification of a ThreadGrp
                object.  The default depends on how MPQC was compiled.

  <dt><tt>-integral</tt><dd>A ParsedKeyVal specification of an Integral
                object. The default is IntegralV3. Note that some
                MolecularEnergy specializations require specific choices
                of Integral specializations and may not work with IntegralV3.

  <dt><tt>-l</tt><dd>Sets a limit on the number of basis functions.  The
                default is zero, which means an unlimited number of basis
                functions.

  <dt><tt>-W</tt><dd>Sets the working directory.  The default is the
                current directory.

  <dt><tt>-c</tt><dd>Check the input and exit.

  <dt><tt>-v</tt><dd>Print the version number.

  <dt><tt>-w</tt><dd>Print the warranty information (there is no warranty).

  <dt><tt>-d</tt><dd>If a debugger object was given in the input, start the
                debugger running as soon as MPQC is started.

  <dt><tt>-h</tt><dd>Print a list of options.

  <dt><tt>-f</tt><dd>The name of an object-oriented input file.  The
                default is <tt>mpqc.in</tt>.  This cannot be used if
                another input file is specified.  This option is
                deprecated, as both input file formats can be read
                by given the input file name on the command line
                without any option flags.

  <dt><tt>-cca-path</tt><dd>A colon-separated list of directories in which 
                CCA component libraries may be found.

  <dt><tt>-cca-load</tt><dd>A colon-separated list of sidl class names for
                CCA components which will be instantiated from the libraries
                found in the path given by <tt>-cca-path</tt>

</dl>

Some MPI environments do not pass the command line to slave programs, but
supply it when MPI_Init is called.  To make MPQC call MPI_Init with the
correct arguments as early as possible use the configure option
<tt>--enable-always-use-mpi</tt>.

\section mpqcenv Environmental Variables

MPQC looks at five environmental variables to set up
communication, find library files, and specify the default Integral
object.  Machine specific libraries
and utilities to run programs in parallel might look
at other environment variables as well.  The five that
apply on all platforms are:

<dl>

  <dt><tt>SCLIBDIR</tt><dd>The name of the library directory.  See the
                     GaussianBasisSet documentation and look below for more
                     information.

  <dt><tt>MESSAGEGRP</tt><dd>A ParsedKeyVal specification of a MessageGrp
                     object.  The default depends on how MPQC was compiled.
                     See the MessageGrp class documentation for more
                     information.

  <dt><tt>MEMORYGRP</tt><dd>A ParsedKeyVal specification of a MemoryGrp
                     object.  The default depends on how MPQC was compiled
                     and the MessageGrp in use.

  <dt><tt>THREADGRP</tt><dd>A ParsedKeyVal specification of a ThreadGrp
                     object.  The default depends on how MPQC was compiled.

  <dt><tt>INTEGRAL</tt><dd>A ParsedKeyVal specification of an Integral
                object. The default is IntegralV3. Note that some
                MolecularEnergy specializations require specific choices
                of Integral specializations and may not work with IntegralV3.

</dl>

By default, MPQC tries to find library files first in the <tt>lib</tt>
subdirectory of the installation directory and then the source code
directory.  If the library files cannot be found, MPQC must be notified of
the new location with the environmental variable <tt>SCLIBDIR</tt>.

For example, if you need to run MPQC on a machine that doesn't have the
source code distribution in the same place as it was located on the machine
on which MPQC is compiled you must do something like the following on the
machine with the source code:

<pre>
cd mpqc/lib
tar cvf ../sclib.tar basis atominfo.kv
</pre>

Then transfer <tt>sclib.tar</tt> to the machine on which you want to run MPQC
and do something like

<pre>
mkdir ~/sclib
cd ~/sclib
tar xvf ../sclib.tar
setenv SCLIBDIR ~/sclib
</pre>

The <tt>setenv</tt> command is specific to the C-shell.  You will need to
do what is appropriate for your shell.

The other three keywords specify objects.  This is done by giving a mini
ParsedKeyVal input in a string.  The object is anonymous, that is, no
keyword is associated with it.  Here is an example:

<pre>
setenv MESSAGEGRP "<ShmMessageGrp>:(n = 4)"
</pre>

\section mpqcshmem Shared Memory Multiprocessor with SysV IPC

By default, MPQC will run on only one CPU.  To specify more, you can give a
ShmMessageGrp object on the command line.
The following would run MPQC in four processes:
<pre>
mpqc -messagegrp "<ShmMessageGrp>:(n = 4)" input_file
</pre>

Alternately, the ShmMessageGrp object can
be given as an environmental variable:
<pre>
setenv MESSAGEGRP "<ShmMessageGrp>:(n = 4)"
mpqc input_file
</pre>

If MPQC should unexpectedly die, shared memory segments and semaphores will
be left on the machine.  These should be promptly cleaned up or other jobs
may be prevented from running successfully.  To see if you have any of
these resources allocated, use the <tt>ipcs</tt> command.  The output will
look something like:

<pre>
IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996
T     ID     KEY        MODE       OWNER    GROUP
Message Queues:
Shared Memory:
m 288800 0x00000000 --rw-------  cljanss     user
Semaphores:
s    390 0x00000000 --ra-------  cljanss     user
s    391 0x00000000 --ra-------  cljanss     user
</pre>

To remove the IPC resources used by <tt>cljanss</tt> in
the above example on IRIX, type:

<pre>
ipcrm -m 288800
ipcrm -s 390
ipcrm -s 391
</pre>

And on Linux, type:

<pre>
ipcrm shm 288800
ipcrm sem 390
ipcrm sem 391
</pre>

\section mpqcpthr Shared Memory Multiprocessor with POSIX Threads

By default, MPQC will run with only one thread.  To specify more, you can
give a PthreadThreadGrp object on the command line.  MPQC is not
parallelized to as large an extent with threads as it is with the more
conventional distributed memory model, so you might not get the best
performance using this technique.  On the other the memory overhead is
lower and no interprocess communication is needed.

The following would run MPQC in four threads:

<pre>
mpqc -threadgrp "<PthreadThreadGrp>:(num_threads = 4)" input_file
</pre>

Alternately, the PthreadThreadGrp object can
be given as an environmental variable:
<pre>
setenv THREADGRP "<PthreadThreadGrp>:(num_threads = 4)"
mpqc input_file
</pre>

\section mpqcmpi Shared or Distributed Memory Multiprocessor with MPI

A MPIMessageGrp object is used to run using MPI.  The number of nodes used
is determined by the MPI run-time and is not specified as input data to
MPIMessageGrp.

<pre>
mpqc -messagegrp "<MPIMessageGrp>:()" input_file
</pre>

Alternately, the MPIMessageGrp object can
be given as an environmental variable:
<pre>
setenv MESSAGEGRP "<MPIMessageGrp>:()"
mpqc input_file
</pre>

Usually, a special command is needed to start MPI jobs; typically it is
named <tt>mpirun</tt>.

\section mpqcmp2 Special Notes for MP2 Gradients

The MP2 gradient algorithm uses MemoryGrp object to access distributed
shared memory.  The MTMPIMemoryGrp class is the most efficient and reliable
implementation of MemoryGrp.  It requires a multi-thread aware MPI
implementation, which is still not common.  To run MP2 gradients on a
machine with POSIX threads and an multi-thread aware MPI, use:

<pre>
mpqc -messagegrp "<MPIMessageGrp>:()" \
     -threadgrp "<PthreadThreadGrp>:()" \
     -memorygrp "<MTMPIMemoryGrp>:()" \
     input_file
</pre>

or

<pre>
setenv MESSAGEGRP "<MPIMessageGrp>:()"
setenv THREADGRP "<PthreadThreadGrp>:()"
setenv MEMORYGRP "<MTMPIMemoryGrp>:()"
mpqc input_file
</pre>

\section mpqcmp2r12 Special Notes for MP2-R12 energies

<p>
<b>Distributed Memory</b>

The MP2-R12 energy algorithm is similar to the MP2 energy algorithm that uses
MemoryGrp object to access distributed memory. Hence the MTMPIMemoryGrp is the
recommended implementation of MemoryGrp for such computations (see \ref mpqcmp2).
</p>

<p>
<b>Disk I/O</b>

In contrast to the MP2 energy and gradient algorithms, the MP2-R12 energy algorithm
may have to use disk to store transformed MO integrals if a single pass through
the AO integrals is not possible due to insufficient memory. The best option in such case
is to increase the total amount of memory available to the computation by either
increasing the number of tasks or the amount of memory per task or both.

When increasing memory further is not possible, the user has to specify which
type of disk I/O should be used for the MP2-R12 energy algorithm. It is done through
the <tt>r12ints</tt> keyword in input for the MBPT2_R12 object. The default choice
is to use POSIX I/O on the node on which task 0 resides. This kind of disk I/O
is guaranteed to work on all parallel machines, provided there's enough disk space
on the node. However, this is hardly most efficient on machines with
some sort of parallel I/O available.
On machines which have an efficient implementation of MPI-IO
the <tt>r12ints</tt> should be set instead to <tt>mpi-mem</tt>.
This will force the MBPT2_R12
object to use MPI-IO for disk I/O. It is user's responsibility to make sure
that the MO integrals file resides on an MPI-IO-compatible file system.
Hence the <tt>r12ints_file</tt> keyword, which specifies the name of the MO integrals
file, should be set to a location which is guaranteed to work properly with MPI-IO.
For example, on IBM SP and other IBM machines which have General Parallel File System
(GPFS), the user should set <tt>r12ints = mpi-mem</tt> and <tt>r12ints_file</tt>
to a file on a GPFS file system.
</p>

<p>
<b>Integral object</b>
<br>

At the moment, MBPT2_R12 objects require specific specialization of Integral,
IntegralCints. Thus in order to compute MP2-R12 energies, your version of MPQC
needs to be compiled with support for IntegralCints.  A free, open-source
library called <tt>libint</tt> is a prerequisite for IntegralCints\if html (see \ref compile)\endif.
In order to use IntegralCints as the default Integral object,
add <tt>-integral "<IntegralCints>:()"</tt> to the command line,
or set environmental variable <tt>INTEGRAL</tt> to <tt>"<IntegralCints>:()"</tt>.
</p>

\section mpqccca Special Notes for CCA Components

<p>
<b>Common Component Architecture (CCA)</b>

Portions of MPQC functionality are being packaged into CCA components.
For general overviews of CCA technology and framework usage, please see 
<a href="http://www.cca-forum.org">www.cca-forum.org</a> (the tutorial in particular) and the 
<a href="http://www.cca-forum.org/~cca-chem/doc-apps-0.2/index.html">cca-chem-apps</a> 
documentation.
MPQC components may be utilized directly within the ccaffeine framework, while some 
components may be instantiated and used within MPQC itself, making use of an embedded
CCA framework.
</p>

<p>
<b>CCA Runtime Environment</b>

For MPQC runs utilizing embedded components, the runtime environment for the CCA
framework must be specified.
The colon-separated path used to locate component libraries must be specified either 
using the <tt>-cca-path</tt> command-line option or using the <tt>cca_path</tt> key 
within the <tt>mpqc</tt> section of a keyval input.
The colon-separated list of component sidl class names which will be referenced within the
input must be specified using either the <tt>-cca-load</tt> command-line option or using
the <tt>cca_load</tt> key within the <tt>mpqc</tt> section of a keyval input.
If defaults for the cca-path and cca-load options are desired, <tt>do_cca</tt> must be 
set to <tt>yes</tt> in the keyval input.

*/