SPINS Science Files

SPINS comes with a variety of Science files which help with simulation data analysis. Below is a list of currently available functions with a brief description of their purpose and the assumptions behind their implementation. These Science files are in spins/src/Science.

Unless otherwise mentioned, the functions below work for both unmapped and mapped domains where the mapping is along the bottom of the domain (where the bottom is at the 0-index in the z-dimension, as opposed to at the Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle N_z-1 } index). Another way to say this is that z increases with the index.

Details and Notes

Notation

Warning! Multiple different notations are used below. Subscripts of Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle u } , Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle v } , and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle w } are always derivatives with respect to the subscript variable. However, subscripts of Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega } and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t } are components. That is, Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle u_x } and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_x } are the x-derivative of Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle u } and the x-component of vorticity.

Units

The units of each of the functions have been built under the assumption that physical units are being used in the simulation. These computations will work for nondimensional simulations, but more care must be taken to ensure the scalings are appropriate. Physical units are typically:

Length	m
Time	s
Density	kg/m^3

The reference density should be 1000 kg/m^3 for the stress and dissipation calculations to be physically correct. The density field can be (and often is) non-dimensionalized to Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \rho'= \rho/\rho_0 - 1 } . If nondimensionalized, compute_Background_PE.cpp and compute_BPE_from_internal.cpp assume this form of scaling. These two functions also need to know if the density field is dimensional or not.

Boundary Stresses

These functions compute the surface stresses on the top and bottom boundaries. It is assumed that Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle z=z_\text{max}} is the top and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle z=z_\text{min}} is the bottom.

Further calculations and saving to disk of various quantities of the stresses are made in the src/BaseCase directory.

bottom_slope.cpp

Compute the vector of the bottom slope at each x-grid point. This is used for calculating the stresses along the bottom boundary (cf. bottom_stress_x.cpp and bottom_stress_y.cpp).

bottom_stress_x.cpp

Compute the 2D vector of the x-component of stress on the bottom boundary. The z boundary condition must be no slip.

If the case is unmapped:

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_x = \mu u_z }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \mu = \nu \rho_0 } is the dynamic viscosity.

If the case is mapped:

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_x = \frac{\mu}{\alpha^2(x)}\left( 2 h'(x) (w_z - u_x) + (u_z + w_x)(1 - h'^2(x)) \right) }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \alpha(x) = \sqrt{1 + h'^2(x)} } and where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle h'(x) } is the bottom slope.

bottom_stress_y.cpp

Compute the 2D vector of the y-component of stress on the bottom boundary. The z boundary condition must be no slip.

If the case is unmapped:

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_y = \mu v_z }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \mu = \nu \rho_0 } is the dynamic viscosity.

If the case is mapped:

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_y = \frac{\mu}{\alpha(x)}\left( v_z - h'(x) v_x \right) }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \alpha(x) = \sqrt{1 + h'^2(x)} } and where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle h'(x) } is the bottom slope.

top_stress_x.cpp

Compute the 2D vector of the x-component of stress on the top boundary. The z boundary condition must be no slip and have no mapping along the top boundary. Implementation for mapping is missing as of 2020 (it would entail copying what is done for the bottom boundary).

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_x = -\mu u_z }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \mu = \nu \rho_0 } is the dynamic viscosity.

top_stress_y.cpp

Compute the 2D vector of the y-component of stress on the top boundary. The z boundary condition must be no slip and have no mapping along the top boundary. Implementation for mapping is missing as of 2020 (it's would entail copying what is done for the bottom boundary).

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle t_y = -\mu v_z }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \mu = \nu \rho_0 } is the dynamic viscosity.

Energy Budget

See Energy Budget for more details.

compute_Background_PE.cpp

Compute the value of the background potential energy,

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle E_b = g \int_V \rho_* z_* dV }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle z_* } is the depth of an element of the sorted density field which minimized the potential energy (ie. Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \rho_*} ). For more information see Winters et al. (1995). It is assumed that gravity points in the negative z direction.

compute_BPE_from_internal.cpp

Compute the rate of energy transfer from internal energy into background potential energy.

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \phi_i = -g\kappa \int_A \rho(z=z_u) - \rho(z=z_l) dA }

where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle z_u } and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle z_l } are the depths of the upper and lower boundaries, respectively. The integral is taken over the horizontal extent. For more information see Winters et al. (1995). It is assumed that gravity points in the negative z direction.

dissipation.cpp

Compute the viscous dissipation Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \epsilon = 2 \mu e_{ij} e_{ij} }

where summation is implied over duplicate indices and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle e_{ij} = \frac{1}{2} (\frac{\partial u_i}{\partial x_j} + \frac{\partial u_j}{\partial x_i})} is the strain rate tensor.

Vorticity and Vorticity Equation

See the Vorticity equation

compute_vorticity.cpp

Compute all vorticity components.

compute_vort_x.cpp

Compute the x-component of vorticity: Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_x = w_y - v_z }

compute_vort_y.cpp

Compute the y-component of vorticity: Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_y = u_z - w_x }

compute_vort_z.cpp

Compute the z-component of vorticity: Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_z = v_x - u_y }

vortex_stretch_x.cpp

Compute the x-component of the vorticity production due to stretching/tilting

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_x u_x + \omega_y u_y + \omega_z u_z }

vortex_stretch_y.cpp

Compute the y-component of the vorticity production due to stretching/tilting

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_x v_x + \omega_y v_y + \omega_z v_z }

vortex_stretch_z.cpp

Compute the z-component of the vorticity production due to stretching/tilting

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_x w_x + \omega_y w_y + \omega_z w_z }

Enstrophy equation

See the Enstrophy equation.

enstrophy_density.cpp

Compute the enstrophy density Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \Omega = \frac{1}{2} \omega_i\omega_i = \frac{1}{2} (\omega_x^2 + \omega_y^2 + \omega_z^2) }

enstrophy_stretch_production.cpp

Compute the enstrophy production due to vortex tilting/stretching Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \omega_i \omega_j e_{ij} = \omega_i \omega_j \frac{\partial u_i}{\partial x_j} }

where summation is implied over duplicate indices and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle e_{ij} = \frac{1}{2} (\frac{\partial u_i}{\partial x_j} + \frac{\partial u_j}{\partial x_i})} is the strain rate tensor.

Coherent Vortex Identification for 3D Flows

The characteristic polynomial of Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle u_{i,j}} can be written as

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle \lambda^3 - P\lambda^2 + Q\lambda - R = 0,}

assuming that the flow is 3D. These coefficients are invariants—i.e., scalars—of the flow, and can be used to identify coherent structures that exist in all reference frames. They are given by

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle P = \lambda_1+\lambda_2+\lambda_3=u_{i,i} , }

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle Q = \frac{1}{2}(\lambda_1^2+\lambda_2^2+\lambda_3^2)=\frac{1}{2}(P^2-u_{i,j}u_{j,i})=\frac{1}{2}(P^2+\Omega_{ij}\Omega_{ij}-S_{ij}S_{ij}), }

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle R = \frac{1}{3}\lambda_1\lambda_2\lambda_3 = det(u_{i,j}). }

SPINS assumes the flow is incompressible, so P=Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle u_{i,i}=0} . The more useful variables are Q and R. As can be seen from the definition of Q, large positive values of Q imply that rotation dominates while large negative values of Q imply that strain dominates; this property therefore clarifies whether a region of high vorticity is due to a vortex, or due to a shear stress, respectively. While not immediately obvious, regions of large and positive R correspond to axial stretching in the flow while large and negative R correspond to planar stretching. As a consequence, intersecting iso-surfaces of large Q and large R likely contain coherent vortices.

This discussion of Q and R is adapted from Anton Baglaenko’s PhD thesis.

Q_invt.cpp

This calculates Q using

Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle Q=-\frac{1}{2}u_{i,j}u_{j,i}).}

R_invt.cpp

This calculates R using

$R=det(u_{i,j})={\frac {1}{3}}u_{i,j}u_{j,k}u_{k,i}$

Other

compute_quadweights.cpp

Compute the quadrature weights for each dimension.

If the boundary condition is no-slip, use the Clenshaw-Curtis quadrature weights:

$w=...$

If the boundary condition is free-slip, use the trapezoid rule:

$w=L_{x}/N_{x}=\Delta x$

find_expansion.cpp

Returns the expansion types for each field.

Boundary Condition	Flow Variable
	u	v	w	otherwise
Fourier	Periodic	Periodic	Periodic	Periodic
No slip	Chebyshev	Chebyshev	Chebyshev	Chebyshev
Free slip in x	sine	cosine	cosine	cosine
Free slip in y	cosine	sine	cosine	cosine
Free slip in z	cosine	cosine	sine	cosine

Spins assumes that a variable ending in _x, _y, or _z is the x, y, or z derivative of that particular variable. This is needed to get the proper expansion type for the derivative of the given variable.

get_quad.cpp

Fairly certain that this is a deprecated function

overturning_2d.cpp

Details to be added. It's an old function and probably deprecated.

read_2d_restart.cpp

For reading 2D spins files and (likely) extending to 3D.

Unsure why this is in /Science. IO should also be cleaned up since there's a bunch of overlapping functions.

read_2d_slice.cpp

For reading 2D matlab files or 2D slices.

Unsure why this is in /Science. IO should also be cleaned up since there's a bunch of overlapping functions.

swap_trig.cpp

Change cosine expansion to sine expansion and vice versa. To be used in find_expansion for variables of derivatives.