Run instructions

In this chapter it is assumed that you have a built SWAN available on your computer, either after installation as described in Chapter 3, or downloaded from the SWAN website (for Windows).


IMPORTANT NOTE:

 The pre-built SWAN for Windows, available at the SWAN website, has been compiled using the Intel Fortran Compiler Classic (as part of Intel

oneAPI HPC Toolkit) and is linked to DLL libraries. Therefore you may run into problems when attempting to run SWAN on your Windows computer, unless you have the Microsoft

Visual Studio installed on your system. At any rate, you will need to run/install the Intel Fortran Compiler Runtime for Windows. You need only the latest version; it will work with older compiler versions.

Before running SWAN you must first complete a command file. Consult the SWAN User Manual how to specify the various settings and instructions to SWAN concerning the (input) grids, boundary conditions, physics, numerics and output. To help you in editing a command file for SWAN input, the file swan.edt is provided which contains the complete set of commands.


After completing the command file, you may run SWAN. Two command-line utilities are provided among the source code, one for running SWAN on the Windows platform, called swanrun.bat, and one for running SWAN on the Linux/UNIX platform, called swanrun. Basically, the run procedure carries out the following actions:

• Copy the command file with extension swn to INPUT (assuming INPUT is the standard file name for command input, see Chapter 4).
• Run SWAN.
• Copy the file PRINT (assuming PRINT is the standard file name for print output, see Chapter 4) to a file which name equals the command file with extension prt.

On other operating system a similar procedure can be followed. For parallel MPI runs, the program mpirun or mpiexec may be needed instead (usually provided in an MPI 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 setting Environment Variables. (Hit the Window key plus R to get command prompt. Then type sysdm.cpl, go to Advanced and select Environment Variables. Note that you must be an administrator in order to modify an environment variable.) In case of Linux or UNIX 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 MPI is resided to PATH to have access to the command mpirun or mpiexec.


You may also specify the number of threads to be used during execution of the multi-threaded 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 utilities 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 Linux/UNIX, 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 the parameter nprocs is optional). By default, $nprocs = 1$.


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:

• A print file with the name PRINT that can be renamed by the user with a batch (DOS) or script (UNIX) file, e.g. with the provided run procedures. For parallel MPI runs, however, a sequence of PRINT files will be generated (PRINT-001, PRINT-002, etc.) depending on the number of processors. The print file(s) contain(s) the echo of the input, information concerning the iteration process, possible errors, timings, etc.
• Numerical output (such as table, spectra and block output) appearing in files with user provided names.
• A file called Errfile (or renamed by the run procedures as well as more than one file in case of parallel MPI runs) containing the error messages is created only when SWAN produces error messages. Existence of this file is an indication to study the results with more care.
• A file called ERRPTS (or renamed by the run procedures as well as more than one file in case of parallel MPI runs) containing the grid-points, where specific errors occured during the calculation, such as non-convergence of an iterative matrix-solver. Existence of this file is an indication to study the spectrum in that grid-point with more care.

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 in the SWAN package. This file contains, e.g. the (basis) name of the hotfile. To concatenate the multiple hotfiles into a single hotfile just execute hcat.exe.