SPINS User Guide

Welcome to the SPINS user guide.

Other information can be found on this SPINS Documentation page, though not everything listed there is fully incorporated into the master SPINS branch.

The basics

The SPINS model is a Navier-Stokes solver that gets parameters and initial/boundary conditions from calls to user-provided routines. The user-provided routines are encapsulated in class derived from BaseCase (see BaseCase.hpp).

Creating your own custom configuration involves supplying the user-provided routines in a derived class based on BaseCase. The case file cases/doc_minimal.cpp shows the structure of a case file. It usually makes sense to start with a similar case file and customise it.

SPINS components

SPINS consists of a bunch of C++ source files and a bunch of case files, and it requires four libraries. UMFPack, AMD and Blitz++ are supplied with SPINS, and it uses the system-installed FFTW.

Directory structure:

• spins/src - SPINS source files
• spins/src/cases - A few dozen example case files
• spins/matlab - Some helper functions for MATLAB analysis

How to get SPINS running

SPINS is hosted in a git repository on the UW git server. A guide to using git can be found here: http://git-scm.com/book. If your system does not have a working copy of git that can access http-based repositories (winisk and kazan are currently notable examples), you may get a full copy of the current repository from Christopher Subich (this replaces step #1 below).

You will need to get the code, build the dependencies, build the model and then run it.

Extracting the code from the git repository

• Create a directory in which to store the code.
• In that directory type "git clone https://git.uwaterloo.ca/SPINS/SPINS_main.git".
• This will create a directory called SPINS_main.

Building SPINS

One-time setup

• Go to the systems directory.
• Type ./makemake.sh [system]. This will construct the system-specific settings for the makefile.
  • This script reads and processes an appropriate script from the systems/ subdirectory; these files contain variable definitions for compiler names, include/library options, and other attributes that are necessary at build time.
  • There are several scripts in the systems/ subdirectory, and in general one needs to be written for each unique system based on its idiosyncrasies.
  • makemake.sh takes the system name as an optional argument. If not specified, it will try to guess the appropriate host file based on the current hostname. E.g., building on winisk will try to read systems/winisk.sh. If this is inappropriate (such as on clusters, where login nodes are numbered), then the system name can be specified at the command-line, e.g. ./makemake.sh graham to read systems/graham.sh.
• Execute ./make_deps.sh in the main repository by typing ./make_deps.sh [system] -j. This file may need to be edited to select which libraries aren't present in the current build environment; when in doubt build everything. FFTW and Boost are the libraries most likely to be already installed system-wide.

To build your case-file

• Enter the src directory.
• Type make cases/case_directory/your_case.x
• This requires a file called your_case.cpp in the cases/case_directory directory. There are several cases included with the code so you may want to start with one of those.
• After successful compilation, an executable called your_case.x is created.

Running SPINS

• Please be careful not to run in your home directory on machines like boogaloo or graham. Typical cases output a great deal of data, and can quickly fill up your /home quota (or the full partition, on non-quota systems).
• The code can be executed using mpirun e.g "mpirun -np 4 ./your_case.x".
• Most cases require a configure file called spins.conf. Options included in the command-line or spins.conf are configured in the main() function of the respective case.

Updating SPINS

Development of spins is on-going and it is advisable to have the most up-to-date version.

To update spins, make sure the SPINS directory is first clean in the git sense (no uncommitted and changed files). Check this by running git status. Once the directory is clean, run git pull.

SPINS was recently (Spring 2018) moved from Belize (which has been decommissioned) to the UW git server. If you installed SPINS prior to this transfer, a git pull will not work as the remote branch is still looking to Belize. Update the remote with

git remote set-url origin https://git.uwaterloo.ca/SPINS/SPINS_main.git

before running git pull.

Sending SPINS Output to a Log-File

For single-processor jobs, it is quite simple to route standard output (stdout) from the terminal to a log-file using myrun_x > logfile.log. With mpirun, this won't do the trick and the process is a bit more convoluted. The command would be:

mpirun -np <numProcs> myrun_x > logfile.log 2>&1 < /dev/null &

The > logfile.log 2>&1 part routes both stdout (1) and stderr (2) to logfile.log. The < /dev/null part tells mpirun to accept 'null' as input instead of the command-line (this allows you to close the terminal while the job is running). Finally, the & at the end makes the whole process run in the background and returns you to the shell prompt.