Export SplitRungeKutta3TimeStepper a few docstring fixes (typos and rendering) (#4571)

* export SplitRungeKutta3TimeStepper

* enhance docstring

* enhance docstring

* fix typo in docs

* fix docstring

* docstring rendering

* tweak docstring

* add refs

* tweaks

* enhance docstrings

* Update src/TimeSteppers/runge_kutta_3.jl

Co-authored-by: Simone Silvestri <[email protected]>

---------

Co-authored-by: Simone Silvestri <[email protected]>

Author: navidcy

src/Grids/grid_utils.jl

@@ -343,6 +343,7 @@ It has been known since the time of Euler and Lagrange that
 
 References
 ==========
+
 * Euler, L. (1778) De mensura angulorum solidorum, Opera omnia, 26, 204-233 (Orig. in Acta adac. sc. Petrop. 1778)
 * Lagrange,  J.-L. (1798) Solutions de quilquies problèmes relatifs au triangles sphéruques, Oeuvres, 7, 331-359.
 """
@@ -374,6 +375,7 @@ that ``P`` above is the same as the volume defined by the vectors `a`, `b`, and
 
 References
 ==========
+
 * Eriksson, F. (1990) On the measure of solid angles, Mathematics Magazine, 63 (3), 184-187, doi:10.1080/0025570X.1990.11977515
 """
 function spherical_area_triangle(a₁::AbstractVector, a₂::AbstractVector, a₃::AbstractVector)

src/Simulations/callback.jl

@@ -36,7 +36,6 @@ which in turn does nothing by default.
 
 `finalize!` can be specialized on `callback.parameters`,
 or specialized for `callback.func`.
-`
 """
 finalize!(callback::Callback, sim) = finalize!(callback.func, sim)
 
@@ -55,7 +54,7 @@ If `isnothing(parameters)`, `func(sim::Simulation)` is called.
 Otherwise, `func` is called via `func(sim::Simulation, parameters)`.
 
 The `callsite` determines where `Callback` is executed. The possible values for
-`callsite` are
+`callsite` are:
 
 * `TimeStepCallsite()`: after a time-step.
 
@@ -143,4 +142,4 @@ function add_callback!(simulation, func, schedule = IterationInterval(1);
     return add_callback!(simulation, callback; name)
 end
 
-validate_schedule(func, schedule) = schedule
+validate_schedule(func, schedule) = schedule

src/Simulations/simulation.jl

@@ -28,7 +28,8 @@ mutable struct Simulation{ML, DT, ST, DI, OW, CB, FT, BL}
 end
 
 """
-    Simulation(model; Δt,
+    Simulation(model;
+               Δt,
                verbose = true,
                stop_iteration = Inf,
                stop_time = Inf,
@@ -43,12 +44,21 @@ Keyword arguments
 - `Δt`: Required keyword argument specifying the simulation time step. Can be a `Number`
         for constant time steps or a `TimeStepWizard` for adaptive time-stepping.
 
-- `stop_iteration`: Stop the simulation after this many iterations.
+- `stop_iteration`: Stop the simulation after this many iterations. Default: `Inf`.
 
-- `stop_time`: Stop the simulation once this much model clock time has passed.
+- `stop_time`: Stop the simulation once this much model clock time has passed. Default: `Inf`.
 
 - `wall_time_limit`: Stop the simulation if it's been running for longer than this many
-                     seconds of wall clock time.
+                     seconds of wall clock time. Default: `Inf`.
+
+- `align_time_step`: When `true` it implies that the simulation will automatically adjust the
+                     time-step to meet a constraint imposed by various schedules like `ScheduledTimes`,
+                     `TimeInterval`, `AveragedTimeInterval`, as well as a `stop_time` criterion.
+                     If `false`, i.e., no time-step alignment, then the simulation might blithely step passed
+                     the specified time. Default: `true`.
+                     By `align_time_step = false` we ensure that the time-step does _not_ change within
+                     `time_step!(simulation)`
+
 - `minimum_relative_step`: time steps smaller than `Δt * minimum_relative_step` will be skipped.
                            This avoids extremely high values when writing the pressure to disk.
                            Default value is 0. See github.com/CliMA/Oceananigans.jl/issues/3593 for details.

src/TimeSteppers/TimeSteppers.jl

@@ -3,6 +3,7 @@ module TimeSteppers
 export
     QuasiAdamsBashforth2TimeStepper,
     RungeKutta3TimeStepper,
+    SplitRungeKutta3TimeStepper,
     time_step!,
     Clock,
     tendencies
@@ -42,13 +43,13 @@ include("split_hydrostatic_runge_kutta_3.jl")
 """
     TimeStepper(name::Symbol, args...; kwargs...)
 
-Returns a timestepper with name `name`, instantiated with `args...` and `kwargs...`.
+Return a timestepper with name `name`, instantiated with `args...` and `kwargs...`.
 
 Example
 =======
 
 ```julia
-julia> stepper = TimeStepper(:QuasiAdamsBashforth2, CPU(), grid, tracernames)
+julia> stepper = TimeStepper(:QuasiAdamsBashforth2, grid, tracernames)
 ```
 """
 TimeStepper(name::Symbol, args...; kwargs...) = TimeStepper(Val(name), args...; kwargs...)

src/TimeSteppers/clock.jl

@@ -121,5 +121,3 @@ Adapt.adapt_structure(to, clock::Clock) = (time          = clock.time,
                                            last_stage_Δt = clock.last_stage_Δt,
                                            iteration     = clock.iteration,
                                            stage         = clock.stage)
-
-

src/TimeSteppers/quasi_adams_bashforth_2.jl

@@ -16,7 +16,7 @@ end
 
 Return a 2nd-order quasi Adams-Bashforth (AB2) time stepper (`QuasiAdamsBashforth2TimeStepper`)
 on `grid`, with `tracers`, and AB2 parameter `χ`. The tendency fields `Gⁿ` and `G⁻`, usually equal to
-the prognostic_fields passed as positional argument, can be specified via  optional `kwargs`.
+the `prognostic_fields` that is passed as positional argument, can be specified via optional `kwargs`.
 
 The 2nd-order quasi Adams-Bashforth timestepper steps forward the state `Uⁿ` by `Δt` via
 

src/TimeSteppers/runge_kutta_3.jl

@@ -4,7 +4,7 @@ using Oceananigans: fields
 """
     RungeKutta3TimeStepper{FT, TG} <: AbstractTimeStepper
 
-Holds parameters and tendency fields for a low storage, third-order Runge-Kutta-Wray
+Hold parameters and tendency fields for a low storage, third-order Runge-Kutta-Wray
 time-stepping scheme described by [LeMoin1991](@citet).
 """
 struct RungeKutta3TimeStepper{FT, TG, TI} <: AbstractTimeStepper
@@ -24,12 +24,13 @@ end
                            Gⁿ = map(similar, prognostic_fields),
                            G⁻ = map(similar, prognostic_fields))
 
-Return a 3rd-order Runge0Kutta timestepper (`RungeKutta3TimeStepper`) on `grid` and with `tracers`.
-The tendency fields `Gⁿ` and `G⁻`, typically equal to the prognostic_fields can be modified via an optional `kwargs`.
+Return a 3rd-order Runge-Kutta timestepper (`RungeKutta3TimeStepper`) on `grid`
+and with `prognostic_fields`. The tendency fields `Gⁿ` and `G⁻`, typically equal
+to the `prognostic_fields` can be modified via the optional `kwargs`.
 
-The scheme described by [LeMoin1991](@citet). In a nutshel, the 3rd-order
-Runge Kutta timestepper steps forward the state `Uⁿ` by `Δt` via 3 substeps. A pressure correction
-step is applied after at each substep.
+The scheme is described by [LeMoin1991](@citet). In a nutshell, the 3rd-order
+Runge-Kutta timestepper steps forward the state `Uⁿ` by `Δt` via 3 substeps.
+A pressure correction step is applied after at each substep.
 
 The state `U` after each substep `m` is
 
@@ -39,11 +40,18 @@ Uᵐ⁺¹ = Uᵐ + Δt * (γᵐ * Gᵐ + ζᵐ * Gᵐ⁻¹)
 
 where `Uᵐ` is the state at the ``m``-th substep, `Gᵐ` is the tendency
 at the ``m``-th substep, `Gᵐ⁻¹` is the tendency at the previous substep,
-and constants ``γ¹ = 8/15``, ``γ² = 5/12``, ``γ³ = 3/4``,
-``ζ¹ = 0``, ``ζ² = -17/60``, ``ζ³ = -5/12``.
+and constants `γ¹ = 8/15`, `γ² = 5/12`, `γ³ = 3/4`, `ζ¹ = 0`, `ζ² = -17/60`,
+and `ζ³ = -5/12`.
+
+The state at the first substep is taken to be the one that corresponds to
+the ``n``-th timestep, `U¹ = Uⁿ`, and the state after the third substep is
+then the state at the `Uⁿ⁺¹ = U⁴`.
+
+References
+==========
+Le, H. and Moin, P. (1991). "An improvement of fractional step methods for the incompressible
+    Navier–Stokes equations." Journal of Computational Physics, 92, 369–379.
 
-The state at the first substep is taken to be the one that corresponds to the ``n``-th timestep,
-`U¹ = Uⁿ`, and the state after the third substep is then the state at the `Uⁿ⁺¹ = U⁴`.
 """
 function RungeKutta3TimeStepper(grid, prognostic_fields;
                                 implicit_solver::TI = nothing,

src/TimeSteppers/split_hydrostatic_runge_kutta_3.jl

@@ -2,9 +2,9 @@ using Oceananigans.Architectures: architecture
 using Oceananigans: fields
 
 """
-    SplitRungeKutta3TimeStepper{FT, TG} <: AbstractTimeStepper
+    SplitRungeKutta3TimeStepper{FT, TG, TE, PF, TI} <: AbstractTimeStepper
 
-Holds parameters and tendency fields for a low storage, third-order Runge-Kutta-Wray
+Hold parameters and tendency fields for a low storage, third-order Runge-Kutta-Wray
 time-stepping scheme described by [Lan2022](@citet).
 """
 struct SplitRungeKutta3TimeStepper{FT, TG, TE, PF, TI} <: AbstractTimeStepper
@@ -28,7 +28,7 @@ end
 Return a 3rd-order `SplitRungeKutta3TimeStepper` on `grid` and with `tracers`.
 The tendency fields `Gⁿ` and `G⁻`, and the previous state ` Ψ⁻` can be modified via optional `kwargs`.
 
-The scheme described by [Lan2022](@citet). In a nutshell, the 3rd-order Runge Kutta timestepper
+The scheme is described by [Lan2022](@citet). In a nutshell, the 3rd-order Runge-Kutta timestepper
 steps forward the state `Uⁿ` by `Δt` via 3 substeps. A barotropic velocity correction step is applied
 after at each substep.
 
@@ -38,22 +38,27 @@ The state `U` after each substep `m` is
 Uᵐ⁺¹ = ζᵐ * Uⁿ + γᵐ * (Uᵐ + Δt * Gᵐ)
 ```
 
-where `Uᵐ` is the state at the ``m``-th substep, `Uⁿ` is the state at the ``n``-th timestep, `Gᵐ` is the tendency
-at the ``m``-th substep, and constants ``γ¹ = 1`, ``γ² = 1/4``, ``γ³ = 1/3``,
-``ζ¹ = 0``, ``ζ² = 3/4``, ``ζ³ = 1/3``.
+where `Uᵐ` is the state at the ``m``-th substep, `Uⁿ` is the state at the ``n``-th timestep,
+`Gᵐ` is the tendency at the ``m``-th substep, and constants `γ¹ = 1`, `γ² = 1/4`, `γ³ = 1/3`,
+`ζ¹ = 0`, `ζ² = 3/4`, and `ζ³ = 1/3`.
 
 The state at the first substep is taken to be the one that corresponds to the ``n``-th timestep,
 `U¹ = Uⁿ`, and the state after the third substep is then the state at the `Uⁿ⁺¹ = U³`.
+
+References
+==========
+Lan, R., Ju, L., Wanh, Z., Gunzburger, M., and Jones, P. (2022). "High-order multirate explicit
+    time-stepping schemes for the baroclinic-barotropic split dynamics in primitive equations",
+    Journal of Computational Physics 457, 111050.
 """
 function SplitRungeKutta3TimeStepper(grid, prognostic_fields, args...;
                                      implicit_solver::TI = nothing,
                                      Gⁿ::TG = map(similar, prognostic_fields),
                                      Ψ⁻::PF = map(similar, prognostic_fields),
                                      G⁻::TE = nothing) where {TI, TG, PF, TE}
 
-
     @warn("Split barotropic-baroclinic time stepping with SplitRungeKutta3TimeStepper is not tested and experimental.\n" *
-          "Use at own risk, and report any issues encountered.")
+          "Use at own risk, and report any issues encountered at [https://github.com/CliMA/Oceananigans.jl/issues](https://github.com/CliMA/Oceananigans.jl/issues).")
 
     !isnothing(implicit_solver) &&
         @warn("Implicit-explicit time-stepping with SplitRungeKutta3TimeStepper is not tested. " *
@@ -70,7 +75,6 @@ function SplitRungeKutta3TimeStepper(grid, prognostic_fields, args...;
     return SplitRungeKutta3TimeStepper{FT, TG, TE, PF, TI}(γ², γ³, ζ², ζ³, Gⁿ, G⁻, Ψ⁻, implicit_solver)
 end
 
-
 function time_step!(model::AbstractModel{<:SplitRungeKutta3TimeStepper}, Δt; callbacks=[])
     Δt == 0 && @warn "Δt == 0 may cause model blowup!"
 
@@ -172,4 +176,3 @@ function cache_previous_fields!(model)
 
     return nothing
 end
-

src/TurbulenceClosures/turbulence_closure_implementations/TKEBasedVerticalDiffusivities/catke_vertical_diffusivity.jl

@@ -58,9 +58,9 @@ Turbulent Kinetic Energy (TKE).
 !!! note "CATKE vertical diffusivity"
     `CATKEVerticalDiffusivity` is a new turbulence closure diffusivity. The default
     values for its free parameters are obtained from calibration against large eddy
-    simulations. For more details please refer to [Wagner25catke](@cite).
+    simulations. For more details please refer to [Wagner25catke](@citet).
 
-    Use with caution and report any issues with the physics at https://github.com/CliMA/Oceananigans.jl/issues.
+    Use with caution and report any issues with the physics at [https://github.com/CliMA/Oceananigans.jl/issues](https://github.com/CliMA/Oceananigans.jl/issues).
 
 Arguments
 =========
@@ -77,18 +77,19 @@ Keyword arguments
 
 - `turbulent_kinetic_energy_equation`: The TKE equation; default: `CATKEEquation()`.
 
-- `maximum_tracer_diffusivity`: Maximum value for tracer diffusivity. CATKE-predicted tracer diffusivities that are larger
-                                than `maximum_tracer_diffusivity` are clipped. Default: `Inf`.
+- `maximum_tracer_diffusivity`: Maximum value for tracer diffusivity. CATKE-predicted tracer
+                                diffusivities that are larger than `maximum_tracer_diffusivity`
+                                are clipped. Default: `Inf`.
 
-- `maximum_tke_diffusivity`: Maximum value for TKE diffusivity. CATKE-predicted diffusivities for TKE that are larger
-                             than `maximum_tke_diffusivity` are clipped. Default: `Inf`.
+- `maximum_tke_diffusivity`: Maximum value for TKE diffusivity. CATKE-predicted diffusivities
+                             for TKE that are larger than `maximum_tke_diffusivity` are clipped.
+                             Default: `Inf`.
 
-- `maximum_viscosity`: Maximum value for momentum diffusivity. CATKE-predicted momentum diffusivities that are larger
-                       than `maximum_viscosity` are clipped. Default: `Inf`.
+- `maximum_viscosity`: Maximum value for momentum diffusivity. CATKE-predicted momentum diffusivities
+                       that are larger than `maximum_viscosity` are clipped. Default: `Inf`.
 
-- `minimum_tke`: Minimum value for the turbulent kinetic energy.
-                 Can be used to model the presence "background" TKE
-                 levels due to, for example, mixing by breaking internal waves.
+- `minimum_tke`: Minimum value for the turbulent kinetic energy. Can be used to model the presence
+                 "background" TKE levels due to, for example, mixing by breaking internal waves.
                  Default: 1e-9.
 
 - `minimum_convective_buoyancy_flux` Minimum value for the convective buoyancy flux. Default: 1e-11.
@@ -99,6 +100,7 @@ Keyword arguments
 
 References
 ==========
+
 Wagner, G. L., Hillier, A., Constantinou, N. C., Silvestri, S., Souza, A., Burns, K., Hill,
     C., Campin, J.-M., Marshall, J., and Ferrari, R. (2025). "Formulation and calibration of CATKE,
     a one-equation parameterization for microscale ocean mixing." J. Adv. Model. Earth Sy., 17, e2024MS004522.

src/TurbulenceClosures/turbulence_closure_implementations/anisotropic_minimum_dissipation.jl

@@ -55,7 +55,7 @@ Keyword arguments
 
 * `Cκ`: Poincaré constant for tracer eddy diffusivities. If one number or function, the same
         number or function is applied to all tracers. If a `NamedTuple`, it must possess
-        a field specifying the Poncaré constant for every tracer.
+        a field specifying the Poincaré constant for every tracer.
 
 * `Cb`: Buoyancy modification multiplier (`Cb = nothing` turns it off, `Cb = 1` was used by [Abkar16](@citet)).
         *Note*: that we _do not_ subtract the horizontally-average component before computing this
@@ -67,8 +67,8 @@ The default Poincaré constant is found by discretizing subgrid scale energy pro
 second-order advection scheme. [Verstappen14](@citet) show that the Poincaré constant
 should be 4 times larger than for straightforward (spectral) discretisation, resulting in `C = 1/3`
 in our formulation. They also empirically demonstrated that this coefficient produces the correct
-discrete production-dissipation balance. We further demonstrated this in
-https://github.com/CliMA/Oceananigans.jl/issues/4367.
+discrete production-dissipation balance. Further demonstration of this can be found at
+[https://github.com/CliMA/Oceananigans.jl/issues/4367](https://github.com/CliMA/Oceananigans.jl/issues/4367).
 
 `C`, `Cν` and `Cκ` may be numbers, or functions of `x, y, z`.