Matlab-to-SPINS grid ordering

Introduction

The idea here is to use Matlab to specify the initial density and velocity fields and then use wave_reader to initialize the simulations. The advantages are that 1) a scripting language like Matlab is more suitable for the task of testing, debugging and visualizing complicated initial conditions (such as an ISW-induced flow field computed using the DJL equation) than a compiled language like C++, and 2) through the combination of a Matlab program and a Bash script, multiple different simulations can be initialized automatically and simultaneously. Currently, the code works for 2D rectangular domains (no topography).

Getting the code

The code is hosted in a git repository on the UW git server. To extract the code from the git repository, go to (or create) the directory in which you want to run simulations using SPINS. In that directory, type git clone https://git.uwaterloo.ca/c2xu/matlab2spins.git. This will create a directory called matlab2spins where the code is stored.

Components

Driver files

There are several driver files in which the user can specify the input parameters (including the analytical form of the initial/background density and velocity profiles) and run the program. It is highly recommended that you test/debug the case on a local machine first by setting test = true;. When you are ready to run the program on a remote machine (e.g. Graham), setting test = false; will allow the program to write data onto disk. Note that these driver files are case specific, and you will probably need to write your own driver files based on these templates.

• driver_iswlong.m: All-in-one driver file for lock-release type of setup. It reads a text file which consists of a table of parameters for multiple different cases. For each of these cases, the code creates a new directory and saves the density field as rho.orig (and any other essential files in their appropriate forms) of this particular case in this directory.
• driver_unidomain.m: Driver file for solving the DJL or TG equation in a single domain.
• driver_multidomain.m: Driver file for solving the DJL and/or TG equations separately in two different subdomains, which are then combined together into the full computational domain.
• driver_readtable.m: Similar to driver_iswlong.m but can solve for the DJL or TG equation (in a single domain).

DJL solver

Adopted from Michael Dunphy's DJL solver. To solve for the DJL equation, set wave = 'djl'; in the driver file and specify the APE you want to use.

• get_eta.m: Main iteration loop of the DJL solver.
• md_diff.m: Michael Dunphy's differentiation matrix for the DJL solver.
• iswpost.m: Post processing to get u, w, and rho.
• iswpic.m: Making plots.
• find_contour.m: Find the contour of Ri=0.25 in the DJL solution.
• contour_data.m: Function called by find_contour.m.

Taylor-Goldstein solver

For traveling and standing linear waves with and without rotation in two dimensions. To solve for the TG equation, set wave = 'lin'; in the driver file and specify various input parameters.

• tg.m: Taylor-Goldstein equation solver for traveling/standing linear waves.
• cheb.m: Chebyshev differentiation matrix and grid for the TG solver adopted from Trefethen (2000).

Interpolation

Except for driver_iswlong.m, interpolation of the data from the DJL and/or TG solver to the SPINS grid is required. Matlab's built-in interpolation methods such as linear, cubic, and spline are available. The spectral method by David Deepwell (resize_x.m and resize_z.m) is also available, except that it does not workfor a Chebyshev grid at this time.

• spins_interp2d.m: Interpolation of flow fields from DJL/TG solver onto SPINS grid.
• resize_x.m: Spectral interpolation in x-direction.
• resize_z.m: Spectral interpolation in z-direction.

Matlab-to-SPINS grid ordering

Finally, the code saves the u, w, and rho fields as SPINS input files u.orig, w.orig, and rho.orig, respectively, and writes the relevant parameters into the SPINS configuration file, spins.conf.

• matlab2spins2d.m: Writing data to disk.

Running the code on Graham

Running a single case using driver_unidomain.m or driver_multidomain.m

Before running the code on Graham, test the case you want to run on a local machine first. When you are ready to run the code on Graham, use the following script to submit a job. You will need to replace <USER> with your user ID, <DRIVER_SCRIPT> with driver_unidomain.m or driver_multidomain.m, and <YOUR_CASE_NAME> with the case name identical to casename you specified in driver_unidomain.m or driver_multidomain.m. Also, make sure you have a copy of wave_reader.x for Graham available in the matlab2spins directory, and a "dummy" (or whatever name you want to call it) directory available for log/error files.

#!/bin/bash
# bash script for submitting a Matlab job to the sharcnet Graham queue

#SBATCH --mem-per-cpu=2G                    # memory per processor (default in Mb)
#SBATCH --time=01-00:00                     # time (DD-HH:MM)
#SBATCH --job-name="<YOUR_CASE_NAME>"       # job name
#SBATCH --input=<DRIVER_SCRIPT>             # Matlab script
##SBATCH —dependency=afterok:<jobid>        # Wait for job to complete

##SBATCH --ntasks=1                         # number of processors
#SBATCH --nodes=1                           # number of nodes
#SBATCH --ntasks-per-node=32                # processors per node
#SBATCH --output=../dummy/sim-%j.log        # log file
#SBATCH --error=../dummy/sim-%j.err         # error file
#SBATCH --mail-user=<USER>@uwaterloo.ca     # who to email
#SBATCH --mail-type=FAIL                    # when to email
#SBATCH --account=ctb-mmstastn              # UW Fluids designated resource allocation

casename='<YOUR_CASE_NAME>'

module load matlab/2018a
matlab -nodisplay -nosplash -singleCompThread

cp wave_reader.x ../$casename
cd ../$casename
srun ./wave_reader.x

Running multiple cases with driver_readtable.m or driver_iswlong.m

The script driver_readtable.m reads parameters from a text file, which, for example, looks like this:

casename, drho, z0,  d,    amp,   wl,  md
case1,    0.01, 0.4, 0.01, 0.005, 1,   1
case2,    0.01, 0.4, 0.01, 0.005, 0.4, 1

At this time, wl (horizontal wavelength) and md (vertical mode number) cannot take vectors. To submit a job, use the following script:

#!/bin/bash
# bash script for submitting a Matlab job to the sharcnet Graham queue

#SBATCH --mem-per-cpu=2G              # memory per processor (default in Mb)
#SBATCH --time=00-01:00               # time (DD-HH:MM)
#SBATCH --job-name="matlab"           # job name
#SBATCH --input=driver_readtable.m    # Matlab script
##SBATCH —dependency=afterok:<jobid>  # Wait for job to complete

#SBATCH --ntasks=1                    # number of processors
##SBATCH --nodes=1                     # number of nodes
##SBATCH --ntasks-per-node=32          # processors per node
#SBATCH --output=../dummy/mat-%j.log        # log file
#SBATCH --error=../dummy/mat-%j.err         # error file
#SBATCH --mail-user=<USER>@uwaterloo.ca     # who to email
#SBATCH --mail-type=FAIL                    # when to email
#SBATCH --account=ctb-mmstastn              # UW Fluids designated resource allocation

module load matlab/2017a
matlab -nodisplay -nosplash -singleCompThread

casenames='<YOUR_CASE_1 YOUR_CASE_2 ... >'

for casename in $casenames
do
    cp wave_reader.x ../$casename
    cp submit.sh ../$casename
    cd ../$casename
    sbatch submit.sh
    cd ../matlab2spins
done

Remember to replace <USER> with your user ID, and <YOUR_CASE_N> with the case names specified in the text file. The script submit.sh should be available in the matlab2spins directory and should look like this:

#!/bin/bash
# bash script for submitting a Matlab job to the sharcnet Graham queue

#SBATCH --mem-per-cpu=2G             # memory per processor (default in Mb)
#SBATCH --time=00-04:00              # time (DD-HH:MM)
#SBATCH --job-name="<JOB_NAME>"      # job name
##SBATCH --input=driver_readtable.m   # Matlab script
##SBATCH —dependency=afterok:<jobid>  # Wait for job to complete

##SBATCH --ntasks=1                   # number of processors
#SBATCH --nodes=1                    # number of nodes
#SBATCH --ntasks-per-node=32         # processors per node
#SBATCH --output=sim-%j.log                 # log file
#SBATCH --error=sim-%j.err                  # error file
#SBATCH --mail-user=<USER>@uwaterloo.ca     # who to email
#SBATCH --mail-type=FAIL                    # when to email
#SBATCH --account=ctb-mmstastn              # UW Fluids designated resource allocation

srun ./wave_reader.x

Running SPINS using the script driver_iswlong.m works in a similar manner, except that the parameters in the text file will be different.