Asymptotic quantities and the BMS group¶

These classes represent fields on the sphere at null infinity and their transformations under the Bondi–Metzner–Sachs (BMS) group.

Functions on the sphere¶

class GWFrames.DataGrid¶

Complex spin-weighted data on an equiangular grid on the sphere.

Given integers N_theta and N_phi, the data are recorded on a “rectangular” grid of N_theta * N_phi points. The polar angle runs from 0 to \(\pi\) inclusive in N_theta equal steps, so that there are N_phi points at each pole, and the azimuthal angle runs from 0 to \(2\pi\) exclusive in N_phi equal steps. The point with polar index i_theta and azimuthal index i_phi is element i_theta * N_phi + i_phi. These objects are mainly a computational tool for pointwise multiplication; otherwise Modes is the preferable representation.

The arithmetic operators +, -, *, and / act point by point on two grids of the same dimensions; a product adds the spin weights, and a quotient subtracts them. A sum or difference is defined only for two grids of equal spin weight, as for Modes, and raises ValueError otherwise.

A float a may also appear on either side, as in a * D, D * a, a / D, D / a, a + D, D + a, a - D, and D - a, each of which acts on every point of D. The products a * D and D * a and the quotient D / a have the spin weight \(s\) of D, and the quotient a / D has spin weight \(-s\), as does D.pow(-1). A sum or difference with a nonzero number is meaningful only when \(s = 0\), because a constant has spin weight 0; the spin weight is not checked, and the result has the spin weight of D.

A DataGrid may be constructed in any of these ways:

DataGrid(size=0): A grid of size zeros with spin weight 0, whose dimensions are both set to the integer part of the square root of size.
DataGrid(A): A copy of the grid A.
DataGrid(Spin, N_theta, N_phi, D): A grid with spin weight Spin, dimensions N_theta and N_phi, and the complex values D, whose length must be N_theta * N_phi.
DataGrid(M, N_theta=0, N_phi=0): The values on the grid of the function whose spin-weighted spherical-harmonic modes are the Modes object M. Each dimension is at least 2 * M.EllMax() + 1.
DataGrid(M, v, N_theta=0, N_phi=0): The values of M on the grid of a frame boosted by the three-velocity v. Each point of the grid is mapped by the rotor from Boost before M is evaluated there with Modes.EvaluateAtPoint. Each dimension is at least 2 * M.EllMax() + 1.
DataGrid(Spin, N_theta, N_phi, v, f): The values of the ScriFunctor f on the grid of a frame boosted by the three-velocity v, with spin weight Spin and dimensions N_theta and N_phi.

classmethod __new__(*args, **kwargs)¶

DataGrid.Spin() → int¶

Return the spin weight of these data.

Returns:: int – The spin weight.

DataGrid.N_theta() → int¶

Return the number of points in the polar direction.

Returns:: int – The number of points.

DataGrid.N_phi() → int¶

Return the number of points in the azimuthal direction.

Returns:: int – The number of points.

DataGrid.size() → int¶

Return the number of values stored in this grid.

Returns:: int – The number of values, which is also given by len.

DataGrid.Data() → ndarray¶

Return a copy of the values on this grid.

Returns:: ndarray of complex – The values, in the order described in DataGrid.

DataGrid.SetSpin(ess: int) → DataGrid¶

Set the spin weight of these data, without changing the values.

Parameters:: ess (int) – The new spin weight.
Returns:: DataGrid – This object, modified in place.

DataGrid.SetNTheta(N_theta: int) → DataGrid¶

Set the number of polar points, without changing the values.

Parameters:: N_theta (int) – The new number of points.
Returns:: DataGrid – This object, modified in place.

DataGrid.SetNPhi(N_phi: int) → DataGrid¶

Set the number of azimuthal points, without changing the values.

Parameters:: N_phi (int) – The new number of points.
Returns:: DataGrid – This object, modified in place.

DataGrid.pow(p: int) → DataGrid¶

Raise the value at each point of this grid to an integer power.

The spin weight of the result is p times that of this grid, just as the spin weight of a product is the sum of the spin weights of its factors.

Parameters:: p (int) – The exponent.
Returns:: DataGrid – The new grid.

class GWFrames.Modes¶

Complex spin-weighted data on the sphere, as spherical-harmonic modes.

The data are the coefficients of the spin-weighted spherical harmonics \({}_{s}Y_{\ell m}\) for every \(\ell\) from 0 to Modes.EllMax, even for \(\ell < |s|\), where they vanish. They are stored in the order \((\ell, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), \ldots\), so that the mode \((\ell, m)\) is element \(\ell^2 + \ell + m\).

The arithmetic operators +, -, *, and / act on two Modes objects. Sums and differences require equal spin weights, and treat the missing higher modes of the shorter operand as zero. Products and quotients are computed point by point on a DataGrid large enough to resolve the result, which is then truncated to the larger of the two values of \(\ell_{\max}\); a product adds the spin weights, and a quotient subtracts them.

A Modes object may be constructed in any of these ways:

Modes(size=0): size zero modes, with spin weight 0 and Modes.EllMax 0 (whatever the value of size).
Modes(A): A copy of the Modes object A.
Modes(spin, Data): The complex modes Data with spin weight spin. The length of Data must be \((\ell_{\max}+1)^2\) for some \(\ell_{\max}\).
Modes(D, L=-1): The modes of the DataGrid D, computed with spinsfast. The value of \(\ell_{\max}\) is the larger of L and the largest value the grid resolves, which is the smaller of (D.N_theta() - 1) // 2 and (D.N_phi() - 1) // 2.

classmethod __new__(*args, **kwargs)¶

Modes.Spin() → int¶

Return the spin weight of these data.

Returns:: int – The spin weight.

Modes.EllMax() → int¶

Return the largest ell value of these data.

Returns:: int – The value of \(\ell_{\max}\).

Modes.size() → int¶

Return the number of modes stored.

Returns:: int – The number of modes, which is also given by len.

Modes.Data() → ndarray¶

Return a copy of the modes.

Returns:: ndarray of complex – The modes, in the order described in Modes.

Modes.SetSpin(ess: int) → Modes¶

Set the spin weight of these data, without changing the modes.

Parameters:: ess (int) – The new spin weight.
Returns:: Modes – This object, modified in place.

Modes.SetEllMax(ell: int) → Modes¶

Set the largest ell value of these data, without changing the modes.

Parameters:: ell (int) – The new value of \(\ell_{\max}\).
Returns:: Modes – This object, modified in place.

Modes.EvaluateAtPoint(vartheta: float, varphi: float) → complex¶

Modes.EvaluateAtPoint(R: Quaternion) → complex

Evaluate the function represented by these modes at a point on the sphere.

The point may be given either by its polar and azimuthal angles or by a rotor R. The rotor might typically be thought of as the rotation taking \(\hat{z}\) into the point \((\vartheta, \varphi)\). More general rotors are possible, however; they are used to construct a DataGrid from a Modes object with a boost.

The modes with \(\ell < |s|\) are skipped, because the spin-weighted spherical harmonics vanish identically there.

Parameters:

vartheta (float) – Polar angle of the point.
varphi (float) – Azimuthal angle of the point.
R (Quaternion) – Rotor taking \(\hat{z}\) into the point.

Returns:

complex – The value of the function at the point.

Modes.bar() → Modes¶

Return the modes of the complex conjugate of the function.

If these modes represent a function \(f\) of spin weight \(s\), the result represents \(\bar{f}\), which has spin weight \(-s\).

Returns:: Modes – The new modes, with spin weight \(-s\).

Notes

Because \({}_{s}\bar{Y}_{\ell,m} = (-1)^{s+m}\, {}_{-s}Y_{\ell,-m}\), the modes of the conjugate are

\[\bar{f}_{\ell,m} = (-1)^{s+m}\, \overline{f_{\ell,-m}}.\]

Modes.edth() → Modes¶

Apply the spin-raising operator \(\eth\) to these data.

This is the operator defined by Geroch, Held, and Penrose (1973). It raises the spin weight by 1, and leaves the boost weight unchanged. Each mode with \(\ell \geq |s+1|\) is multiplied by \(\sqrt{(\ell-s)(\ell+s+1)/2}\), and the others are set to zero.

Returns:: Modes – The new modes, with spin weight \(s+1\).

Slices of null infinity¶

class GWFrames.SliceOfScriGrid¶

The data on one slice of null infinity, each as a DataGrid.

A slice is the set of points of null infinity at one value of the retarded time. The data needed to describe its geometry are the Newman–Penrose curvature scalars \(\psi_0, \ldots, \psi_4\), the complex shear \(\sigma\) of outgoing null rays, and its time derivative \(\dot{\sigma}\). Besides being available as attributes, these seven grids may be accessed by index, in that order, so that S[0] is psi0 and S[6] is sigmadot; len(S) is always 7. Indexing and attribute access both return the stored grid, not a copy. Objects of this class are returned by SliceModes.BMSTransformationOnSlice.

A SliceOfScriGrid may be constructed in either of these ways:

SliceOfScriGrid(size=0): Seven grids constructed as DataGrid(size), with the spin weights 2, 1, 0, -1, -2, 2, and 2 of the quantities above.
SliceOfScriGrid(S): A copy of the slice S.

psi0, psi1, psi2, psi3, psi4

The Newman–Penrose curvature scalars.

Type:: DataGrid

sigma¶

The complex shear.

Type:: DataGrid

sigmadot¶

The time derivative of the complex shear.

Type:: DataGrid

class GWFrames.SliceOfScriModes¶

The data on one slice of null infinity, each as a Modes object.

A slice is the set of points of null infinity at one value of the retarded time. The data needed to describe its geometry are the Newman–Penrose curvature scalars \(\psi_0, \ldots, \psi_4\), the complex shear \(\sigma\) of outgoing null rays, and its time derivative \(\dot{\sigma}\). Besides being available as attributes, these seven Modes objects may be accessed by index, in that order, so that S[0] is psi0 and S[6] is sigmadot; len(S) is always 7. Indexing and attribute access both return the stored object, not a copy. This is the base class of SliceModes, which is usually the class to use.

A SliceOfScriModes may be constructed in either of these ways:

SliceOfScriModes(size=0): Seven objects constructed as Modes(size), with the spin weights 2, 1, 0, -1, -2, 2, and 2 of the quantities above.
SliceOfScriModes(S): A copy of the slice S.

psi0, psi1, psi2, psi3, psi4

The Newman–Penrose curvature scalars.

Type:: Modes

sigma¶

The complex shear.

Type:: Modes

sigmadot¶

The time derivative of the complex shear.

Type:: Modes

class GWFrames.SliceModes¶

The data on one slice of null infinity, as modes, with derived quantities.

This subclass of SliceOfScriModes adds methods for the supermomentum, the Bondi four-momentum, and the mass on the slice, and for transforming the data on the slice under the Bondi–Metzner–Sachs (BMS) group.

A SliceModes object may be constructed in either of these ways:

SliceModes(ellMax=0): Seven Modes objects of zeros, each with \(\ell_{\max}\) equal to ellMax and with the spin weights 2, 1, 0, -1, -2, 2, and 2 of \(\psi_0, \ldots, \psi_4\), \(\sigma\), and \(\dot{\sigma}\).
SliceModes(S): A copy of the slice S.

classmethod __new__(*args, **kwargs)¶

SliceModes.EllMax() → int¶

Return the largest ell value of the data on this slice.

Returns:: int – The largest value of Modes.EllMax among the seven quantities.

SliceModes.Mass() → float¶

Calculate the mass of the system from the four-momentum.

Returns:: float – The mass \(\sqrt{p_0^2 - p_1^2 - p_2^2 - p_3^2}\), where \(p\) is the result of SliceModes.FourMomentum.

SliceModes.FourMomentum() → ndarray¶

Calculate the Bondi four-momentum of the system from the supermomentum.

The four-momentum is given by the \(\ell = 0\) and \(\ell = 1\) modes of the result of SliceModes.SuperMomentum.

Returns:: ndarray of float, shape (4,) – The four-momentum, with the time component first.

SliceModes.SuperMomentum() → Modes¶

Calculate the Moreschi supermomentum on this slice.

The supermomentum is

\[\Psi = \psi_2 + \sigma \dot{\bar{\sigma}} + \eth^2 \bar{\sigma},\]

where \(\eth\) is the operator of Modes.edth.

Returns:: Modes – The supermomentum.

SliceModes.BMSTransformationOnSlice( u: float, v: ndarray, delta: Modes, ) → SliceOfScriGrid¶

Apply a BMS transformation within this slice, without moving points in time.

A full BMS transformation needs data from several slices, because the supertranslation moves points between slices. This method only transforms the data within the slice: it evaluates them on the grid of the frame boosted by v, with the factors of the conformal factor, the mixing of the curvature scalars caused by the change of tetrad, and the shift of \(\sigma\) by \(\eth^2 \delta\). Each point of the resulting grids can then be interpolated in time to the supertranslated slice, as Scri.BMSTransformation does. The grids have 2 * EllMax() + 1 points in each direction.

Parameters:

u (float) – Retarded time of this slice.
v (array_like of float, shape (3,)) – Three-velocity of the boost relative to the current frame.
delta (Modes) – Spherical-harmonic modes of the supertranslation.

Returns:

SliceOfScriGrid – The transformed data on the boosted grid.

class GWFrames.Scri¶

The asymptotic geometry of null infinity, as a sequence of slices.

A Scri object contains the data needed to express the asymptotic geometry of null infinity and its symmetry transformations. This geometry is encoded in the Newman–Penrose curvature scalars \(\psi_0, \ldots, \psi_4\) and the complex shear \(\sigma\) of outgoing null rays (the strain in gravitational-wave detectors). The general symmetry transformation is an element of the Bondi–Metzner–Sachs (BMS) group, which transforms these data among themselves.

The data are stored as one SliceModes object at each time. len(S) is the number of times, and S[i] is a copy of the slice at time index i, which may be replaced by assigning to S[i].

A Scri object may be constructed in either of these ways:

Scri(psi0, psi1, psi2, psi3, psi4, sigma): The data in six Waveform objects, which must have the same number of times and the same value of Waveform.EllMax, and must contain every mode \((\ell, m)\) up to that value, including \(\ell = 0\) and \(\ell = 1\). The times are taken from psi0, and \(\dot{\sigma}\) is computed by differentiating sigma in time.
Scri(S): A copy of the Scri object S.

classmethod __new__(*args, **kwargs)¶

Scri.NTimes() → int¶

Return the number of time steps.

Returns:: int – The number of slices, which is also given by len.

Scri.T() → ndarray¶

Return the times of the slices.

Returns:: ndarray of float – The times.

Scri.BMSTransformation(u0: float, v: ndarray, delta: Modes) → SliceModes¶

Apply a constant BMS transformation to the data on null infinity.

A general BMS transformation is a conformal transformation of the sphere (which encompasses rotations and boosts) together with a supertranslation (which affects only the time coordinate on null infinity). Here the conformal transformation is assumed to be a pure boost with velocity v; the rotation is taken to be zero. The supertranslation is given by its (scalar) spherical-harmonic modes, which are assumed to describe a real function on the sphere.

The new and old time coordinates are related by \(u' = K(u - \delta)\), where the conformal factor \(K\) depends on the angle. The slice returned is the one on which \(u' = 0\), since any other choice can be absorbed into a translation in time and space. The data at each grid point are therefore interpolated, with cubic splines in time, to the original time \(u = u_0 + \delta\), which differs from point to point. The data are first evaluated on the grid of the final frame by SliceModes.BMSTransformationOnSlice, and are finally transformed back into modes. An error is raised if these times are not all within the time span of the data.

Parameters:

u0 (float) – Time of the slice to be transformed, to which the supertranslation is added.
v (array_like of float, shape (3,)) – Three-velocity of the boost relative to the current frame.
delta (Modes) – Spherical-harmonic modes of the supertranslation.

Returns:

SliceModes – The transformed data on the new slice.

class GWFrames.SuperMomenta¶

The supermomentum of a system as a function of time.

A SuperMomenta object stores a Modes object for the supermomentum at each of a sequence of times, as computed by SliceModes.SuperMomentum, and is used to find a BMS frame by Moreschi’s algorithm. len(S) is the number of times, and S[i] is a copy of the supermomentum at time index i, which may be replaced by assigning to S[i].

A SuperMomenta object may be constructed in any of these ways:

SuperMomenta(size): size times, all zero, with empty Modes objects.
SuperMomenta(S): A copy of the SuperMomenta object S.
SuperMomenta(T, psi): The times T, a sequence of floats, and the supermomenta psi, a sequence of Modes objects.
SuperMomenta(scri): The times of the Scri object scri, and the supermomentum of each of its slices.

classmethod __new__(*args, **kwargs)¶

SuperMomenta.NTimes() → int¶

Return the number of time steps.

Returns:: int – The number of times, which is also given by len.

SuperMomenta.T() → ndarray¶

Return the times at which the supermomentum is stored.

Returns:: ndarray of float – The times.

SuperMomenta.BMSTransform(OneOverK: Modes, delta: Modes) → Modes¶

Return the supermomentum on a constant-time slice of a BMS-transformed frame.

The boost of the transformation is found from OneOverK by vFromOneOverK. At each time, the quantity \((\Psi - \eth^2 \bar{\eth}^2 \delta)/K^3\) is evaluated on the grid of the boosted frame, and the values at each grid point are interpolated, with cubic splines in time, to the time \(u = \delta\) at that point. This is the slice \(u' = 0\) of the new frame, which is centered on the \(\ell = 0\) mode of delta. An error is raised if these times are not all within the time span of the data.

Parameters:

OneOverK (Modes) – Modes of the inverse conformal factor \(1/K\) of the boost.
delta (Modes) – Spherical-harmonic modes of the supertranslation.

Returns:

Modes – The transformed supermomentum.

SuperMomenta.MoreschiIteration(OneOverK: Modes, delta: Modes) → None¶

Take one step of Moreschi’s algorithm, updating a BMS transformation in place.

The supermomentum \(\Psi\) is first transformed by SuperMomenta.BMSTransform with the given OneOverK and delta, and the mass \(M\) is computed from the four-momentum given by its \(\ell \leq 1\) modes. The arguments are then replaced by the next step of the algorithm. Each mode of delta with \(\ell \geq 2\) becomes \(4/[(\ell-1)\ell(\ell+1)(\ell+2)]\) times the corresponding mode of \(\Psi + M K^3\); its \(\ell = 0\) and \(\ell = 1\) modes are unchanged. The \(\ell = 0\) mode of OneOverK becomes \(\Psi_{00} / M\), and its \(\ell = 1\) modes become \(-\Psi_{1m} / (3M)\), with the sign reversed so that the boost found is removed by the next step rather than reported.

Parameters:

OneOverK (Modes) – Inverse conformal factor, with at least the \(\ell \leq 1\) modes; it is replaced by the next step.
delta (Modes) – Supertranslation; it is replaced by the next step.

Boosts and conformal factors¶

GWFrames.Boost(v: ndarray, n: ndarray) → Quaternion¶

Return a rotor taking a direction into its boosted version.

The returned rotor \(R_b\) takes the unit vector \(\hat{n}\) (the normalized n), regarded as a point on the future null sphere, into its image under a boost with velocity v. The rotor therefore depends on both the direction and the boost. It is a rotation about the axis \(\hat{v} \times \hat{n}\) that changes the angle \(\Theta\) between \(\hat{v}\) and \(\hat{n}\) into \(\Theta' = 2 \arctan\left(e^{\alpha} \tan(\Theta/2)\right)\), where \(\alpha\) is the rapidity of the boost. The identity is returned when v is negligibly small or n is parallel to v.

Parameters:

v (array_like of float, shape (3,)) – Three-velocity of the new frame relative to the current frame, in units where \(c = 1\).
n (array_like of float, shape (3,)) – Direction to be boosted. It is normalized, and must not be zero.

Returns:

Quaternion – The rotor \(R_b\).

GWFrames.ConformalFactorGrid(v: ndarray, n_theta: int, n_phi: int) → DataGrid¶

Construct a grid with the conformal factor of a boost at each point.

The conformal factor is \(K = 1 / \left[\gamma (1 - \vec{v} \cdot \hat{n})\right]\), where \(\hat{n}\) is the direction of the grid point and \(\gamma\) is the Lorentz factor of v. The grid has spin weight 0.

Parameters:

v (array_like of float, shape (3,)) – Three-velocity of the boost.
n_theta (int) – Number of points in the polar direction.
n_phi (int) – Number of points in the azimuthal direction.

Returns:

DataGrid – The conformal factor on the grid.

GWFrames.InverseConformalFactorGrid(v: ndarray, n_theta: int, n_phi: int) → DataGrid¶

Construct a grid with the inverse conformal factor of a boost at each point.

The inverse conformal factor is \(1/K = \gamma (1 - \vec{v} \cdot \hat{n})\), where \(\hat{n}\) is the direction of the grid point and \(\gamma\) is the Lorentz factor of v. The grid has spin weight 0.

Parameters:

v (array_like of float, shape (3,)) – Three-velocity of the boost.
n_theta (int) – Number of points in the polar direction.
n_phi (int) – Number of points in the azimuthal direction.

Returns:

DataGrid – The inverse conformal factor on the grid.