Add documentation for Rotation Physics in TORAX.

PiperOrigin-RevId: 842320397

Author: hamelphi

docs/links.rst

@@ -24,6 +24,8 @@
 .. _body2025_link: https://doi.org/10.1088/1741-4326/ade4d9
 .. _kallenbach2024_link: https://doi.org/10.1088/1741-4326/ad3139
 .. _mavrin2017_link: https://doi.org/10.1007/s10894-017-0136-z
+.. _kim1991_link: https://doi.org/10.1063/1.859671
+.. _hinton1976_link: https://doi.org/10.1103/RevModPhys.48.239
 
 .. Define substitutions using link targets
 .. |qlknn10d| replace:: `[van de Plassche et al, Phys. Plasmas 2020] <qlknn10d_link_>`_
@@ -51,3 +53,5 @@
 .. |body2025| replace:: `[Body et al, NF 2025] <body2025_link_>`_
 .. |kallenbach2024| replace:: `[Kallenbach et al, NF 2024] <kallenbach2024_link_>`_
 .. |mavrin2017| replace:: `[Mavrin, J Fusion Energ 2017] <mavrin2017_link_>`_
+.. |kim1991| replace:: `[Kim et al, Phys. Fluids B 1991] <kim1991_link_>`_
+.. |hinton1976| replace:: `[Hinton & Hazeltine, Rev. Mod. Phys. 1976] <hinton1976_link_>`_

docs/physics_models.rst

@@ -327,6 +327,94 @@ importance for ion heat transport in the inner core. When extending TORAX to
 include impurity transport, incorporating fast analytical neoclassical models
 for heavy impurity transport will be of great importance.
 
+Rotation Physics
+================
+The radial electric field (:math:`E_r`), which drives :math:`E \times B` plasma
+rotation, is a crucial factor in turbulent transport, as :math:`E \times B`
+shear can suppress turbulence.
+
+The radial electric field :math:`E_r` is determined from the radial force
+balance equation for the main ions:
+
+.. math::
+  E_r = \frac{1}{Z_i e n_i} \frac{d P_i}{dr} - v_{\phi} B_{\theta} + v_{\theta} B_{\phi}
+
+where :math:`P_i` is the main ion pressure, :math:`n_i` is the main ion
+density, :math:`Z_i` is the main ion charge number, :math:`e` is the elementary
+charge, :math:`v_{\phi}` is the toroidal rotation velocity, :math:`v_{\theta}`
+is the poloidal rotation velocity, :math:`B_{\theta}` is the poloidal magnetic
+field, and :math:`B_{\phi}` is the toroidal magnetic field. The derivatives
+are with respect to a midplane-averaged radial coordinate.
+
+The poloidal velocity :math:`v_{\theta}` is calculated using neoclassical
+formulas. Specifically, it implements Equation 33 from |kim1991|. The formula
+used is:
+
+.. math::
+  v_{\theta} = k_{neo} \frac{1}{Z_i e} \frac{dT_i}{dr} \frac{B_{tor}}{B_{total}^2}
+
+where :math:`k_{neo}` is a neoclassical coefficient, :math:`dT_i/dr` is the
+radial gradient of the ion temperature, and :math:`B_{total}` is the total
+magnetic field.
+
+The neoclassical coefficient :math:`k_{neo}` is based on Equation (6.135) from
+|hinton1976|. This coefficient depends on the normalized ion collisionality
+(:math:`\nu_{i}^{*}`) and the inverse aspect ratio (:math:`\epsilon`). The
+limits of this formula are approximately 1.17 in the banana regime
+(:math:`\nu_{i}^{*} \rightarrow 0`) and -2.1 in the Pfirsch-Schluter regime
+(:math:`\nu_{i}^{*} \rightarrow \infty`).
+
+The normalized ion collisionality :math:`\nu_{i}^{*}` is calculated based on
+|sauter99|, and depends on the safety factor (:math:`q`), geometry, ion
+density (:math:`n_i`), ion temperature (:math:`T_i`), effective charge number
+(:math:`Z_{eff}`), and the ion-ion Coulomb logarithm (:math:`\log \Lambda_{ii}`).
+
+The :math:`E \times B` velocity (:math:`v_{E \times B}`) is derived from the
+radial electric field :math:`E_r` and the total magnetic field as follows:
+
+.. math::
+  v_{E \times B} = \frac{E_r}{B_{total}}
+
+Rotation effects are currently disabled by default in transport models. They can
+be enabled through the transport model configuration.
+
+**Rotation in Transport Models:**
+
+*   **TGLFNN-ukaea:** The TGLFNN-ukaea model includes the :math:`E \times B`
+    shearing rate as an input feature, directly informing the model's turbulent
+    transport predictions. To enable this, set the `use_rotation` parameter to
+    `True` in the transport model configuration.
+
+*   **QLKNN:** The QLKNN transport model
+    incorporates a "rotation rule" that reduces turbulent fluxes (specifically
+    for ITG and TEM modes), see |qlknn10d|. This reduction is based on the
+    ratio of the :math:`E \times B` shearing rate (:math:`\gamma_{E \times B}`)
+    to the maximum linear growth rate (:math:`\gamma_{max}`). The scaling
+    factor is calculated as:
+
+    .. math::
+      f_{rot} = 1 + f_{rule} \frac{\gamma_{E \times B}}{\gamma_{max}}
+
+    Here, :math:`f_{rule}` is a factor derived from experimental observations,
+    depending on the safety factor, magnetic shear, and inverse aspect ratio.
+    This rule effectively suppresses turbulent transport when :math:`E \times B`
+    shear is strong. The application of this rule is controlled by the
+    `rotation_mode` configuration parameter. Options for `rotation_mode` are:
+  * ``off``: No rotation correction is applied.
+  * ``half_radius``: The rotation correction is only applied to the outer
+    half of the radius (:math:`rhon > 0.5`).
+  * ``full_radius``: The rotation correction is applied everywhere.
+
+**Tuning Rotation Effects:**
+
+Two parameters are available to fine-tune the impact of rotation, both of them
+default to 1.0:
+
+*   `rotation_multiplier`: Located in the transport model configs, this
+    parameter scales the :math:`E \times B` shear term.
+*   `poloidal_velocity_multiplier`: Found under the `neoclassical`
+    configuration, this parameter directly scales the poloidal velocity term.
+
 Edge models
 ===========