MuonFlux

A metatype for representing a primary flux of atmospheric muons.

Attributes

Name Type Description
model function or string Reference model for atmospheric muon spectra (see below).
altitude number or nil Model default altitude, in m.

Note

Attributes are readonly. The model cannot be modified once created. Instead one must create a new MuonFlux object.

Constructor

The MuonFlux constructor requires a spectrum model to be provided as first argument. Optionally one can also provide a default model altitude as well as a specific vertical axis or origin. If not specified spectrum models are provided w.r.t. the local vertical using the WGS84 ellipsoid (GPS altitude).

The spectrum model can be provided as a user defined Lua function, as a string path to a flux tabulation file or as a string name refering to a predefined model as listed in the table below.

Name Altitude (m) Description
'chirkin' 0 Parametric model from Chirkin, 2003.
'gaisser' 0 Gaisser's semi-analytical model, see e.g. Zyla et al., 2020.
'gccly' 0 Parametric model from Guan et al., 2015.
'mceq' 0-9000 Tabulation of MCEq results. Production yields have been weighted according to the global fit to experimental data of Yanez et al., 2019.

Warning

The 'chirkin', 'gaisser' and 'gccly' models are analytical parameterisations. They are only provided at sea level. No correction is applied if they are used at another altitude.

The 'mceq' model is a flux tabulation embedded in the pumas Lua package. Alternative flux tabulation files can be downloaded from the atmospheric-muon-flux GitHub project and provided as model argument. The GitHub project also contains a Python script allowing to generate these tabulations with MCeq.

If a function is provided as spectrum model then it synopsis must conform to the MuonFlux.spectrum one as:

model(kinetic_energy, cos_theta, (charge)=, (altitude)=)

The spectrum model function must return a number indicating the corresponding flux, in \text{GeV}^{-1}\text{m}^{-2}\text{s}^{-1}\text{sr}^{-1}.

Synopsis

pumas.MuonFlux{(altitude)=, (axis)=, (charge_ratio)=, (gamma)=, (model)=,
    (normalisation)=, (origin)=})

Arguments

Name Type Description
(altitude) number Default model altitude, in m. If specified this sets the sampling altitude of the sample method.
(axis) string or Coordinates Vertical axis of the flux model. Defaults to 'vertical' i.e. the local vertical is used assuming Earth-Centered Earth-Fixed (ECEF) coordinates for the simulation frame. Alternativelly if Coordinates are provided a constant vertical axis is used.
(charge_ratio) number Constant charge ratio (\mu^+ / \mu^-) for analytical models. Defaults to 1.2766 as measured by CMS.
(gamma) number Spectral exponent for analytical models. The default value depends on the model, e.g. \gamma = 2.7 for 'gaisser' model.
(model) function or string Reference model for atmospheric muon spectra. One of 'chirkin', 'gaisser', 'gccly', 'mceq', a path string to a flux tabulation file or a spectrum Lua function. Defaults to 'mceq'.
(normalisation) number Flux relative normalization. Defaults to 1, i.e. native model values are used.
(origin) Coordinates Origin of the flux model, in m. Defaults to the WGS84 ellipsoid if a local vertical axis is used or to the origin of the simulation frame otherwise.

MuonFlux.sample

Sample the primary MuonFlux for a given particle State. If a default altitude was specified when creating the MuonFlux object then it is also checked that the particle reached the corresponding value. On success the particle weight is updated by the sampled flux value.

Synopsis

MuonFlux:sample(state)

Arguments

Name Type Description
state State Particle state sampling the primary muon flux.

Returns

Type Description
boolean false if a primary flux altitude was specified but not reached by the particle, true otherwise.
number or nil Value of the sampled flux on success, in \text{GeV}^{-1}\text{m}^{-2}\text{s}^{-1}\text{sr}^{-1}, otherwise nil.

Note

On success the Monte Carlo weight of the input State is updated by the sampled flux value.

See also

spectrum.

MuonFlux.spectrum

Evaluate the differential muon flux for a given kinetic energy and cosine of the observation zenith angle. Optionally a specific charge and altitude can be requested. If no charge is provided then the total flux is returned, i.e. for both charges. If no altitude is provided then the default value of the MuonFlux object is used. If the MuonFlux object has no default altitude then a value of 0 m is assumed.

Note

The cosine of the observation zenith angle and the altitude have to be provided in the native frame of the model not in the simulation one. The zenith angle corresponds to the opposite of the direction of propagation of the muon. E.g. a cosine value of 1 indicates a vertically down going muon.

Synopsis

MuonFlux:spectrum(kinetic_energy, cos_theta, (charge)=, (altitude)=)

Arguments

Name Type Description
kinetic_energy number Muon kinetic energy, in \text{GeV}.
cos_theta number Cosine of the observation angle (see above).
(charge) number Muon electric charge. If 0 or nil the total flux is returned, i.e. for both charges.
(altitude) number Model altitude, in \text{m}. See above for default value.

Returns

Type Description
number Value of the differential flux, in \text{GeV}^{-1}\text{m}^{-2}\text{s}^{-1}\text{sr}^{-1}.

See also

sample.