6.2. Coord. & rotations (geometry.h)

The observer framework (Solar system) does not coincide with the Galactic (or any DM halo) coordinate systems. The library geometry.h provides transformation laws to go from the observer system to coordinates centred on DM haloes. Moreover, when dealing with triaxial haloes, we need to specify their orientation (Euler rotation angles).

6.2.1. Coordinate systems

To avoid confusion, we use the subscripts \((\dots)_\oplus\) and \((\dots)_G\) in the following to denote the coordinate frames attached to the Earth (or the Sun if you wish) and to the Galactic centre (GC), respectively. Generally, distances are given in \(\rm kpc\) and angles in \(\rm rad\) (except for Euler rotations, for which angles are given in degrees).


Fig. 6.2 Coordinates and definitions. \(\rm [GW]\): Galactic West, \(\rm [GE]\): Galactic East, \(\rm [SGP]\): South Galactic Pole, \(\rm [NGP]\): North Galactic Pole, \(\rm [GC]\): Galactic centre. Click to enlarge the figure.


In CLUMPY, the coordinates \((\psi,\theta)_\oplus\) are equivalent to the usual notation of Galactic longitude \(l\) and latitude \(b\), \((\psi,\theta)_\oplus \equiv (l,b)\).

:Coordinates along the line of sight (l.o.s.):

The angles \((\alpha,\beta)_\oplus\) are defined with respect to the base \((\vec{i}',\vec{j}',\vec{k}')_\oplus\) such as the unit vectors of this basis are collinear with the axis \(Oxyz\) when \(\psi=\theta=0\). The coordinates of the point \(P\) (i.e. \(\vec{OP}\), see Fig. 6.2) in this frame are either \((l,\alpha,\beta)_\oplus\) or \((x',y',z')_\oplus\), where

\[\vec{OP}_{w.r.t.\, \vec{OS}=(\theta,\psi)} = (x',y',z')_\oplus =\big( l\cos\alpha,\, l\sin\alpha \sin\beta,\, l\sin\alpha \cos\beta\big)\,.\]

As a result,

  • \(\alpha=0\) corresponds to \(y'=z'=0\),
  • \(\beta=0\) corresponds to \(y'=0\) and \(z'>0\),
  • \(\beta=\pi/2\) corresponds to \(z'=0\) and \(y'>0\),
  • \(\beta \in [0,2\pi]\).

Another useful coordinate system is \((x,y,z)_{\rm halo}\), i.e. the coordinate system \((x',y',z')_\oplus\) shifted to the halo centre position (located at distance d and assuming the los points at the halo centre).

\[(x,y,z)_{\rm halo} = (x',y',z')_\oplus =\big( l\cos\alpha-d,\, l\sin\alpha \sin\beta,\, l\sin\alpha \cos\beta\big)\,.\]
Galactic coordinates:

In Galactic coordinates (origin attached to the Earth), we have the corresponding directions for \((\psi,\theta)_\oplus\) equals:

  • \((0,0)_\oplus \Rightarrow\) Galactic centre (GC),
  • \((0,\pi/2)_\oplus\Rightarrow\) North Galactic Pole (NGP),
  • \((0,-\pi/2)_\oplus\Rightarrow\) South Galactic Pole (SGP),
  • \((\pi/2,0)_\oplus\Rightarrow\) Galactic West direction (GW),
  • \((3\pi/2,0)_\oplus\Rightarrow\) Galactic East direction (GE).

This choice of angles (appropriate for Galactic coordinates) differs slightly from the standard choice. Indeed, our choice of unit vectors \((\vec{i}',\vec{j}',\vec{k}')_\oplus\) are related to the standard spherical coordinate unit vectors by means of \(\vec{i}' = + \vec{e}_{r}\), \(\vec{j}' = + \vec{e}_{\psi}\), and \(\vec{k}' = - \vec{e}_{\theta}\). We can then express the unit vectors \((\vec{i}',\vec{j}',\vec{k}')_\oplus\) in the base \((\vec{i},\vec{j},\vec{k})_\oplus\):

\[\begin{split}\vec{i}' &= + \cos(\theta) \; \cos(\psi) \;\vec{i} \quad + \cos(\theta) \; \sin(\psi) \; \vec{j} \quad + \sin(\theta) \; \vec{k} \\ \vec{j}' &= - \sin(\psi) \;\vec{i} \qquad\quad\;\;\; + \cos(\psi) \; \vec{j}\\ \vec{k}' &= -\sin(\theta) \; \cos(\psi) \; \vec{i} \quad - \sin(\theta) \; \sin(\psi) \; \vec{j} \quad +\cos(\theta) \; \vec{k}\\\end{split}\]

6.2.2. \((l,\alpha,\beta)_{\oplus}\) to \((x,y,z)_G\)

For the sake of understanding, we recall below the main steps to move from spherical coordinates in the framework attached to the line of sight, to Cartesian coordinates in the Galactic framework. Summary formulae for the global transformation are given in the next paragraph.

  • Step 1: \((l,\alpha,\beta)_{\oplus}\) to \((x',y',z')_{\oplus}\).
    This is given in Section 6.2.1 above by the expression for \(\vec{OP}\).

  • Step 2: \((x',y',z')_{\oplus}\) to \((x,y,z)_{\oplus}\).
    This is obtained by the transformation of the unit vectors as in Section 6.2.1 above. Another way would have been to use the rotation matrices \({\cal R}\), corresponding to the two rotations along the angles \((\psi,\theta)\) between the galactic frame attached to the Earth and the l.o.s. direction:

    \[\begin{split}\begin{pmatrix} x \\ y \\ z \end{pmatrix} \;=\; {\cal R}^{-1}(\psi)\;\,{\cal R}^{-1}(\theta)\;\, \begin{pmatrix} x' \\ y' \\ z' \end{pmatrix}\end{split}\]
  • Step 3: \((x,y,z)_{\oplus}\) to \((x, y, z)_G\).
    We merely have \((x,y,z)_G = (x-R_\odot,y,z)_{\oplus}\).

Summary formulae

  • Transformation: from \((l,\alpha,\beta)_\oplus\) along the l.o.s. direction \((\psi,\theta)_\oplus\) to \((x,y,z)_G\)

    \[\begin{split}x &= x' \cos(\psi) \cos(\theta) - y' \sin(\psi) - z' \sin(\theta) \cos(\psi) - R_\odot\\ y &= x' \sin(\psi) \cos(\theta) + y' \cos(\psi) - z' \sin(\theta) \sin(\psi)\\ z &= x' \sin(\theta) + z' \cos(\theta)\end{split}\]

    where we have

    \[\begin{split}x' &= l \cos(\alpha)\\ y' &= l \sin(\alpha) \sin(\beta)\\ z' &= l \sin(\alpha) \cos(\beta)\end{split}\]
  • Inverse transformation: from \((x,y,z)_G\) to \((l,\alpha,\beta)_\oplus\) along the l.o.s. direction \((\psi,\theta)_\oplus\)

    \[\begin{split}l = & \sqrt{x'^2 + y'^2 + z'^2} \\ \alpha = & \;\cos^{-1}\left(\frac{x'}{l}\right) \\ \beta = & \; \cos^{-1}\left(\frac{z'}{\sqrt{x'^{2}+y'^{2}}}\right) \quad {\rm if} \quad y'\geq 0 \\ & \; 2\pi - \cos^{-1}\left(\frac{z'}{\sqrt{x'^{2}+y'^{2}}}\right) \quad {\rm if} \quad y'<0\end{split}\]

    where we have

    \[\begin{split}x' &= \quad(x+R_\odot) \cos(\psi) \cos(\theta) + y \sin(\psi) \cos(\theta) + z \sin(\theta)\\ y' &= -(x+R_\odot) \sin(\psi) + y \cos(\psi)\\ z' &= -(x+R_\odot) \cos(\psi) \sin(\theta) - y \sin(\psi) \sin(\theta) + z \cos(\theta).\end{split}\]

6.2.3. Halo rotation (Euler angles)

It is useful to define Euler angles for a body whose origin is the centre of the dark matter halo we are looking at. The Euler angles \((\alpha,\,\beta,\,\gamma)_{\rm Euler}\) allow to define a rotation of the object in its framework, which is useful for triaxial haloes considered in CLUMPY. Fig. 6.3 below represents the original framework and the rotated framework (see the corresponding Wikipedia pages for more details), where

  • \(\alpha \in [-180^\circ,180^\circ]\) represents a rotation around the z axis (xOy plane),
  • \(\beta \in [-90^\circ,90^\circ]\) represents a rotation around the N axis (or X axis, obtained after first rotation),
  • \(\gamma \in [-180^\circ,180^\circ]\) represents a rotation around the Z axis.

Fig. 6.3 Euler angles: original (xyz) and rotated (XYZ) coordinates

Transformation law

It is convenient to write the transformation laws in a matrix form. The result is the product of three rotation matrices along three different axes (as depicted in Fig. 6.3):

\[\begin{split}\begin{pmatrix} X \\ Y \\ Z \end{pmatrix} = \begin{pmatrix} \cos\alpha\cos\gamma-\sin\alpha\sin\gamma\cos\beta & \sin\alpha\cos\gamma+\cos\alpha\sin\gamma\cos\beta & \sin\gamma\sin\beta\\ -\cos\alpha\sin\gamma-\sin\alpha\cos\gamma\cos\beta & -\sin\alpha\sin\gamma+\cos\alpha\cos\gamma\cos\beta & \cos\gamma\sin\beta \\ \sin\alpha\sin\beta & -\cos\alpha\sin\beta & \cos\beta \end{pmatrix}\; \begin{pmatrix} x \\ y \\ z \end{pmatrix}\end{split}\]

Euler angles in the context of triaxial DM halos

The Euler rotations are used in CLUMPY for triaxial DM profiles. The default orientation \((\alpha,\,\beta,\,\gamma)_{\rm Euler} = (0,\,0,\,0)\) corresponds to:

  • Major axis \(a\) along the l.o.s. direction, i.e. \(x'\) axis in Fig. 6.2 (\(b\) and \(c\) in the plane perpendicular to the l.o.s.);
  • Second axis \(b\) along the lateral direction w.r.t. the los, i.e. \(y'\) axis in Fig. 6.2;
  • Minor axis \(c\) along the vertical direction w.r.t. the los i.e. \(z'\) axis in Fig. 6.2.

To have a better grasp of the angle orientations, one can run:

$ clumpy -h4 -D; clumpy -h4 -i clumpy_params_h4.txt

to get a 2D plot of one of a triaxial halo in the list_generic_triaxial.txt of example haloes shipped with the code:

$ clumpy -h4 -i clumpy_params_h4.txt --gLIST_HALOES=$CLUMPY/data/list_generic_triaxial.txt --gLIST_HALONAME=m5kpc_rs01_g10_1.47_1.22_0.7

The input variable gLIST_HALOES selects a file with halo definitions (here, the variable passed via the command line overwrites the file specified in clumpy_params_h4.txt). This file may contain various halo definitions, and the variable gLIST_HALONAME selects the halo to compute. See the Accessing the FITS output section for different possibilities to view the FITS 2D output map of the halo.

Exchanging the values of the major, second, and minor axes of the halo definition in list_generic_triaxial.txt is directly seen on the orientation of the 2D projection map obtained. The effects of Euler rotation angles (w.r.t. the reference framework) can be checked in a similar way, and the following special cases correspond to:

  • \((\alpha,\,\beta,\,\gamma)_{\rm Euler} = (~~~~0~,~~~0~,~~~~0~)\)
    \(\rightarrow\,\) DM halo major axis \(a\) along the l.o.s. (see default orientation above);

  • \((\alpha,\,\beta,\,\gamma)_{\rm Euler} = (~~90^\circ,~~~0~,~~~~0~)\)
    \(\rightarrow\,\) Rotation along \(Oz'\), i.e. \(Ox'\) (major axis \(a\)) moves to \(Oy'\) (second axis \(b\));

  • \((\alpha,\,\beta,\,\gamma)_{\rm Euler} = (~~~~0~,~90^\circ,~~~~0~)\)
    \(\rightarrow\,\) Rotation along \(Ox'\), i.e. minor axis \(c\) (along \(Oz'\)) moves to \(Oy'\) (second axis \(b\));

  • \((\alpha,\,\beta,\,\gamma)_{\rm Euler} = (-90^\circ,~\!90^\circ,-90^\circ)\)
    \(\rightarrow\,\) Rotation along \(Oy'\), i.e. major axis \(a\) (along \(Ox'\)) moves to \(Oz'\) (minor axis \(c\)).


The orientation of the DM halo axes in the plane perpendicular to the l.o.s. only matters for 2D maps. For the 1D J-factor integration, the halo is integrated on a regular conic section (solid angle) that intersects the projected profile as a circle, so that the result is invariant under rotation in this plane.