source: ThirdParty/mpqc_open/src/bin/mpqc/mpqcrun.dox

/** \page mpqcrun

The mpqcrun program simplifies running MPQC.

\if man
<h1>Synopsis</h1>

<pre>
mpqcrun [options] [file1.in] [file2.in] ...
</pre>
\endif

<h1>Description</h1>

The mpqcrun program simplifies the task of running MPQC on multiple input
files.  Although it was primarily designed to run the validation suite,
mpqcrun, is
general enough to be useful in other situations.  If multiple nodes or
processors are present, it can be used to manage multiple invocations of
MPQC.

<h1>Running mpqcrun</h1>

mpqcrun takes the following command line options:

<dl>

  <dt><tt>--mpqc</tt> path<dd>The mpqc executable to use.
  <dt><tt>--objdir</tt><dd>Run the mpqc executable in the compile directory,
                           rather than the install directory.
  <dt><tt>--small</tt><dd>Skip big runs in verification suite.
  <dt><tt>--nnodeperjob</tt> n<dd>Run with n nodes per job.  If this is <tt>nnode</tt>, use all available nodes.
  <dt><tt>--nprocpernode</tt> n<dd>Run with n processes per node.
  <dt><tt>--nprocperjob</tt> n<dd>Run with n processes per job.  The default is to use all available processors.
  <dt><tt>--nthreadperproc</tt> n<dd>Use n threads per process.
  <dt><tt>--threadgrp</tt> grp<dd>Use the given threading layer.
  <dl>
       <dt>grp=<tt>none</tt><dd>Use MPQC's default.
       <dt>grp=<tt>proc</tt><dd>Do a single threaded run.
       <dt>grp=<tt>posix</tt><dd>Use POSIX threads.
  </dl>
  <dt><tt>--messagegrp</tt> grp<dd>Use the given communication layer.
  <dl>
       <dt>grp=<tt>none</tt><dd>Use MPQC's default.
       <dt>grp=<tt>proc</tt><dd>Does a single processor run.
       <dt>grp=<tt>mpi</tt><dd>Use MPI.
  </dl>
  <dt><tt>--memorygrp</tt> grp<dd>Use the given remote memory communication layer.
  <dl>
       <dt>grp=<tt>none</tt><dd>Use MPQC's default.
       <dt>grp=<tt>proc</tt><dd>Does a single processor run.
       <dt>grp=<tt>mtmpi</tt><dd>Use multi-threaded MPI.
       <dt>grp=<tt>armci</tt><dd>Use ARMCI.
  </dl>
  <dt><tt>--launch</tt> cmd<dd>Use the given command to launch jobs. See below.
  <dt><tt>--nodefile</tt> file<dd>Specifies a file listing nodes to use.
                                 Duplicated nodes are removed.
  <dt><tt>--nodes</tt> nodes<dd>Specifies list of machines to use.
                                A range of nodes can be given with two
                                integers separated by a dash.  Groups of
                                nodes can be separated by a comma.
  <dt><tt>--nodename</tt> fmt<dd>This is a format string that converts the
                                 node number to its name.
  <dt><tt>--seq</tt> regex<dd>Run inputs matching reqex sequentially.
                              This is useful when one input requires that
                              another be run first, and more than
                              one job is run at a time.
  <dt><tt>--exclude</tt> regex<dd>Exclude files matching regex.
  <dt><tt>--readdir</tt> dir<dd>Run mpqc on all files matching dir/*.in.
  <dt><tt>--inputprefix</tt> prefix<dd>Prepend prefix to all input file names.
  <dt><tt>--outputprefix</tt> prefix<dd>Prepend prefix to all output file names.
  <dt><tt>--count</tt><dd>Print the number of input files that would be run.
  <dt><tt>--printfiles</tt><dd>Print the list of input files that would be run.
  <dt><tt>--rerun</tt><dd>Overwrite output file, even if up-to-date.
  <dt><tt>--onlynew</tt><dd>Do not overwrite output file, even if not up-to-date.
  <dt><tt>--simpout</tt><dd>Do not append extra info like nnode to filename.
  <dt><tt>--uniqout</tt><dd>Generate unique output filenames.
  <dt><tt>--autoout</tt><dd>Generate output filenames by replacing
                            the suffix with "out".
  <dt><tt>--verbose</tt><dd>Print out what action is to be taken on each file.
  <dt><tt>--debug</tt><dd>Don't actually run mpqc.
  <dt><tt>--help</tt><dd>Print the documentation.

</dl>

The cmd given with the <tt>--launch</tt> option can contain special strings
that will be substituted:
<dl>
  <dt><tt>\%MPQC%</tt><dd>The MPQC program to run.
  <dt><tt>\%INPUT%</tt><dd>The input filename.
  <dt><tt>\%OUTPUT%</tt><dd>The output filename.
  <dt><tt>\%NPROC%</tt><dd>The number of processes to start.
  <dt><tt>\%NODEFILE%</tt><dd>The name of a file containing the node names.
  <dt><tt>\%NODELIST%</tt><dd>A comma separated list of node names.
</dl>

For these last two, if they are contained within square brackets
and a substitution is not available, then everything within the
the brackets is removed.

This argument will launch MPI jobs giving mpirun a nodefile.
<pre>
  --launch "mpirun [-hf %NODEFILE%] -n %NPROC% %MPQC% -o %OUTPUT% %INPUT%"
</pre>

This argument will launch MPI jobs giving mpirun list of hosts on the
command line.
<pre>
  --launch "mpirun [-H %NODELIST%] -n %NPROC% %MPQC% -o %OUTPUT% %INPUT%"
</pre>

<h1>License</h1>

mpqcrun is open-source software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

<h1>Warranty</h1>

mpqcrun is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

*/