SPINS Tutorial: Difference between revisions

From Fluids Wiki
Jump to navigation Jump to search
mNo edit summary
 
(18 intermediate revisions by 2 users not shown)
Line 17: Line 17:
# Diagnostic files
# Diagnostic files
#* These will generally be text files and contain information about the simulation
#* These will generally be text files and contain information about the simulation
#* Matlab plotters for the diagnostic files are found in the [https://git.uwaterloo.ca/ddeepwel/SPINSmatlab SPINSmatlab toolbox] (preinstalled on boogaloo).
#* Matlab plotters for the diagnostic files are found in [[SPINS MATLAB tools]], available [https://github.com/ddeepwel/SPINSmatlab here].
{| class="wikitable"
{| class="wikitable"
!colspan="4"|Diagnostic Files
!colspan="4"|Diagnostic Files
Line 45: Line 45:
Matlab and Python are the primary languages used for analyzing SPINS simulations. These are great for computation of quantities specific to your study. The [https://git.uwaterloo.ca/bastorer/SPINSpy Python (SPINSpy)] and [https://git.uwaterloo.ca/ddeepwel/SPINSmatlab Matlab (SPINSmatlab)] packages contain much of the important tools for each language. Three dimensional visualization should use Paraview or VisIt (see [[Visualization]]).
Matlab and Python are the primary languages used for analyzing SPINS simulations. These are great for computation of quantities specific to your study. The [https://git.uwaterloo.ca/bastorer/SPINSpy Python (SPINSpy)] and [https://git.uwaterloo.ca/ddeepwel/SPINSmatlab Matlab (SPINSmatlab)] packages contain much of the important tools for each language. Three dimensional visualization should use Paraview or VisIt (see [[Visualization]]).


Here, we will use Matlab to make a simple plot of the density field. We assume that the SPINSmatlab package is on your path (as is the case for boogaloo).
Here, we will use Matlab to make a simple plot of the density field. We assume that the SPINSmatlab package is on your path.


#<code>gdpar = spins_gridparams(); split_gdpar</code>
#<code>gdpar = spins_gridparams(); split_gdpar</code>
Line 119: Line 119:
Try it yourself. See what each parameter does when they're changed.
Try it yourself. See what each parameter does when they're changed.


= Extend to 3D =
Often, a case initially simulated in 2D will undergo various physical processes that allow it to become 3D, thus, in many circumstances, a 2D simulation could be a misrepresentation of the overall dynamics. To this end, there are different mechanisms built into SPINS to deal with this. The simplest process is the run a 2D simulation until you believe that 3D effects will have occurred. This is problem specific and is left up to the choice of the modeller.
Once a particular output is chosen, the simulation can be extended into the spanwise (assumed to be the <math> y </math> dimension), and the simulation can be restarted from that point and run in 3D.
To use this functionality, the script <code> extend_all()</code> has been included in the <code>SPINSmatlab</code> toolbox.
# Run the simulation until the output 30
# Navigate to the directory where the output is stored. Go into MATLAB and enter <code>extend_all(30,0.1,32)</code>.
# <code>extend_all</code> creates a sub-directory called <code>extended/</code> which contains the now 3D data, the <code>spins.conf</code> with updated grid and restarting information, and the executable.
# Navigate into the <code>extended/</code> directory and run the executable.
Note now that the data is three dimensional, to read it into MATLAB, you must choose a slice (an <math>x-y</math>, <math>x-z</math>, or <math>y-z</math> cross-section) to plot. This is commonly done in two ways.
# You can use <code>spins_reader()</code> to read in slices of fields and grids by entering <code>spins_reader(field,output,x_start:x_end,y_start:y_end,z_start:z_end)</code>. <code>[]</code> implies the entire dimension. This is imperative for large datasets, as MATLAB has immense difficulty opening very large arrays without freezing.
# For smaller sized 3D data sets, the entire field can be loaded in and slices taken at different points in analysis. To get a fast plot, use the following command:
imagesc(flipud(squeeze(u(:,y_ind,:))'))
if you want to plot an <math>x-z</math> slice at the span corresponding to <code>y_ind</code>. The <code>squeeze()</code> command remove the singleton dimension leaving the field as a 2D array. The combination of the <code>flipud()</code> and transpose (<code>'</code>) operations allow the bottom of the field to align with the bottom of the plot.
Note that an <math>x-y</math> slice does not need the <code>flipud()</code> and transpose (<code>'</code>) operations.
= Editing Casefiles =
This needs to be done.
<!-- NOTE THAT THE SECTIONS BELOW NEED TO BE REFINED IF THEY ARE TO BE INLCUDED. CONSIDER ADDING THEM AS A SEPARATE WIKI PAGE AS THEY ARE NOT 'NEED-TO-KNOW' ASPECTS OF SPINS. THIS PAGE IS RESERVED FOR THE MOST BASIC SPINS FUNCTIONALITY -->
<!--
= Part 2: Matlab driver scripts (UNDER CONSTRUCTION)=
= Part 2: Matlab driver scripts (UNDER CONSTRUCTION)=
Part 2 and 3 extend the previous tutorial. In the remaining sections of this tutorial you will:
Part 2 and 3 extend the previous tutorial. In the remaining sections of this tutorial you will:
Line 163: Line 193:
== Summary ==  
== Summary ==  


[[File:Flow_charts.002.png|frameless|border|caption]]
For future reference, the user may want to refer to the following flow chart as a reminder of how to use the workflow functionality.
 
[[File:workflow.png|frameless|border|caption]]


= Part 3: Refining the grid from existing outputs (UNDER CONSTRUCTION)=
= Part 3: Refining the grid from existing outputs (UNDER CONSTRUCTION)=
Line 169: Line 201:
Say you ran a simulation and noticed that after a certain time, the model output began to exhibit signs of small unphysical oscillations. Or perhaps you almost managed to resolve a feature of interest near the end of your simulation. Both of these scenarios could be solved by restarting your simulation from the beginning with higher resolution, however, in the interest of time (especially for large runs), it may be useful to start from an earlier point in your existing simulation with a higher resolution.  
Say you ran a simulation and noticed that after a certain time, the model output began to exhibit signs of small unphysical oscillations. Or perhaps you almost managed to resolve a feature of interest near the end of your simulation. Both of these scenarios could be solved by restarting your simulation from the beginning with higher resolution, however, in the interest of time (especially for large runs), it may be useful to start from an earlier point in your existing simulation with a higher resolution.  


This is where the script <code>spins_refinement.m</code> becomes useful. <code>spins_refinement.m</code> takes all the field at a specified output, makes a finer grid, and interpolates the existing outputs onto this finer grid. It then outputs new fields that can be read by <code>wavereader.x</code>. This effectively allows you to restart a simulation from an earlier output but with higher resolution.
This is where the script <code>spins_refinement.m</code> becomes useful. <code>spins_refinement.m</code> takes all the fields at a specified output, makes a finer grid, and interpolates the existing outputs onto this finer grid. It then outputs new fields that can be read by <code>wave_reader.x</code>. This effectively allows you to restart a simulation from an earlier output but with higher resolution.
 
Spectral refinement is also available, more information below.


== Usage ==
== Usage ==


Using <code>spins_refinement.m</code> is easy (trust us). The necessary steps are are outlined below and the code snippet is given.
Using <code>spins_refinement.m</code> is easy (trust us). There are a few steps that must be taken before using it though.
First, <code>wave_reader.x</code> must be compiled on the machine you intend to run the refined cases on. The process for this is identical to the process for compiling <code>mode1_mode2.x</code> above, except you simply compile <code>wave_reader.cpp</code>. Once this is complete, the next step is to clone the <code>SPINSMatlab</code> functions. The process for this is introduced earlier in this tutorial.
 
The necessary steps to use <code>spins_refinement.m</code> as well as the code snippet are given below.
  nx = 4;              % nx times of original resolution in x
  nx = 4;              % nx times of original resolution in x
  nz = 2;              % nz times of original resolution in z
  nz = 2;              % nz times of original resolution in z
Line 180: Line 217:
                           % 'nearest', 'linear', 'spline' or 'cubic'
                           % 'nearest', 'linear', 'spline' or 'cubic'


# The first step is to adjust the parameters in the script that specify the new grid, the first refined output, and the interpolation method. The only lines that the user should have to edit are given below.<br /> The parameters <code>nx = 4</code> and <code>nz = 2</code> mean that the number of grid points in the horizontal and vertical directions will be increased by a factor of 4 and 2 respectively. The line <code>ii = 100</code> determined what output would the user would like to refine and begin the new simulation from. This output will be the new initial condition for the higher resolution version of your case. Be aware that the output you choose must be sufficiently early that any transient motion due to the interpolation can be removed by viscosity or filtering before the motion of interest is analyzed.  Lastly, you may also edit the variable ‘method’, which changes the interpolation method used. Currently, the only methods available are nearest, linear, spline, or cubic. In the future, a separate script for spectral interpolation may be added.
# The first step is to adjust the parameters in the script that specify the new grid, the first refined output, and the interpolation method. The only parameters that the user should have to edit are given above.<br /> The parameters <code>nx = 4</code> and <code>nz = 2</code> mean that the number of grid points in the horizontal and vertical directions will be increased by a factor of 4 and 2 respectively.  
# Next, you run the edited script above in the working directory. The script will create the interpolated fields on the finer grid and place them in a new directory called <code>high_res</code> along with a new <code>spins.conf</code>.
# Next, the line <code>ii = 100</code> determined what output the user would like to refine and begin the new simulation from. This output will be the new initial condition for the higher resolution version of your case. Be aware that the output you choose must be sufficiently early that any transient motion due to the interpolation can be removed by viscosity or filtering before the motion of interest is analyzed.   
# Lastly, copy the submit script and <code>wavereader.x</code> into the directory <code>high_res</code> and submit.
# Lastly, you may also edit the variable ‘method’, which changes the interpolation method used. Currently, the only methods available are `nearest', `linear', `spline', or `cubic'. In the future, a separate script for spectral interpolation may be added.
# With the new grid parameters specified, move <code>spins_reader.m</code> and <code>spins_refinement.m</code> into the working directory and run <code>spins_refinement.m</code>. The script will create the interpolated fields on the finer grid and place them in a new subdirectory called <code>high_res</code> along with a new <code>spins.conf</code>.
# Lastly, copy the submit script and <code>wave_reader.x</code> into the directory <code>high_res</code> and submit the refined case.
 
Spectral refinement (rather than the matlab interpolation schemes) is available in [[SPINS resize]] (a subset of the [https://git.uwaterloo.ca/ddeepwel/SPINSmatlab SPINSmatlab toolbox]). This refinement toolbox also allows for arbitrary refinement or coarsening, rather than a mutliplication of the current resolution.
 


== Summary ==
== Summary ==
Line 188: Line 230:
For future reference, the user may want to refer to the following flow chart as a reminder of how to use the <code>spins_refinement.m</code> functionality.  
For future reference, the user may want to refer to the following flow chart as a reminder of how to use the <code>spins_refinement.m</code> functionality.  


[[File:Flow_charts.001.png|frameless|border|caption]]
[[File:refinement.png|frameless|border|caption]]
-->

Latest revision as of 11:13, 18 October 2021

This is a tutorial for getting up to speed with SPINS using the case mode1_mode2. The first part of the tutorial discusses running the case with the default parameters, some basic analysis tools and techniques, and manually changing parameters. The second part of the tutorial explores more parameter combinations using Matlab driver scripts to automate the workflow. The final part uses a Matlab script spins_refinement.m to interpolate an existing SPINS output onto a finer grid and restart SPINS at higher resolution.

You must first have followed the instructions to install SPINS and compile the case file.

Part 1: Getting familiar with SPINS

Run

Transfer the executable (mode1_mode2.x) and the configuration file (spins.conf) into a clean directory.

Run simulation by executing mpirun -np 4 ./mode1_mode2.x on the command line, or submit the job to the queue on a Compute Canada system with a submit script (see submitting jobs to Graham).

This will create two types of files

  1. Output files
    • These are of the form rho.3 where the name (rho) is the variable and the extension is the output number
    - For example rho.3 is the density field at output number 3. Zero-indexing is used, so this is the 4th density file
    • Since these can be memory expensive, they are created relatively infrequently
  2. Diagnostic files
    • These will generally be text files and contain information about the simulation
    • Matlab plotters for the diagnostic files are found in SPINS MATLAB tools, available here.
Diagnostic Files
File Optional Matlab plotter Description
diagnostics.txt No plot_diagnos High temporal resolution information about the simulation (occurs at every time step). Examples include: KE, max velocity, energy budget terms, simulation timings.
stresses_top.txt and/or stresses_bottom.txt Yes plot_stress Surface forces and surface stress extrema at the top/bottom surfaces. Only applicable if no slip boundary condition is used.
plot_times.txt No plot_diagnos Explicit statement of the time associated with each output. Also gives the time to write output files.

Analyze

Matlab and Python are the primary languages used for analyzing SPINS simulations. These are great for computation of quantities specific to your study. The Python (SPINSpy) and Matlab (SPINSmatlab) packages contain much of the important tools for each language. Three dimensional visualization should use Paraview or VisIt (see Visualization).

Here, we will use Matlab to make a simple plot of the density field. We assume that the SPINSmatlab package is on your path.

  1. gdpar = spins_gridparams(); split_gdpar
    • This reads in the grid and parameters and places them in a structure (gdpar). split_gdpar separates the two sub-structures into the structures par and gd, which are the parameters and grid, respectively.
    • par contains information from spins.conf in addition to further simulation parameters
    • gd contains the grid. x,y,z grids can be extracted with gd.x, gd.y, or gd.z
    • The default setting is that the grid is unmapped and vector grids are produced, to get the full grid use gdpar = spins_gridparams('FastFull'); or gdpar = spins_gridparams('Full');
  2. spins_plot2d('rho',0);
    • First argument is the field to plot
    • Second argument is the output number. The simulation time can also be specified in this argument as a string. spins_plot2d('rho','2'); will plot the simulation at the closest output to t=2s. Many optional arguments exist (type help spins_plot2d for more options).

To read an individual file: u = spins_reader('u',10);

caption

Restart

Should you need to restart the simulation (due to expenditure of allocated time, require more time, a node failure, or otherwise) simply change the restart flags in the configuration file.

The simplest change is to set

restart = true
restart_time = 5.5
restart_sequence = 11

where the simulation will restart at output 11 which corresponds to t=5.5s. These numbers can be found in the last row of plot_times.txt.

SPINS also has an automatic safety dump if the allocated time is close to expiring (See automatically specify the runtime for more info). In this case, if the safety write was done successfully then you only need to set

restart_from_dump = true

Change

If after analyzing the simulation you realize that you wanted to change a parameter (it wasn't quite right), then you only need to change the parameter in the configuration file (as opposed to older editions of SPINS where you'd need to recompile the entire code).

Here is a description of the problem parameters:

 --delta_rho     arg   Density difference between upper and lower layers (as a percentage of rho_0)
 --pyc_loc       arg   Pycnocline location
 --h_halfwidth   arg   Pycnocline half-width
 --delta_x       arg   Horizontal transition half-width
 --H2            arg   Height of mixed region (mode-2) - sets mode-2 wave amplitude
 --H1            arg   Heigth of mixed region (mode-1) - sets mode-1 wave amplitude
 --L1            arg   Length of region 1 (mode-2)
 --L2            arg   Length of region 2 (mode-1)
 --dye1_loc      arg   Location of dye 1
 --dye2_loc      arg   Location of dye 2
 --dye1_width    arg   Width of dye 1
 --dye2_width    arg   Width of dye 2
 --dye_halfwidth arg   Sharpness of the dye transition
 --enable_tracer       Enable evolution of second tracers

If you run the simulation in the same directory, remember to clear all simulation files (output and diagnostic files).

Only Mode-1 ISW

To change the simulation to only have the left mode-1 ISW change spins.conf to have:

H2 = 0.0

This will set the mode-2 amplitude to zero.

caption

Only Mode-2 ISW

To change the simulation to only have the right mode-2 ISW change spins.conf to have:

H1 = 0.0

This will set the mode-1 amplitude to zero.

caption

Gravity Current

To change the simulation to have a rightward moving gravity current change spins.conf to have:

pyc_loc = -0.2
H1 = -1.0
H2 = 0.0

This will move the pycnocline below the bottom boundary, set the mode-1 amplitude to result in a region of high density at on end of the tank, and give no mode-2 contribution.

caption

Try it yourself. See what each parameter does when they're changed.

Extend to 3D

Often, a case initially simulated in 2D will undergo various physical processes that allow it to become 3D, thus, in many circumstances, a 2D simulation could be a misrepresentation of the overall dynamics. To this end, there are different mechanisms built into SPINS to deal with this. The simplest process is the run a 2D simulation until you believe that 3D effects will have occurred. This is problem specific and is left up to the choice of the modeller.

Once a particular output is chosen, the simulation can be extended into the spanwise (assumed to be the dimension), and the simulation can be restarted from that point and run in 3D. To use this functionality, the script extend_all() has been included in the SPINSmatlab toolbox.

  1. Run the simulation until the output 30
  2. Navigate to the directory where the output is stored. Go into MATLAB and enter extend_all(30,0.1,32).
  3. extend_all creates a sub-directory called extended/ which contains the now 3D data, the spins.conf with updated grid and restarting information, and the executable.
  4. Navigate into the extended/ directory and run the executable.

Note now that the data is three dimensional, to read it into MATLAB, you must choose a slice (an , , or cross-section) to plot. This is commonly done in two ways.

  1. You can use spins_reader() to read in slices of fields and grids by entering spins_reader(field,output,x_start:x_end,y_start:y_end,z_start:z_end). [] implies the entire dimension. This is imperative for large datasets, as MATLAB has immense difficulty opening very large arrays without freezing.
  1. For smaller sized 3D data sets, the entire field can be loaded in and slices taken at different points in analysis. To get a fast plot, use the following command:
imagesc(flipud(squeeze(u(:,y_ind,:))'))

if you want to plot an slice at the span corresponding to y_ind. The squeeze() command remove the singleton dimension leaving the field as a 2D array. The combination of the flipud() and transpose (') operations allow the bottom of the field to align with the bottom of the plot.

Note that an slice does not need the flipud() and transpose (') operations.

Editing Casefiles

This needs to be done.