tomopt.volume package

Submodules

tomopt.volume.heatmap module

class tomopt.volume.heatmap.DetectorHeatMap(*, res, eff, init_xyz, init_xy_span, m2_cost=1, budget=None, realistic_validation=False, device=device(type='cpu'), n_cluster=30)

Bases: Module

assign_budget(budget=None)

Return type:

None

clamp_params(musigz_low, musigz_high)

Return type:

None

get_cost()

Return type:

Tensor

get_efficiency(xy, mask=None, as_2d=False)

Return type:

Tensor

get_hits(mu)

Return type:

Dict[str, Tensor]

get_resolution(xy, mask=None)

Return type:

Tensor

get_xy_mask(xy)

Return type:

Tensor

plot_map(bpixelate=False, bsavefig=False, filename=None)

Return type:

None

property x: Tensor

property y: Tensor

tomopt.volume.layer module

class tomopt.volume.layer.AbsDetectorLayer(pos, *, lw, z, size, device=device(type='cpu'))

Bases: AbsLayer

Abstract base class for layers designed to record muon positions (hits) using detectors. Inheriting classes should override a number methods to do with costs/budgets, and hit recording.

When optimisation of operating in ‘fixed budget’ mode, the Volume will check the _n_costs class attribute of the layer and will add this to the total number of learnable budget assignments, and pass that number of budgets as an (_n_costs) tensor. By default this is zero, and inheriting classes should set the correct number during initialisation, or via a new default value.

Some parts of TomOpt act differently on detector layers, according to how the detectors are modelled. A type_label attribute is used to encode extra information, rather than relying purely on the object-instance type.

Multiple detection layers can be grouped together, via their pos attribute (position); a string-encoded value. By default, the inference methods expect detectors above the passive layer to have pos==’above’, and those below the passive volume to have pos==’below’. When retrieving hits from the muon batch, hits will be stacked together with other hits from the same pos.

The length and width (lw) is the spans of the layer in metres in x and y, and the layer begins at x=0, y=0. z indicates the position of the top of the layer, in meters, and size is the distance from the top of the layer to the bottom.

Important

By default, the detectors will not scatter muons.

Parameters:

• pos (str) – string-encoding of the detector-layer group

• lw (Tensor) – the length and width of the layer in the x and y axes in metres, starting from (x,y)=(0,0).

• z (float) – the z position of the top of layer in metres. The bottom of the layer will be located at z-size

• size (float) – the voxel size in metres. Must be such that lw is divisible by the specified size.

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

assign_budget(budget)

Inheriting classes should override this method to correctly assign elements of an (_n_costs) tensor to the parts of the detector to which they relate. All ordering of the tensor is defined using the function, but proper optimisation of the budgets may require that the same ordering is used, or that it is deterministic.

Parameters:

budget (Optional[Tensor]) – (_n_costs) tensor of budget assignments in unit currency

Return type:

None

conform_detector()

Optional method designed to ensure that the detector parameters lie within any require boundaries, etc. It will be called via the AbsVolumeWrapper after any update to the detector layers, but by default does nothing.

Return type:

None

abstract forward(mu)

Inheriting classes should override this method to implement the passage of the muons through the layer, and record muon positions (hits) according to the detector model.

Parameters:

mu (MuonBatch) – the incoming batch of muons

Return type:

None

abstract get_cost()

Inheriting classes should override this method to return the total, current cost of the detector(s) in the layer.

Return type:

Tensor

Returns:

Single-element tensor with the current total cost of the detector in the layer.

class tomopt.volume.layer.AbsLayer(lw, z, size, device=device(type='cpu'))

Bases: Module

Abstract base class for volume layers. The length and width (lw) is the spans of the layer in metres in x and y, and the layer begins at x=0, y=0. z indicates the position of the top of the layer, in meters, and size is the distance from the top of the layer to the bottom. size is also used to set the length, width, and height of the voxels that make up the layer.

Important

Users must ensure that both the length and width of the layer are divisible by size

Parameters:

• lw (Tensor) – the length and width of the layer in the x and y axes in metres, starting from (x,y)=(0,0).

• z (float) – the z position of the top of layer in metres. The bottom of the layer will be located at z-size

• size (float) – the voxel size in metres. Must be such that lw is divisible by the specified size.

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

abstract forward(mu)

Inheriting classes should override this method to implement the passage of the muons through the layer.

Parameters:

mu (MuonBatch) – the incoming batch of muons

Return type:

None

get_lw_z_size()

Return type:

Tuple[Tensor, Tensor, float]

Returns:

The length and width of the layer in the x and y axes in metres, starting from (x,y)=(0,0), the z position of the top of layer in metres, and the voxel size in metres.

class tomopt.volume.layer.PanelDetectorLayer(pos, *, lw, z, size, panels)

Bases: AbsDetectorLayer

A detector layer class that uses multiple “panels” to record muon positions (hits). Currently, two “panel” types are available: DetectorPanel and DetectorHeatMap Each detector layer, however, should contain the same type of panel, as this is used to set the type_label of the layer.

When optimisation of operating in ‘fixed budget’ mode, the Volume will check the _n_costs class attribute of the layer and will add this to the total number of learnable budget assignments, and pass that number of budgets as an (_n_costs) tensor. During initialisation, this is set to the number of panels in the layer, at time of initialisation.

Multiple detection layers can be grouped together, via their pos attribute (position); a string-encoded value. By default, the inference methods expect detectors above the passive layer to have pos==’above’, and those below the passive volume to have pos==’below’. When retrieving hits from the muon batch, hits will be stacked together with other hits from the same pos.

The length and width (lw) is the spans of the layer in metres in x and y, and the layer begins at x=0, y=0. z indicates the position of the top of the layer, in meters, and size is the distance from the top of the layer to the bottom.

Important

The detector panels do not scatter muons.

Parameters:

• pos (str) – string-encoding of the detector-layer group

• lw (Tensor) – the length and width of the layer in the x and y axes in metres, starting from (x,y)=(0,0).

• z (float) – the z position of the top of layer in metres. The bottom of the layer will be located at z-size

• size (float) – the voxel size in metres. Must be such that lw is divisible by the specified size.

• panels (Union[List[DetectorPanel], List[DetectorHeatMap], List[SigmoidDetectorPanel], ModuleList]) – The set of initialised panels to contain in the detector layer

assign_budget(budget)

Passes elements of an (_n_costs) tensor to each of the panels’ assign_budget method. Panels are ordered by decreasing z-position, i.e. the zeroth budget element will relate always to the highest panel, rather than necessarily to the same panel through the optimisation process

# TODO investigate whether it would be better to instead assign budgets based on a fixed ordering, rather than the z-order of the panels.

Parameters:

budget (Optional[Tensor]) – (_n_costs) tensor of budget assignments in unit currency

Return type:

None

conform_detector()

Loops through panels and calls their clamp_params method, to ensure that panels are located within the bounds of the detector layer. It will be called via the AbsVolumeWrapper after any update to the detector layers.

Return type:

None

forward(mu)

Propagates muons to each detector panel, in order of decreasing z-position, and calls their get_hits method to record hits to the muon batch. After this, the muons will be propagated to the bottom of the detector layer.

Parameters:

mu (MuonBatch) – the incoming batch of muons

Return type:

None

get_cost()

Returns the total, current cost of the detector(s) in the layer, as computed by looping over the panels and summing the returned values of calls to their get_cost methods.

Return type:

Tensor

Returns:

Single-element tensor with the current total cost of the detector in the layer.

static get_device(panels)

Helper method to ensure that all panels are on the same device, and return that device. If not all the panels are on the same device, then an exception will be raised.

Parameters:

panels (ModuleList) – ModuleLists of either DetectorPanel or DetectorHeatMap objects on device

Return type:

device

Returns:

Device on which all the panels are.

get_panel_zorder()

Return type:

List[int]

Returns:

The indices of the panels in order of decreasing z-position.

yield_zordered_panels()

Yields the index of the panel, and the panel, in order of decreasing z-position.

Return type:

Union[Iterator[Tuple[int, DetectorPanel]], Iterator[Tuple[int, DetectorHeatMap]]]

Returns:

Iterator yielding panel indices and panels in order of decreasing z-position.

class tomopt.volume.layer.PassiveLayer(lw, z, size, rad_length_func=None, step_sz=0.01, scatter_model='pdg', device=device(type='cpu'))

Bases: AbsLayer

Default layer of containing passive material that scatters the muons. The length and width (lw) is the spans of the layer in metres in x and y, and the layer begins at x=0, y=0. z indicates the position of the top of the layer, in meters, and size is the distance from the top of the layer to the bottom. size is also used to set the length, width, and height of the voxels that make up the layer.

Important

Users must ensure that both the length and width of the layer are divisible by size

If the layer is set to scatter muons (rad_length is not None), then two scattering models are available:

• ‘pdg’: The default and currently recommended model based on the Gaussian scattering model described in https://pdg.lbl.gov/2019/reviews/rpp2018-rev-passage-particles-matter.pdf

• ‘pgeant’: An under-development model based on a parameterised fit to data sampled from GEANT 4

The X0 values of each voxel is defined via a “radiation-length function”, which should return an (n_x,n_y) tensor of voxel X0 values, when called with the z, lw, and size of the layer. For example:

def arb_rad_length(*, z: float, lw: Tensor, size: float) -> float:
    rad_length = torch.ones(list((lw / size).long())) * X0["lead"]
    if z < 0.5:
        rad_length[...] = X0["beryllium"]
    return rad_length

This function can either be supplied during initialisation, or later via the load_rad_length method.

Parameters:

• lw (Tensor) – the length and width of the layer in the x and y axes in metres, starting from (x,y)=(0,0).

• z (float) – the z position of the top of layer in metres. The bottom of the layer will be located at z-size

• size (float) – the voxel size in metres. Must be such that lw is divisible by the specified size.

• rad_length_func (Optional[Callable[[Tensor, Tensor, float], Tensor]]) – lookup function that returns an (n_x,n_y) tensor of voxel X0 values for the layer. After initialisation, the load_rad_length method may be used to load X0 layouts.

• step_sz (float) – The step size in metres over which to compute muon propagation and scattering.

• scatter_model (str) – String selection for the scattering model to use. Currently either ‘pdg’ or ‘pgeant’.

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

abs2idx(xy)

Helper method to return the voxel indices in the layer of the supplied tensor of xy positions.

Warning

This method does NOT account for the possibility of positions may be outside the layer. Please ensure that positions are inside the layer.

Parameters:

xy (Tensor) – (N,xy) tensor of absolute xy positions in metres in the volume frame

Return type:

Tensor

Returns:

(N,xy) tensor of voxel indices in x,y

forward(mu)

Propagates the muons through the layer to the bottom in a series of scattering steps. If the ‘pdg’ model is used, then the step size is the step_sz of the layer, as supplied during initialisation. If the ‘pgeant’ model is used, the the step size specified as part of the fitting of the scattering model.

Parameters:

mu (MuonBatch) – the incoming batch of muons

Return type:

None

load_rad_length(rad_length_func)

Loads a new X0 layout into the layer voxels.

Parameters:

rad_length_func (Callable[[Tensor, Tensor, float], Tensor]) – lookup function that returns an (n_x,n_y) tensor of voxel X0 values for the layer.

Return type:

None

mu_abs2idx(mu, mask=None)

Helper method to return the voxel indices in the layer that muons currently occupy.

Warning

This method does NOT account for the possibility of muons being outside the layer. Please also supply a mask, to only select muons inside the layer.

Parameters:

• mu (MuonBatch) – muons to look up

• mask (Optional[Tensor]) – Optional (muons) Boolean tensor where True indicates that the muon position should be checked

Return type:

Tensor

Returns:

(muons,2) tensor of voxel indices in x,y

scatter_and_propagate(mu, mask=None)

Propagates the muons through (part of) the layer by the prespecified step_sz. If the layer is set to scatter muons (rad_length is not None), then the muons will also undergo scattering (changes in their trajectories and positions) according to the scatter model of the layer.

Warning

When computing scatterings, the X0 used for each muon is that of the starting voxel: If a muon moves into a neighbouring voxel of differing X0, then this will only be accounted for in the next step.

Parameters:

• mu (MuonBatch) – muons to propagate

• mask (Optional[Tensor]) – Optional (N,) Boolean mask. Only muons with True values will be scattered and propagated

Return type:

None

tomopt.volume.panel module

class tomopt.volume.panel.DetectorPanel(*, res, eff, init_xyz, init_xy_span, m2_cost=1, budget=None, realistic_validation=True, device=device(type='cpu'))

Bases: Module

Provides an infinitely thin, rectangular panel in the xy plane, centred at a learnable xyz position (metres, in absolute position in the volume frame), with a learnable width in x and y (xy_span). Whilst this class can be used manually, it is designed to be used by the PanelDetectorLayer class.

Despite inheriting from nn.Module, the forward method should not be called, instead passing a MuonBatch to the get_hits method will return hits corresponding to the muons.

During training model (.train() or .training is True), a continuous model of the resolution and efficiency will be used, such that hits are differentiable w.r.t. the learnable parameters of the panel. This means that muons outside of the physical panel will have hits at non-zero resolution. The current model is a 2D uncorrelated Gaussian in xy, centred over the panel, with width parameters equal to the xy_spans/4, i.e. the panel is 4-sigma across.

Efficiency is accounted for via a weighting approach, rather than deciding whether to record hits or not, i.e. muons will always record hits, but the probability of the hit actually being recorded is computable.

During evaluation mode (.eval() or .training is False), if the panel is set to use realistic_validation, then the physical panel will be simulated: Muons outside the panel have zero resolution and efficiency, resulting in NaN hits positions. Muons inside the panel will have the full resolution and efficiency of the panel, but hits will not be differentiable w.r.t. the panel xy-position or xy-span. If realistic_validation is False, then the continuous model will be used also in evaluation mode.

The cost of the panel is based on the supplied cost per metre squared, and the current area of the panel, according to its learnt xy-span. Panels can also be run in “fixed-budget” mode, in which a cost of the panel is specified via the .assign_budget method. Based on the cost per m^2, the panel will change in effective width, based on its learn xy_span (now an aspect ratio), such that its area results in a cost equal to the specified cost of the panel.

The resolution and efficiency remain fixed at the specified values. If intending to run in “fixed-budget” mode, then a budget can be specified here, however the :class”~tomopt.volume.volume.Volume class will pass through all panels and initialise their budgets.

Parameters:

• res (float) – resolution of the panel in m^-1, i.e. a higher value improves the precision on the hit recording

• eff (float) – efficiency of the hit recording of the panel, indicated as a probability [0,1]

• init_xyz (Tuple[float, float, float]) – initial xyz position of the panel in metres in the volume frame

• init_xy_span (Tuple[float, float]) – initial xy-span (total width) of the panel in metres

• m2_cost (float) – the cost in unit currency of the 1 square metre of detector

• budget (Optional[Tensor]) – optional required cost of the panel. Based on the span and cost per m^2, the panel will resize to meet the required cost

• realistic_validation (bool) – if True, will use the physical interpretation of the panel during evaluation

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

assign_budget(budget=None)

Sets the budget for the panel. This is then used to set a multiplicative coefficient, budget_scale, based on the m2_cost which rescales the xy_span such that the area of the resulting panel matches the assigned budget.

Parameters:

budget (Optional[Tensor]) – required cost of the panel in unit currency

Return type:

None

clamp_params(xyz_low, xyz_high)

Ensures that the panel is centred within the supplied xyz range, and that the span of the panel is between xyz_high/20 and xyz_high*10. A small random number < 1e-3 is added/subtracted to the min/max z position of the panel, to ensure it doesn’t overlap with other panels.

Parameters:

• xyz_low (Tuple[float, float, float]) – minimum x,y,z values for the panel centre in metres

• xyz_high (Tuple[float, float, float]) – maximum x,y,z values for the panel centre in metres

Return type:

None

forward()

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: None

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_cost()

Return type:

Tensor

Returns:

current cost of the panel according to its area and m2_cost

get_efficiency(xy, mask=None)

Computes the efficiency of panel at the supplied list of xy points. If running in evaluation mode with realistic_validation, then these will be the full efficiency of the panel for points inside the panel (indicated by the mask), and zero outside. Otherwise, the Gaussian model will be used.

Parameters:

• xy (Tensor) – (N,) or (N,xy) tensor of positions

• mask (Optional[Tensor]) – optional pre-computed (N,) Boolean mask, where True indicates that the xy point is inside the panel. Only used in evaluation mode and if realistic_validation is True. If required, but not supplied, than will be computed automatically.

Return type:

Tensor

Returns:

eff, a (N,)tensor of the efficiency at the xy points

get_gauss()

Return type:

Normal

Returns:

A Gaussian distribution, with 2 uncorrelated components corresponding to x and y, centred at the xy position of the panel, and sigma = panel span/4

get_hits(mu)

Return type:

Dict[str, Tensor]

The main interaction method with the panel: returns hits for the supplied muons. Hits consist of:

reco_xy: (muons,xy) tensor of reconstructed xy positions of muons included simulated resolution gen_xy: (muons,xy) tensor of generator-level (true) xy positions of muons z: z position of the panel

If running in evaluation mode with realistic_validation, then these will be the full resolution of the panel for points inside the panel (indicated by the mask), and zero outside. Otherwise, the Gaussian model will be used.

get_resolution(xy, mask=None)

Computes the xy resolutions of panel at the supplied list of xy points. If running in evaluation mode with realistic_validation, then these will be the full resolution of the panel for points inside the panel (indicated by the mask), and zero outside. Otherwise, the Gaussian model will be used.

Parameters:

• xy (Tensor) – (N,xy) tensor of positions

• mask (Optional[Tensor]) – optional pre-computed (N,) Boolean mask, where True indicates that the xy point is inside the panel. Only used in evaluation mode and if realistic_validation is True. If required, but not supplied, than will be computed automatically.

Return type:

Tensor

Returns:

res, a (N,xy) tensor of the resolution at the xy points

get_scaled_xy_span()

Computes the effective size of the panel by rescaling based on the xy-span, cost per m^2, and budget.

Return type:

Tensor

Returns:

Rescaled xy-span such that the panel has a cost equal to the specified budget

get_xy_mask(xy)

Computes which of the xy points lie inside the physical panel.

Parameters:

xy (Tensor) – xy2) tensor of points

Return type:

Tensor

Returns:

(N,) Boolean mask, where True indicates the point lies inside the panel

property x: Tensor

property y: Tensor

class tomopt.volume.panel.SigmoidDetectorPanel(*, smooth, res, eff, init_xyz, init_xy_span, m2_cost=1, budget=None, realistic_validation=True, device=device(type='cpu'))

Bases: DetectorPanel

Provides an infinitely thin, rectangular panel in the xy plane, centred at a learnable xyz position (metres, in absolute position in the volume frame), with a learnable width in x and y (xy_span). Whilst this class can be used manually, it is designed to be used by the PanelDetectorLayer class.

Despite inheriting from nn.Module, the forward method should not be called, instead passing a MuonBatch to the get_hits method will return hits corresponding to the muons.

During training model (.train() or .training is True), a continuous model of the resolution and efficiency will be used, such that hits are differentiable w.r.t. the learnable parameters of the panel. This means that muons outside of the physical panel will have hits at non-zero resolution. The model is a 2D uncorrelated Sigmoid in xy, centred over the panel, which pass 0.5 at the xy_spans/2. The smoothness of the sigmoid affects the rate of change of resolution|efficiency near the edge of the physical border: A higher smooth value provides a slower change, with higher resolution|efficiency outside the physical panel, whereas a lower smooth value provides a sharper transition, with lower sensitivity to muons outside the panel (and therefore more strongly approximated a physical panel). The SigmoidPanelSmoothnessSchedule can be used to anneal this smoothness during optimisation.

Efficiency is accounted for via a weighting approach, rather than deciding whether to record hits or not, i.e. muons will always record hits, but the probability of the hit actually being recorded is computable.

During evaluation mode (.eval() or .training is False), if the panel is set to use realistic_validation, then the physical panel will be simulated: Muons outside the panel have zero resolution and efficiency, resulting in NaN hits positions. Muons inside the panel will have the full resolution and efficiency of the panel, but hits will not be differentiable w.r.t. the panel xy-position or xy-span. If realistic_validation is False, then the continuous model will be used also in evaluation mode.

The cost of the panel is based on the supplied cost per metre squared, and the current area of the panel, according to its learnt xy-span. Panels can also be run in “fixed-budget” mode, in which a cost of the panel is specified via the .assign_budget method. Based on the cost per m^2, the panel will change in effective width, based on its learn xy_span (now an aspect ratio), such that its area results in a cost equal to the specified cost of the panel.

The resolution and efficiency remain fixed at the specified values. If intending to run in “fixed-budget” mode, then a budget can be specified here, however the :class”~tomopt.volume.volume.Volume class will pass through all panels and initialise their budgets.

Parameters:

• smooth (Union[float, Tensor]) – smoothness of the sigmoid: A higher smooth value provides a slower change, with higher resolution|efficiency outside the physical panel, whereas a lower smooth value provides a sharper transition, with lower sensitivity to muons outside the panel (and therefore more strongly approximated a physical panel).

• res (float) – resolution of the panel in m^-1, i.e. a higher value improves the precision on the hit recording

• eff (float) – efficiency of the hit recording of the panel, indicated as a probability [0,1]

• init_xyz (Tuple[float, float, float]) – initial xyz position of the panel in metres in the volume frame

• init_xy_span (Tuple[float, float]) – initial xy-span (total width) of the panel in metres

• m2_cost (float) – the cost in unit currency of the 1 square metre of detector

• budget (Optional[Tensor]) – optional required cost of the panel. Based on the span and cost per m^2, the panel will resize to meet the required cost

• realistic_validation (bool) – if True, will use the physical interpretation of the panel during evaluation

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

get_efficiency(xy, mask=None)

Computes the efficiency of panel at the supplied list of xy points. If running in evaluation mode with realistic_validation, then these will be the full efficiency of the panel for points inside the panel (indicated by the mask), and zero outside. Otherwise, the Sigmoid model will be used.

Parameters:

• xy (Tensor) – (N,) or (N,xy) tensor of positions

• mask (Optional[Tensor]) – optional pre-computed (N,) Boolean mask, where True indicates that the xy point is inside the panel. Only used in evaluation mode and if realistic_validation is True. If required, but not supplied, than will be computed automatically.

Return type:

Tensor

Returns:

eff, a (N,)tensor of the efficiency at the xy points

get_resolution(xy, mask=None)

Computes the xy resolutions of panel at the supplied list of xy points. If running in evaluation mode with realistic_validation, then these will be the full resolution of the panel for points inside the panel (indicated by the mask), and zero outside. Otherwise, the Sigmoid model will be used.

Parameters:

• xy (Tensor) – (N,xy) tensor of positions

• mask (Optional[Tensor]) – optional pre-computed (N,) Boolean mask, where True indicates that the xy point is inside the panel. Only used in evaluation mode and if realistic_validation is True. If required, but not supplied, than will be computed automatically.

Return type:

Tensor

Returns:

res, a (N,xy) tensor of the resolution at the xy points

sig_model(xy)

Models fractional resolution and efficiency from a sigmoid-based model to provide a smooth and differentiable model of a physical detector-panel.

Parameters:

xy (Tensor) – (N,xy) tensor of positions

Return type:

Tensor

Returns:

Multiplicative coefficients for the nominal resolution or efficiency of the panel based on the xy position relative to the panel position and size

property smooth: Tensor

tomopt.volume.scatter_model module

tomopt.volume.volume module

class tomopt.volume.volume.Volume(layers, budget=None)

Bases: Module

The Volume class is used to contain both passive layers and detector layers. It is designed to act as an interface to them for the convenience of e.g. VolumeWrapper, and to allow new passive-volume layouts to be loaded.

When optimisation is acting in fixed-budget mode, the volume is also responsible for learning the optimal assignments of the budget to detector parts.

Volumes can also have a “target” value. This could be e.g. the class ID of the passive-volume configuration which is currently loaded. See e.g. VolumeClassLoss. The target can be set as part of the call to load_rad_length()

The volume is expected to have its low-left-front (zxy) corner located at (0,0,0) metres.

Important

Currently this class expects that all PassiveLayer s form a single contiguous block, i.e. it does not currently support sparse, or multiple, passive volumes.

Parameters:

• layers (ModuleList) – torch.nn.ModuleList of instantiated AbsLayer s, ordered in decreasing z position.

• budget (Optional[float]) – optional budget of the detector in currency units. Supplying a value for the optional budget, here, will prepare the volume to learn budget assignments to the detectors, and configure the detectors for the budget.

assign_budget()

Distributed the total budget for the detector system amongst the various sub-detectors. When assigning budgets to layers, the budget weights are softmax-normalised to one, and multiplied by the total budget. Slices of these budgets are then passed to the layers, with the length of the slices being taken from _n_layer_costs.

Return type:

None

build_xyz_edges()

Computes the xyz locations of low-left-front edges of voxels in the passive layers of the volume.

Return type:

Tensor

property device: device

draw(*, xlim, ylim, zlim)

Draws the layers/panels pertaining to the volume. When using this in a jupyter notebook, use “%matplotlib notebook” to have an interactive plot that you can rotate.

Parameters:

• xlim (Tuple[float, float]) – the x axis range for the three-dimensional plot.

• ylim (Tuple[float, float]) – the y axis range for the three-dimensional plot.

• zlim (Tuple[float, float]) – the z axis range for the three-dimensional plot.

Return type:

None

forward(mu)

Propagates muons through each layer in turn. Prior to propagating muons, the assign_budget() method is called.

Parameters:

mu (MuonBatch) – the incoming batch of muons

Return type:

None

get_cost()

Return type:

Tensor

Returns:

The total, current cost of the layers in the volume,

or the assigned budget for the volume (these two values should be the same but, the actual cost won’t be evaluated explicitly)

get_detectors()

Return type:

List[AbsDetectorLayer]

Returns:

A list of all AbsDetectorLayer s in the volume, in the order of layers (normally decreasing z position)

get_passive_z_range()

Return type:

Tuple[Tensor, Tensor]

Returns:

The z position of the bottom of the lowest passive layer, and the z position of the top of the highest passive layer.

get_passives()

Return type:

List[PassiveLayer]

Returns:

A list of all PassiveLayer s in the volume, in the order of layers (normally decreasing z position)

get_rad_cube()

Return type:

Tensor

Returns:

zxy tensor of the values stored in the voxels of the passive volume, with the lowest layer being found in the zeroth z index position.

property h: Tensor

Returns: The height of the volume (including both passive and detector layers), as computed from the z position of the zeroth layer.

load_rad_length(rad_length_func, target=None)

Loads a new passive-volume configuration. Optionally, a “target” for the configuration may also be supplied. This could be e.g. the class ID of the passive-volume configuration which is currently loaded. See e.g. VolumeClassLoss.

Parameters:

• rad_length_func (Callable[[Tensor, Tensor, float], Tensor]) – lookup function that returns an (n_x,n_y) tensor of voxel X0 values for the layer.

• target (Optional[Tensor]) – optional target for the new layout

Return type:

None

lookup_passive_xyz_coords(xyz)

Looks up the voxel indices of the supplied list of absolute positions in the volume frame

Warning

Assumes the same size for all passive layers, and that they form a single contiguous block

Parameters:

xyz (Tensor) – an (N,xyz) tensor of absolute positions in the volume frame

Return type:

Tensor

Returns:

an (N,xyz) tensor of zero-ordered voxel indices, which correspond to the supplied positions

property lw: Tensor

Returns: The length and width of the passive volume

property passive_size: float

Returns: The size of voxels in the passive volume

property target: Tensor | None

Returns: The “target” value of the volume. This could be e.g. the class ID of the passive-volume configuration which is currently loaded. See e.g. VolumeClassLoss. The target can be set as part of the call to load_rad_length()

property xyz_centres: Tensor

xyz locations of the centres of voxels in the passive layers of the volume.

property xyz_edges: Tensor

xyz locations of low-left-front edges of voxels in the passive layers of the volume.