SPINS MATLAB tools

Many versatile MATLAB functions have been written to easily read and analyze SPINS outputs. They are accessible for use on Belize and Boogaloo, and can also be pulled from github at https://github.com/ddeepwel/SPINSmatlab.git.

The main functionality is:

• parse spins.conf file into a matlab structure
• automatic calculation of secondary grid parameters (spacing, expansion type, ...)
• easy reading of grid
• easy cross-sectional plotting
• plotting of spins diagnostics
• functions for calculating characteristics (amplitude, wavelength) of waves
• SPINS resize

See David Deepwell (ddeepwel@uwaterloo.ca) or the github page for more information on usage, making bug reports, or suggesting other options or functions to add.

SPINSmatlab has a host of useful functions. Some are very general, while some are specialized. Below is a list of every function included in SPINSmatlab (as of October 2021), as well as a short description of what the function does. In parentheses is the directory in which the described script is located.

Following the list of scripts that every SPINS user should know about is a short summary of each script within the set of SPINSmatlab tools.

Scripts every SPINS user should know

Below is a list of "MUST KNOW" SPINSmatlab scripts. These scripts are the most widely used on the day-to-day and fluency in their use is imperative to a smooth workflow. Many of these codes rely on the spins.conf, so ensure that your current working directory contains it. Furthermore, for this software to work wherever the you need it, include a file called startup.m in your ~/Documents/MATLAB folder (on Unix based systems). A sample startup.m file is included below.

%For SPINSmatlab
sm_loc = genpath('<path to wherever you installed SPINSmatlab>');
addpath(sm_loc);
% remove all hidden subdirectories
all_subs =  strsplit(sm_loc,':');
for ii = 1:length(all_subs)
	    if ~isempty(strfind(all_subs{ii},'.')) 
	        rmpath(all_subs{ii});
	    end
end
% clean work space
clear all

Other paths can be added to startup.m by using the addpath command.

spins_params() and par2var()

Reading in parameters from the spins.conf typically takes place in two steps. The first is parse the parameters from the spins.conf. This is done by entering params = spins_gridparams(). The output params is a MATLAB structure containing all of the parameters from the spins.conf.

The second step is to access the variables within the structure params and recast them as workspace variables. This is done by entering par2var(params). Now, all parameters from the spins.conf can be accessed as MATLAB variables. To learn more about the size and datatype of each parameter, type whos in the MATLAB command window.

spins_reader()

spins_reader() is the function one uses to read in SPINS output into MATLAB as an array. To access the basic functionality, you specify the field name that you want to read in as a character vector, as well as the field's output index. As an example, if you would like to import the file rho.14 (i.e. the density field at the 14th output), you would enter my_rho = spins_reader('rho',14). Now, this file is accessible in the MATLAB workspace as an array of size Nx*Ny*Nz (or Nx*Nz id two dimensional).

It is often impractical to load large datasets into MATLAB (large here means greater than about $512^{3}$ grid points). To this end, the user can specify certain subsets of the data they wish to import. This is done by specifying index ranges in the $x$ dimension, $y$ dimension, and/or $z$ dimension. Each of the range arguments take an index or set of indices and returns the field values at those indices. As an example, one could write my_rho = spins_reader('rho',14,xstart:xend,y_slice_ind,[]). For the $x$ dimension, a custom range of indices beginning at xstart and ending at xend was used. For the $y$ dimension, the field was sliced at a single location indicated by y_slice_ind. Finally, the entire $z$ dimension was imported by using [].

If data is two-dimensional, accessing custom subsets of the data is done by ignoring the fifth argument. When only four arguments are supplied, spins_reader() assumes that the data only has $x$ and $z$ dimensions and no $y$ dimension.

plot_diagnos()

plot_diagnos() is the function used to parse and plot data from diagnostics.txt (a text file containing iteration-specific information about a simulation). Entering info = plot_diagnos() saves the information from the diagnostics.txt in a MATLAB structure called info, and plots several figures with information pertaining to the simulation. To suppress the plots, enter info = plot_diagnos(false).

The MATLAB structure info contains several structures within it, each holding related information. They are diagnos, Scales, EnergyBudget, EnergyRates, and Mixing.

Scales holds information on the Kolmogorov and Batchelor scales of the simulation.

Mixing contains information pertaining to mixing (efficiency, cumulative efficiency, and coefficients).

EnergyBudget contains information about the energy reservoirs in the flow. Information on total, kinetic, available, and available potential energy are found here. (cite winters) Additionally, information on the total amount of energy exchanged between different reservoirs is also found here.

EnergyRate contains information about the rate of energy exchange between the reservoirs in the flow.

diagnos is a catch-all, and should be used as a first order assessment of the dynamics. It holds timing information, quantities such as domain averaged kinetic energy, enstrophy, and dissipation, as well as maximum quantities. It also hold diagnostics such as total mass and maximum density, which can be used to quickly assess whether or not there are significant numerical instabilities in a simulation.

cmocean()

cmocean() is a package of perceptually uniform colormaps(Add Thyng reference). These colormaps should be used whenever possible, as they avoid artificial gradients created by using some other colormaps.

To access the colormaps within the package, when using the colormap command, write colormap(cmocean(my_colormap)) where my_colormap (a character vector) is any of the available colormaps found by typing help cmocean in the MATLAB command window.

print_figure()

print_figure() is used to print the contents of a figure to a file whose file type is specified by the user. To use the basic functionality, enter print_figure(filename,'opt1',val1,'opt2',val2,...). filename is a character vector, and the different options, opt1, opt2, ... and values val1, val2, ... are given in the following table.

print_figure() options
Option	Value	Description
fig_hand	integer/figure handle	Figure window
format	'pdf', 'pdf', 'eps' (not recommended) ...	File format to save figure
units	'inches', 'cm'	Units of figure size
size	[width height]	Vector of dimensions (in units specified by units)
res	integer	Resolution in dpi
renderer	'painters', 'opengl'	This option can often be ignored

resize_all()

resize_all() is used to spectrally interpolate existing SPINS data onto a finer (or more coarse) grid where the size of the grid is specified by the user. The utility of this function comes when a user wishes to resume a simulation with a higher spatial resolution. This script can be used with both Fourier and Chebyshev ($z$ only) grids.

To use resize_all(), go to the directory where the existing data is located, and run resize_all(output, [Nx_new Ny_new Nz_new]). output is the index you want to interpolate, and [Nx_new Ny_new Nz_new] is the grid size of the refined data. This script will spectrally interpolate the existing data for every field with the index output and put it in a new subdirectory called resized/. Included in this subdirectory is the executable file, and the spins.conf which has been updated to reflect the new grid and restarting information.

To use resize_all() in two dimensions, in the directory with the unrefined data, simply enter resize_all(output, [Nx_new Nz_new]) (the code implicitly assume two dimensional data is in the $x-z$ plane).

extend_all()

extend_all() provides a means to starting a three-dimensional simulation based on a two dimensional ($x-z$ plane) initial condition. The intended use is for running a two dimensional simulation until three dimensional effects are expected to occur, then extending the last output from the two dimenisonal simulation into three dimensions and re-running from there.

To use extend_all(), go to the directory where the existing data is located, and run extend_all(output, Ly, Ny). output is the index you want to extend, Ly is the length in the spanwise dimension, and Ny is the number of grid points in that dimension. This script will extend the existing data into a third dimension for every field with the index output and put it in a new subdirectory called extended/. Included in this subdirectory is the executable file, and the spins.conf which has been updated to reflect the new third dimension and restarting information.

More specialized scripts

More information can be found on the following functions by typing help followed by the name of the function in MATLAB command window. Scripts are listed based on their parent directory.

analysis/

characterize_wave()

Tracks the core of a propagating wave.

clean_diagnostics

Removes errors due to restarts in diagnostics.txt.

find_contour()

Finds the $(x,y)$ positions of a contour specified by the user.

find_halfmax()

Finds the halfmax of a wave height.

find_position()

Finds the position (x_0) where f(x)=y for a specified y value for a monotonic function f.

find_wave_max()

Finds the value and position of the maximum of a function.

FiniteDiff()

Creates an arbitrary order finite difference matrix. Odd orders of accuracy may not work, so stick with even numbers.

figs/

choose_caxis()

Chooses an appropriate colour axis and colour map based on data.

figure_defaults()

Includes Latex features on figure (fonts, ticklabels) and minor changes to the axes style

print_all()

Prints all figures on screen to separate files.

rgb()

Returns the colour vector based on standardized colour naming conventions from CSS colour module (source).

rotate_axes()

Rotates coordinate axes clockwise based on user input.

shift_axes()

Translates coordinate axes based on user input.

subplot_labels()

Provides text subplot labels.

plotting/

make_movie()/make_movie_bare()

Strings together user generated figures to make a mp4 video. Notes that this function requires installation of ffmpeg.

plot_stress()

Plots surface and bottom stresses from files called stresses_top.txt and stresses_bottom.txt.

spins_hovmoller()

Creates space-time data of a field at a user-specified location.

IO/

spins_grid()

Reads in grid data from the spins.conf.

spins_gridparams()

Reads in both grid and parameter data from the spins.conf.

spins_plot2D()

General plotting software for use with spins_params(), spins_gridparams(), and spins_grid().

spins_readdata()

Generalized data reader at a user specified location in space and time. Can call things such as 'KE' (kinetic energy), 'Density' (rho), 'Mean u' (the spanwise mean of u, can operate on any spins field), 'SD u' (the standard deviation of u, can operate on any spins field), etc.

spins_writer()

Writes a MATLAB array to a SPINS readable format.

xz_reader()/xy_reader()

Reads in $x$ and $z$ ($x$ and $y$) grids.

extra/

clear_except()

Clears variables from the workspace except those specified by the user.

completion()

Checks the completion percentage of a script.

check_make_dir()

Checks if a path exists, and creates it if it doesn't

contour_data()

Obtain structured contour data.

fftfreq()

Obtains sampling frequencies for the fft.

filters()

Provides examples of different types of numerical filters.

find_fields()

Finds valid SPINS fields given an index.

first_output()

Finds the first SPINS output.

get_fixed_z()

Finds a 2D slice at a constant depth. Very useful for mapped grids.

get_lab_frame()

Wrapper for rotate_refframe().

get_output_times()

Gets output times from a run.

get_planar_grid()

Returns cross sections of a three dimensional grid.

get_plot_points()

Gives grid and indices info for plotting sections of a field.

get_rectilinear_grid()

Interpolates a mapped grid onto a rectilinear grid.

get_vector_grid()

Gets one dimensional vectors of grids.

interp_onto_rect_grid()

Interpolates a mapped field onto a rectilinear grid.

last_output()

Gets last output in a SPINS run.

max_grid_spacing()

Finds max grid spacing in each dimension.

nearest_index()

Finds the position of an element in a list for which the element is closest to a specified value.

rotate_refframe()/rotation_transform()

Rotates grid to lab frame (rotate_refframe()) or to an arbitrary angle (rotation_transform()).

spins_plotoptions

Helper script for spins_plot2D.

split_gdpar

Splits the structure generated by spins_gridparams() into separate structures. One contains the grid and the other the parameters from the spins.conf.

wave_region

Finds a region surrounding a wave by looking to a file called wave_characteristics.mat.

eos/

lineos()

A linear equation of state where coeffiecients are calculated by compute_eos_coeffs.

quadeos()

A quadratic equation of state for use around the temperature of maximum density.

nleos()

A full non-linear equation of a state.

compute_eos_coeffs()

Computes the thermal expansion coefficient, haline contraction coefficient, and background density given a reference temperature and salinity.

compare_eos

A tutorial script to show the use of each equation of state.