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 are:

• 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

The first three are organized into the spins_gridparams function. The plotting is accomplished by spins_plot2d which has many optional arguments for making plots with very little work. 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 description of the scripts, a list of "MUST KNOW" scripts is included. These scripts are the most widely used on the day-to-day and fluency in them is imperative to a smooth workflow. Many of these codes rely on the spins.conf, so ensure that the working directory contains it.

Reading in parameters from the spins.conf

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

The second step is to access the variables within the structure params and recast then as workspace variables. This is done by writing 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 a MATLAB array. The basic functionality comes rom specifying the field name as a character vector, as well as the output index. As an example, if one would like to import the file rho.14 (i.e. the density field at the 14th output), they could write my_rho = spins_reader('rho',14).

For larger datasets, it is often impractical to load the entire dataset into MATLAB. 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 (xrange), $y$ dimension (yrange), and/or $z$ dimension (zrange). Each of the range arguments take an index or set of indices and return the field values at those indices. To access this functionality, 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 an $x$ and $z$ dimension and no $y$ dimension.

plot_diagnos()

plot_diagnos() is the function used to parse and plot data from diagnostics.txt (a text file containing certain information about a simulation saved at every iteration). 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 diagnos = plot_diagnos(false).

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

The structure diagnos is a catch-all. It hold timing information, domain averaged quantitites such as kinetic energy (total and components), enstrophy (total and components).

Scales hold information of the Kolmogorov and Batchelor scales.

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

EnergyBudget

EnergyRate

cmocean()

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

To access the colourmaps within the package, when writing the colormap command, write colormap(cmocean(my_colourmap)) where my_colourmap(character vector) is any of the available colourmaps found by typing help cmocean.

print_figure()

print_figure() is used to print the contents of a figure to a file whose filetype is specified by the user. To use the basic functionality, write print_figure(filename,'opt1',val1,'opt2',val2,...). The filename is a character vector. 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()

extend_all()

1. ind = nearest_index(x1d,xi)
2. diagnos = plot_diagnos(make_plots,do_filter)
3. clean_diagnostics
4. print_figure(filename, 'opt1', val1, 'opt2', val2, ...)
5. cmocean
6. resize_all(out,[Nx_new, Ny_new, Nz_new])
7. extend_all(out,Ly,Ny)