WVTransformStratifiedQG

Represent stratified quasigeostrophic flow with variable stratification.

---

Declaration

classdef WVTransformStratifiedQG < WVTransform

Overview

To initialize an instance of the WVTransformStratifiedQG class you must specify the domain size, the number of grid points, and either the density profile or the stratification profile.

N0 = 3*2*pi/3600;
L_gm = 1300;
N2 = @(z) N0*N0*exp(2*z/L_gm);
wvt = WVTransformStratifiedQG([100e3,100e3,4000],[64,64,65],N2Function=N2,latitude=30);

The quasigeostrophic state is stored in A0, with current-time view A0t. This transform has no active Ap, Am, Apt, or Amt content.

Topics

• Create and restore a transform
  • WVTransformStratifiedQG Create a stratified quasigeostrophic transform.
  • waveVortexTransformFromFile Restore a WVTransformStratifiedQG instance from an existing file
• Inspect the domain
  • Physical environment
    • Planetary rotation
      • beta Meridional gradient of the Coriolis parameter.
      • f Coriolis parameter in radians per second.
      • inertialPeriod Inertial period in seconds.
      • latitude Central latitude of the rotating domain in degrees north.
      • planetaryRadius Radius of the rotating planetary body in meters.
      • rotationRate Planetary rotation rate in radians per second.
    • Stratification and reference density
      • N2 Buoyancy frequency squared sampled on the vertical grid.
      • N2Function Function returning buoyancy frequency squared at requested depths.
      • buoyancyPeriod Shortest buoyancy period in seconds.
      • dLnN2 \(\partial_z \ln N^2\), vertical derivative of the logarithm of squared buoyancy frequency
      • rho0 Boussinesq reference density in kilograms per cubic meter.
      • rhoFunction Function returning the no-motion density profile at requested depths.
    • Gravity
      • g Gravitational acceleration in meters per second squared.
  • Spatial grid
    • Coordinate axes
      • x Periodic x-coordinate axis in meters.
      • y Periodic y-coordinate axis in meters.
      • z Three-dimensional vertical-coordinate array in meters.
    • Coordinate arrays
      • X Gridded x-coordinate array in meters with shape [Nx Ny Nz].
      • Y Gridded y-coordinate array in meters with shape [Nx Ny Nz].
      • Z Gridded vertical-coordinate array in meters with shape [Nx Ny Nz].
      • xyzGrid Return the three-dimensional spatial coordinate arrays.
    • Domain dimensions
      • Lx Periodic domain length in the x direction.
      • Ly Periodic domain length in the y direction.
      • Lz Vertical domain depth in meters.
    • Resolution and shape
      • Nx Number of spatial grid points in the x direction.
      • Ny Number of spatial grid points in the y direction.
      • Nz Number of vertical spatial grid points.
      • spatialMatrixSize Shape of a gridded physical-space field.
    • Quadrature and integration
      • z_int Vertical quadrature weights in meters.
  • Spectral grid
    • Compact grid vectors
      • k Compact Nkl-by-1 x-wavenumber vector in \(\mathrm{rad\,m^{-1}}\).
      • l Compact Nkl-by-1 y-wavenumber vector in \(\mathrm{rad\,m^{-1}}\).
      • j Dimensionless Nj-by-1 vertical-mode index vector.
    • Compact grid arrays
      • K X-direction angular-wavenumber array in \(\mathrm{rad\,m^{-1}}\) with shape [Nj Nkl].
      • L Y-direction angular-wavenumber array in \(\mathrm{rad\,m^{-1}}\) with shape [Nj Nkl].
      • J Dimensionless vertical-mode index array with shape [Nj Nkl].
      • kljGrid Return spectral-coordinate arrays in wave-vortex layout.
    • Wavenumber spacing
      • dk Spacing of the x-direction angular-wavenumber axis.
      • dl Spacing of the y-direction angular-wavenumber axis.
    • Horizontal wavenumber geometry
      • Kh Horizontal angular-wavenumber magnitude on the coefficient grid.
      • K2 Squared horizontal angular wavenumber on the coefficient grid.
    • Resolution and shape
      • Nj Number of retained vertical modes.
      • Nkl Number of retained compact horizontal-wavenumber columns.
      • spectralMatrixSize Shape of a wave-vortex coefficient array.
      • effectiveHorizontalGridResolution returns the effective grid resolution in meters
      • effectiveVerticalGridResolution returns the effective vertical grid resolution in meters
      • effectiveJMax Largest active vertical-mode index.
      • summarizeDegreesOfFreedom Summarize the spatial grid and active spectral degrees of freedom.
    • Vertical modes and scaling
      • verticalModes Vertical-mode solution used to construct the transform basis.
      • h_0 Geostrophic equivalent-depth scale for each vertical mode.
      • h_pm Wave equivalent depth on the spectral grid.
      • Lr2 Squared Rossby deformation radius in square meters.
      • waveModeVerticalStructureAtIndex Return wave vertical-structure factors at one vertical grid index.
    • Vertical-mode transformation matrices
      • FMatrix Transformation matrix \(F\) projecting F-grid values onto vertical modes; shape [Nj Nz].
      • FinvMatrix Transformation matrix \(F^{-1}\) reconstructing F-grid values from vertical modes; shape [Nz Nj].
      • GMatrix Transformation matrix \(G\) projecting G-grid values onto vertical modes; shape [Nj Nz].
      • GinvMatrix Transformation matrix \(G^{-1}\) reconstructing G-grid values from vertical modes; shape [Nz Nj].
  • Transform configuration
    • isHydrostatic Whether the transform uses the hydrostatic approximation.
    • shouldAntialias Whether the spectral grid excludes modes that alias quadratic products.
• Initialize the flow
  • General initialization
    • addRandomFlow add randomized flow to the existing state
    • addUVEta add \((u,v,\eta)\) to the existing values
    • initFromNetCDFFile initialize the flow from a NetCDF file
    • initWithRandomFlow initialize with a random flow state
    • initWithUVEta initialize with fluid variables \((u,v,\eta)\)
    • initWithUVRho initialize with fluid variables \((u,v,\rho)\)
    • removeAll removes all energy from the model
  • Geostrophic motions
    • initWithGeostrophicStreamfunction initialize with a geostrophic streamfunction
    • setGeostrophicStreamfunction set a geostrophic streamfunction
    • addGeostrophicStreamfunction add a geostrophic streamfunction to existing geostrophic motions
    • setGeostrophicModes set amplitudes of the given geostrophic modes
    • addGeostrophicModes add amplitudes of the given geostrophic modes
    • removeAllGeostrophicMotions remove all geostrophic motions
• Evaluate physical fields
  • Registered variables
    • hasVariableWithName Test whether state variables are registered by name.
    • summarizeVariables Print a table of registered state variables and cache status.
    • variableNames Return the names of all registered state variables.
    • variableWithName Compute or retrieve one or more registered transform variables.
  • On the model grid
    • Velocity
      • u x-component of the fluid velocity
      • v y-component of the fluid velocity
    • Density and displacement
      • eta approximate isopycnal deviation
      • rho_e excess density
      • rho_nm0 Reference no-motion density profile, [Nz 1], in \(\mathrm{kg\,m^{-3}}\).
      • rho_total total potential density
    • Pressure and surface fields
      • p pressure anomaly
      • pi height anomaly
      • ssh sea-surface height
      • ssu x-component of the fluid velocity at the surface
      • ssv y-component of the fluid velocity at the surface
    • Vorticity and geostrophic fields
      • psi geostrophic streamfunction
      • qgpv quasigeostrophic potential vorticity
      • zeta_z vertical component of relative vorticity
  • At arbitrary positions
    • variableAtPositionWithName Access dynamical variables at arbitrary positions in the domain.
  • Isopycnal utilities
    • placeParticlesOnIsopycnal Return particle depths on the isopycnal identified by a no-motion depth.
• Manage forcing and closures
  • Configure forcing
    • addForcing Add forcing or closure objects to this transform.
    • setForcing Replace the complete forcing registry.
    • removeForcing Remove the exact registered forcing objects.
    • removeAllForcing Remove every forcing and closure from this transform.
  • Inspect forcing and closures
    • forcing array of WVForcing objects
    • forcingNames Return forcing and closure names in application order.
    • forcingWithName Return registered forcing objects by name.
    • hasForcingWithName Test whether forcing objects are registered by name.
    • hasClosure Whether a closure is currently attached to the transform.
  • Summarize forcing
    • summarizeForcing Print a table of registered forcing and closure objects.
• Analyze the flow
  • Flow diagnostics
    • hasMeanPressureDifference Diagnose an MDA mean-pressure difference between the boundaries.
    • uvMax max horizontal fluid speed
  • Density validity
    • isDensityInValidRange Test whether total density remains within the no-motion density range.
  • Potential vorticity and enstrophy
    • totalEnstrophy Potential enstrophy computed from geostrophic coefficients.
    • totalEnstrophySpatiallyIntegrated Potential enstrophy evaluated from the gridded QGPV field.
  • Spectra
    • Spectral fields
      • kAxis Centered Nx-by-1 x-wavenumber axis in \(\mathrm{rad\,m^{-1}}\).
      • lAxis Centered Ny-by-1 y-wavenumber axis in \(\mathrm{rad\,m^{-1}}\).
      • transformToKLAxes transforms in the spectral domain from (j,kl) to (kAxis,lAxis,j)
      • crossSpectrumWithFgTransform Compute a real modal cross-spectrum using the F-basis transform.
      • crossSpectrumWithGgTransform Compute a real modal cross-spectrum using the G-basis transform.
      • spectrumWithFgTransform Compute a modal autospectrum using the F-basis transform.
      • spectrumWithGgTransform Compute a modal autospectrum using the G-basis transform.
    • Radial wavenumber
      • kRadial radial (k,l) wavenumber on the WV grid
      • transformToRadialWavenumber transforms in the spectral domain from (j,kl) to (j,kRadial)
• Analyze energy
  • Component energy
    • geostrophicKineticEnergy kinetic energy of the geostrophic flow
    • geostrophicPotentialEnergy potential energy of the geostrophic flow
    • geostrophicEnergy total energy, geostrophic
    • totalEnergyOfFlowComponent Compute the energy carried by one flow component.
  • Total energy
    • totalEnergy Total energy computed from wave-vortex coefficients.
    • totalEnergySpatiallyIntegrated Total energy computed from physical-space fields.
  • Energy summaries
    • summarizeEnergyContent displays a summary of the energy content of the fluid
    • summarizeModeEnergy List the most energetic modes
• Save transform state
  • writeToFile Write this instance to NetCDF file.
• Convert representations
  • Physical fields and coefficients
    • transformQGPVToWaveVortex Project quasigeostrophic potential vorticity onto A0 coefficients.
    • transformUVEtaToWaveVortex transform fluid variables \((u,v,\eta)\) to wave-vortex coefficients \((A_+,A_-,A_0)\).
    • transformWaveVortexToUVWEta transform wave-vortex coefficients \((A_+,A_-,A_0)\) to fluid variables \((u,v,\eta)\).
• Differentiate and integrate fields
  • diffX Differentiate a gridded field in the periodic x direction.
  • diffY Differentiate a gridded field in the periodic y direction.
  • diffZF Differentiate an F-grid field with respect to z.
  • diffZG Differentiate a G-grid field with respect to z.
  • intZF Return the first antiderivative of an F-representation.
  • intZG Return the bottom-zero first antiderivative of a G-representation.
• Inspect flow components
  • Primary flow components
    • geostrophicComponent returns the geostrophic flow component
    • primaryFlowComponents Primary flow components that partition the active coefficient state.
    • primaryFlowComponentNames retrieve the names of all available variables
    • primaryFlowComponentWithName retrieve a WVPrimaryFlowComponent by name
  • Registered and combined components
    • flowComponents All registered physical and diagnostic flow components.
    • flowComponentNames retrieve the names of all available variables
    • flowComponentWithName retrieve a WVFlowComponent by name
    • totalFlowComponent Combined view of all primary flow components.
  • Summarize flow components
    • summarizeFlowComponents Print a table of registered primary and diagnostic components.
• Inspect wave-vortex coefficients
  • Stored coefficients
    • A0 Zero-frequency geostrophic coefficients.
  • Coefficients at the current time
    • A0t A0t is the zero-frequency coefficient array evaluated at the current transform time. On the supported \(f\)-plane transforms, A0 has no linear phase winding and therefore
  • Coefficient evolution
    • t0 Reference time for the stored wave phases, in seconds.
    • t Current transform time in seconds.
• Create a related transform
  • hydrostaticTransform Create the corresponding hydrostatic wave-vortex transform.
  • spectralVariableWithResolution create a new variable with different resolution
  • waveVortexTransformWithDoubleResolution create a new WVTransform with double resolution
  • waveVortexTransformWithResolution Create the same transform family at a new resolution.
• Extend a transform
  • Flow components
    • addFlowComponent add a flow component and its standard variables
    • addPrimaryFlowComponent add a primary flow component, automatically added to the flow
  • Operations and variables
    • addOperation Register one or more operations and their output variables.
    • operationWithName retrieve a WVOperation by name
    • removeOperation Remove the exact registered operation and its cached outputs.
• Get package information
  • version Installed WaveVortexModel version.

Developer Topics

These items document internal implementation details and are not part of the primary public API.

• Projection and reconstruction coefficients
  • A0N Projects density displacement onto \(A_0\).
  • A0U Projects \(u\) onto \(A_0\).
  • A0V Projects \(v\) onto \(A_0\).
  • A0Z Projects vertical vorticity onto \(A_0\).
  • NA0 Reconstructs density displacement from \(A_0\).
  • PA0 Reconstructs pressure height from \(A_0\).
  • UA0 Reconstructs \(u\) from \(A_0\).
  • VA0 Reconstructs \(v\) from \(A_0\).
• Geometry and mode indexing
  • Mode numbers and validity
    • isValidConjugateKLModeNumber return a boolean indicating whether (k,l) is a valid conjugate WV mode number
    • isValidConjugateModeNumber returns a boolean indicating whether (k,l,j) is a valid conjugate mode number
    • isValidKLModeNumber return a boolean indicating whether (k,l) is a valid WV mode number
    • isValidModeNumber returns a boolean indicating whether (k,l,j) is a valid mode number
    • isValidPrimaryKLModeNumber return a boolean indicating whether (k,l) is a valid primary (non-conjugate) WV mode number
    • isValidPrimaryModeNumber returns a boolean indicating whether (k,l,j) is a valid primary (non-conjugate) mode number
    • kMode_dft k mode-number on the DFT grid
    • kMode_wv k mode number on the WV grid
    • lMode_dft l mode-number on the DFT grid
    • lMode_wv l mode number on the WV grid
    • primaryKLModeNumberFromKLModeNumber takes any valid WV mode number and returns the primary mode number
  • Linear-index conversion
    • indexFromKLModeNumber return the linear index into k_wv and l_wv from a mode number
    • indexFromModeNumber return the linear index into a spectral matrix given (k,l,j)
    • klModeNumberFromIndex return mode number from a linear index into a WV matrix
    • modeNumberFromIndex Return mode numbers for spectral linear indices.
  • DFT and WV layout metadata
    • Nk_dft length of the k-wavenumber dimension on the DFT grid
    • Nl_dft length of the l-wavenumber dimension on the DFT grid
    • conjugateDimension assumed conjugate dimension
    • dftConjugateIndices2D index into the DFT grid of the conjugate of each WV mode
    • dftPrimaryIndices2D index into the DFT grid of each WV mode
    • indicesOfFourierConjugates a matrix of linear indices of the conjugate
    • k_dft k wavenumber dimension on the DFT grid
    • kl wavenumber dimension
    • l_dft l wavenumber dimension on the DFT grid
    • shouldExcludeConjugates whether the WV grid excludes redundant Hermitian-conjugate wavenumbers
    • shouldExcludeNyquist whether the WV grid includes Nyquist wavenumbers
  • Layout conversion
    • indicesFromDFTGridToWVGrid indices to convert from DFT to WV grid
    • indicesFromWVGridToDFTGrid indices to convert from WV to DFT grid
    • transformFromDFTGridToWVGrid convert from DFT to WV grid
    • transformFromSpatialDomainToDFTGrid transform from \((x,y,z)\) to \((k,l,z)\) on the DFT grid
    • transformFromWVGridToDFTGrid convert from a WV to DFT grid
    • transformToSpatialDomainFromDFTGrid transform from \((k,l,z)\) on the DFT grid to \((x,y,z)\)
    • transformToSpatialDomainFromDFTGridAtPosition transform from \((k,l)\) on the DFT grid to \((x,y)\) at any position
  • Masks and Hermitian bookkeeping
    • isHermitian Check if the matrix is Hermitian. Report errors.
    • maskForAliasedModes returns a mask with locations of modes that will alias with a quadratic multiplication.
    • maskForConjugateFourierCoefficients a mask indicate the components that are redundant conjugates
    • maskForNyquistModes returns a mask with locations of modes that are not fully resolved
    • setConjugateToUnity set the conjugate of the wavenumber (iK,iL) to 1
• Spectral transforms and operators
  • P0 Preconditioner for F, size(P)=[Nj 1]. Fu = uhat, (PF)u = Puhat, so ubar==Puhat
  • PF0 size(PF,PG)=[Nj x Nz]
  • PF0inv Transformation matrices
  • Q0 Preconditioner for G, size(Q)=[Nj 1]. Geta = etahat, (QG)eta = Qetahat, so etabar==Qetahat.
  • QG0 dimensionless preconditioned G-mode forward transformation
  • QG0inv dimensionless preconditioned G-mode inverse transformation
  • degreesOfFreedomForComplexMatrix a matrix with the number of degrees-of-freedom at each entry
  • degreesOfFreedomForRealMatrix a matrix with the number of degrees-of-freedom at each entry
  • fastTransform fast transform object
  • transformFromSpatialDomainWithFio
  • transformFromSpatialDomainWithFourier
  • transformToSpatialDomainWithFourier
  • transformToSpatialDomainWithFourierAtPosition
  • transformWithG_wg
• Nonlinear flux and forcing internals
  • enstrophyFluxFromF0
  • fluxForForcing
  • qgpvFluxFromF0
• Persistence internals
  • classRequiredPropertyNames
  • geometryFromGroup
  • namesOfRequiredPropertiesForGeometry
  • namesOfRequiredPropertiesForRotatingFPlane
  • namesOfRequiredPropertiesForTransform
  • namesOfTransformVariables
  • newNonrequiredPropertyNames
  • newRequiredPropertyNames
  • requiredPropertiesForGeometryFromGroup
  • requiredPropertiesForRotatingFPlaneFromGroup
  • requiredPropertiesForTransformFromGroup
  • transformFromGroup
• Caches and registries
  • propertyAnnotationsForGeometry return array of CAPropertyAnnotations initialized by default
  • propertyAnnotationsForRotatingFPlane
• Class internals
  • chebfunForZArray
  • maxFg
  • maxFw
  • quadraturePointsForStratifiedFlow return the quadrature points for a given stratification
  • throwErrorIfDensityViolation checks if the proposed coefficients are a valid adiabatic re-arrangement of the base state
  • verticalProjectionOperatorsWithRigidLid return the normalized projection operators with prefactors

---