hexrec package

Subpackages

Submodules

hexrec.app module

Extension of app.py from hexsample

class hexrec.app.ArgumentParser(prog=None, usage=None, description=None)[source]

Bases: ArgumentParser

add_analysis_options()[source]

Add an option group for the analysis.

Return type:

None

add_eta_options()[source]

Add an option group for eta function analysis.

Return type:

None

add_line_source_options()[source]

Add an option group for line source properties.

Return type:

None

add_model_name()[source]
Return type:

None

add_neural_net_options()[source]

Add an option group for neural network

Return type:

None

add_nnet_recon_options()[source]

Add an option group for neural network reconstruction

Return type:

None

add_reconstruction_options()[source]

Add an option group for reconstruction.

Return type:

None

add_simple_readout_options()[source]

Add an option group for the readout properties.

Return type:

None

hexrec.clustering module

Extension of clustering.py from hexsample

class hexrec.clustering.Cluster(x, y, pha, pitch=None, gamma=None, model=None)[source]

Bases: Cluster

Overwritten class Cluster from hexsample

fitted_position()[source]

Return the reconstructed position of a two pixel cluster using the eta function fit

Return type:

Tuple[float, float]

nnet_position()[source]

Return the reconstructed position of a pixels cluster using a neural network model

Return type:

Tuple[float, float]

size()[source]

Return the size of the cluster, calculated as the number of pixels with charge greater than zero (overload the size function of hexsample because if NNet is used, size of x is always 7)

Return type:

int

property xdata

Return normalized input data for the neural network model.

class hexrec.clustering.ClusteringNN(grid, zero_sup_threshold, num_neighbors, pitch=None, gamma=None, model=None)[source]

Bases: ClusteringBase

Overwritten class ClusteringBase from hexsample to handle eta function and neural network event reconstruction

Parameters:

  • num_neighbors (int) – The number of neighbors (between 0 and 6) to include in the cluster.

  • putch (float = None) – The pitch of the hexagonal grid

  • gamma (float = None) – The index of the power law for eta function reconstruction

  • model (ModelBase = None) – Instance of ModelBase or any of its subclasses

gamma: float = None
model: ModelBase = None
num_neighbors: int
pitch: float = None
run(event)[source]

Overladed method.

Warning

The loop ever the neighbors might likely be vectorized and streamlined for speed using proper numpy array for the offset indexes.

Return type:

Cluster

hexrec.hexagon module

Extension of hexsample hexagon module

class hexrec.hexagon.HexagonalGrid(layout, num_cols, num_rows, pitch)[source]

Bases: HexagonalGrid

Extension of HexagonalGrid from hexsample

static create_rotator(theta)[source]

Create a 2D rotation function for a given angle

Parameters:

theta (float) – the rotation angle in radians

Returns:

function that takes 2D vectors and returns the vector rotated by theta radians

Return type:

function

find_vertices(col, row, i=0)[source]

Find the vertices of a triangular section of hexagons. The first section, corresponding to i=0, is the one which lies on the x-axis or intersects it, depending on the orientation of the hexagon. The sections are counted counter-clockwise.

Parameters:

  • col (np.array) – array with column pixel coordinates of hexagons

  • row (np.array) – array with row pixel coordinates of hexagons

  • i (int, optional) – triangular section. Defaults to 0.

Returns:

the first array are the (x, y) coordinates of the centers, the second and the third contain each the (x, y) coordinates of one of the other two vertices of the triangle

Return type:

Tuple[np.array, np.array, np.array]

hexrec.hist module

Extension of hist.py from hexsample

class hexrec.hist.Histogram2d(xbins, ybins, xlabel='', ylabel='', zlabel='Entries/bin')[source]

Bases: HistogramBase

Container class for two-dimensional histograms.

PLOT_OPTIONS = {'cmap': <matplotlib.colors.LinearSegmentedColormap object>}

hexrec.network module

Module to handle neural networks

class hexrec.network.GNNRegression[source]

Bases: Module

Defines the architecture of the default Graph Neural Network (GNN) regression model.

The model consists of two graph convolutional layers followed by two fully connected linear layers. It performs graph-level regression by applying global mean pooling after convolutional layers.

forward(x, edge_index, batch)[source]

Perform a forward pass through the network.

Applies two graph convolutional layers with ReLU activations, followed by global mean pooling, then two fully connected layers with ReLU activation before the final output layer.

class hexrec.network.ModelBase[source]

Bases: ABC

Abstract base class for the definition of a neural network model class. Subclasses must implement the core methods for saving and loading models, loading pretrained models, training and prediction.

This class cannot be instantiated directly.

abstractmethod classmethod load(path)[source]

Load the model from the given path.

This method must be implemented by all subclasses.

Parameters:

path (str) – The path to the model file to load.

Returns:

An instance of the loaded model.

Return type:

ModelBase

abstractmethod classmethod load_pretrained()[source]

Load the pre-trained model provided by the package.

This method must be implemented by all subclasses.

Returns:

An instance of the pre-trained model.

Return type:

ModelBase

abstractmethod predict(xdata)[source]

Generate predictions for the given input data.

This method must be implemented by all subclasses.

Parameters:

xdata (np.ndarray) – Input data for prediction.

Returns:

Predicted output data.

Return type:

np.ndarray

abstractmethod save(name)[source]

Save the model to the default “models” folder with the given name.

This method must be implemented by all subclasses.

Parameters:

name (str) – The name of the file to save the model as.

Returns:

The path to the saved model file.

Return type:

Path

abstractmethod train(xdata, ydata, epochs, val_split=0.2, **kwargs)[source]

Train the neural network model.

This method must be implemented by all subclasses.

Parameters:

  • xdata (np.ndarray) – Input training data.

  • ydata (np.ndarray) – Target training data.

  • epochs (int) – Number of training epochs.

  • val_split (float, optional) – Fraction of data to use for validation. Defaults to 0.2.

  • **kwargs – Additional keyword arguments for training configuration.

class hexrec.network.ModelDNN(model)[source]

Bases: ModelBase

Concrete implementation of a deep dense neural network model.

This class manages the saving, loading, training and prediction of a deep dense neural network according to the ModelBase interface.

classmethod load(path)[source]

Load the DNN model from the given path.

Parameters:

path (str) – The path to the model file to load.

Returns:

An instance of the ModelDNN with the loaded architecture.

Return type:

ModelDNN

classmethod load_pretrained()[source]

Load the pre-trained DNN model provided by the package.

Returns:

An instance of the pre-trained DNN model.

Return type:

ModelBase

model: Model
predict(xdata)[source]

Generate predictions for the given input data.

Parameters:

xdata (np.ndarray) – Input data for prediction.

Returns:

Predicted output data.

Return type:

np.ndarray

save(name)[source]

Save the DNN model to the default “models” folder with the given name.

Parameters:

name (str) – The name of the file to save the model as.

Returns:

The path to the saved model file.

Return type:

Path

train(xdata, ydata, epochs, val_split=0.2, **kwargs)[source]

Train the DNN model.

Parameters:

  • xdata (np.ndarray) – Input training data.

  • ydata (np.ndarray) – Target training data.

  • epochs (int) – Number of training epochs.

  • val_split (float, optional) – Fraction of data to use for validation. Defaults to 0.2.

  • **kwargs – Additional keyword arguments for training configuration.

class hexrec.network.ModelGNN(model)[source]

Bases: ModelBase

Concrete implementation of a graph neural network model.

This class manages the saving, loading, training and prediction of a graph neural network according to the ModelBase interface.

static data_loader(xdata, ydata=None, batch_size=16, **kwargs)[source]

Prepare data for training or prediction

Parameters:

  • xdata (np.ndarray) – data for training or prediction. Shape must be (7, 3) for single data, or (N, 7, 3) for multiple data

  • ydata (np.ndarray, optional) – data for training. Shape must be (2,) for single data or (N, 2) for multiple data

Returns:

data prepared for training and prediction

Return type:

DataLoader

static event_to_graph(xdata, ydata=None)[source]

Convert event data to a graph of PyTorch Geometric

Parameters:

  • pha (np.ndarray) – normalized pha array with values of all of the 7 pixels

  • x (np.ndarray) – normalized x-position of all of the 7 pixels

  • y (np.ndarray) – normalized y-position of all of the 7 pixels

Returns:

graph of the event

Return type:

Data

load(path)[source]

Load the GNN model from the given path.

Parameters:

path (str) – The path to the model file to load.

Return type:

None

classmethod load_pretrained()[source]

Load the pre-trained GNN model provided by the package.

Returns:

An instance of the pre-trained GNN model.

Return type:

ModelGNN

model: Module
plot_history()[source]

Plot history of loss and val_loss metrics over training epochs

Return type:

None

predict(xdata)[source]

Generate predictions for the given input data.

Parameters:

xdata (np.ndarray) – Input data for prediction.

Returns:

Predicted output data.

Return type:

np.ndarray

save(name)[source]

Save the GNN model to the default “models” folder with the given name.

Parameters:

name (str) – The name of the file to save the model as.

Returns:

The path to the saved model file.

Return type:

Path

train(xdata, ydata, epochs, val_split=0.2, **kwargs)[source]

Train the GNN model.

Parameters:

  • xdata (np.ndarray) – Input training data.

  • ydata (np.ndarray) – Target training data.

  • epochs (int) – Number of training epochs.

  • val_split (float, optional) – Fraction of data to use for validation. Defaults to 0.2.

  • **kwargs – Additional keyword arguments for training configuration.

Return type:

None

hexrec.recon module

Extension of recon.py from hexsample

class hexrec.recon.ReconEventFitted(trigger_id, timestamp, livetime, cluster)[source]

Bases: object

Descriptor for a reconstructed event with only two pixels.

Parameters:

  • trigger_id (int) – The trigger identifier.

  • timestamp (float) – The timestamp (in s) of the event.

  • livetime (int) – The livetime (in us) since the last event.

  • cluster (Cluster) – The reconstructed cluster for the event.

cluster: Cluster
energy(ionization_potential=3.68)[source]

Return the energy of the event in eV.

Warning

This is currently using the ionization energy of Silicon to do the conversion, assuming a detector gain of 1. We will need to do some bookkeeping, here, to make this work reliably.

Return type:

float

livetime: int
position()[source]

Return the reconstructed position of the event.

Return type:

Tuple[float, float]

timestamp: float
trigger_id: int
class hexrec.recon.ReconEventNNet(trigger_id, timestamp, livetime, cluster)[source]

Bases: object

Descriptor for a reconstructed event with only two pixels.

Parameters:

  • trigger_id (int) – The trigger identifier.

  • timestamp (float) – The timestamp (in s) of the event.

  • livetime (int) – The livetime (in us) since the last event.

  • cluster (Cluster) – The reconstructed cluster for the event.

cluster: Cluster
energy(ionization_potential=3.68)[source]

Return the energy of the event in eV.

Warning

This is currently using the ionization energy of Silicon to do the conversion, assuming a detector gain of 1. We will need to do some bookkeeping, here, to make this work reliably.

Return type:

float

livetime: int
position()[source]

Return the reconstructed position of the event.

Return type:

Tuple[float, float]

timestamp: float
trigger_id: int

hexrec.source module

Extension of Source class from hexsample

class hexrec.source.HexagonalBeam(x0=0.0, y0=0.0, v0=(0, 0), v1=(0, 0))[source]

Bases: BeamBase

Triangular X-ray beam inside an hexagon

Parameters:

  • x0 (float) – The x-coordinate of the center of the hexagon in cm.

  • y0 (float) – The y-coordinate of the center of the hexagon in cm.

  • v0 (np.ndarray) – The (x, y) coordinates of the first vertex of the hexagon in cm.

  • v1 (np.ndarray) – The (x, y) coordinates of the second vertex of the hexagon in cm.

rvs(size=1)[source]

Overloaded method.

Parameters:

size (int) – The number of X-ray photon positions to be generated.

Returns:

x, y – The photon positions on the x-y plane.

Return type:

2-element tuple of np.ndarray of shape size

v0: tuple = (0, 0)
v1: tuple = (0, 0)
class hexrec.source.Line(energy)[source]

Bases: SpectrumBase

Class describing a monochromatic emission line at a given energy

plot()[source]

Plot the monochromatic line

Return type:

None

rvs(size=1)[source]
Parameters:

  • size (int, optional) – The number of X-ray photon energies to be generated.

  • 1. (Defaults to)

Returns:

The photon energies in eV.

Return type:

energy (np.ndarray)

class hexrec.source.TriangularBeam(x0=0.0, y0=0.0, v0=(0, 0), v1=(0, 0))[source]

Bases: BeamBase

Triangular X-ray beam inside an hexagon

Parameters:

  • x0 (float) – The x-coordinate of the center of the hexagon in cm.

  • y0 (float) – The y-coordinate of the center of the hexagon in cm.

  • v0 (np.ndarray) – The (x, y) coordinates of the first vertex of the hexagon in cm.

  • v1 (np.ndarray) – The (x, y) coordinates of the second vertex of the hexagon in cm.

rvs(size=1)[source]

Overloaded method.

Parameters:

size (int) – The number of X-ray photon positions to be generated.

Returns:

x, y – The photon positions on the x-y plane.

Return type:

2-element tuple of np.ndarray of shape size

v0: tuple = (0, 0)
v1: tuple = (0, 0)

Module contents

Init constructor for package