View source for Matlab-to-SPINS grid ordering

== Introduction ==

The idea here is to use Matlab to specify the initial density and velocity fields and then use <code>wave_reader</code> 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 [https://git.uwaterloo.ca/c2xu/matlab2spins 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 <code>git clone https://git.uwaterloo.ca/c2xu/matlab2spins.git</code>. This will create a directory called <code>matlab2spins</code> 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 <code>test = true;</code>. When you are ready to run the program on a remote machine (e.g. Graham), setting <code>test = false;</code> 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.

* <code>driver_iswlong.m</code>: 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 <code>rho.orig</code> (and any other essential files in their appropriate forms) of this particular case in this directory. 
* <code>driver_unidomain.m</code>: Driver file for solving the DJL or TG equation in a single domain.
* <code>driver_multidomain.m</code>: 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.
* <code>driver_readtable.m</code>: Similar to <code>driver_iswlong.m</code> 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 <code>wave = 'djl';</code> in the driver file and specify the APE you want to use.

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

=== Taylor-Goldstein solver ===

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

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

=== Interpolation ===

Except for <code>driver_iswlong.m</code>, 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 <code>linear</code>, <code>cubic</code>, and <code>spline</code> are available. The spectral method by David Deepwell (<code>resize_x.m</code> and <code>resize_z.m</code>) is also available, except that it does not
workfor a Chebyshev grid at this time.

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

=== Matlab-to-SPINS grid ordering ===

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

* <code>matlab2spins2d.m</code>: Writing data to disk.

== Running the code on Graham ==

=== Running a single case using <code>driver_unidomain.m</code> or <code>driver_multidomain.m</code> ===

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 <code><USER></code> with your user ID, <code><DRIVER_SCRIPT></code> with <code>driver_unidomain.m</code> or <code>driver_multidomain.m</code>, and <code><YOUR_CASE_NAME></code> with the case name identical to <code>casename</code> you specified in <code>driver_unidomain.m</code> or <code>driver_multidomain.m</code>. Also, make sure you have a copy of <code>wave_reader.x</code> for Graham available in the <code>matlab2spins</code> directory, and a "dummy" (or whatever name you want to call it) directory available for log/error files.

<syntaxhighlight lang="bash">
#!/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
</syntaxhighlight>

=== Running multiple cases with <code>driver_readtable.m</code> or <code>driver_iswlong.m</code> ===

The script <code>driver_readtable.m</code> reads parameters from a text file, which, for example, looks like this:
 
<syntaxhighlight>
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
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
#!/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
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
#!/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
</syntaxhighlight>

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