SPINS User Guide

Welcome to the SPINS user guide.

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

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 http://belize.math.uwaterloo.ca/~csubich/spins.git".
• This will create a directory called spins.

Building the dependencies

• Go to the spins directory.
• Type "./make_deps.sh".

Building SPINS

• Go to the systems directory.
• Type "./makemake.sh". This will build the code based on the system architecture. Note that there are several files that include instructions for several systems e.g. gpc.sh. makemake.sh will try to guess which instructions to use if you do not include options in your makemake.sh call from the command line.
• Enter the src directory.
• Type "make cases/your_case.x".
• This requires a file called your_case.cpp in the cases 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 belize or winisk.
• The code can be executed using mpirun e.g "mpirun -np 4 ./your_case.x".
• Please note that some cases may require command line options or a configure file called spins.conf.

Examples of common operations

You can find examples of how to do various operations by digging through the case files. Some of the common operations are reproduced here.

Using wave_reader.cpp

The case file wave_reader.cpp is a special case used for initialising the model with specified velocity and density fields. A configuration file, spins.conf, is used to hand parameters to SPINS. An example spins.conf is provided below.

// Todo: paste a spins.conf here

Generating the grid files: regular grid

For an unmapped grid, include the following call in your case file's constructor to generate the grid files and grid file readers:

automatic_grid(MinX,MinY,MinZ);

where MinX, MinY and MinZ are the coordinates of the starting corner of your grid.

Using a mapped grid

Can someone write this?

Analytic initialisation

Can someone write this?

Boundary conditions

Can someone write this?

Forcing / sponge regions

Can someone write this?

Online Analysis

Some analysis can be done online, some examples are shown below.

Energy Diagnostics

If you're using a periodic grid, use this for computing kinetic energy diagnostic

double dV = (Lx/Nx)*(Ly/Ny)*(Lz/Nz);
double ke = 0.5*rho_0*pssum(sum( u*u+v*v+w*w ))*dV; // KE

If you're on a Chebyshev grid, you can use this for the KE computation

double ke = pssum(sum((*get_quad_x())(ii)*(*get_quad_y())(jj)*(*get_quad_z())(kk)*
                  (pow(u(ii,jj,kk),2)+pow(v(ii,jj,kk),2)+pow(w(ii,jj,kk),2))));

and you will need to compute the quadrature weights in the constructor

// Compute the quadrature weights
compute_quadweights(size_x(),size_y(),size_z(),
                    length_x(),length_y(),length_z(),
                    type_x(),type_y(),type_z());