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.

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

• driver_iswlong.m All-in-one driver file for Matlab to SPINS grid ordering for multiple different cases.
• driver_unidomain.m Input parameters and main driver file for matlab2spins2d.m.
• driver_multidomain.m Input parameters and main driver file for matlab2spins2d.m with different waves in multiple domains combined together.
• driver_readtable.m Input parameters and main driver file for matlab2spins2d.m, with parameters read from a text file.

DJL solver

• get_eta.m Main iteration loop of the DJL solver.
• md_diff.m Differentiation matrix for the DJL solver.
• iswpost.m Post processing for the DJL solver.
• iswpic.m Making plots for the DJL solver.
• 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

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

Interpolation

• 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

• matlab2spins2d.m Writing data to disk.

SPINS automation

Currently, the process of Matlab to SPINS grid ordering works for a 2D domain with periodic (or free-slip) conditions in the x-direction and free-slip conditions in the z-direction and a flat bottom boundary. It solves the DJL equation for solitary waves or the Taylor-Goldstein equation for traveling/standing linear waves, interpolates the u, w and rho fields onto a regular (non-Cheb) grid, and then saves the data as SPINS input files (for wave_reader.x).

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

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