legendhpges package

Submodules

legendhpges.base module

class legendhpges.base.HPGe(metadata, name=None, registry=None, material=None)

Bases: ABC, LogicalVolume

An High-Purity Germanium detector.

Parameters:

  • metadata (str | dict | AttrsDict) – LEGEND HPGe configuration metadata file name describing the detector shape.

  • name (str | None) – name to attach to this detector. Used to name solid and logical volume.

  • registry (geant4.Registry | None) – pyg4ometry Geant4 registry instance.

  • material (geant4.Material | None) – pyg4ometry Geant4 material for the detector.

_abc_impl = <_abc._abc_data object>
abstract _decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

Must be overloaded by derived classes.

_g4_solid()

Build a pyg4ometry.solid.GenericPolycone instance from the (r, z) information.

Returns:

An object of a derived from pyg4ometry.geant4.solid.SolidBase to be used to construct the logical volume.

Return type:

SolidBase

Note

Detectors with a special geometry can have this method overridden in their class definition.

distance_to_surface(coords, surface_indices=None, tol=1e-11, signed=False)

Compute the distance of a set of points to the nearest detector surface.

Parameters:

  • coords (ArrayLike) – 2D array of shape (n,3) of (x,y,z) coordinates for each of n points, second index corresponds to (x,y,z).

  • surface_indices (ArrayLike | None) – list of indices of surfaces to consider. If None (the default) all surfaces used.

  • tol (float) – distance outside the surface which is considered inside. Should be on the order of numerical precision of the floating point representation.

  • signed (bool) – whether to return signed distanced (inside the HPGe is positive, outside is negative).

Return type:

NDArray

Note

  • Only implemented for solids based on geant4.solid.GenericPolycone

  • Coordinates should be relative to the origin of the polycone.

get_profile()

Get the profile of the HPGe detector.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

For V02160A and P00664A the detector profile is that of the solid without cut.

is_inside(coords, tol=1e-11)

Compute whether each point is inside the volume.

Parameters:

  • coords (ArrayLike) – 2D array of shape (n,3) of (x,y,z) coordinates for each of n points, second index corresponds to (x,y,z).

  • tol (float) – distance outside the surface which is considered inside. Should be on the order of numerical precision of the floating point representation.

Return type:

NDArray[bool]

property mass: Quantity

Mass of the HPGe.

surface_area(surface_indices=None)

Surface area of the HPGe.

If a list of surface_indices is provided the area is computed only considering these surfaces, from \(r_i\) to \(r_{i+1}\) and \(z_i\) to \(z_{i+1}\). Else the full area is computed.

Parameters:

surface_indices (ArrayLike | None) – list of indices or None.

Return type:

NDArray[Quantity]

Note

Calculation is based on a polycone geometry so is incorrect for asymmetric detectors.

property volume: Quantity

Volume of the HPGe.

legendhpges.bege module

class legendhpges.bege.BEGe(metadata, name=None, registry=None, material=None)

Bases: HPGe

A broad-energy germanium detector.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Note

Must be overloaded by derived classes.

legendhpges.build_utils module

legendhpges.build_utils.make_pplus(geometry)

Make the pplus contact for BeGe and some ICPC.

Methods to avoid duplicating code.

Parameters:

geometry (Mapping) – dictionary with the geometry information.

Returns:

Tuple (r,z,surfaces) of lists of r,z coordinates and surface names.

Return type:

tuple[list, list, list]

legendhpges.draw module

legendhpges.draw.plot_profile(hpge, axes=None, split_by_type=False, **kwargs)

Plot the HPGe profile with matplotlib.

Parameters:

  • hpge (HPGe) – detector.

  • axes (Axes | None) – pre-existing axes where the profile will be plotted.

  • split_by_type (bool) – boolean to separate surfaces of different types.

  • **kwargs – any keyword argument supported by matplotlib.pyplot.plot().

Return type:

tuple[Figure, Axes]

legendhpges.draw.visualize(hpge, viewer=None)

Visualize the HPGe with pyg4ometry.visualisation.VtkViewer.

Parameters:

  • viewer (VtkViewer | None) – pre-existing VTK viewer.

  • hpge (HPGe)

Return type:

VtkViewer

legendhpges.invcoax module

class legendhpges.invcoax.InvertedCoax(*args, **kwargs)

Bases: HPGe

An inverted-coaxial point contact germanium detector.

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

Must be overloaded by derived classes.

is_inside_borehole(coords, tol=1e-11)

Check if a point is inside the ICPC borehole

Parameters:

  • coords (ArrayLike) – 2D array of shape (n,3) of (x,y,z) coordinates for each of n points, second index corresponds to (x,y,z).

  • tol (float) – distance outside the surface which is considered inside. Should be on the order of numerical precision of the floating point representation.

Return type:

NDArray

legendhpges.make_hpge module

legendhpges.make_hpge.make_hpge(metadata, registry, allow_cylindrical_asymmetry=True, **kwargs)

Construct an HPGe detector logical volume based on the detector metadata.

Parameters:

  • metadata (str | dict | AttrsDict) – LEGEND HPGe configuration metadata file containing detector static properties.

  • registry (Registry | None) – pyg4ometry Geant4 registry instance.

  • allow_cylindrical_asymmetry (bool) – if true, use derived classes for detectors that break cylindrical symmetry. Otherwise, just build them using the base class (i.e. ignoring the non-symmetric features).

  • **kwargs –

    Additionally, the following arguments are allowed for overriding the name and the material from the metadata:

    name

    name to attach to the detector. Used to name solid and logical volume.

    material

    pyg4ometry Geant4 material for the detector.

Return type:

LogicalVolume

Examples

>>> gedet = make_hpge(metadata, registry)

>>> gedet = make_hpge(metadata, registry, name = "my_det", material = my_material)

legendhpges.materials module

LEGEND HPGe material descriptions for use in geometries.

legendhpges.materials._make_ge_isotopes(registry)
Parameters:

registry (Registry | None)

Return type:

dict[int, Callable[[], Isotope]]

legendhpges.materials._make_germanium(ge_name, el_symbol, iso_fracs, density, reg)
Parameters:
Return type:

Material

legendhpges.materials._number_density_meas()

Calculate the measured number density of germanium.

At room temperature, starting from the measured mass density of natural germanium.

Return type:

Quantity

legendhpges.materials._number_density_theo()

Calculate the theoretical number density of germanium.

At room temperature, starting from the measured atomic radius.

Return type:

Quantity

legendhpges.materials.enriched_germanium_density(ge76_fraction=0.92)

Calculate the density of enriched germanium.

Starting from the measured density of natural germanium at room temperature.

Parameters:

ge76_fraction (float) – fraction of Ge76 atoms.

Return type:

Quantity

legendhpges.materials.ge_iso_a: dict = {70: 69.924, 72: 71.922, 73: 72.923, 74: 73.921, 76: 75.921}

Molar weight of Germanium isotopes.

Source: NIST.

legendhpges.materials.make_enriched_germanium(ge76_fraction=0.92, registry=None)

Enriched germanium material builder.

Note

The isotopic composition is approximated as a mixture of Ge76 and Ge74.

Parameters:

  • ge76_fraction (float) – fraction of Ge76 atoms.

  • registry (Registry | None)

Return type:

Material

legendhpges.materials.make_natural_germanium(registry=None)

Natural germanium material builder.

Parameters:

registry (Registry | None)

Return type:

Material

legendhpges.materials.natge_density_meas: Quantity = <Quantity(5.3234, 'gram / centimeter ** 3')>

Measured density of natural germanium at room temperature.

legendhpges.materials.natge_isotopes: dict = {70: 0.2057, 72: 0.2745, 73: 0.0775, 74: 0.365, 76: 0.0773}

Isotopic composition of natural germanium.

Source: NIST.

legendhpges.p00664b module

class legendhpges.p00664b.P00664B(metadata, name=None, registry=None, material=None)

Bases: HPGe

A p-type point contact germanium detector P00664B with a special detector geometry.

Note

The normal vector of the cut plane is in the positive x-direction.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Note

Must be overloaded by derived classes.

_g4_solid()

Build a pyg4ometry.solid.GenericPolycone instance from the (r, z) information.

Returns:

An object of a derived from pyg4ometry.geant4.solid.SolidBase to be used to construct the logical volume.

Note

Detectors with a special geometry can have this method overridden in their class definition.

property volume

Volume of the HPGe.

legendhpges.ppc module

class legendhpges.ppc.PPC(metadata, name=None, registry=None, material=None)

Bases: HPGe

A p-type point contact germanium detector.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Note

Must be overloaded by derived classes.

legendhpges.semicoax module

class legendhpges.semicoax.SemiCoax(metadata, name=None, registry=None, material=None)

Bases: HPGe

A semi-coaxial germanium detector.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Note

Must be overloaded by derived classes.

legendhpges.utils module

legendhpges.utils.convert_coords(coords)

Converts (x,y,z) coordinates into (r,z)

Parameters:

coords (ArrayLike) – numpy array of coordinates where the second index corresponds to (x,y,z) respectively

Returns:

numpy array of (r,z) coordinates for each point

Return type:

NDArray

legendhpges.utils.get_line_segments(r, z, surface_indices=None)

Extracts the line segments from a shape.

Parameters:

  • r (ArrayLike) – array or list of radial positions defining the polycone.

  • z (ArrayLike) – array or list of vertical positions defining the polycone.

  • surface_indices (ArrayLike | None) – list of integer indices of surfaces to consider. If None (the default) all surfaces used.

Returns:

  • tuple of (s1,s2) arrays describing the line segments, both s1 and

  • s2 have shape (n_segments,2) where the first axis represents thhe

  • segment and the second (r,z).

Return type:

tuple[NDArray, NDArray]

legendhpges.utils.iterate_segments(s1, s2, coords_rz, tol, signed)
legendhpges.utils.load_dict(fname, ftype=None)

Load a text file as a Python dict.

Parameters:

  • fname (str)

  • ftype (str | None)

Return type:

dict

legendhpges.utils.shortest_distance(s1_list, s2_list, points, tol=1e-11, signed=True)

Get the shortest distance between each point and a line segment.

Based on vector algebra where the distance vector is given by:

\[d = s_1 - p - ( (n · (s_1- p)) * n )\]

where:

  • \(s_1\) is a vector from which the distance is measured,

  • p is a point vector,

  • n is a unit direction vector from \(s_1\) to \(s_2\),

  • a is another point vector.

If the projection point lies inside the segment s1-s2. Else the closest point is either \(s_1\) or \(s_2\). The distance is the modulus of this vector and this calculation is performed for each point. A sign is attached based on the cross product of the line vector and the distance vector. To avoid numerical issues any point within the tolerance is considered inside.

Parameters:

  • s1_list (NDArray) – (n_segments,2) np.array of the first points in the line segment, for the second axis indices 0,1 correspond to r,z.

  • s2_list (NDArray) – second points, same format as s1_list.

  • points (NDArray) – (n_points,2) array of points to compare, first axis corresponds to the point index and the second to (r,z).

  • tol (float) – tolerance when computing sign, points within this distance to the surface are pushed inside.

  • signed (bool) – boolean flag to attach a sign to the distance (positive if inside).

Returns:

(n_points,n_segments) numpy array of the shortest distances for each segment.

Return type:

tuple[NDArray, NDArray]

legendhpges.utils.shortest_distance_to_plane(a_vec, d, points, rmax=None, zrange=None)

Get the shortest distance from a plane (constrained in r and z) to each point.

The equation of the plane is given by \(a_1x+a_2y+a_3z=d\). Where \(\vec{a}=(a_1,a_2,a_3)\). The closest point on the plane to the point (\(y\)) is then given by:

\[x =y-(y*a-d)*a/||a||^2\]

The distance is then given by the length of the vector \(x-y\). This function also checks if the intersection point is above rmax or inside the zrange, if not, numpy.nan is returned for that point.

Parameters:

  • a_vec (NDArray) – 3 coordinate array defining the plane.

  • d (float) – scalar in the plane definition.

  • points (NDArray) – set of points to compute distance.

  • rmax (float | None) – maximum radius for the plane.

  • zrange (tuple[float, float] | None) – range in z for the plane.

Return type:

NDArray

legendhpges.utils.shortest_grid_distance(points, s1, s2, axis, signed=True, sign_factor=1)

legendhpges.v02160a module

class legendhpges.v02160a.V02160A(metadata, name=None, registry=None, material=None)

Bases: HPGe

An inverted-coaxial point contact germanium detector V02160A with a special geometry.

Note

The center of the cut plane faces the positive x-direction with a certain angle with respect to xz-plane.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

Must be overloaded by derived classes.

_g4_solid()

Build a pyg4ometry.solid.GenericPolycone instance from the (r, z) information.

Returns:

An object of a derived from pyg4ometry.geant4.solid.SolidBase to be used to construct the logical volume.

Note

Detectors with a special geometry can have this method overridden in their class definition.

property volume

Volume of the HPGe.

legendhpges.v02162b module

class legendhpges.v02162b.V02162B(metadata, name=None, registry=None, material=None)

Bases: HPGe

An inverted-coaxial point contact germanium detector V02162B with a special detector geometry.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

Must be overloaded by derived classes.

legendhpges.v07646a module

class legendhpges.v07646a.V07646A(metadata, name=None, registry=None, material=None)

Bases: HPGe

An inverted-coaxial point contact germanium detector V07646A with a special geometry.

Parameters:

  • metadata (str | dict | AttrsDict)

  • name (str | None)

  • registry (geant4.Registry | None)

  • material (geant4.Material | None)

_abc_impl = <_abc._abc_data object>
_decode_polycone_coord()

Decode shape information from geometry dictionary into (r, z) coordinates.

Suitable for building a pyg4ometry.geant4.solid.GenericPolycone.

Returns:

two lists of r and z coordinates, respectively.

Return type:

tuple[list[float], list[float]]

Note

Must be overloaded by derived classes.