WVTransformConstantStratification

Decompose constant-stratification flow into wave and geostrophic components.

---

Declaration

classdef WVTransformConstantStratification < WVTransform

Overview

To initialize an instance of the WVTransformConstantStratification class you must specify the domain size, the number of grid points, and the constant buoyancy frequency.

N0 = 3*2*pi/3600;
wvt = WVTransformConstantStratification([100e3,100e3,4000],[64,64,65],N0=N0,latitude=30);
wvtHydrostatic = WVTransformConstantStratification([100e3,100e3,4000],[64,64,65],N0=N0,latitude=30,isHydrostatic=true);

The transform state is stored in Ap, Am, and A0. Their current-time views are Apt, Amt, and A0t.

Topics

• Create and restore a transform
  • WVTransformConstantStratification Create a wave-vortex transform for constant stratification.
  • waveVortexTransformFromFile Restore a WVTransformConstantStratification 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
      • N0 Constant buoyancy frequency in radians per second.
      • 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.
      • shouldUseTrueNoMotionProfile Whether density diagnostics use the supplied no-motion profile directly.
    • 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
    • computationalBackend Active nonlinear-flux implementation.
    • computationalBackendMetadata Identity, scope, and storage information for the active backend.
    • 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
  • Waves
    • Individual modes
      • addWaveModes add amplitudes of the given wave modes
      • initWithWaveModes initialize with the given wave modes
      • removeAllWaves removes all wave from the model, including inertial oscillations
      • setWaveModes set amplitudes of the given wave modes
    • Wave spectra
      • addGMSpectrum add waves following a Garrett-Munk spectrum
      • addWavesWithFrequencySpectrum add waves with a specified frequency spectrum
      • initWavesWithFrequencySpectrum initialize with waves of a specified frequency spectrum
      • initWithAlternativeSpectrum initialize with an alternative formulation of the GM spectrum in the wavenumber domain.
      • initWithGMSpectrum initialize the wave field following a Garrett-Munk spectrum
  • Inertial oscillations
    • addInertialMotions add inertial motions to existing inertial motions
    • initWithInertialMotions initialize with inertial motions
    • removeAllInertialMotions remove all inertial motions
    • setInertialMotions set inertial motions
  • 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
  • Mean density anomalies
    • addMeanDensityAnomaly Add a mean-density anomaly to the existing fluid state.
    • initWithMeanDensityAnomaly Initialize the fluid state with a mean-density anomaly.
    • removeAllMeanDensityAnomaly remove all mean density anomalies
    • setMeanDensityAnomaly Set the mean-density-anomaly component.
• 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
      • w z-component of the fluid velocity
    • Density and displacement
      • eta approximate isopycnal deviation
      • rho_e excess density
      • rho_nm Diagnosed no-motion density profile, [Nz 1], in \(\mathrm{kg\,m^{-3}}\).
      • 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_x x-component component of relative vorticity
      • zeta_y y-component component of relative 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
    • wMax max vertical 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)
    • Frequency
      • convertFromWavenumberToFrequency Bin wave energy by vertical mode and intrinsic frequency
• Analyze energy
  • Component energy
    • inertialEnergy total energy of the inertial flow
    • mdaEnergy total energy of the mean density anomaly
    • geostrophicKineticEnergy kinetic energy of the geostrophic flow
    • waveEnergy Total energy of the internal-gravity-wave 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
    • transformUVEtaToWaveVortex transform fluid variables \((u,v,\eta)\) to wave-vortex coefficients \((A_+,A_-,A_0)\).
    • transformUVWEtaToWaveVortex transform momentum variables \((u,v,w,\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
    • waveComponent returns the internal gravity wave flow component
    • inertialComponent returns the inertial oscillation flow component
    • geostrophicComponent returns the geostrophic flow component
    • mdaComponent returns the mean density anomaly 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
    • Ap Positive-frequency wave–vortex coefficient array.
    • Am Negative-frequency wave–vortex coefficient array.
    • A0 Zero-frequency wave–vortex coefficient array.
  • Coefficients at the current time
    • Apt Apt is the positive-frequency coefficient array evaluated at the current transform time:
    • Amt Amt is the negative-frequency coefficient array evaluated at the current transform 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
    • waveCoefficientsAtTimeT Return positive- and negative-frequency coefficients at the current time.
  • Coefficient evolution
    • t0 Reference time for the stored wave phases, in seconds.
    • t Current transform time in seconds.
    • Omega Intrinsic angular frequency of each wave and inertial mode.
    • iOmega Imaginary angular frequency, \(i\Omega\), used for linear phase evolution.
    • phase unit-magnitude phase factor that advances Ap from t0 to t
    • conjPhase conjugate phase factor that advances Am from t0 to t
• Create a related transform
  • spectralVariableWithResolution create a new variable with different resolution
  • waveVortexTransformWithDoubleResolution create a new WVTransform with double resolution
  • waveVortexTransformWithExplicitAntialiasing Create an explicit-antialiasing transform with the same grid.
  • 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\).
  • ApmD Projects horizontal divergence onto \(A_+\) and \(A_-\).
  • ApmD_scaled
  • ApmN Projects density displacement onto \(A_+\) and \(A_-\).
  • ApmW_scaled
  • NA0 Reconstructs density displacement from \(A_0\).
  • NAm Reconstructs density displacement from \(A_-\).
  • NAp Reconstructs density displacement from \(A_+\).
  • PA0 Reconstructs pressure height from \(A_0\).
  • UA0 Reconstructs \(u\) from \(A_0\).
  • UAm Reconstructs \(u\) from \(A_-\).
  • UAp Reconstructs \(u\) from \(A_+\).
  • VA0 Reconstructs \(v\) from \(A_0\).
  • VAm Reconstructs \(v\) from \(A_-\).
  • VAp Reconstructs \(v\) from \(A_+\).
  • WAm Reconstructs \(w\) from \(A_-\).
  • WAp Reconstructs \(w\) from \(A_+\).
• 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
  • Additional geometry utilities
    • buildVerticalModeProjectionOperators Build the transformation matrices
• Spectral transforms and operators
  • CosineTransformBackMatrix Discrete Cosine Transform (DCT-I) matrix
  • CosineTransformForwardMatrix Discrete Cosine Transform (DCT-I) matrix
  • DCT
  • DST
  • FwInvMatrix transformation matrix \(F_w^{-1}\)
  • FwMatrix transformation matrix \(F_w\)
  • GwInvMatrix transformation matrix \(G_w^{-1}\)
  • GwMatrix transformation matrix \(G_w\)
  • SineTransformBackMatrix CosineTransformBackMatrix Discrete Cosine Transform (DCT-I) matrix
  • SineTransformForwardMatrix CosineTransformForwardMatrix Discrete Cosine Transform (DCT-I) matrix
  • 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
  • iDCT
  • iDST
  • transformFromSpatialDomainWithFio
  • transformFromSpatialDomainWithFourier
  • transformStorageLedger Return known transform storage and explicitly opaque internal storage.
  • transformToSpatialDomainWithFourier
  • transformToSpatialDomainWithFourierAtPosition
  • transformWithG_wg
• Nonlinear flux and forcing internals
  • Feta
  • Fu
  • Fv
  • enstrophyFluxFromF0
  • fluxForForcing
  • nonlinearFluxFunction
  • nonlinearFluxHydrostatic
  • nonlinearFluxNonhydrostatic
  • qgpvFluxFromF0
  • spatialFluxForForcingWithName
• 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
  • F_g
  • F_wg
  • G_g
  • G_wg
  • chebfunForZArray
  • cos_alpha
  • maxFg
  • maxFw
  • quadraturePointsForStratifiedFlow return the quadrature points for a given stratification
  • sin_alpha
  • throwErrorIfDensityViolation checks if the proposed coefficients are a valid adiabatic re-arrangement of the base state
  • verticalProjectionOperatorsWithRigidLid return the normalized projection operators with prefactors

---