WVTransformBoussinesq

Decompose nonhydrostatic variable-stratification flow into wave and geostrophic components.

---

Declaration

classdef WVTransformBoussinesq < WVTransform

Overview

To initialize an instance of the WVTransformBoussinesq 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 = WVTransformBoussinesq([100e3,100e3,4000],[64,64,65],N2Function=N2,latitude=30);

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
  • WVTransformBoussinesq Create a nonhydrostatic wave-vortex transform for variable stratification.
  • waveVortexTransformFromFile Restore a WVTransformBoussinesq 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.
      • 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.
      • volumeIntegral Compute the horizontally averaged depth integral of a scalar field.
  • 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
  • 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_bar Current horizontally averaged density, [Nz 1], in \(\mathrm{kg\,m^{-3}}\).
      • 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
    • exactPotentialEnstrophy Exact potential enstrophy evaluated from available potential vorticity.
    • 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
    • exactTotalEnergy Nonlinear total energy evaluated from physical-space fields.
    • 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_-\).
  • ApmN Projects density displacement onto \(A_+\) and \(A_-\).
  • ApmW
  • 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
• Spectral transforms and operators
  • FwInvMatrix transformation matrix \(F_w^{-1}\)
  • FwMatrix transformation matrix \(F_w\)
  • GwInvMatrix transformation matrix \(G_w^{-1}\)
  • GwMatrix transformation matrix \(G_w\)
  • 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
  • PFpm size(PF,PG)=[Nj x Nz x Nk]
  • PFpmInv IGW 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
  • QGpm dimensionless preconditioned G-mode forward transformation
  • QGpmInv dimensionless preconditioned G-mode inverse transformation
  • QGwg size(PF,PG)=[Nj x Nj x Nk]
  • 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
  • transformFromSpatialDomainWithG_w
  • transformToSpatialDomainWithFg arguments
  • transformToSpatialDomainWithFourier
  • transformToSpatialDomainWithFourierAtPosition
  • transformToSpatialDomainWithFw
  • transformToSpatialDomainWithGg arguments
  • transformToSpatialDomainWithGw
  • transformWithG_wg
• Nonlinear flux and forcing internals
  • Feta
  • Fu
  • Fv
  • enstrophyFluxFromF0
  • fluxForForcing
  • 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
  • Ddelta
  • K2unique unique squared-wavenumbers
  • K2uniqueK2Map cell array Nk in length. Each cell contains indices back to K2
  • Ppm Preconditioner for F, size(P)=[Nj x Nk]. Fu = uhat, (PF)u = Puhat, so ubar==Puhat
  • Qpm Preconditioner for G, size(Q)=[Nj x Nk]. Geta = etahat, (QG)eta = Qetahat, so etabar==Qetahat.
  • chebfunForZArray
  • delta_uhat
  • delta_vhat
  • iK2unique map from 2-dim K2, to 1-dim K2unique
  • maxFg
  • maxFw
  • nK2unique number of unique squared-wavenumbers
  • 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
  • wvBuffer

---