tomopt.muon package

Submodules

tomopt.muon.generation module

class tomopt.muon.generation.AbsMuonGenerator(x_range, y_range, fixed_mom=5.0, energy_range=(0.5, 500), theta_range=(0, 1.2217304763960306))

Bases: object

Abstract generator base class implementing core functionality. Inheriting classes should override the flux method.

Once initialised, the object can be called, or it’s generate_set method called, to generate a set of initial muon kinematics. Each muon will have a starting x and y position sampled uniformly within a defined region. Theta and momentum will be defined by sampling the defined flux model.

Parameters:

• x_range (Tuple[float, float]) – range in metres of the absolute initial x-position in the volume reference frame over which muons can be generated

• y_range (Tuple[float, float]) – range in metres of the absolute initial y-position in the volume reference frame over which muons can be generated

• fixed_mom (Optional[float]) – if not None, will only generate muons with the specified momentum in GeV

• energy_range (Tuple[float, float]) – if fixed_mom is None, muons will have initial momentum sampled according to the flux model in the specified range in GeV

• theta_range (Tuple[float, float]) – muons will have initial theta sampled according to the flux model in the specified range in radians

abstract flux(energy, theta)

Inheriting classes should override this to implement their flux model for the supplied pairs of energies and thetas

Parameters:

• energy (Union[float, ndarray]) – energy values at which to compute the flux, in GeV

• theta (Union[float, ndarray]) – theta values at which to compute the flux, in radians

Return type:

Union[float, ndarray]

Returns:

muon flux for every energy & theta pair

classmethod from_volume(volume, min_angle=0.2617993877991494, fixed_mom=5.0, energy_range=(0.5, 500), theta_range=(0, 1.2217304763960306))

Class method to initialise x and y ranges of muon generation from the passive volume. Heuristically computes x,y generation range as (0-d,x+d), (0-d,y+d). Where d is such that a muon generated at (0-d,1) will only hit the last layer of the passive volume if it’s initial angle is at least min_angle. This balances a trade-off between generation efficiency and generator realism.

Parameters:

• volume (Volume) – Volume through which the muons will pass

• min_angle (float) – the minimum theta angle that a muon generated at the extreme x or y boundary would require to hit at least the last passive layer of the passive volume, if it’s phi angle were to point directly towards the passive volume.

• fixed_mom (Optional[float]) – if not None, will only generate muons with the specified momentum in GeV

• energy_range (Tuple[float, float]) – if fixed_mom is None, muons will have initial momentum sampled according to the flux model in the specified range in GeV

• theta_range (Tuple[float, float]) – muons will have initial theta sampled according to the flux model in the specified range in radians

Return type:

AbsMuonGenerator

generate_set(n_muons)

Generates a set of muons as a rank-2 tensor of shape (n_muons, 5), with initial kinematic variables [x, y, momentum, theta, phi]. Theta and, optionally, momentum are sampled from the flux model. x and y are sampled uniformly from the defined ranges. Phi is sampled uniformly from [0,2pi].

Parameters:

n_muons (int) – number of muons to generate

Return type:

Tensor

Returns:

Rank-2 tensor of shape (n_muons, 5), with initial kinematic variables [x, y, momentum, theta, phi]

class tomopt.muon.generation.MuonGenerator2015(x_range, y_range, fixed_mom=5.0, energy_range=(0.5, 500), theta_range=(0, 1.2217304763960306))

Bases: AbsMuonGenerator

Provides muon generator for sampling initial muon kinematics according to Guan et al. 2015 (arXiv:1509.06176).

Once initialised, the object can be called, or it’s generate_set method called, to generate a set of initial muon kinematics. Each muon will have a starting x and y position sampled uniformly within a defined region. Theta and momentum will be defined by sampling the defined flux model.

Parameters:

• x_range (Tuple[float, float]) – range in metres of the absolute initial x-position in the volume reference frame over which muons can be generated

• y_range (Tuple[float, float]) – range in metres of the absolute initial y-position in the volume reference frame over which muons can be generated

• fixed_mom (Optional[float]) – if not None, will only generate muons with the specified momentum in GeV

• energy_range (Tuple[float, float]) – if fixed_mom is None, muons will have initial momentum sampled according to the flux model in the specified range in GeV

• theta_range (Tuple[float, float]) – muons will have initial theta sampled according to the flux model in the specified range in radians

P1 = 0.102573

P2 = -0.068287

P3 = 0.958633

P4 = 0.0407253

P5 = 0.817285

flux(energy, theta)

Function returning modified Gaisser formula for cosmic muon flux given energy (float/np.array) and incidence angle (float/np.array) Uses model defined in Guan et al. 2015 (arXiv:1509.06176)

Parameters:

• energy (Union[float, ndarray]) – energy values at which to compute the flux, in GeV

• theta (Union[float, ndarray]) – theta values at which to compute the flux, in radians

Return type:

Union[float, ndarray]

Returns:

muon flux for every energy & theta pair

class tomopt.muon.generation.MuonGenerator2016(x_range, y_range, fixed_mom=5.0, energy_range=(0.5, 500), theta_range=(0, 1.2217304763960306))

Bases: AbsMuonGenerator

Provides muon generator for sampling initial muon kinematics according to Shukla and Sanskrith 2018 arXiv:1606.06907

Once initialised, the object can be called, or it’s generate_set method called, to generate a set of initial muon kinematics. Each muon will have a starting x and y position sampled uniformly within a defined region. Theta and momentum will be defined by sampling the defined flux model.

Parameters:

• x_range (Tuple[float, float]) – range in metres of the absolute initial x-position in the volume reference frame over which muons can be generated

• y_range (Tuple[float, float]) – range in metres of the absolute initial y-position in the volume reference frame over which muons can be generated

• fixed_mom (Optional[float]) – if not None, will only generate muons with the specified momentum in GeV

• energy_range (Tuple[float, float]) – if fixed_mom is None, muons will have initial momentum sampled according to the flux model in the specified range in GeV

• theta_range (Tuple[float, float]) – muons will have initial theta sampled according to the flux model in the specified range in radians

E_0 = 3.87

E_c = 0.5

I_0 = 88.0

N = 38.1938

Rod = 174.0

epinv = 0.00117096018735363

flux(energy, theta)

Function returning modified Gaisser formula for cosmic muon flux given energy (float/np.array) and incidence angle (float/np.array) Uses model defined in Shukla and Sanskrith 2018 arXiv:1606.06907

Parameters:

• energy (Union[float, ndarray]) – energy values at which to compute the flux, in GeV

• theta (Union[float, ndarray]) – theta values at which to compute the flux, in radians

Return type:

Union[float, ndarray]

Returns:

muon flux for every energy & theta pair

n = 3

tomopt.muon.muon_batch module

class tomopt.muon.muon_batch.MuonBatch(xy_p_theta_phi, init_z, device=device(type='cpu'))

Bases: object

Container class for a batch of many muons, defined by their position and kinematics.

Each muon has its own:

• x, y, and z position in metres, which are absolute coordinates in the volume frame.

• theta, the angle in radians [0,pi) between the muon trajectory and the negative z-axis in the volume frame muons with a theta > pi/2 (i.e. travel upwards) may be removed automatically

• phi, the anticlockwise angle in radians [0,2pi) between the muon trajectory and the positive x-axis, in the x-y plane of the volume frame.

• momentum (mom), the absolute value of the muon momentum in GeV

Muon properties should not be updated manually. Instead, call:

• .propagate_dz_dz(dz) to update the x,y,z positions of the muons for a given propagation dz in the z-axis.

• .propagate_dz_d(d) to update the x,y,z positions of the muons for a given propagation d in the muons’ trajectories.

• .scatter_dxy(dx_vol, dy_vol, mask) to shift the x,y positions of the muons, for which the values of the optional Boolean mask is true, by the specified amount.

• .scatter_dtheta_dphi(dtheta_vol, dphi_vol, mask) to alter the theta,phi angles of the muons, for which the values of the optional Boolean mask is true, by the specified amount.

Important

Muon momenta is currently constant

Important

Eventually the muon batch will be extended to store information about the inferred momentum of the muons reco_mom. However currently the reco_mom property will return the TRUE momentum of the muons, with no simulation of measurement precision.

By default, the MuonBatch class only contains the current position of the muons, however the .snapshot_xyz method can be used to store the xy positions of the muons at any time, to a dictionary with float z-position keys, xyz_hist.

In addition to storing the properties of the muons, the MuonBatch class is also used to store the detector hits associated with each muon. Hits may be added via the .append_hits method, and stored in the _hits attribute. Hits can then be retrieved by the .get_hits method.

Parameters:

• xy_p_theta_phi (Tensor) – (N_muon, 5) tensor, with xy [m], p [GeV], theta [r] (0, pi/2) defined w.r.t z axis, phi [r] (0, 2pi) defined anticlockwise from x axis

• init_z (Union[Tensor, float]) – initial z position of all muons in the batch

• device (device) – device on which to place the muon tensors

append_hits(hits, pos)

Record hits to _hits.

Parameters:

• hits (Dict[str, Tensor]) – dictionary of ‘reco_xy’, ‘gen_xy’, ‘z’ keys to (muons, *) tensors.

• pos (str) – Position of detector array in which the hits were recorded, currently either ‘above’ or ‘below’.

Return type:

None

copy()

Creates a copy of the muon batch at the current position and trajectories. Tensors are detached and cloned.

Important

This does NOT copy of hits

Return type:

MuonBatch

Returns:

New MuonBatch with xyz, and theta,phi equal to those of the current MuonBatch.

dtheta(theta_ref)

Computes absolute difference in the theta between the muons and the supplied theta angles

Parameters:

theta_ref (Tensor) – (N,) tensor to compare with the muon theta values

Return type:

Tensor

Returns:

Absolute difference between muons’ theta and the supplied reference theta

dtheta_x(theta_ref_x)

Computes absolute difference in the theta_x between the muons and the supplied theta_x angles

Parameters:

theta_ref_x (Tensor) – (N,) tensor to compare with the muon theta_x values

Return type:

Tensor

Returns:

Absolute difference between muons’ theta_x and the supplied reference theta_x

dtheta_y(theta_ref_y)

Computes absolute difference in the theta_y between the muons and the supplied theta_y angles

Parameters:

theta_ref_y (Tensor) – (N,) tensor to compare with the muon theta_y values

Return type:

Tensor

Returns:

Absolute difference between muons’ theta_y and the supplied reference theta_y

filter_muons(keep_mask)

Removes all muons, and their associated hits, except for muons specified as True in keep_mask.

Parameters:

keep_mask (Tensor) – (N,) Boolean tensor. Muons with False elements will be removed, along with their hits.

Return type:

None

get_hits(xy_low=None, xy_high=None)

Retrieve the recorded hits for the muons, optionally only for muons between the specified xy ranges. For ease of use, the list of hits are stacked into single tensors, resulting in a dictionary mapping detector-array position to a dictionary mapping hit variables to (N_muons, N_hits, *) tensors.

Parameters:

• xy_low (Union[Tuple[float, float], Tensor, None]) – (2,N) optional lower limit on xy positions

• xy_high (Union[Tuple[float, float], Tensor, None]) – (2,N) optional upper limit on xy positions

Return type:

Dict[str, Dict[str, Tensor]]

Returns:

Hits, a dictionary mapping detector-array position to a dictionary mapping hit variables to (N_muons, N_hits, *) tensors.

get_xy_mask(xy_low, xy_high)

Computes a (N,) Boolean tensor, with True values corresponding to muons which are within the supplied ranges in xy.

Parameters:

• xy_low (Union[Tuple[float, float], Tensor, None]) – (2,N) optional lower limit on xy positions

• xy_high (Union[Tuple[float, float], Tensor, None]) – (2,N) optional upper limit on xy positions

Return type:

Tensor

Returns:

(N,) Boolean mask with True values corresponding to muons which are with xy positions >= xy_low and < xy_high

property mom: Tensor

property muons: Tensor

p_dim = 3

ph_dim = 5

property phi: Tensor

static phi_from_theta_xy(theta_x, theta_y)

Computes the phi angle from theta_x and theta_y.

Important

This function does NOT work if theta is > pi/2

Parameters:

• theta_x (Tensor) – angle from the negative z-axis in the xz plane

• theta_y (Tensor) – angle from the negative z-axis in the yz plane

Return type:

Tensor

Returns:

phi, the anti-clockwise angle from the positive x axis, in the xy plane

propagate_d(d, mask=None)

Propagates all muons in their direction of flight by the specified distances.

Parameters:

• d (Union[Tensor, float]) – (1,) or (N,) distance(s) in metres to move.

• mask (Optional[Tensor]) – (N,) Boolean tensor. If not None, only muons with True mask elements are altered.

Return type:

None

propagate_dz(dz, mask=None)

Propagates all muons in their direction of flight such that afterwards they will all have moved a specified distance in the negative z direction.

Parameters:

• dz (Union[Tensor, float]) – distance in metres to move in the negative z direction, i.e. a positive dz results in the muons travelling downwards.

• mask (Optional[Tensor]) – (N,) Boolean tensor. If not None, only muons with True mask elements are altered.

Return type:

None

property reco_mom: Tensor

remove_upwards_muons()

Removes muons, and their hits, if their theta >= pi/2, i.e. they are travelling upwards after a large scattering. Should be run after any changes to theta, but make sure that references (e.g. masks) to the complete set of muons are no longer required.

Return type:

None

scatter_dtheta_dphi(dtheta_vol=None, dphi_vol=None, mask=None)

Changes the trajectory of the muons in theta-phi by the specified amounts, with no change in their x,y,z positions. If a mask is supplied, then only muons with True mask elements are altered.

Parameters:

• dtheta_vol (Optional[Tensor]) – (N,) tensor of angular changes in theta

• dphi_vol (Optional[Tensor]) – (N,) tensor of angular changes in phi

• mask (Optional[Tensor]) – (N,) Boolean tensor. If not None, only muons with True mask elements are altered.

Return type:

None

scatter_dtheta_xy(dtheta_x_vol=None, dtheta_y_vol=None, mask=None)

Changes the trajectory of the muons in theta-phi by the specified amounts in dtheta_xy, with no change in their x,y,z positions. If a mask is supplied, then only muons with True mask elements are altered.

Parameters:

• dtheta_x_vol (Optional[Tensor]) – (N,) tensor of angular changes in theta_x

• dtheta_y_vol (Optional[Tensor]) – (N,) tensor of angular changes in theta_y

• mask (Optional[Tensor]) – (N,) Boolean tensor. If not None, only muons with True mask elements are altered.

Return type:

None

scatter_dxyz(dx_vol=None, dy_vol=None, dz_vol=None, mask=None)

Displaces the muons in xyz by the specified amounts. If a mask is supplied, then only muons with True mask elements are displaced.

Parameters:

• dx_vol (Optional[Tensor]) – (N,) tensor of displacements in x

• dy_vol (Optional[Tensor]) – (N,) tensor of displacements in y

• dz_vol (Optional[Tensor]) – (N,) tensor of displacements in z

• mask (Optional[Tensor]) – (N,) Boolean tensor. If not None, only muons with True mask elements are displaced.

Return type:

None

snapshot_xyz()

Store the current xy positions of the muons in .xyz_hist, indexed by the current z position.

Return type:

None

th_dim = 4

property theta: Tensor

static theta_from_theta_xy(theta_x, theta_y)

Computes the theta angle from theta_x and theta_y.

Important

This function does NOT work if theta is > pi/2

Parameters:

• theta_x (Tensor) – angle from the negative z-axis in the xz plane

• theta_y (Tensor) – angle from the negative z-axis in the yz plane

Return type:

Tensor

Returns:

theta, the anti-clockwise angle from the negative z axis, in the xyz plane

property theta_x: Tensor

static theta_x_from_theta_phi(theta, phi)

Computes the angle from the negative z-axis in the xz plane from theta and phi

Important

This function does NOT work if theta is > pi/2

Parameters:

• theta (Tensor) – the anti-clockwise angle from the negative z axis, in the xyz plane

• phi (Tensor) – the anti-clockwise angle from the positive x axis, in the xy plane

Return type:

Tensor

Returns:

theta_x, the angle from the negative z-axis in the xz plane

property theta_xy: Tensor

property theta_y: Tensor

static theta_y_from_theta_phi(theta, phi)

Computes the angle from the negative z-axis in the yz plane from theta and phi

Important

This function does NOT work if theta is > pi/2

Parameters:

• theta (Tensor) – the anti-clockwise angle from the negative z axis, in the xyz plane

• phi (Tensor) – the anti-clockwise angle from the positive x axis, in the xy plane

Return type:

Tensor

Returns:

theta_y, the angle from the negative z-axis in the yz plane

property upwards_muons: Tensor

property x: Tensor

x_dim = 0

property xy: Tensor

property xyz: Tensor

property xyz_hist: List[Tensor]

property y: Tensor

y_dim = 1

property z: Tensor

z_dim = 2