Skip to content

Add MaximumMask forcing mask#5576

Open
ewquon wants to merge 13 commits into
mainfrom
eq/maximum-mask
Open

Add MaximumMask forcing mask#5576
ewquon wants to merge 13 commits into
mainfrom
eq/maximum-mask

Conversation

@ewquon
Copy link
Copy Markdown
Collaborator

@ewquon ewquon commented May 12, 2026

Summary

  • New MaximumMask(masks...) callable: composes any number of mask objects by
    their pointwise maximum, mask(x, y, z) = max(mask₁(x, y, z), mask₂(x, y, z), …).
  • Mask-agnostic — composes GaussianMask, PiecewiseLinearMask, or any other
    callable mask (no hard dependency on CosineRampMask from Add CosineRampMask forcing mask #5574).
  • Sits next to GaussianMask / PiecewiseLinearMask in src/Forcings/relaxation.jl,
    exported from Forcings.jl and re-exported from Oceananigans.
  • 3-arg (x, y, z) callable matching the existing mask precedent; default Adapt
    covers the struct.
  • No new dependencies.

Why

Composing multiple sponge or boundary-nudging zones via MultipleForcings is
additive, which double-strengths the relaxation rate wherever zones overlap —
typically at corners in Davies-style lateral nudging or where an upper sponge
meets a lateral one. MaximumMask saturates at 1 in the overlap region instead,
preserving the user-specified timescale 1/rate throughout the nudging volume.

This is independently useful for users assembling boundary forcing today (no
CosineRampMask required), and pairs cleanly with CosineRampMask (#5574) once
that lands for the canonical Davies recipe.

Tests

  • New @testset "MaximumMask construction and pointwise max" in
    test/test_forcings.jl covers:
    • single-mask passthrough
    • pointwise max correctness across a 3D (x, y, z) sweep
    • composition with mixed mask types (GaussianMask + PiecewiseLinearMask)
    • saturation at 1 with overlapping unit-peaked masks
    • ArgumentError on the no-arg constructor
    • summary string format
  • New relaxed_time_stepping_max_mask(arch) smoke test runs a Davies-style
    MaximumMask of two GaussianMasks inside a Relaxation on a
    NonhydrostaticModel for one time step, exercising the mask through the
    kernel path; wired into the existing relaxation-forcing testset (CPU + GPU).
  • Doctest snippet in docs/src/models/forcing_functions.md showing a
    Davies-style construction; output verified locally.

Test plan

  • CPU unit + smoke tests pass locally
  • Doctest output verified to match
  • CI green (CPU + GPU)
  • Docs build green

ewquon and others added 3 commits May 11, 2026 23:42
Composes any number of callable masks via pointwise `max`, so overlapping
nudging zones saturate at 1 rather than summing. Useful for Davies-style
lateral boundary nudging where corner zones overlap and additive combination
would double the effective relaxation rate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a host-side `@testset` covering single-mask passthrough, pointwise
`max` correctness across a 3D sweep, composition with mixed mask types
(`GaussianMask` + `PiecewiseLinearMask`), saturation at 1 for overlapping
unit-peaked masks, the no-arg `ArgumentError`, and the `summary` string.

Adds an architecture-parameterized smoke test that runs a `Relaxation` with
a Davies-style `MaximumMask` of two `GaussianMask`s for one time step on a
`NonhydrostaticModel`, exercising the mask through the kernel path on both
CPU and GPU.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds `MaximumMask` to the mask-type bullet list in the `Relaxation` section
and a jldoctest snippet showing a Davies-style lateral mask built from two
`GaussianMask`s near opposite x-boundaries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Comment thread src/Forcings/relaxation.jl Outdated
Comment thread src/Oceananigans.jl Outdated
Comment thread src/Forcings/Forcings.jl Outdated
Comment thread docs/src/models/forcing_functions.md
Comment thread src/Forcings/Forcings.jl Outdated
Comment thread src/Forcings/relaxation.jl Outdated
Comment thread src/Oceananigans.jl Outdated
Comment thread docs/src/models/forcing_functions.md Outdated
Comment thread src/Forcings/relaxation.jl
Comment thread src/Forcings/relaxation.jl Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants