WVTransform

Represent a fluid state with orthogonal wave and geostrophic solutions.

---

Declaration

classdef WVTransform < matlab.mixin.indexing.RedefinesDot & CAAnnotatedClass

Overview

WVTransform is the abstract base class for wave-vortex transforms. Each concrete transform represents the fluid state at time t with spectral coefficients and exposes physical variables such as velocity, isopycnal displacement, pressure, and potential vorticity. Density is denoted by \(\rho\). Energetic quantities are normalized per unit reference density \(\rho_0\) unless a method states otherwise.

The distinguishing feature of a WVTransform is that an instantaneous fluid state is represented as energetically orthogonal wave, inertial, geostrophic, and mean-density-anomaly constituents. No temporal filter is required to perform the decomposition. The same object can reconstruct \((u,v,w,\rho,p)\), relative vorticity, potential vorticity, energetic diagnostics, and custom registered variables from those coefficients.

Choose one of five concrete transform classes:

• WVTransformConstantStratification, in hydrostatic or nonhydrostatic mode
• WVTransformHydrostatic
• WVTransformBoussinesq
• WVTransformStratifiedQG
• WVTransformBarotropicQG

Wave-bearing transforms store positive- and negative-frequency wave and inertial coefficients in Ap and Am, and zero-frequency geostrophic and mean-density-anomaly coefficients in A0. Quasigeostrophic transforms use A0 only. The Apt, Amt, and A0t variables are the corresponding coefficients evaluated at the current transform time.

Topics

• Create and restore a transform
  • waveVortexTransformFromFile Initialize a WVTransform instance from an existing file
• Inspect the domain
  • Spectral grid
    • Resolution and shape
      • summarizeDegreesOfFreedom Summarize the spatial grid and active spectral degrees of freedom.
  • Transform configuration
    • isHydrostatic Whether the transform uses the hydrostatic approximation.
• 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
• 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.
  • At arbitrary positions
    • variableAtPositionWithName Access dynamical variables at arbitrary positions in the domain.
• 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
    • 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.
  • Spectra
    • Frequency
      • convertFromWavenumberToFrequency Bin wave energy by vertical mode and intrinsic frequency
• Analyze energy
  • Component energy
    • 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)\).
    • transformWaveVortexToUVWEta transform wave-vortex coefficients \((A_+,A_-,A_0)\) to fluid variables \((u,v,\eta)\).
• Inspect flow components
  • Primary flow components
    • 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.
  • Coefficient evolution
    • t0 Reference time for the stored wave phases, in seconds.
    • t Current transform time in seconds.
• Create a related 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
  • A0_KE_factor
  • A0_PE_factor
  • A0_Psi_factor
  • A0_QGPV_factor
  • A0_TE_factor
  • A0_TZ_factor
  • Apm_TE_factor
• Geometry and mode indexing
  • Additional geometry utilities
    • concatenateVariablesAlongTimeDimension Concatenate variables along the time dimension
    • spatialDimensionNames
    • spectralDimensionNames
• Spectral transforms and operators
  • optimizedTransformsForFlowComponent returns optimized transforms that avoid unnecessary computation
  • transformFromSpatialDomainWithFg Required for transformUVEtaToWaveVortex
  • transformFromSpatialDomainWithGg
  • transformToSpatialDomainWithF Required for transformWaveVortexToUVEta
  • transformToSpatialDomainWithFAllDerivatives
  • transformToSpatialDomainWithG
  • transformToSpatialDomainWithGAllDerivatives
• Nonlinear flux and forcing internals
  • energyFluxFromNonlinearFlux converts nonlinear flux into energy flux
  • enstrophyFluxFromNonlinearFlux converts nonlinear flux into enstrophy flux
  • forcingType
  • nFluxedComponents
  • nonlinearFlux
  • nonlinearFluxForFlowComponents returns the flux of each coefficient as determined by the nonlinear flux operation
  • nonlinearFluxWithGradientMasks returns the flux of each coefficient as determined by the nonlinear flux operation
  • nonlinearFluxWithMask returns the flux of each coefficient as determined by the nonlinear flux
  • rk4NonlinearFlux
  • rk4NonlinearFluxForFlowComponents
  • spatialFluxForcing
  • spectralAmplitudeForcing
  • spectralFluxForcing
• Persistence internals
  • createNetCDFFileForTimeStepOutput Output the WVTransform to file with variable time dimension
  • initForcingFromNetCDFFile forcingGroupName = join( [string(class(self)),”forcing”],”-“);
  • restoreForcingAmplitudes
• Caches and registries
  • addToVariableCache add variable to internal cache, in case it is needed again
  • classDefinedOperationForKnownVariable This is one of two functions that returns operations for computing
  • clearVariableCacheOfApAmA0DependentVariables clear the internal cache
  • clearVariableCacheOfTimeDependentVariables clear the internal cache of variables that claim to be time dependent
  • defaultOperations return array of WVOperation instances initialized by default
  • fetchFromVariableCache retrieve a set of variables from the internal cache
  • flowComponentNameMap
  • forcingNameMap
  • operationForKnownVariable This is one of two functions that returns operations for computing
  • operationNameMap
  • operationVariableNameMap
  • performOperation computes (runs) the operation
  • performOperationWithName computes (runs) the operation
  • primaryFlowComponentNameMap
  • propertyAnnotationForKnownVariable This is one of two functions that returns operations for computing
  • propertyAnnotationsForTransform return array of CAPropertyAnnotations for the WVTransform
  • removeFromVariableCache remove one variable from the internal cache
  • timeDependentVariablesNameMap
  • updateDependentVariablesNameMap
  • variableCache
  • wvCoefficientDependentVariablesNameMap
• Class internals
  • hasPVComponent
  • hasWaveComponent
• Construction internals
  • WVTransform Initialize the internal WVTransform state for a concrete subclass.

---