.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro 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 Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH pbs_mpihp 8B "23 October 2017" Local "PBS Professional"
.SH NAME
.B pbs_mpihp 
\- run an MPI application in a PBS job with HP MPI

.SH SYNOPSIS
.B pbs_mpihp
[-h <host>] [-np <number>] [<other HP mpirun options>] <program> [<args>]

.B pbs_mpihp  
[<HP mpirun options>] -f <appfile> [-- [<extra_args>]]

.B pbs_mpihp
--version

.SH DESCRIPTION
The PBS command 
.B pbs_mpihp 
replaces the standard 
.I mpirun
command in a PBS
HP MPI job, for executing programs.  
.B pbs_mpihp 
is a front end to the HP MPI version of mpirun.  

When 
.B pbs_mpihp 
is invoked from a PBS job, it 
processes the command line arguments, then calls standard HP mpirun to
actually start the MPI ranks.  The ranks created are mapped onto
CPUs on the vnodes allocated to the PBS job.  The environment variable 
.B MPI_REMSH 
is set to 
.I $PBS_EXEC/bin/pbs_tmrsh.  
This causes
the processes that are created to become part of the PBS job.

The path to standard HP mpirun is found by checking to see if a link
exists with the name 
.I "PBS_EXEC/etc/pbs_mpihp".  
If this link exists,
it points to standard HP mpirun.  If it does not exist, a call
to 
.I "mpirun -version" 
is made to determine whether it is HP mpirun.
If so, the call is made to "mpirun" without an absolute path.
If HP mpirun cannot be found, an error is output, all temp
files are cleaned up and the script exits with value 127.

If 
.B pbs_mpihp 
is invoked from outside a PBS job, it passes all of
its arguments directly to standard HP mpirun without further processing.

.B Configuration
.br
When HP MPI is wrapped with pbs_mpihp, "rsh" is the default used to 
start the mpids. If you wish to use "ssh" or something else, 
be sure to set the following in $PBS_HOME/pbs_environment:

.RS 5
.I PBS_RSHCOMMAND=ssh
.RE

or put the following in the job script:

.RS 5
.I export PBS_RSHCOMMAND=<rsh_cmd>
.RE

.SH USAGE
Usage is the same as for HP 
.I mpirun.

.B pbs_mpihp <program>
allows one executable to be specified.

.B pbs_mpihp -f <appfile>
uses an
.I appfile 
to list multiple executables.
The format is described in the HP mpirun man page.  If this form
is used from inside a PBS job, the file is read to determine
what executables are to be run and how many processes are
started for each.

Executing 
.B pbs_mpihp 
with the 
.I -client 
option is not supported under PBS.

.SH OPTIONS
All options except the following are passed directly to HP mpirun
with no modification.

.IP "-client" 15  
Not supported.

.IP "-f <appfile>"  
The specified 
.I appfile 
is read by 
.B pbs_mpihp.

.IP "-h <host>" 15    
Ignored by 
.B pbs_mpihp.

.IP "-l <user>"     
Ignored by pbs_mpihp.

.IP "-np <number>" 15  
Specifies the 
.I number 
of processes to run on the PBS vnodes.

.IP "--version" 15
The 
.B pbs_mpihp
command returns its PBS version information and exits.
This option can only be used alone.

.SH EXIT VALUES

.IP 127 15
If HP
.B mpirun
cannot be found

.SH SEE ALSO
The 
.B PBS Professional Administrator's Guide
.LP
mpirun(1)