Python interface

class danton.Box(size=None, *, latitude=None, longitude=None, altitude=None, declination=None, ellipsoid=None)

This class defines a bounding box for an area of interest in the Monte Carlo geometry. It also allows for transformation between geographic and local coordinates.

__new__(size=None, **kwargs)

Create a new bounding-box.

The size argument defines the dimensions of the box along the local x, y and z axes. It can be a float (cube), a size two array (square base) or a size three array. For examples, the following creates a 1 km high box with a 10x10 km² base.

>>> box = danton.Box([1E+04, 1E+03], latitude=45, longitude=3)

Refer to the attributes below for the possible values of the optional kwargs.

altitude

Altitude coordinate of box centre, in m.

The altitude is expressed in m, w.r.t. the ellipsoid (see the Coordinates systems section).

declination

Box declination angle, in deg.

The declination angle is expressed in deg, w.r.t. the geographic north (see the Local coordinates section).

ellipsoid

Reference ellipsoid for geographic coordinates.

See Table 1 below for possible values.

latitude

Latitude coordinate of box centre, in deg.

longitude

Longitude coordinate of box centre, in deg.

size

Box size along the x, y and z-axis, in m.

surface_area

Box surface area, in square-metres.

Note

This attribute is read-only. It is defined by the box size.

volume

Box cubic volume, in cubic-metres.

Note

This attribute is read-only. It is defined by the box size.

from_local(position=None, direction=None)

Convert local cartesian coordinates to geographic ones.

The position and direction arguments must be arrays-like containing local Cartesian coordinates in the box frame. For instance,

>>> coordinates = box.from_local([0, 0, 100])

inside(array=None, /, **kwargs)

Check if coordinates are inside the box.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

This method returns a boolean (or a ndarray of booleans), where True value(s) indicate that coordinates are inside the box.

The array argument, if specified, must be a structured ndarray containing geographic coordinates ("latitude", "longitude", "altitude").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> inside = box.inside(latitude=45, longitude=3, altitude=0)

projected_area(array=None, /, *, direction=None, **kwargs)

Compute the projected surface area, in square-metres.

Note

The positional array argument and keyword only (direction, kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing geographic coordinates ("azimuth", "elevation").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> area = box.projected_area(azimuth=30, elevation=45)

Geocentric coordinates can also be provided, in-lieu of geographic ones, with the direction argument. For example,

>>> area = box.projected_area(direction=[0, 0, 1])

to_local(array=None, /, **kwargs)

Convert geographic coordinates to local cartesian ones.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing geographic coordinates ("latitude", "longitude", "altitude", and optionally "azimuth", "elevation").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> position = box.to_local(latitude=45, longitude=3, altitude=0)

---

class danton.Geometry(**kwargs)

This class provides an interface to the Monte Carlo geometry, which may be configured through attributes. See the Geometry description section for more details.

__new__(**kwargs)

Create a new Earth geometry.

>>> geometry = danton.Geometry(geoid="EGM96")

By default, the Earth geometry is initialised according to the Preliminary Reference Earth Model (PREM). See the attributes below for other options.

ellipsoid

Reference ellipsoid for coordinates systems.

Note

This attribute is read-only. It is defined by the geoid model (see Table 1 below).

geoid

Reference geoid for the sea level.

Get or set the reference geoid for the sea level. By default, a spherical Earth is assumed, according to the PREM. Possible values are listed in Table 1 below.

Table 1 Available geoid models.

Model	Description	Ellipsoid
"EGM96"	An undulated Earth, according to the EGM96 model.	"WGS84"
"PREM81"	A spherical Earth, according to the PREM model.	"PREM81"
"WGS84"	An elliptical Earth, according to the WGS84 ellipsoid.	"WGS84"

ocean

Flag to enable / disable the ocean.

By default, the Earth is covered by a 3 km deep ocean, according to the PREM. Setting this attribute to False overrides the ocean by extending the upper crust layer.

topography

The topography elevation model.

Get or set the elevation model for describing the topography layer. By default, this is None, i.e. there are no topography elements. A float value specifies a uniform topography level, in m. For instance, the following sets the topography height to 1 km (all over the Earth).

>>> geometry.topography = 1E+03

Alternatively, a path to a folder containing tiles from a Global Digital Elevation Model (GDEM) can be provided (see e.g. SRTMGL1). For instance, as

>>> geometry.topography = "/path/to/gdem/"

topography_density

The topography bulk density.

Get or set the density of the topography layer, in kg/m³. For example, the following sets the ground density to 0.92 g/cm³.

>>> geometry.density = 0.92E+03 # kg/m3

topography_material

The topography constitutive material.

Get or set the constitutive material of the topography layer, which is "Rock" by default. For instance, the following sets the ground composition to water (to represent an ice cover, for example).

>>> geometry.material = "Water"

from_ecef(position, direction=None)

Convert ECEF coordinates to geographic ones.

The position and direction arguments must be arrays-like containing geocentric Cartesian coordinates in Earth-Centered Earth-Fixed (ECEF) frame. For instance,

>>> coordinates = geometry.from_ecef([6378137, 0, 0])

geoid_undulation(array=None, /, **kwargs)

Get undulation(s) w.r.t. the geoid.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing geographic ("latitude", "longitude").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> undulation = geometry.geoid_undulation(latitude=45, longitude=3)

locate(array=None, /, *, resolve=None, **kwargs)

Return the medium at geographic coordinates.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

If resolve is False (the default), then atmospheric layers are undifferentiated.

to_ecef(array=None, /, **kwargs)

Convert geographic coordinates to ECEF ones.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing geographic coordinates ("latitude", "longitude", "altitude", and optionally "azimuth", "elevation").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> position = geometry.to_ecef(latitude=45, longitude=3, altitude=0)

topography_elevation(array=None, /, *, reference=None, **kwargs)

Get topography elevation value(s).

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing geographic coordinates ("latitude", "longitude").

Alternativelly, geographic coordinates can be specified as kwargs. For instance,

>>> z = geometry.topography_elevation(latitude=45, longitude=3)

The optional reference argument specifies the reference surface for elevation values. Possible values are "ellipsoid" (default) or "geoid".

trace(array=None, /, *, backward=None, limit=None, resolve=None, **kwargs)

Trace the distance to the next medium.

Algorithm

The ray tracing is performed using the Turtle library, with the algorithm outlined in [NBCM20].

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The array argument, if specified, must be a structured ndarray containing start position ("latitude", "longitude", "altitude") and tracing direction ("azimuth", "elevation").

Alternativelly, position and direction can be specified as kwargs. For instance,

>>> trace = geometry.trace(
...     latitude = 45, longitude = 3, altitude = 0,
...     azimuth = 0, elevation = 90
... )

The optional backward argument reverses the tracing direction, if set to True.

The optional limit argument specifies a maximum distance, in m, for the tracing.

If resolve is False (the default), then atmospheric layers are undifferentiated.

translate(distance, array=None, /, *, copy=None, **kwargs)

Translate geographic coordinates.

Translate geographic coordinates by distance (in m) along a straight line. If a negative distance is provided, then the translation direction is reversed.

Note

The positional array argument and keyword only (kwargs) arguments are mutually exclusive.

The positional array argument, if specified, must be a structured ndarray containing the initial position ("latitude", "longitude", "altitude") and the translation direction ("azimuth", "elevation").

Alternativelly, the initial position and the translation direction can be specified as kwargs. For instance,

>>> coordinates = geometry.translate(
...     1000,
...     latitude = 45, longitude = 3, altitude = 0,
...     azimuth = 0, elevation = 90
... )

When an array argument is provided, set copy to False in order to translate coordinates in-place.

---

class danton.Materials(path=None)

This class provides an interface to a set of Monte Carlo materials, which are specified by a Materials Description File (MDF), in TOML format. Refer to the Materials description section for further details.

__new__(path=None, \)

Load a set of Monte Carlo materials from a MDF. For instance,

>>> materials = danton.Materials("examples/rocks.toml")

If path is None, Danton’s default materials are loaded.

__getitem__(name, \)

Return the properties of a material given its name.

---

class danton.ParticlesGenerator(*, geometry=None, random=None, weight=None)

This class provides a utility for the generation of Monte Carlo particles from configurable distributions. This tool is typically used to seed the Monte Carlo simulation with an initial set of particles.

Once initialised, the generator can be further configured using the methods detailed below (i.e. following a builder pattern). The generate() method then triggers the actual sampling of Monte Carlo particles. As an example, the following generates N particles uniformly within a solid angle (spanning elevation values between -5 and +5 deg), and with a \(1/E^2\) power-law energy distribution (between 1 PeV and 1 EeV).

>>> particles = generator                    \
...     .solid_angle(elevation=[-5, 5])      \
...     .powerlaw(1E+06, 1E+12, exponent=-2) \
...     .generate(N)

__new__(*, geometry=None, random=None, weight=True)

Create a new particles generator.

The weight argument specifies whether the particles should be weighted by the inverse of their generation likelihoods (\(\omega = 1 / \text{pdf}(\text{S})\), for a Monte Carlo state \(\text{S}\)) or not. Note that this can be overridden by individual distributions (using the weight flag of other methods).

direction(ecef=None, /, *, azimuth=None, elevation=None)

Fix the Monte Carlo particles direction.

The direction may be specified using geographic coordinates (azimuth, elevation) or geocentric ones (ecef).

energy(value, /)

Fix the Monte Carlo particles energy.

generate(shape=None, /)

Generate Monte Carlo particles according to the current settings.

The shape argument defines the number of particles requested (as a ndarray shape).

The outcome of this method is dependent on the generator configuration. If rejection sampling techniques are employed, then the actual sample size is returned along with the selected particles. Otherwise, only the generated particles are returned.

inside(*, limit=True, weight=None)

Set particles positions to be distributed inside a box volume.

Note

This method utilises rejection sampling techniques.

This method is best used in conjunction with a backward simulation, as it generates potential tau decay vertices within the specified box volume, contingent on being located inside the atmosphere.

By default, the candidate vertices are selected based on their likelihood of originating from the ground (including any topography), according to the tau lifetime. It is possible to disable this selection by setting the limit argument to False.

When setting the limit argument to a float, the provided value controls the distance to the ground (in multiples of the tau decay length) over which the selection operates, as

\[p = e^{-x}, \quad x = \min{\left\{\frac{d}{\lambda}, x_\ell\right\}},\]

where \(p\) is the selection probability, \(d\) the distance to the ground, \(\lambda\) the decay length, and \(x_\ell\) the limit value. The default limit is 3 times the tau decay length (i.e., limit=3).

pid(value, /)

Fix the Monte Carlo particles type.

Monte Carlo particles are indentified by their Particle ID (PID), which follows the Particle Data Group (PDG) numbering scheme.

position(ecef=None, /, *, latitude=None, longitude=None, altitude=None)

Fix the Monte Carlo particles position.

The position may be specified using geographic coordinates (latitude, longitude, and altitude) or geocentric ones (ecef).

powerlaw(energy_min, energy_max, /, *, exponent=None, weight=None)

Set particles energy to follow a power-law.

The energy_min and energy_max arguments define the support of the power-law, as an interval.

The default setting is a \(1 / E\) power-lawx, corresponding to exponent=-1. Note that setting the exponent value to zero results in a uniform distribution being used.

solid_angle(azimuth=None, elevation=None, *, weight=None)

Set particles direction to be distributed over a solid-angle.

The default settings is to consider the entire solid angle. The optional azimuth and elevation arguments may be used to restrict the solid angle by specifying an interval of acceptable angular values, in deg.

target(box, /, *, weight=None)

Set particles to target a box volume.

This method is best used in conjunction with a forward simulation, as it generates target points over the surface of the specified box.

The generation method is dependent on the direction configuration. If the direction is fixed (the azimuth and elevation values referring to the box origin), then all generated particles are colinear. Otherwise, the particles are ingoing on the box, with a cosine angular distribution (corresponding to an isotropic flux entering the box).

Note

In the event that the solid angle of incoming particles is restricted, then a rejection sampling method is employed.

---

class danton.Physics(**kwargs)

This class provides an interface to the Monte Carlo physics, which may be configured through attributes. See the Physics description section for further details.

__new__(**kwargs)

Create a new instance of Physics.

Refer to the attributes below for the possible values of the optional kwargs.

bremsstrahlung

The Bremsstrahlung model for tau energy losses.

The possible values of bremsstralung models are summarised in Table 2 below, the default setting being "SSR19".

Table 2 Available bremsstrahlung models.

Model	Reference
"ABB94"	Andreev, Bezrukov and Bugaev, Physics of Atomic Nuclei 57 (1994) 2066.
"KKP95"	Kelner, Kokoulin and Petrukhin, Moscow Engineering Physics Inst., Moscow, 1995.
"SSR19"	PROPOSAL‘s implementation of [SSR19].

dis

The Deep Inelastic Scattering (DIS) model for neutrino interactions.

The possible values of predefined cross-section models are summarised in Table 3 below, the default setting being "CMS11".

Table 3 Available DIS models.

Model	Reference
"BGR18"	Next-to-Next Leading Order (NNLO) computation from [BGR18].
"CMS11"	Next-to-Leading Order (NLO) computation from [CMS11].
"LO"	Leading Order (LO) computation using the selected PDFs (as in R. Gandhi et al., Astropart.Phys.5:81-110 (1996)).

Note

Selecting a predefined DIS model defines the corresponding PDF model (see Table 5), if not explicitly overridden.

Custom cross-sections

Alternatively to the predefined models, one might specify a path to a text file containing cross-section values in exactly the following format (BGR18.txt).

pair_production

The e+e- pair-production model for tau energy losses.

The possible values of pair-production models are summarised in Table 4 below, the default setting being "SSR19".

Table 4 Available pair-production models.

Model	Reference
"KKP68"	Kelner, Kokoulin and Petrukhin, Soviet Journal of Nuclear Physics 7 (1968) 237.
"SSR19"	PROPOSAL‘s implementation of [SSR19].

pdf

The Parton Distribution Functions (PDF) for neutrino interactions.

The possible values of predefined PDF models are summarised in Table 5 below, the default being None (i.e., the PDF are set according to the DIS model).

Table 5 Available PDF models.

PDF Model	DIS Model	Reference
"CT14nlo"	"LO".	CT14nlo.info.
"HERAPDF15NLO"	"CMS11".	HERAPDF15NLO_EIG.info.
"NNPDF31sx"	"BGR18".	[BGR18], see also here.

Custom PDFs

Alternatively to the predefined PDFs, one might specify a path to a text file containing PDF values in Les Houches Accord (LHA) format.

photonuclear

The photonuclear model for tau energy losses.

The possible values of photonuclear interaction models are summarised in Table 6 below, the default setting being "DRSS01".

Table 6 Available photonuclear interaction models.

Model	Reference
"BBKS03"	Bezrukov, Bugaev, Sov. J. Nucl. Phys. 33 (1981), 635, with improved photon-nucleon cross-section according to Kokoulin and hard component from Bugaev and Shlepin.
"BM02"	Butkevich and Mikheyev, Soviet Journal of Experimental and Theoretical Physics 95 (2002) 11.
"DRSS01"	Dutta, Reno, Sarcevic and Seckel, Phys.Rev. D63 (2001) 094020.

---

class danton.Random(seed=None, index=None)

A Pseudo-Random Numbers Generator (PRNG).

This class provides an interface to the Monte Carlo Pseudo Random Numbers Generator (PRNG). Refer to section Monte Carlo history for further details.

Note

The PRNG index and seed are 128-bit unsigned integers. However, since ndarrays do not support this format, an alternative representation is available as a size-two array of 64-bit unsigned integers.

__new__(**kwargs)

Create a new PRNG stream.

Refer to the attributes below for the possible values of the optional kwargs.

index

PRNG stream index.

seed

PRNG initial seed.

Note

Modifying the PRNG seed resets the stream index to zero.

uniform01(shape=None)

Generate pseudo-random number(s) uniformly distributed over (0,1).

The optional shape argument defines the number of numbers generated (as a ndarray shape). The default setting is to generate a single number.

---

class danton.Simulation(**kwargs)

This class provides an interface to a Danton Monte Carlo simulation, which may be configured through attributes.

__new__(**kwargs)

Create a new simulation interface, configured by default for the backward sampling of tau decays. For instance

>>> simulation = danton.Simulation()

Optional kwargs may be provided in order to override the default simulation attributes described below. For your convenience, the kwargs may also be used to specify Monte Carlo Geometry, Physics or Random attributes. For instance, the following creates a new simulation interface using the EGM96 geoid and a specific random seed.

>>> simulation = danton.Simulation(
...     geoid = "EGM96",
...     seed = 123456789
... )

geometry

The Monte Carlo geometry.

Get, modify, or set the Monte Carlo Geometry. For instance, the following sets an elliptical Earth, according to the WGS84 ellipsoid.

>>> simulation.geometry.geoid = "WGS84"

Refer to the Geometry description section for further information on the Monte Carlo geometry.

longitudinal

Flag to control the longitudinal approximation.

By default, a full 3D Monte Carlo simulation is performed. When this attribute is set to True, then deflections are neglected during collision (but not the resulting energy losses), leading to all particles propagating along the same line.

mode

The Monte Carlo simulation mode.

Must be one of "backward" (default), "forward" or "grammage". Refer to the Monte Carlo workflow section for further information.

physics

The Monte Carlo physics models.

Get, modify, or set the Monte Carlo Physics. For instance, the following changes the DIS interaction model to [BGR18].

>>> simulation.physics.dis = "BGR18"

Refer to the Physics description section for further information on the Monte Carlo physics.

random

The Monte Carlo random engine.

Get, modify, or set the Monte Carlo Random stream. For instance, the following changes the seed.

>>> simulation.random.seed = 123456789

Refer to the Monte Carlo history section for further information.

record_steps

Flag to control the recording of Monte Carlo steps.

By default, only a few Monte Carlo states of interest are recorded (see e.g. the run method). Setting this attribute to True results in the full history of Monte Carlo steps being recorded.

tau_decays

Flag to control the sampling of tau decays.

By default, Danton is configured to sample tau decays over a volume. Setting this flag to False results in the sampling of flux events instead, through a boundary surface defined by a constant altitude (w.r.t. the reference ellipsoid).

box(size=None, *, latitude=None, longitude=None, altitude=None, declination=None)

Create a bounding-box.

Refer to the Box constructor for further details on arguments.

Note

The Box ellipsoid attribute is set according to the simulation geometry.

particles(*, weight=None)

Create a Monte Carlo particles generator.

The returned ParticlesGenerator object is configured according to the simulation settings.

run(particles, /)

Run a Danton Monte Carlo simulation.

This method returns a namespace object whose content depends on the simulation mode, record_steps and tau_decays attributes. For example, in Backward mode with tau decays (but no steps recording), the returned namespace contains the sampled primaries, as well as the tau creation vertices, and the tau decay products (as structured ndarray, each). The corresponding data structures are described in Table 7 and Table 8 below.

Refer to the Monte Carlo workflow section for further information.

Table 7 Primaries, secondaries or vertices array structure.

Field	Format	Units
"event"	"u8"
"pid"	"i4"
"energy"	"f8"	GeV
"latitude"	"f8"	deg
"longitude"	"f8"	deg
"altitude"	"f8"	m
"azimuth"	"f8"	deg
"elevation"	"f8"	deg
"weight"	"f8"
"random_index"	"2u8"

Event

The "event" field indicates the index in the particles array that is provided as input to the run method.

Random index

The "random_index" field indicates the state of the PRNG (index) at the start of the event.

Table 8 Decay products array structure.

Field	Format	Units
"event"	"u8"
"pid"	"i4"
"momentum"	"f8"	GeV
"theta"	"f8"	deg
"phi"	"f8"	deg

Decay products direction

The "theta" and "phi" fields are spherical coordinates w.r.t. the tau direction at decay. That is, \(\theta = 0\) is an aligned decay product.

---

danton.compute(*args, **kwargs)

Compute materials tables.

This function pre-computes material tables, and caches the result (under danton.DEFAULT_CACHE or $DANTON_CACHE if defined).

The positional arguments (*args) are paths to Material Description Files (MDFs), while the keyword arguments may specify physics settings. Without any argument the default materials and physics tables are pre-computed.

Refer to the Physics description section for further information.

Note

Material tables are automatically pre-computed, on need, when no cached data are found. This function allows users to manually perform this pre-computation, whenever needed.

---

danton.particles(shape=None, /, **kwargs)

Create an array of Monte Carlo particles.

This function returns a structured ndarray with the given shape. Particles are initialised with default properties, if not overriden by specifying kwargs. For instance, the following creates an array of 100 particles (taus, by default) with an energy of 1 EeV, starting from the Equator (by default), and going to the North.

>>> particles = danton.particles(100, energy=1E+09)

The data structure (dtype) of a particle is the following (the corresponding physical units are also indicated).

Table 9 Particles array structure.

Field	Format	Units
"pid"	"i4"
"energy"	"f8"	GeV
"latitude"	"f8"	deg
"longitude"	"f8"	deg
"altitude"	"f8"	m
"azimuth"	"f8"	deg
"elevation"	"f8"	deg
"weight"	"f8"

Particle ID

The type of a Monte Carlo particle ("pid") is encoded according to the Particle Data Group (PDG) numbering scheme.