Ramps

A forcing switched on at full strength in a model at rest excites waves that take days to leave the domain. Cocoa scales each forcing by a ramp that rises from 0 to 1 instead. Every ramp in the configuration is the same block:

forcing:
  ramp:
    enabled: true      # default true
    duration: 1d       # time to rise from 0 to 1
    form: tanh         # the curve it rises along
    delay: 0           # time held at 0 before it rises

Where Ramps Apply

The spin-up ramps start once, near the start of the run:

Block	Scales
forcing.ramp	Tidal potential and boundary forcing, and meteorology unless forcing.meteorological.ramp is given (Tidal Forcing)
forcing.meteorological.ramp	Wind and pressure forcing; a key it omits takes the value from forcing.ramp (Combining Meteorological and Tidal Forcing)
forcing.flow_boundary.ramp	Flow boundary discharge and elevation (Boundary Conditions)
forcing.baroclinic.ramp	The baroclinic pressure gradient, internal-tide drag and dispersion (Baroclinic Coupling)
forcing.water_level_correction.ramp	The water level correction (Data Assimilation)

Each starts at the cold start (simulation.start_time), except the meteorological ramp, which starts at the earlier of the cold start and the first meteorological snapshot. Each defaults to enabled, one day and tanh. A restart continues every ramp from its original start rather than starting it again.

The activation fades bring a meteorological source in and out partway through the run: domains[i].ramp for one domains: entry and vortex.ramp for each storm track (Activation Ramp). A fade starts at its source’s own window edges, so it takes the block without delay. Fades are off by default, and an enabled fade must give its duration.

Keys

Key	Type	Default	Description
enabled	bool	true	A disabled ramp is 1 throughout.
duration	duration	1d	Time the ramp takes to rise from 0 to 1. 0 means no ramp, or a step when delay is set. Accepts a duration string (e.g. 1d, 12h) or a bare number of seconds.
form	string	tanh	tanh, linear or smoothstep (Forms).
delay	duration	0	Time after the ramp’s start during which it is 0, so the forcing is off. It then rises over duration; with duration: 0 it steps from 0 to 1 at the end of the delay. A delay needs an enabled ramp, and the fades do not take it.

Forms

With \(x\) the fraction of duration elapsed since the delay ended, clamped to \([0, 1]\), the forms are:

form	Ramp value	Slope, for a duration \(T\)
tanh	\(\tanh(2x)/\tanh(2)\)	Jumps from 0 to \(2.07/T\) at the start and ends at \(0.15/T\)
linear	\(x\)	Jumps from 0 to \(1/T\) at the start and back to 0 at the end
smoothstep	\(3x^2 - 2x^3\)	Zero at both ends, peaking at \(1.5/T\) mid-ramp

Fig. 4 The three forms (left) and their slopes in units of \(1/T\) (right). tanh brings the forcing in fastest; smoothstep is the only form whose slope does not jump where the ramp starts and ends.

A ramp evaluated every time step with smoothstep adds no jump to the forcing’s rate of change, though the forcing’s own interpolation between data times may still have one.

Activation Fades

A fade with duration \(T\) on a source whose window runs from \(t_{open}\) to \(t_{close}\) weights the source by

\[w(t) = r\!\left(\frac{t - t_{open}}{T}\right) \cdot r\!\left(\frac{t_{close} - t}{T}\right),\]

where \(r\) is the block’s form. A window shorter than \(2T\) never reaches full weight: for a window of length \(L\) the weight is at most \(r(L/2T)^2\), reached mid-window. For a window half the fade duration, that is 0.23 with tanh, 0.06 with linear and 0.02 with smoothstep, so a short-lived source needs a short fade.

A vortex or a moving storm grid evaluates its weight every time step. A gridded domain evaluates it at the meteorological snapshot times (every gridded source’s times, merged) and interpolates it linearly between them, so its form shapes the fade only when the fade spans several data intervals: with only 6-hourly data, a 6-hour fade is the same straight line whatever its form. Activation Ramp describes how the weight blends a source into the composed field.

With debug logging, the startup log describes each enabled spin-up ramp as <form> ramp over <hours> h from <time> or step at <time>.