.. _ramps:

=====
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:

.. code-block:: yaml

   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:

.. list-table::
   :header-rows: 1
   :widths: 32 68

   * - Block
     - Scales
   * - ``forcing.ramp``
     - Tidal potential and boundary forcing, and meteorology unless
       ``forcing.meteorological.ramp`` is given
       (:doc:`tidal_forcing`)
   * - ``forcing.meteorological.ramp``
     - Wind and pressure forcing; a key it omits takes the value from
       ``forcing.ramp`` (:ref:`meteo-cold-start-ramp`)
   * - ``forcing.flow_boundary.ramp``
     - Flow boundary discharge and elevation (:doc:`boundary_conditions`)
   * - ``forcing.baroclinic.ramp``
     - The baroclinic pressure gradient, internal-tide drag and dispersion
       (:doc:`baroclinic_coupling`)
   * - ``forcing.water_level_correction.ramp``
     - The water level correction (:doc:`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 (:ref:`meteo-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
----

.. list-table::
   :header-rows: 1
   :widths: 15 15 15 55

   * - 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
       :ref:`duration string <duration-syntax>` (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.

.. _ramp-forms:

Forms
-----

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

.. list-table::
   :header-rows: 1
   :widths: 18 30 52

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

.. figure:: ../_static/images/diagrams/ramp_forms.svg
   :alt: The three ramp forms and their slopes against the elapsed fraction
   :width: 700px
   :align: center

   The three forms (left) and their slopes in units of :math:`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.

.. _ramp-activation-fades:

Activation Fades
----------------

A fade with duration :math:`T` on a source whose window runs from
:math:`t_{open}` to :math:`t_{close}` weights the source by

.. math::

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

where :math:`r` is the block's form. A window shorter than :math:`2T`
never reaches full weight: for a window of length :math:`L` the weight is
at most :math:`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. :ref:`meteo-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>``.