Physics-models.md

 ## Coordinate Reference systems
 
-In the following, for any coordinate $`j`$ of a reference system, the corresponding versor is defined as $`\hat{\bf e}_j = \nabla j / \lvert \nabla j \rvert`$. A few **right-handed** coordinate systems are used in the code:
+In this documentation, the following notation is used:
+
+- a bold font is used for vector quantities, e.g. $`{\bf v}`$, a normal font for their magnitude, e.g. $`v = \lVert {\bf v} \rVert`$, and for scalar values in general.
+- for any coordinate $`j`$ of a reference system, the corresponding versor is defined as $`\hat{\bf e}_j = \nabla j / \lVert \nabla j \rVert`$.
+
+A few **right-handed** coordinate systems are used in the code:
 
 - The **tokamak** reference system, sed to define the beam launch point, the magnetic equilibrium, the first wall shape, and the beam trajectory.
 
   It can be alternatively expressed:
   - In **Cartesian** coordinates $`(x, y, z)`$.
-  - In **cylindrical** coordinates $`(R, φ, Z)`$, sharing the origin the vertical axis $`z = Z`$ with the Cartesian system
+  - In **cylindrical** coordinates $`(R, φ, Z)`$, sharing the origin the vertical axis $`z = Z`$ with the Cartesian system.
 
   The transformation from the cylindrical to the Cartesian system given by:
 
-        x = R \cos\phi \quad y = R \sin\phi \quad z = Z
+  ```math
+  x = R \cos\phi, \quad y = R \sin\phi, \quad z = Z
+  ```
 
-  The $`z`$-axis is the tokamak symmetry axis. and $`z = 0`$ is typically at the tokamak mid-plane.
+  The $`z`$-axis is the tokamak symmetry axis, and $`z = 0`$ is typically at the tokamak mid-plane.
 
   For the purpose of the physics analysis it may be convenient to rotate this coordinate system around the $`z`$-axis, so that the launching point is at $`\phi = 0`$, i.e., in the $`xz`$-plane. In this case, at the launching point $`\hat{\bf e}_x`$ points radially outward, and $`\hat{\bf e}_y = \hat{\bf e}_\phi`$ is pointing in the counter clockwise direction when viewed from above.
 
@@ -23,11 +30,39 @@ In the following, for any coordinate $`j`$ of a reference system, the correspond
   - beam polarisation angles
 
   This Cartesian system $`(\tilde x, \tilde y, \tilde z)`$ is co-moving with the beam. At any point along the beam path, it has:
+
   - origin on the beam axis
-  - $`\tilde z`$-axis aligned with the on-axis wavevector $`k`$
-  - $`\tilde x`$-axis in the **tokamak** 
+  - $`\tilde z`$-axis aligned with the on-axis wavevector $`{\bf k}`$
+  - $`\tilde x`$-axis in the **tokamak** horizontal plane
+
+  ```math
+  \hat{\bf e}_{\tilde x} = (\hat{\bf e}_{z} \times {\bf k})/
+                     \lVert \hat{\bf e}_{z} \times {\bf k} \rVert, \quad
+  \hat{\bf e}_{\tilde y} = \hat{\bf e}_{\tilde z} \times \hat{\bf e}_{\tilde x}, \quad
+  \hat{\bf e}_{\tilde z} = {\bf k}/k
+  ```
+
+  In case $`{\bf k} \parallel \hat{\bf e}_z`$ the above expression for $`\hat{\bf e}_{\tilde x}`$ is undefined, and $`\hat{\bf e}_{\tilde x} = -\hat{\bf e}_{\phi}`$ is used instead.
+
+  > Check sign of $`\hat{\bf e}_{\tilde x}`$ (both cases)
+
+- The local **plasma** system, where the local plasma dispersion relation is solved. In this Cartesian system $`(\bar x, \bar y, \bar z)`$:
+
+  - the local magnetic field $`B`$ is along the $`\bar z`$-axis
+  - the wavevector is in the $`\bar{x}\bar{z}`$-plane
+
+  ```math
+  \hat{\bf e}_{\bar x} = \hat{\bf e}_{\bar y} \times \hat{\bf e}_{\bar z}, \quad
+  \hat{\bf e}_{\bar y} = ({\bf B} \times {\bf k})/
+                   \lVert {\bf B} \times {\bf k} \rVert, \quad
+  \hat{\bf e}_{\bar z} = {\bf B}/B
+  ```
+
+  In case $`{\bf k} \parallel {\bf B}`$ the above expression for $`\hat{\bf e}_{\tilde y}`$ is undefined, and ...
+
+  > Missing definition for the case $`{\bf k} \parallel {\bf B}`$
 
-- The local **plasma-wave** system, where the local plasma dispersion relation is solved.
+  > Check sign of $`\hat{\bf e}_{\tilde y}`$
 
 ## Quasi-optical approximation