==================
Global Simulations
==================

This guide covers the setup and configuration of global ocean simulations in
Cocoa. Global models present unique challenges compared to regional coastal
models, including coordinate singularities at the poles and handling elements
that cross the prime meridian or date line.

Overview
--------

Global ocean models cover the entire Earth's ocean surface. Unlike regional
models that can ignore edge effects, global models must handle:

1. **Pole singularities**: The shallow water equations have singularities at
   geographic poles where meridians converge and the Coriolis parameter
   approaches its maximum value.

2. **Meridian discontinuities**: Elements that span the :math:`\pm 180`\ |deg|
   longitude line have coordinate discontinuities that can cause incorrect
   geometry calculations.

3. **Spherical geometry**: Scale factors and metric corrections become more
   important when the domain spans large latitude ranges.

Cocoa addresses these challenges through:

- **Automatic meridian crossing detection**: Elements straddling the antimeridian
  are automatically detected and corrected during mesh initialization.

- **Coordinate rotation**: An optional coordinate transformation that relocates
  the computational poles away from the geographic poles.

.. figure:: ../_static/images/diagrams/coordinate_rotation.svg
   :alt: Coordinate rotation moves pole singularities away from geographic poles
   :width: 550px
   :align: center

   Coordinate rotation relocates the computational poles (singularities) from
   the geographic poles to other positions, usually which are well over land,
   effectively removing the singularities from the model.

When to Use Coordinate Rotation
-------------------------------

Coordinate rotation is **required** when your global mesh includes elements
near the geographic poles (typically within 5-10 degrees of :math:`\pm 90`\ |deg|
latitude). Without rotation, simulations will experience:

- Numerical instability from near-singular Coriolis terms
- Time step restrictions due to converging meridians
- Degraded solution quality in polar regions

Coordinate rotation is **not required** for:

- Regional models (any latitude range)
- Global models that exclude polar regions (e.g., :math:`\pm 80`\ |deg| latitude bounds)

.. note::

   If your mesh was generated with ADCIRC's rotated pole system (IFSPROTS=1),
   you should use the same rotation parameters in Cocoa for consistency.

Configuration
-------------

Basic Global Mesh Setup
^^^^^^^^^^^^^^^^^^^^^^^

A minimal configuration for a global simulation without rotation:

.. code-block:: yaml

   mesh:
     filename: "global_mesh.nc"
     projection:
       type: "Mercator"
       center: [0.0, 0.0]  # Centered on equator

   simulation:
     start_time: 2025-01-01
     end_time: 2025-02-01
     time_step: 60s  # Global models often need larger time steps

   physics:
     manning_n: 0.025
     tau0: 0.005

The projection center ``[0.0, 0.0]`` places the reference point at the
intersection of the prime meridian and equator, which is typical for global
models.

Global Mesh with Coordinate Rotation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For global models including polar regions, enable coordinate rotation:

.. code-block:: yaml

   mesh:
     filename: "global_mesh_with_poles.nc"
     projection:
       type: "Mercator"
       center: [0.0, 0.0]
     rotation:
       enabled: true
       pole_location: [0.0, 0.0]  # New pole at (lon=0, lat=0)

The ``pole_location`` specifies where the geographic North Pole will be
relocated to in the rotated coordinate system. This uses the same format as
ADCIRC's ``znorth_in_spherical_coors`` in the fort.rotm file.

Common choices:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Pole Location
     - Effect
   * - ``[0.0, 0.0]``
     - North Pole moves to equator at prime meridian
   * - ``[180.0, 0.0]``
     - North Pole moves to equator at date line
   * - ``[-90.0, 0.0]``
     - North Pole moves to equator in Atlantic

The best choice depends on your domain and the location of your areas of
interest. Ideally, the rotated poles should be placed in regions of less
importance to your simulation (e.g., over land or in deep ocean far from
your study area).

Choosing a Pole Location
^^^^^^^^^^^^^^^^^^^^^^^^

When selecting the pole location, consider:

1. **Avoid areas of interest**: The new poles will have numerical singularities,
   so place them where solution accuracy is less critical.

2. **Land placement**: Placing poles over land (e.g., Antarctica or northern
   Canada) is ideal if your mesh excludes those regions.

3. **Match existing meshes**: If your mesh was generated with ADCIRC using
   rotated coordinates, use the same pole location for consistency.

Understanding Rotation Effects
------------------------------

When coordinate rotation is enabled, several quantities are affected:

Coordinates
^^^^^^^^^^^

All node coordinates are transformed from geographic :math:`(\lambda, \phi)` to
rotated :math:`(\lambda', \phi')` coordinates. The mesh file remains unchanged;
transformations happen at runtime.

Coriolis Parameter
^^^^^^^^^^^^^^^^^^

The Coriolis parameter :math:`f = 2\Omega\sin\phi` uses the **rotated latitude**
:math:`\phi'`, not the geographic latitude. This is correct because the Coriolis
effect depends on the local vertical component of Earth's rotation vector, which
is properly captured in the rotated frame.

Tidal Potential
^^^^^^^^^^^^^^^

Tidal potential forcing (gravitational attraction from the Moon and Sun) uses
**geographic latitude** :math:`\phi`. This is a physical requirement because the
tidal potential depends on the actual position relative to celestial bodies.

Velocities
^^^^^^^^^^

Velocities are computed in the rotated coordinate frame (rotated east/north
directions). For output, Cocoa transforms velocities back to the geographic
frame so that output files show true eastward (u) and northward (v) components.

Projection Selection
--------------------

For global simulations, projection choice affects numerical accuracy:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Projection
     - Recommendation
   * - **Mercator**
     - Best for global models with rotation. Conformal (angle-preserving)
       properties are important for accurate velocity calculations. Requires
       rotation if including high latitudes.
   * - Equidistant Cylindrical
     - Acceptable for global models. Simple but introduces errors at high
       latitudes.
   * - Equal Area
     - Good for mass conservation, but distorts shapes. Use when accurate
       integrated quantities are more important than local accuracy.
   * - Miller
     - A compromise between Mercator and cylindrical equal-area. Moderate
       distortion at all latitudes.
   * - Gall Stereographic
     - Cylindrical projection with two standard parallels at 45 degrees.
       Moderate distortion compromise.

Complete Example
----------------

A complete configuration for a global ocean model with tidal potential forcing,
self-attraction and loading (SAL), and spatially varying friction. This
corresponds to the :ref:`global-test` test case:

.. code-block:: yaml

   output:
     step_interval: 5

   diagnostics:
     screen_interval: 60
     log_file: log.json

   mesh:
     filename: "global.nc"
     projection:
       type: "Mercator"
       center: [0.0, 45.0]
     rotation:
       enabled: true
       pole_location: [114.16991, 0.77432]

   simulation:
     start_time: 2025-01-01
     end_time: 2025-02-01
     time_step: 12m

   physics:
     manning_n: "mesh"
     cf_lower_limit: 0.0010
     tau0: 0.0022222
     smagorinsky_coefficient: 0.2
     min_viscosity: 1.0e-6

   numeric:
     solver: implicit
     gwce_coefficients: [0.5, 0.5, 0.0]

   forcing:
     ramp:
       enabled: true
       duration: 5d
     tide:
       sal:
         enabled: true
       potential:
         enabled: true

   initial_conditions:
     water_level: 0.0

Key aspects of this configuration:

- **Coordinate rotation** relocates the North Pole to ``[114.16991, 0.77432]``,
  placing the singularity over land (Borneo).
- **Mercator projection** centered at 45\ |deg|\ N provides conformal mapping.
- **Spatially varying friction** (``manning_n: "mesh"``) reads Manning's *n*
  values from a mesh variable rather than using a uniform value.
- **SAL correction** (``tide.sal.enabled: true``) accounts for self-attraction
  and loading effects on the tide.
- **Tide potential** is enabled without specifying constituents --- Cocoa
  automatically computes tidal potential forcing from built-in constituent
  parameters.
- **Implicit solver** with ``gwce_coefficients: [0.5, 0.5, 0.0]`` enables the
  large 720-second time step needed for efficiency on a global domain.
- No **tidal boundary** section is needed because a global mesh has no open
  boundaries.

See Also
--------

- :ref:`coordinate-rotation` - Mathematical details of the rotation system
- :ref:`prime-meridian-handling` - How meridian crossings are detected
- :doc:`mesh_preparation` - Creating mesh files for Cocoa