KerrSchildCoords.hpp
1 // Distributed under the MIT License.
2 // See LICENSE.txt for details.
3 
4 #pragma once
5 
6 #include <limits>
7 
9 
10 // IWYU pragma: no_include <pup.h>
11 
12 /// \cond
13 namespace PUP {
14 class er; // IWYU pragma: keep
15 } // namespace PUP
16 /// \endcond
17 
18 namespace gr {
19 /*!
20  * \brief Contains helper functions for transforming tensors in Kerr
21  * spacetime to Kerr-Schild coordinates.
22  *
23  * Consider the Kerr-Schild form of the Kerr metric in Cartesian
24  * coordinates \f$ (t, x, y, z)\f$,
25  *
26  * \f{align*}
27  * ds^2 = -dt^2 + dx^2 + dy^2 + dz^2 + \dfrac{2Mr^3}{r^4 + a^2 z^2}
28  * \left[dt + \dfrac{r(x\,dx + y\,dy)}{r^2 + a^2} +
29  * \dfrac{a(y\,dx - x\,dy)}{r^2 + a^2} + \dfrac{z}{r}dz\right]^2,
30  * \f}
31  *
32  * where \f$r\f$ is the function defined through
33  *
34  * \f{align*}
35  * r^2(x, y, z) = \frac{x^2 + y^2 + z^2 - a^2}{2} +
36  * \sqrt{\left(\frac{x^2 + y^2 + z^2 - a^2}{2}\right)^2 + a^2 z^2}.
37  * \f}
38  *
39  * Depending on the physical context, the following coordinate transformations
40  * are usually adopted:
41  *
42  * - \em Spherical \em coordinates, defined by the usual transformation
43  *
44  * \f{align*}
45  * x &= r_\text{sph}\sin\theta\cos\phi,\\
46  * y &= r_\text{sph}\sin\theta\sin\phi,\\
47  * z &= r_\text{sph}\cos\theta.
48  * \f}
49  *
50  * Note that \f$r_\text{sph} \neq r\f$, so the
51  * horizon of a Kerr black hole is \em not at constant \f$r_\text{sph}\f$.
52  *
53  * - \em Oblate \em spheroidal \em coordinates,
54  *
55  * \f{align*}
56  * x &= \sqrt{r^2 + a^2}\sin\vartheta\cos\phi,\\
57  * y &= \sqrt{r^2 + a^2}\sin\vartheta\sin\phi,\\
58  * z &= r\cos\vartheta.
59  * \f}
60  *
61  * Notice that \f$r\f$ is that defined in the Kerr-Schild form of the Kerr
62  * metric, so the horizon is at constant \f$r\f$. (As it will be noted below,
63  * \f$r\f$ corresponds to the Boyer-Lindquist radial coordinate.) Also, note
64  * that the azimuthal angle \f$\phi\f$ is the same as the corresponding
65  * angle in spherical coordinates, whereas the zenithal angle
66  * \f$\vartheta\f$ differs from the corresponding angle \f$\theta\f$.
67  *
68  * - \em Kerr \em coordinates (sometimes also referred to as
69  * "Kerr-Schild coordinates"), defined by
70  *
71  * \f{align*}
72  * x &= (r \cos\varphi - a \sin\varphi)\sin\vartheta =
73  * \sqrt{r^2 + a^2}\sin\vartheta\cos\left(\varphi +
74  * \tan^{-1}(a/ r)\right),\\
75  * y &= (r \sin\varphi + a \cos\varphi)\sin\vartheta =
76  * \sqrt{r^2 + a^2}\sin\vartheta\sin\left(\varphi +
77  * \tan^{-1}(a/ r)\right),\\
78  * z &= r \cos\vartheta.
79  * \f}
80  *
81  * These are the coordinates used in the gr::KerrSchildCoords class.
82  * Notice that \f$r\f$ and \f$\vartheta\f$ are the same as those in
83  * spheroidal coordinates, whereas the azimuthal angle
84  * \f$\varphi \neq \phi\f$.
85  *
86  * \note Kerr's original "advanced Eddington-Finkelstein" form of his metric
87  * is retrieved by performing the additional transformation \f$t = u - r\f$.
88  * Note that Kerr's choice of the letter \f$u\f$ for the time coordinate
89  * is not consistent with the convention of denoting the advanced time
90  * \f$v = t + r\f$ (in flat space), and the retarded time \f$u = t - r\f$
91  * (in flat space). Finally, note that Kerr's original metric has the sign
92  * of \f$a\f$ flipped.
93  *
94  * The Kerr coordinates have been used in the hydro community to evolve the
95  * GRMHD equations. They are the intermediate step in getting the Kerr metric
96  * in Boyer-Lindquist coordinates. The relation between both is
97  *
98  * \f{align*}
99  * dt_\text{BL} &=
100  * dt - \frac{2M r\,dr}{r^2 - 2Mr + a^2}, \\
101  * dr_\text{BL} &= dr,\\
102  * d\theta_\text{BL} &= d\vartheta,\\
103  * d\phi_\text{BL} &= d\varphi - \frac{a\,dr}{r^2-2Mr + a^2}.
104  * \f}
105  *
106  * The above transformation makes explicit that \f$r\f$ is the Boyer-Lindquist
107  * radial coodinate, \f$ r = r_\text{BL}\f$. Likewise,
108  * \f$\vartheta = \theta_\text{BL}\f$.
109  *
110  * \note Sometimes (especially in the GRMHD community), the Kerr coordinates
111  * as defined above are referred to as "spherical Kerr-Schild" coordinates.
112  * These should not be confused with the true spherical coordinates defined
113  * in this documentation.
114  *
115  * The Kerr metric in Kerr coodinates is sometimes used to write analytic
116  * initial data for hydro simulations. In this coordinate system, the
117  * metric takes the form
118  *
119  * \f{align*}
120  * ds^2 &= -(1 - B)\,dt^2 + (1 + B)\,dr^2 + \Sigma\,d\vartheta^2 +
121  * \left(r^2 + a^2 + B a^2\sin^2\vartheta\right)\sin^2\vartheta\,d\varphi^2\\
122  * &\quad + 2B\,dt\,dr - 2aB\sin^2\vartheta\,dt\,d\varphi -
123  * 2a\left(1 + B\right)\sin^2\vartheta\,dr\,d\varphi,
124  * \f}
125  *
126  * where \f$B = 2M r/ \Sigma\f$ and \f$\Sigma = r^2 + a^2\cos^2\vartheta\f$.
127  * Using the additional relations
128  *
129  * \f{align*}
130  * \sin\vartheta &= \sqrt{\frac{x^2 + y^2}{r^2 + a^2}},\quad
131  * \cos\vartheta = \frac{z}{r},\\
132  * \sin\varphi &= \frac{y r - x a}{\sqrt{(x^2 + y^2)(r^2 + a^2)}},\quad
133  * \cos\varphi = \frac{x r + y a}{\sqrt{(x^2 + y^2)(r^2 + a^2)}},
134  * \f}
135  *
136  * the Jacobian of the transformation to Cartesian Kerr-Schild coordinates is
137  *
138  * \f{align*}
139  * \dfrac{\partial(x, y, z)}{\partial(r, \vartheta, \varphi)} &=
140  * \left(\begin{array}{ccc}
141  * \dfrac{xr + ya}{r^2 + a^2} &
142  * \dfrac{xz}{r}\sqrt{\dfrac{r^2 + a^2}{x^2 + y^2}} & -y\\
143  * \dfrac{yr - ax}{r^2 + a^2} &
144  * \dfrac{yz}{r}\sqrt{\dfrac{r^2 + a^2}{x^2 + y^2}} & x\\
145  * \dfrac{z}{r} & - r\sqrt{\dfrac{x^2 + y^2}{r^2 + a^2}} & 0
146  * \end{array}\right),
147  * \f}
148  *
149  * which can be used to transform tensors between both coordinate systems.
150  */
152  public:
153  KerrSchildCoords() = default;
154  KerrSchildCoords(const KerrSchildCoords& /*rhs*/) = delete;
155  KerrSchildCoords& operator=(const KerrSchildCoords& /*rhs*/) = delete;
156  KerrSchildCoords(KerrSchildCoords&& /*rhs*/) noexcept = default;
157  KerrSchildCoords& operator=(KerrSchildCoords&& /*rhs*/) noexcept = default;
158  ~KerrSchildCoords() = default;
159 
160  KerrSchildCoords(double bh_mass, double bh_dimless_spin) noexcept;
161 
162  /// Transforms a spatial vector from Kerr (or "spherical Kerr-Schild")
163  /// coordinates to Cartesian Kerr-Schild coordinates. If applied on points
164  /// on the z-axis, the vector to transform must have a vanishing
165  /// \f$v^\vartheta\f$ in order for the transformation to be single-valued.
166  template <typename DataType>
167  tnsr::I<DataType, 3, Frame::Inertial> cartesian_from_spherical_ks(
168  const tnsr::I<DataType, 3, Frame::NoFrame>& spatial_vector,
169  const tnsr::I<DataType, 3, Frame::Inertial>& cartesian_coords) const
170  noexcept;
171 
172  /// Kerr-Schild \f$r^2\f$ in terms of the Cartesian coordinates.
173  template <typename DataType>
174  Scalar<DataType> r_coord_squared(
175  const tnsr::I<DataType, 3, Frame::Inertial>& cartesian_coords) const
176  noexcept;
177 
178  // clang-tidy: google-runtime-references
179  void pup(PUP::er& /*p*/) noexcept; // NOLINT
180 
181  private:
182  friend bool operator==(const KerrSchildCoords& lhs,
183  const KerrSchildCoords& rhs) noexcept;
184 
185  // The spatial components of the Jacobian of the transformation from
186  // Kerr coordinates to Cartesian coordinates (x, y, z).
187  template <typename DataType>
188  tnsr::Ij<DataType, 3, Frame::NoFrame> jacobian_matrix(const DataType& x,
189  const DataType& y,
190  const DataType& z) const
191  noexcept;
192 
194 };
195 
196 bool operator!=(const KerrSchildCoords& lhs,
197  const KerrSchildCoords& rhs) noexcept;
198 
199 } // namespace gr
Definition: Strahlkorper.hpp:14
T signaling_NaN(T... args)
Contains helper functions for transforming tensors in Kerr spacetime to Kerr-Schild coordinates...
Definition: KerrSchildCoords.hpp:151
Holds functions related to general relativity.
Definition: KerrHorizon.cpp:14
Defines a list of useful type aliases for tensors.
Tensor< T, Symmetry<>, index_list<> > Scalar
Scalar type.
Definition: TypeAliases.hpp:21