next up previous
Next: Compiling and running unstructured Up: swanimp Previous: User dependent changes and


Usage of SWAN executable

To help you in editing an command file for SWAN input, the file swan.edt is provided.


Two run procedures are provided among the source code, one for the Windows platform, called swanrun.bat, and one for the UNIX/Linux platform, called swanrun. Basically, the run procedure carries out the following actions:

On other operating system a similar procedure can be followed. For parallel MPI runs, the program mpirun or mpiexec is needed and is provided in the MPICH2 distribution.


Before calling the run procedure, the environment variable PATH need to be adapted by including the pathname of the directory where swan.exe can be found. In case of Windows, this pathname can be specified through the category System of Control Panel (on the Advanced tab, click Environment Variables). In case of UNIX or Linux running the bash shell (sh or ksh), the environment variable PATH may be changed as follows:
export PATH=${PATH}:/usr/local/swan
if /usr/local/swan is the directory where the executable swan.exe is resided. In case of the C shell (csh), use the following command:
setenv PATH ${PATH}:/usr/local/swan

If appropriate, you also need to add the directory path where the bin directory of MPICH2 is resided to PATH to have access to the command mpiexec.


You may also specify the number of threads to be used during execution of the multithreaded implementation of SWAN on multiprocessor systems. The environment variable for this is OMP_NUM_THREADS and can be set like

export OMP_NUM_THREADS=4
or
setenv OMP_NUM_THREADS 4
or, in case of Windows,
OMP_NUM_THREADS = 4
When dynamic adjustment of the number of threads is enabled, the value given in
OMP_NUM_THREADS represents the maximum number of threads allowed.


The provided run procedures enable the user to properly and easily run SWAN both serial as well as parallel (MPI or OpenMP). Note that for parallel MPI runs, the executable swan.exe should be accessible by copying it to all the multiple machines or by placing it in a shared directory. When running the SWAN program, the user must specify the name of the command file. However, it is assumed that the extension of this file is swn. Note that contrary to UNIX/Linux, Windows does not distinguish between lowercase and uppercase characters in filenames. Next, the user may also indicate whether the run is serial or parallel. In case of Windows, use the run procedure swanrun.bat from a command prompt:
swanrun filename [nprocs]
where filename is the name of your command file without extension (assuming it is swn) and nprocs indicates how many processes need to be launched for a parallel MPI run (do not type the brackets; they just indicate that nprocs is optional). By default, nprocs = 1. You may also run on a dual/quad core computer; do not set nprocs.


The command line for the UNIX script swanrun is as follows:
./swanrun -input filename [-omp n | -mpi n]
where filename is the name of your command file without extension. Note that the script swanrun need to be made executable first, as follows:
chmod +rx ./swanrun
The parameter -omp n specifies a parallel run on n cores using OpenMP. Note that the UNIX script will set OMP_NUM_THREADS to n. The parameter -mpi n specifies a parallel run on n processors using MPI. The parameter -input is obliged, whereas the parameters -omp n and -mpi n can be omitted (default: n = 1). To redirect screen output to a file, use the sign >. Use an ampersand to run SWAN in the background. An example:
./swanrun -input f31har01 -omp 4 > swanout &

For a parallel MPI run, you may also need a machinefile that contains the names of the nodes in your parallel environment. Put one node per line in the file. Lines starting with the # character are comment lines. You can specify a number after the node name to indicate how many cores to launch on the node. This is useful e.g., for multi-core processors. The run procedure will cycle through this list until all the requested processes are launched. Example of such a file may look like:

# here, eight processes will be launched
node1
node2:2
node4
node7:4
Note that for Windows platforms, a space should be used instead of a colon as the separation character in the machinefile.


SWAN will generate a number of output files: If indicated by the user, a single or multiple hotfiles will be generated depending on the number of processors, i.e. the number of hotfiles equals the number of processors (see the User Manual). Restarting a (parallel MPI) run can be either from a single (concatenated) hotfile or from multiple hotfiles. In the latter case, the number of processors must be equal to the number of generated hotfiles. If appropriate, the single hotfile can be created from a set of multiple hotfiles using the program hcat.exe as available from SWAN version 40.51A. This executable is generated from the Fortran program swanhcat.ftn. A self-contained input file hcat.nml is provided. This file contains, e.g. the (basis) name of the hotfile. To concatenate the multiple hotfiles into a single hotfile just execute hcat.exe.


next up previous
Next: Compiling and running unstructured Up: swanimp Previous: User dependent changes and
The SWAN team 2017-07-31