Tidal Forcing

Cocoa supports two methods for tidal forcing:

Harmonic constituents - Traditional method using pre-defined tidal amplitudes, frequencies, and phases
Astronomical tide potential - Direct calculation of Moon and Sun positions using Jean Meeus algorithms for automatic inclusion of all tidal constituents

The harmonic constituent method requires pre-computed tidal databases, while the astronomical method computes tide-generating forces directly from Moon and Sun positions.

Astronomical Tide Potential

The astronomical tide potential method computes the equilibrium tide directly from celestial body positions, automatically capturing:

All tidal constituents (no explicit harmonic decomposition needed)
Nodal modulation (18.6-year lunar cycle)
Long-period tides (fortnightly, monthly, semi-annual, annual)

This method is recommended for:

Long simulations where nodal factors may become outdated
Global or regional applications without constituent databases
Studies requiring accurate representation of the complete tidal spectrum

Configuration

Enable astronomical tide potential in your configuration file:

forcing:
  ramp:
    enabled: true
    duration: 1d
  tide:
    potential:
      enabled: true
      type: "astronomical"
      astronomical:
        order: 2              # Expansion order: 2=P2, 3=P3, 4=exact
        include_nutation: true
        k2: 0.302             # Optional Love number override
        h2: 0.609             # Optional Love number override

Parameters:

Parameter	Default	Description
`order`	4	Legendre polynomial expansion order. 2 (P2) is standard equilibrium tide; 3 (P3) adds degree-3 term for improved coastal accuracy; 4+ uses full expansion matching ADCIRC.
`include_nutation`	true	Include nutation corrections in position calculations for higher accuracy at the cost of slightly more computation.
`k2`	0.302	Second-degree Love number for body tide. Represents elastic deformation of Earth due to tidal forces.
`h2`	0.609	Second-degree Love number for vertical displacement. Represents radial displacement of Earth’s surface.

The Earth elasticity factor \((1 + k_2 - h_2) \approx 0.69\) reduces the equilibrium tide amplitude to account for the solid Earth’s elastic response.

Note

When using the astronomical method, you do not need to specify individual tidal constituents for the potential. The method automatically computes the complete tide-generating potential from calculated celestial positions.

Self-Attraction and Loading (SAL)

Self-attraction and loading (SAL) accounts for two effects that modify the ocean tide:

The gravitational attraction of the ocean on itself (self-attraction)
The deformation of the Earth’s crust under the weight of the ocean tide (loading)

SAL corrections are applied as spatially-varying amplitude and phase adjustments per tidal constituent at each mesh node. The SAL data must be pre-computed externally (e.g., from a global tide model) and embedded in the mesh file during conversion.

Preparing SAL Data

SAL data is included during mesh conversion using the --sal flag:

python utils/convert_adcirc_format.py \
    --mesh fort.14 \
    --attributes fort.13 \
    --sal fort.24 \
    --output mesh.nc

The SAL file can be in ADCIRC ASCII format (fort.24) or NetCDF format (fort.24.nc). It contains per-node amplitude (meters) and phase (degrees) for each SAL constituent.

Configuration

Enable SAL in the configuration file:

forcing:
  tide:
    sal:
      enabled: true
      parameter_source: "auto"  # or "manual"

Parameters:

Parameter	Default	Description
`enabled`	false	Enable SAL forcing
`parameter_source`	“auto”	How to determine constituent frequencies and nodal factors. `"auto"` looks up each constituent in the built-in tidal database. `"manual"` uses values provided in the config file.

Auto Mode

In auto mode (the default), Cocoa matches SAL constituent names from the mesh file against its built-in tidal constituent database to determine frequencies, nodal factors, and equilibrium arguments at the simulation coldstart time. No additional configuration is needed:

forcing:
  tide:
    sal:
      enabled: true

Manual Mode

Manual mode is used for exact validation against ADCIRC, where you need to specify the precise frequency, nodal factor, and equilibrium argument for each constituent:

forcing:
  tide:
    sal:
      enabled: true
      parameter_source: "manual"
      constituents:
        - name: M2
          frequency: 1.405189028e-04  # rad/s (converted to rad/hr internally)
          nodal_factor: 1.026777
          equilibrium_arg: 26.668130  # degrees (converted to radians internally)
        - name: K1
          frequency: 7.292117e-05     # rad/s
          nodal_factor: 1.0064
          equilibrium_arg: 12.45      # degrees

Each constituent in the list must have a name matching one of the constituent names stored in the mesh SAL data.

Note

If SAL is enabled but no SAL data is found in the mesh file, Cocoa will log a warning and continue without SAL corrections. Re-run the mesh converter with the --sal flag to include the data.

Harmonic Constituents

The harmonic constituent method specifies tides using pre-computed amplitudes, frequencies, and phases. This approach is suitable when tidal databases are available and for shorter simulations where nodal factors remain valid.

Common Tidal Constituents

Common tidal constituents used in Cocoa:

Name	Description	Period (hours)	Frequency (rad/s)
M2	Principal lunar semidiurnal	12.42	1.405189e-4
S2	Principal solar semidiurnal	12.00	1.454441e-4
N2	Larger lunar elliptic	12.66	1.378797e-4
K1	Lunar diurnal	23.93	7.292117e-5
O1	Lunar diurnal	25.82	6.759774e-5
K2	Lunisolar semidiurnal	11.97	1.458423e-4
Q1	Larger lunar elliptic	26.87	6.495854e-5

Boundary Configuration

Tidal boundary constituents are specified in the forcing section of the configuration file:

forcing:
  tide:
    boundary:
      enabled: true
      constituents:
        - name: M2
          frequency: 0.000140518902509  # rad/s
          nodal_factor: 0.96461          #
          equilibrium_arg: 315.69        # degrees
          boundary_values:               # Per-node amplitude/phase
            - { amplitude: 0.52, phase: 344.17 }
            - { amplitude: 0.51, phase: 345.15 }
        - name: K1
          frequency: 0.000072921158358
          nodal_factor: 1.0064
          equilibrium_arg: 12.45
          boundary_values:
            - { amplitude: 0.15, phase: 45.0 }
            - { amplitude: 0.14, phase: 46.2 }

Each constituent requires:

name: Constituent identifier (M2, S2, K1, O1, etc.)
frequency: Angular frequency in rad/s
nodal_factor: Nodal modulation factor
equilibrium_arg: Equilibrium argument in degrees
boundary_values: List of amplitude/phase pairs, one per open boundary node

Spatially Varying Amplitudes

The boundary_values list provides per-node tidal amplitudes and phases for open boundaries. Each entry corresponds to a boundary node in mesh order:

boundary_values:
  - { amplitude: 0.50, phase: 340.0 }  # Node 1
  - { amplitude: 0.52, phase: 342.0 }  # Node 2
  - { amplitude: 0.48, phase: 338.0 }  # Node 3
  # ... one entry per open boundary node

where:

amplitude: Tidal amplitude in meters
phase: Tidal phase in degrees

Ramp-up Period

To avoid initial transients, use a ramp-up period:

forcing:
  ramp:
    enabled: true
    duration: 1d  # 1 day ramp-up

The tidal forcing is gradually increased during the ramp-up period using a normalized hyperbolic tangent function:

\[R(t) = \frac{1}{\tanh(2)}\tanh\left(\frac{2t}{T_{ramp}}\right)\]

The normalization by \(\tanh(2)\) ensures the ramp reaches exactly 1.0 at \(t = T_{ramp}\). The value is clamped to 1.0 for \(t \ge T_{ramp}\).