<commit_before>The Aronnax Model
********************

The Physics
============

Aronnax can run in two different modes:

- n + 1/2 layer mode, in which the bottom layer is quiescent and infinitely deep
- n layer mode, in which the bottom topography is specified and all layers have finite thickness


n + 1/2 layer mode
-------------------

The n + 1/2 layer mode is very cheap to run: Each time-step takes time
linear in the number of grid points.

n layer mode
--------------------

The n layer mode is more expensive, because the integration method is
party implicit (to wit, solves a system of equations to ensure
non-divergence of the barotropic flow).  This tends to cost an extra
factor of one grid side length in the run time, but admits a more
realistic simulation, in that the effect of the ocean floor is
included.


Governing Equations
=====================

The model solves the hydrostatic Boussinesq equations within a finite number of discrete isopycnal layers. At the layer interfaces there is a discrete jump in velocity and density, but not in pressure.

Continuity equation
-------------------
.. math::
    \label{eqn:reduced_gravity_layer_continuity} 
    \frac{\partial h_{n}}{\partial t} = \mathbf{\nabla} \cdot \left(h_{n} \mathbf{v_{n}} \right).


in which :math:`\mathbf{v_{n}}` represents the vertically averaged horizontal velocity in layer :math:`n`.

Momentum equations
-------------------
.. math::
    \label{eqn:reduced_grav_layer_1_momentum} 
    \frac{D \mathbf{v_{n}}}{D t} +  \mathbf{f} \times \mathbf{v_{n}} + g^{'}\mathbf{\nabla}h_{n} = \mathbf{F_{n}},



in which :math:`g^{'}` is the reduced gravity given by :math:`{g(\rho_{2} - \rho_{1})}/{\rho_{1}}`. The reduced gravity is dynamically equivalent to gravity, but is scaled to take into account the density difference between the two layers.

This can be rewritten in terms of the Bernoulli Potential to give,

.. math::
    \label{eqn:momentum_Bernoulli_form}
    \frac{\partial\mathbf{v_{n}}}{\partial t} - (f+\zeta_{n}) \times v_{n} + \nabla \Pi_{n} + = \kappa \nabla^{2}v_{n} + \frac{\mathbf{F_{n}}}{\rho_{0}}

where :math:`\Pi_{n}` is the Bernoulli potential, :math:`\left(\mathbf{v_{n}}\cdot\mathbf{v_{n}}\right)/2 + p/\rho_{0}`, and :math:`p` is the hydrostatic pressure. In this form the non-linearity from the material derivative has been moved into the Bernoulli Potential and the vorticity term. 



The model can be used in either reduced gravity mode, with a quiescent abyss, or in n-layer mode with bathymetry. In the n-layer case the model can either be run with a rigid lid, or with a free surface. In simulations with a free surface the following equation is also solved

.. math::
    \label{eqn:}
    \frac{\partial \eta}{\partial t} + \mathbf{\nabla} \cdot (H \mathbf{V}) = 0,

where :math:`H` is the depth from the free-surface to the bathymetry, and :math:`V` is the vertically averaged flow, the barotropic flow. With a rigid lid, the model solves an analogous equation, but it is just for the pressure field to keep the vertically integrated horizontal flow divergence free - the result is not carried from one timestep to the next.


Discretisation
===============
Aronnax is discretised on an Arakawa C grid.

.. figure:: _static/C-grid.png
   :alt: Arakawa C grid
   :width: 33%
   :align: center

   A single grid cell from an Arakawa C grid.

<commit_msg>all n-layer simulations solve matrix eqn<commit_after>The Aronnax Model
********************

The Physics
============

Aronnax can run in two different modes:

- n + 1/2 layer mode, in which the bottom layer is quiescent and infinitely deep
- n layer mode, in which the bottom topography is specified and all layers have finite thickness


n + 1/2 layer mode
-------------------

The n + 1/2 layer mode is very cheap to run: Each time-step takes time
linear in the number of grid points.

n layer mode
--------------------

The n layer mode is more expensive, because the integration method is
party implicit (to wit, solves a system of equations to ensure
non-divergence of the barotropic flow).  This tends to cost an extra
factor of one grid side length in the run time, but admits a more
realistic simulation, in that the effect of the ocean floor is
included.


Governing Equations
=====================

The model solves the hydrostatic Boussinesq equations within a finite number of discrete isopycnal layers. At the layer interfaces there is a discrete jump in velocity and density, but not in pressure.

Continuity equation
-------------------
.. math::
    \label{eqn:reduced_gravity_layer_continuity} 
    \frac{\partial h_{n}}{\partial t} = \mathbf{\nabla} \cdot \left(h_{n} \mathbf{v_{n}} \right).


in which :math:`\mathbf{v_{n}}` represents the vertically averaged horizontal velocity in layer :math:`n`.

Momentum equations
-------------------
.. math::
    \label{eqn:reduced_grav_layer_1_momentum} 
    \frac{D \mathbf{v_{n}}}{D t} +  \mathbf{f} \times \mathbf{v_{n}} + g^{'}\mathbf{\nabla}h_{n} = \mathbf{F_{n}},



in which :math:`g^{'}` is the reduced gravity given by :math:`{g(\rho_{2} - \rho_{1})}/{\rho_{1}}`. The reduced gravity is dynamically equivalent to gravity, but is scaled to take into account the density difference between the two layers.

This can be rewritten in terms of the Bernoulli Potential to give,

.. math::
    \frac{\partial\mathbf{v_{n}}}{\partial t} - (f+\zeta_{n}) \times v_{n} + \nabla \Pi_{n} + = \kappa \nabla^{2}v_{n} + \frac{\mathbf{F_{n}}}{\rho_{0}}
    :name: eqn_momentum_Bernoulli_form

where :math:`\Pi_{n}` is the Bernoulli potential, :math:`\left(\mathbf{v_{n}}\cdot\mathbf{v_{n}}\right)/2 + p/\rho_{0}`, and :math:`p` is the hydrostatic pressure. In this form the non-linearity from the material derivative has been moved into the Bernoulli Potential and the vorticity term. 


The model can be used in either reduced gravity mode, with a quiescent abyss, or in n-layer mode with bathymetry. In the n-layer case the model can either be run with a rigid lid, or with a free surface. In n-layer simulations the following equation is also solved

.. math::
    :name:eqn
    \frac{\partial \eta}{\partial t} + \mathbf{\nabla} \cdot (H \mathbf{V}) = 0,

where :math:`\eta` is the free surface height, :math:`H` is the depth from the free-surface to the bathymetry, and :math:`V` is the vertically averaged flow, the barotropic flow. With a rigid lid :math:`\eta` represents the pressure field required to keep the vertically integrated horizontal flow divergence free - the result is not carried from one timestep to the next.



Discretisation
===============
Aronnax is discretised on an Arakawa C grid.

.. figure:: _static/C-grid.png
   :alt: Arakawa C grid
   :width: 33%
   :align: center

   A single grid cell from an Arakawa C grid.


{'fraction_non_alphanumeric': 0.1393188854489164, 'fraction_numerical': 0.005012531328320802, 'mean_word_length': 3.6465753424657534, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5734165', 'n_tokens_mistral': 2040, 'n_tokens_neox': 1922, 'n_words': 879}