magnus.earth

earth.py

Contains helper functions related to the Earth: its internal matter density and the geometry of neutrino trajectories through it.

Routine listings

density_matter_func_prem - Returns the density inside the Earth
using the Preliminary Reference Earth Model (PREM)

prem_layer_edges_along_chord - Returns the positions at which a
chord through the Earth crosses the PREM layer boundaries

distance_traveled_inside_earth - Returns the chord length for a
given neutrino direction

earth_radial_distance_from_depth - Converts position along a
chord to radial distance from the center of the Earth

dms_to_decimal - Converts (degree, minute, second) coordinates to
decimal degrees

chord_length_inside_earth - Returns the chord length between two
locations on the surface of the Earth

costhz_between_points_on_surface - Returns the zenith angle of
the chord between two locations on the surface of the Earth

coordinates_of_named_location - Returns the coordinates of a
predefined location (e.g., a neutrino detector site)

Attributes

`loc_coords_dms`
`PREM_BOUNDARIES`

Functions

`density_matter_func_prem`(→ Union[float, numpy.ndarray])	Returns the matter density inside the Earth according to the
`distance_traveled_inside_earth`(→ float)	Returns the distance traveled by a neutrino inside the Earth,
`earth_radial_distance_from_depth`(→ Union[float, ...)	Returns the radial distance measured from the center of the
`prem_layer_edges_along_chord`(→ numpy.ndarray)	Returns the positions along a chord through the Earth at which
`dms_to_decimal`(→ float)	Converts (degree, minute, second) coordinates to decimal degrees.
`chord_length_inside_earth`(→ float)	Returns the chord length between two locations on the surface of
`costhz_between_points_on_surface`(→ float)	Returns the zenith angle of the chord between two locations on
`coordinates_of_named_location`(→ numpy.ndarray)	Returns the coordinates of a predefined location (e.g., a

Module Contents

magnus.earth.loc_coords_dms[source]

magnus.earth.PREM_BOUNDARIES[source]

magnus.earth.density_matter_func_prem(r: float | numpy.ndarray, tol: float | None = 1e-08) → float | numpy.ndarray[source]

Returns the matter density inside the Earth according to the Preliminary Reference Earth Model (PREM) [1].

Returns the matter density inside the Earth according to the PREM, for a given radial distance measured from the center of the Earth. Accepts a single radial distance or an array of radial distances; array input is evaluated in a single vectorized pass.

Added in version 1.0.0.

Parameters:

r (float or np.ndarray) – Radial distance(s) measured from the center of the Earth [km].
tol (float, optional) – Relative tolerance by which a radial distance may exceed globaldefs.EARTH_RADIUS before a ValueError is raised; radii within the tolerance are clamped onto the surface. Default: 1e-8.

Returns:

Matter density [\(\text{g cm}^{-3}\)].

Return type:

float or np.ndarray

Raises:

ValueError – If any radial distance exceeds globaldefs.EARTH_RADIUS by more than the relative tolerance tol.

References

Examples

from magnus import earth

for r in (0.0, 3000.0, 5000.0, 6371.0):
    print('r = %6.0f km -> %6.2f g/cm^3'
          % (r, earth.density_matter_func_prem(r)))

r =      0 km ->  13.09 g/cm^3
r =   3000 km ->  10.60 g/cm^3
r =   5000 km ->   4.79 g/cm^3
r =   6371 km ->   1.02 g/cm^3

magnus.earth.distance_traveled_inside_earth(costhz: float) → float[source]

Returns the distance traveled by a neutrino inside the Earth, traveling with a cosine of zenith angle costhz.

Returns the length of the path traveled by a neutrino from the surface ot the Earth, through it, until it reaches a detector. The direction of the neutrino is parametrized by the zenith angle of the neutrino. Assumes that the neutrino detector is on the surface of the Earth, not underground. As a result, the distance is zero for all values of costhz > 0.

Added in version 1.0.0.

Parameters:: costhz (float) – Cosine of the zenith angle of the neutrino.
Returns:: Path length inside the Earth [km].
Return type:: float

Examples

from magnus import earth

for costhz in (-0.2, -0.5, -1.0):
    print('costhz = %5.2f -> %8.1f km'
          % (costhz, earth.distance_traveled_inside_earth(costhz)))

costhz = -0.20 ->   2548.4 km
costhz = -0.50 ->   6371.0 km
costhz = -1.00 ->  12742.0 km

magnus.earth.earth_radial_distance_from_depth(costhz: float, l: float | numpy.ndarray, tol: float | None = 1e-08) → float | numpy.ndarray[source]

Returns the radial distance measured from the center of the Earth to a position inside the Earth, given by costhz and l.

A neutrino with direction given by the cosine of the zenith angle, costhz, travels from l=0 to l=distance_traveled_inside_earth, computed below. The routine returns the radial distance to the neutrino when its distance from its point of entry into the Earth is l. Accepts a single distance or an array of distances; array input is evaluated in a single vectorized pass.

Added in version 1.0.0.

Parameters:

costhz (float) – Cosine of the zenith angle of the neutrino.
l (float or np.ndarray) – Distance(s) of the neutrino from its point of entry into the Earth [km].
tol (float, optional) – Absolute tolerance by which l may exceed the distance traveled inside the Earth before a ValueError is raised; distances within the tolerance are clamped onto the exit point. Default: 1e-8.

Returns:

Radial distance to the neutrino [km].

Return type:

float or np.ndarray

Raises:

ValueError – If any l exceeds the distance traveled inside the Earth for this value of costhz by more than the tolerance tol.

magnus.earth.prem_layer_edges_along_chord(costhz: float) → numpy.ndarray[source]

Returns the positions along a chord through the Earth at which the chord crosses the PREM layer boundaries.

A neutrino entering the Earth with direction costhz travels along a chord from \(l = 0\) to \(l =\) distance_traveled_inside_earth() (costhz). The matter density along the chord is piecewise-smooth, with discontinuities (or kinks) where the chord crosses the boundaries between PREM shells. This routine returns those crossing positions, which are useful as mandatory slab edges for the Magnus expansion: high-order quadrature converges at its nominal order only if the Hamiltonian is smooth within each slab.

The crossing positions solve \(r(l) = r_b\) for each boundary radius \(r_b\), which is a quadratic equation in \(l\): with \(u = d - l\) and \(d = -2 R \cos\theta_z\), one has

\[u^2 + 2 R \cos\theta_z\, u + \left(R^2 - r_b^2\right) = 0 .\]

Added in version 1.0.0.

Parameters:: costhz (float) – Cosine of the zenith angle of the neutrino (crossings exist only for costhz < 0).
Returns:: Sorted crossing positions l [km], each strictly inside (0, d). Empty if the chord crosses no boundary.
Return type:: np.ndarray

Examples

import numpy as np

from magnus import earth

edges = earth.prem_layer_edges_along_chord(-0.8)
d = earth.distance_traveled_inside_earth(-0.8)

print('%d crossings; the first three at %s km'
      % (len(edges), np.round(edges[:3], 1)))
print('symmetric about the midpoint:',
      np.allclose(edges + edges[::-1], d))

14 crossings; the first three at [ 3.8 18.8 30.5] km
symmetric about the midpoint: True

magnus.earth.dms_to_decimal(degrees: float, minutes: float, seconds: float) → float[source]

Converts (degree, minute, second) coordinates to decimal degrees.

Added in version 1.0.0.

Parameters:

degrees (float) – Degree part of the coordinate.
minutes (float) – Minute part of the coordinate.
seconds (float) – Second part of the coordinate.

Returns:

Coordinate in decimal degrees.

Return type:

float

magnus.earth.chord_length_inside_earth(lat1_dms: tuple[float, float, float], lon1_dms: tuple[float, float, float], lat2_dms: tuple[float, float, float], lon2_dms: tuple[float, float, float]) → float[source]

Returns the chord length between two locations on the surface of the Earth.

Computes the straight-line (chord) distance between two locations on the surface of the Earth, assumed spherical, using the haversine formula for the central angle between the two locations and converting it to a chord length.

Added in version 1.0.0.

Parameters:

lat1_dms (tuple of float) – Latitude of the first location, as (degrees, minutes, seconds).
lon1_dms (tuple of float) – Longitude of the first location, as (degrees, minutes, seconds).
lat2_dms (tuple of float) – Latitude of the second location, as (degrees, minutes, seconds).
lon2_dms (tuple of float) – Longitude of the second location, as (degrees, minutes, seconds).

Returns:

Chord length between the two locations [km].

Return type:

float

Examples

from magnus import earth

fermilab = ((41.0, 49.0, 55.0), (-88.0, -15.0, -26.0))
sanford = ((44.0, 21.0, 12.0), (-103.0, -45.0, -5.0))

print('Fermilab to Sanford: %.1f km'
      % earth.chord_length_inside_earth(fermilab[0], fermilab[1],
                                        sanford[0], sanford[1]))

Fermilab to Sanford: 1284.7 km

magnus.earth.costhz_between_points_on_surface(lat1_dms: tuple[float, float, float], lon1_dms: tuple[float, float, float], lat2_dms: tuple[float, float, float], lon2_dms: tuple[float, float, float]) → float[source]

Returns the zenith angle of the chord between two locations on the surface of the Earth.

Computes the cosine of the zenith angle at which a neutrino would need to travel in a straight chord through the Earth to reach the second location from the first (e.g., a source and a detector both on the surface). Assumes a spherical Earth and a detector on the surface, not underground, so the returned value is always non-positive (an upward- or horizontally-traveling neutrino, i.e. costhz > 0, would not cross the Earth’s interior at all).

Added in version 1.0.0.

Parameters:

lat1_dms (tuple of float) – Latitude of the first location, as (degrees, minutes, seconds).
lon1_dms (tuple of float) – Longitude of the first location, as (degrees, minutes, seconds).
lat2_dms (tuple of float) – Latitude of the second location, as (degrees, minutes, seconds).
lon2_dms (tuple of float) – Longitude of the second location, as (degrees, minutes, seconds).

Returns:

Cosine of the zenith angle of the chord connecting the two locations.

Return type:

float

magnus.earth.coordinates_of_named_location(source_func_name: str, loc_name: str) → numpy.ndarray[source]

Returns the coordinates of a predefined location (e.g., a neutrino detector site).

Looks up loc_name (case-insensitively, spaces treated as underscores) in the loc_coords_dms dictionary of predefined locations (neutrino telescopes/detector sites and a few reference points) and returns its latitude and longitude.

Added in version 1.0.0.

Parameters:

source_func_name (str) – Name of the calling function, used only to build a more informative error message if loc_name is not found.
loc_name (str) – Name of the predefined location (e.g., 'kamioka', 'south_pole'). See earth.loc_coords_dms for the full list.

Returns:

Array [lat, lon], with lat and lon each a (degree, minute, second) tuple.

Return type:

np.ndarray