SPINS Tutorial

This is a tutorial for getting up to speed with SPINS using the case mode1_mode2. The first part of the tutorial discusses running the case with the default parameters, some basic analysis tools and techniques, and manually changing parameters. The second part of the tutorial explores more parameter combinations using Matlab driver scripts to automate the workflow. The final part uses a Matlab script spins_refinement.m to interpolate an existing SPINS output onto a finer grid and restart SPINS at higher resolution.

You must first have followed the instructions to install SPINS and compile the case file.

Part 1: Getting familiar with SPINS

Run

Transfer the executable (mode1_mode2.x) and the configuration file (spins.conf) into a clean directory.

Run simulation by executing mpirun -np 4 ./mode1_mode2.x on the command line, or submit the job to the queue on a Compute Canada system with a submit script (see submitting jobs to Graham).

This will create two types of files

1. Output files
   • These are of the form rho.3 where the name (rho) is the variable and the extension is the output number

   - For example rho.3 is the density field at output number 3. Zero-indexing is used, so this is the 4th density file

   • Since these can be memory expensive, they are created relatively infrequently
2. Diagnostic files
   • These will generally be text files and contain information about the simulation
   • Matlab plotters for the diagnostic files are found in SPINS MATLAB tools, available here.

Diagnostic Files
File	Optional	Matlab plotter	Description
diagnostics.txt	No	plot_diagnos	High temporal resolution information about the simulation (occurs at every time step). Examples include: KE, max velocity, energy budget terms, simulation timings.
stresses_top.txt and/or stresses_bottom.txt	Yes	plot_stress	Surface forces and surface stress extrema at the top/bottom surfaces. Only applicable if no slip boundary condition is used.
plot_times.txt	No	plot_diagnos	Explicit statement of the time associated with each output. Also gives the time to write output files.

Analyze

Matlab and Python are the primary languages used for analyzing SPINS simulations. These are great for computation of quantities specific to your study. The Python (SPINSpy) and Matlab (SPINSmatlab) packages contain much of the important tools for each language. Three dimensional visualization should use Paraview or VisIt (see Visualization).

Here, we will use Matlab to make a simple plot of the density field. We assume that the SPINSmatlab package is on your path.

1. gdpar = spins_gridparams(); split_gdpar
   • This reads in the grid and parameters and places them in a structure (gdpar). split_gdpar separates the two sub-structures into the structures par and gd, which are the parameters and grid, respectively.
   • par contains information from spins.conf in addition to further simulation parameters
   • gd contains the grid. x,y,z grids can be extracted with gd.x, gd.y, or gd.z
   • The default setting is that the grid is unmapped and vector grids are produced, to get the full grid use gdpar = spins_gridparams('FastFull'); or gdpar = spins_gridparams('Full');
2. spins_plot2d('rho',0);
   • First argument is the field to plot
   • Second argument is the output number. The simulation time can also be specified in this argument as a string. spins_plot2d('rho','2'); will plot the simulation at the closest output to t=2s. Many optional arguments exist (type help spins_plot2d for more options).

To read an individual file: u = spins_reader('u',10);

Restart

Should you need to restart the simulation (due to expenditure of allocated time, require more time, a node failure, or otherwise) simply change the restart flags in the configuration file.

The simplest change is to set

restart = true
restart_time = 5.5
restart_sequence = 11

where the simulation will restart at output 11 which corresponds to t=5.5s. These numbers can be found in the last row of plot_times.txt.

SPINS also has an automatic safety dump if the allocated time is close to expiring (See automatically specify the runtime for more info). In this case, if the safety write was done successfully then you only need to set

restart_from_dump = true

Change

If after analyzing the simulation you realize that you wanted to change a parameter (it wasn't quite right), then you only need to change the parameter in the configuration file (as opposed to older editions of SPINS where you'd need to recompile the entire code).

Here is a description of the problem parameters:

 --delta_rho     arg   Density difference between upper and lower layers (as a percentage of rho_0)
 --pyc_loc       arg   Pycnocline location
 --h_halfwidth   arg   Pycnocline half-width
 --delta_x       arg   Horizontal transition half-width
 --H2            arg   Height of mixed region (mode-2) - sets mode-2 wave amplitude
 --H1            arg   Heigth of mixed region (mode-1) - sets mode-1 wave amplitude
 --L1            arg   Length of region 1 (mode-2)
 --L2            arg   Length of region 2 (mode-1)
 --dye1_loc      arg   Location of dye 1
 --dye2_loc      arg   Location of dye 2
 --dye1_width    arg   Width of dye 1
 --dye2_width    arg   Width of dye 2
 --dye_halfwidth arg   Sharpness of the dye transition
 --enable_tracer       Enable evolution of second tracers

If you run the simulation in the same directory, remember to clear all simulation files (output and diagnostic files).

Only Mode-1 ISW

To change the simulation to only have the left mode-1 ISW change spins.conf to have:

H2 = 0.0

This will set the mode-2 amplitude to zero.

Only Mode-2 ISW

To change the simulation to only have the right mode-2 ISW change spins.conf to have:

H1 = 0.0

This will set the mode-1 amplitude to zero.

Gravity Current

To change the simulation to have a rightward moving gravity current change spins.conf to have:

pyc_loc = -0.2
H1 = -1.0
H2 = 0.0

This will move the pycnocline below the bottom boundary, set the mode-1 amplitude to result in a region of high density at on end of the tank, and give no mode-2 contribution.

Try it yourself. See what each parameter does when they're changed.

Extend to 3D

Often, a case initially simulated in 2D will undergo various physical processes that allow it to become 3D, thus, in many circumstances, a 2D simulation could be a misrepresentation of the overall dynamics. To this end, there are different mechanisms built into SPINS to deal with this. The simplest process is the run a 2D simulation until you believe that 3D effects will have occurred. This is problem specific and is left up to the choice of the modeller.

Once a particular output is chosen, the simulation can be extended into the spanwise (assumed to be the $y$ dimension), and the simulation can be restarted from that point and run in 3D. To use this functionality, the script extend_all() has been included in the SPINSmatlab toolbox.

1. Run the simulation until the output 30
2. Navigate to the directory where the output is stored. Go into MATLAB and enter extend_all(30,0.1,32).
3. extend_all creates a sub-directory called extended/ which contains the now 3D data, the spins.conf with updated grid and restarting information, and the executable.
4. Navigate into the extended/ directory and run the executable.

Note now that the data is three dimensional, to read it into MATLAB, you must choose a slice (an $x-y$, $x-z$, or $y-z$ cross-section) to plot. This is commonly done in two ways.

1. You can use spins_reader() to read in slices of fields and grids by entering spins_reader(field,output,x_start:x_end,y_start:y_end,z_start:z_end). [] implies the entire dimension. This is imperative for large datasets, as MATLAB has immense difficulty opening very large arrays without freezing.

1. For smaller sized 3D data sets, the entire field can be loaded in and slices taken at different points in analysis. To get a fast plot, use the following command:

imagesc(flipud(squeeze(u(:,y_ind,:))'))

if you want to plot an $x-z$ slice at the span corresponding to y_ind. The squeeze() command remove the singleton dimension leaving the field as a 2D array. The combination of the flipud() and transpose (') operations allow the bottom of the field to align with the bottom of the plot.

Note that an $x-y$ slice does not need the flipud() and transpose (') operations.

Editing Casefiles

This needs to be done.