e15190.neutron_wall.geometry.Bar

class e15190.neutron_wall.geometry.Bar(vertices, contain_pyrex=True)

Functions

__init__(vertices[, contain_pyrex])

Construct a Neutron Wall bar, either from Wall A or Wall B.

add_pyrex()

Add Pyrex thickness to the bar.

construct_plotly_mesh3d()

Update bar's attribute self.triangle_mesh.

dimension([index])

Returns the dimension(s) of the bar.

draw_hit_pattern2d(hits, ax[, frame, ...])

Draw the hit pattern of the bar with 2D histogram.

get_empirical_distance_bounds([n_pts, n_iters])

Returns the empirical bounds of the relation between local x and distance.

get_geometry_efficiency_alphashape(delta, alpha)

Calculate the geometry efficiency of the bar using the alphashape.

get_hit_positions([hit_t, frame, ...])

Return the hit positions of the simulation.

get_theta_phi_alphashape(delta, alpha[, cut])

Calculate the alphashape of the bar in (theta, phi) coordinates.

get_total_solid_angle([method])

Return the total solid angle of the bar.

get_total_solid_angle_alphashape(delta, alpha)

Calculate the total solid angle of the bar using the alphashape.

get_total_solid_angle_monte_carlo([n_rays, ...])

Calculate the total solid angle of the bar by Monte Carlo simulation.

is_inside(coordinates[, frame, tol])

Check if the given coordinates are inside the bar.

randomize_from_local_x(local_x[, ...])

Returns randomized point(s) from the given local x coordinate(s).

remove_pyrex()

Remove Pyrex thickness from the bar.

simple_simulation([n_rays, random_seed, ...])

A simple ray simulation on the bar.

to_lab_coordinates(local_coordinates)

Converts coordinates from local frame to lab frame.

to_local_coordinates(lab_coordinates)

Converts coordinates from lab frame to local frame.

Properties

edges_x

height

Height of the bar.

left_shadow_x

length

Length of the bar.

right_shadow_x

shadowed_bars

thickness

Longitudinal thickness of the bar.

contain_pyrex

Status of Pyrex thickness

pyrex_thickness

The thickness of the Pyrex (unit cm)

__init__(vertices, contain_pyrex=True)

Construct a Neutron Wall bar, either from Wall A or Wall B.

This class only deals with individual bar. The Neutron Wall object is implemented in :py:class`Wall`.

Parameters

vertices (ndarray of shape (8, 3)) – Exactly eight (x, y, z) lab coordinates measured in centimeter (cm). As long as all eight vertices are distinct, i.e. can properly define a cuboid, the order of vertices does not matter because PCA will be applied to automatically identify the 1st, 2nd and 3rd principal axes of the bar, which, for Neutron Wall bar, corresponds to the x, y and z directions in the local (bar) coordinate system.

contain_pyrex

Status of Pyrex thickness

Type

bool

pyrex_thickness

The thickness of the Pyrex (unit cm)

Should be 0.125 inches or 0.3175 cm.

Type

float

property length: float

Length of the bar.

Should be around 76 inches without Pyrex.

property height: float

Height of the bar.

Should be around 3.0 inches without Pyrex.

property thickness: float

Longitudinal thickness of the bar.

Should be around 2.5 inches without Pyrex.

_modify_pyrex(mode)

To add or remove Pyrex thickness.

Parameters

mode ('add' or 'remove') –

If ‘add’, the Pyrex thickness will be added to the bar; if ‘remove’, the Pyrex thickness will be removed from the bar.

An Exception will be raised if bar is already in the desired state.

remove_pyrex()

Remove Pyrex thickness from the bar.

add_pyrex()

Add Pyrex thickness to the bar.

randomize_from_local_x(local_x, return_frame='lab', local_ynorm: float | tuple[float, float] = (- 0.5, 0.5), local_znorm: float | tuple[float, float] = (- 0.5, 0.5), random_seed: Optional[int] = None)

Returns randomized point(s) from the given local x coordinate(s).

This is useful for getting a uniform hit distribution within the bulk of the bar. Experimentally, we can only determine the local x coordinate for each hit.

Parameters
  • local_x (float or list of floats) – The local x coordinate(s) of the point(s) in centimeters.

  • return_frame ('lab' or 'local', default 'lab') – The frame of the returned point(s) in Cartesian coordinates.

  • local_ynorm (float or 2-tuple of floats, default (-0.5, 0.5)) – The range of randomization in the local y coordinate. If float, no randomization is performed. Center is at 0.0; the top surface is +0.5; the bottom surface is -0.5. Values outside this range will still be calculated, but those points will be outside the bar.

  • local_znorm (float or 2-tuple of floats, default (-0.5, 0.5)) – The range of randomization in the local z coordinate. If float, no randomization is performed. Center is at 0.0; the front surface is +0.5; the back surface is -0.5. Values outside this range will still be calculated, but those points will be outside the bar.

  • random_seed (int, default None) – The random seed to be used. If None, randomization is non-reproducible.

Returns

randomized_coordinates – The randomized point(s) in Cartesian coordinates.

Return type

3-tuple or list of 3-tuples

get_empirical_distance_bounds(n_pts=50000, n_iters=6)

Returns the empirical bounds of the relation between local x and distance.

Parameters
  • n_pts (int, default 50_000) – The number of points to be used for the empirical calculation.

  • n_iters (int, default 6) – The number of iterations to be used to refine the bounds.

Returns

  • fit_low (np.array of size 3) – The coefficients of the lower bound quadratic fit.

  • fit_high (np.array of size 3) – The coefficients of the upper bound quadratic fit.

static _deco_numpy_ndim(func)

Decorator for preserving numpy array’s dimensionality.

Some functions only accepts 2D arrays, i.e. rows of 1D arrays, and perform some row-wise operations. To apply this kind of functions on 1D arrays, we may use this decorator. The decorated functions can take in either a 2D array or a 1D array. If the input is a 2D array, the output will be a 2D array; if the input is a 1D array, the output will be kept as a 1D array.

Parameters

func (function) – The function to decorate.

Returns

func – The decorated function.

Return type

function

Example

>>> f = lambda X: np.array([np.square(x) for x in X])
>>> from e15190.utilities import geometry as geom
>>> deco_f = geom.RectangularBar._deco_numpy_ndim(f)
>>> deco_f(np.array([[1, 2, 3], [4, 5, 6]]))
np.array([[1, 4, 9], [16, 25, 36]])
>>> deco_f(np.array([1, 2, 3]))
np.array([1, 4, 9])
static _get_vertices_dict(loc_vertices, vertices)

Convert both dictionaries into mappings from egocentric directions onto vertices.

A rectangular bar has eight vertices. To distinguish the vertices, we use 3-tuples of -1 and +1 to indicate the directions in local (bar) frame. For example, (-1, +1, -1) implies the vertex, when observed in the local frame, is in the negative x direction, positive y direction, and negative z direction. Each vertex’s coordinates would be stored as numpy array of length 3, representing \((x, y, z)\).

Parameters
  • loc_vertices (array-like of shape (8, 3)) –

    The local vertices of the bar, e.g. vertex coordinates in the bar frame. This array will be used to determine the egocentric directions. It is user’s responsibility to ensure that the eight coordinates form a cuboid whose center is at the origin and the edges are all parallel to one of the x, y or z axes.

    This can usually be done easily by applying the to_local_coordinates() function to vertices. Under the hood, PCA is applied to identify the three principal axes of the bar.

  • vertices (array-like of shape (8, 3)) – The vertices in the lab frame. The order of vertices must match the order of loc_vertices.

Returns

  • loc_vertices_dict (dict) – A dictionary of {(i, j, k): (x', y', z')}, where \((x', y', k')\) are the points in loc_vertices.

  • vertices_dict (dict) – A dictionary of {(i, j, k): (x, y, z)}, where \((x, y, z)\) are the points in vertices.

_make_vertices_dict()

Convert self local vertices and vertices into dictionaries.

Simply apply _get_vertices_dict() to update both self.loc_vertices and self.vertices.

static _split_theta_phi_alphashape_to_upper_and_lower(ashape)

Split the alphashape into upper and lower parts.

After splitting, both parts should form a function of theta. This is a function written mainly to help calculating the azimuthal width \(\delta\phi\) as a function of theta, which then is used to give the geometry efficiency.

Parameters

ashape (ndarray, shape (n, 2)) – Vertices that define the alphashape in (theta, phi) coordinates.

Returns

split_ashape – The upper and lower parts of the alphashape. The keys are ‘upper’ and ‘lower’, the values are ndarrays of shape (n, 2).

Return type

dict

construct_plotly_mesh3d() → None

Update bar’s attribute self.triangle_mesh.

Construct a TriangleMesh object, i.e. a triangular mesh for the geometry of the bar, and save as self.triangle_mesh.

dimension(index: Optional[int] = None) → float | tuple[float, float, float]

Returns the dimension(s) of the bar.

Parameters

index (int, default None) – The index of the direction. If None, all three dimensions will be returned. Indices 1, 2 and 3 correspond to the x, y and z in the local (bar) frame.

Returns

dimension – The dimension(s) of the bar.

Return type

float or 3-tuple of floats

draw_hit_pattern2d(hits, ax, frame='lab', coordinate='spherical', cartesian_coordinates=('x', 'y'), cmap='jet')

Draw the hit pattern of the bar with 2D histogram.

Parameters
  • hits (ndarray, shape (n, 3)) – The hits to draw.

  • ax (matplotlib.axes.Axes) – The axes to draw the hits on.

  • frame ('lab' or 'local') – The frame of reference to use for the hits.

  • coordinate ('spherical' or 'cartesian') – The coordinate system to use for the hits.

  • cartesian_coordinates (tuple of str) – The Cartesian coordinates to use for the hits. If coordinate is not ‘cartesian’, this argument has no effect.

  • cmap (str or matplotlib.colors.Colormap) – The colormap to use for plotting the hits in 2D histogram.

Returns

hist – The histogram counts of the hits.

Return type

2D ndarray

get_geometry_efficiency_alphashape(delta, alpha, cut=None) → tuple[typing.Callable, typing.Callable]

Calculate the geometry efficiency of the bar using the alphashape.

The geometry efficiency is defined as the effective azimuthal coverage ratio, i.e. \(\delta\phi/(2\pi)\), as a function of theta.

Parameters

cut (str or list of str, default None) –

Cut to apply to the dataframe of the bar. Available variables include ‘x’, ‘y’ and ‘z’ in local frame. If None, no cut is applied.

Users should make sure that the every cut string must only split the geometry of the bar into one volume, so cut like (-10 < x & x < 10) is okay, but (-10 < x & x < 10) & (15 < x & x < 25) is not because there is a gap from x = 10 to x = 15, resulting in two unconnected volumes. To apply cuts that result in multiple volumes, supply a list of cuts instead. So cut = ['(-10 < x & x < 10)', '(15 < x & x < 25)'] would be okay.

Returns

delta_phi – A function that takes theta (radian) as an argument and returns the geometry efficiency.

Return type

callable

get_hit_positions(hit_t='uniform', frame='local', coordinate='cartesian', simulation_result=None, random_seed=None, tol=1e-09)

Return the hit positions of the simulation.

This function should be called after self.simulation_result is updated, e.g. by calling simple_simulation.

Parameters
  • hit_t (scalar or callable or 'uniform', default 'uniform') – If scalar, its value should be within [0, 1], with 0 being at the incident point at the surface, 1 being at the exit point, and the rest being somewhere in between. If callable, it should take in an integer n_rays, and return an array of size n_rays that collect the hit_t values in the range of [0, 1]. If ‘uniform’, the hit_t values will be uniformly distributed over [0, 1].

  • frame ('local' or 'lab', default 'local') – The coordinate frame of the returned hit positions.

  • coordinate ('cartesian' or 'spherical', default 'cartesian') – The coordinate system of the returned hit positions.

  • simulation_result (dict, default None) – The simulation result to be used. If None, the function uses self.simulation_result.

  • random_seed (int, default None) – The random seed used to generate the hit_t values. If None, a time-based seed will be used, i.e. non-reproducible.

  • tol (float, default 1e-9) – The tolerance used to filter out hit points that are too close to the origin, i.e. there were no intersections. The default simulation setting is such that if there were no intersections, the hit position will be the origin. Here, we simply put in a non-zero tolerance to account for any floating point errors.

Returns

hit_positions – The hit positions of the simulation.

Return type

ndarray, shape (n_rays, 3)

get_theta_phi_alphashape(delta, alpha, cut=None)

Calculate the alphashape of the bar in (theta, phi) coordinates.

Parameters
  • delta (int or array of size 3) – Grid spacing in cm.

  • alpha (float) – The alphashape parameter. The larger the value, the greater the curvature of the alphashape can be. When alpha is zero, the alphashape reduces into a convex hull; when alpha is too large, the alphashape could be “overfitted” to data points.

  • cut (str, default None) – The cut of the alphashape. Available variables include ‘x’, ‘y’ and ‘z’ in local frame. If None, no cut will be applied.

Returns

alpha_shape_xy – Vertices that define the alphashape in (theta, phi) coordinates.

Return type

ndarray, shape (n, 2)

get_total_solid_angle(method='alphashape', **kwargs)

Return the total solid angle of the bar.

A wrapper function for the different methods of calculating the total solid angle.

Parameters
  • method ('alphashape' or 'monte_carlo') – The method to use to calculate the total solid angle.

  • kwargs (dict()) – Keyword arguments to pass to the method.

Returns

total_solid_angle – The total solid angle of the bar in steradians.

Return type

float

get_total_solid_angle_alphashape(delta, alpha, return_error=False)

Calculate the total solid angle of the bar using the alphashape.

Parameters

return_error (bool, default False) – Whether to return the error (uncertainty) of the calculation.

Returns

  • total_solid_angle (float) – The total solid angle of the bar in steradians.

  • error (float, optional) – The uncertainty of the calculation. Only returned if return_error is True.

get_total_solid_angle_monte_carlo(n_rays=5000000, random_seed=None, return_error=False, verbose=False)

Calculate the total solid angle of the bar by Monte Carlo simulation.

Parameters
  • n_rays (int, default 5_000_000) – The number of rays to simulate.

  • random_seed (int, default None) – The random seed of the Monte Carlo simulation. If None, a time-based seed will be used, i.e. non-reproducible.

  • return_error (bool, default False) – Whether to return the error (uncertainty) of the calculation.

  • verbose (bool, default False) – Whether to print out the progress of the calculation.

Returns

  • total_solid_angle (float) – The total solid angle of the bar in steradians.

  • error (float, optional) – The uncertainty of the calculation. Only returned if return_error is True.

is_inside(coordinates, frame='lab', tol=0.0005)

Check if the given coordinates are inside the bar.

Parameters
  • coordinates (array of shape (N, 3) or (3, )) – The coordinates to be checked. Only support Cartesian coordinates.

  • frame ('local' or 'lab', default 'lab') – The frame of the coordinates.

  • tol (float, default 5e-4) – The tolerance of the boundary check.

Returns

inside – True if the coordinates are inside the bar, otherwise False.

Return type

bool or an array of bool

simple_simulation(n_rays=10, random_seed=None, polar_range=None, azimuth_range=None, save_result=True)

A simple ray simulation on the bar.

Simple simulation means that there is no scattering, reflection, refraction, or any other actual physics consideration. Instead, we are only calculating geometrical intersections of random rays with the bar geometry.

By default, this function would first identify the smallest rectangular region in the (theta, phi) space that fully contains the entire bar geometry. Then, it would randomly emit rays toward this minimal region. Both theta range and phi range will be saved, so that user can calculate the actual solid angle later on.

Parameters
  • n_rays (int, default 10) – Number of rays to be emitted. Not all of them are guaranteed to interact.

  • random_seed (int, default None) – Random seed to be used for random number generation. If None, a time-based seed will be used, i.e. non-reproducible.

  • polar_range (2-tuple of floats or None, default None) – The polar range in radians. If None, the algorithm will use the minimal range determined by the bar vertices. This allows more efficient simulation.

  • azimuth_range (2-tuple of floats or None, default None) – The azimuth range in radians. If None, the algorithm will use the minimal range determined by the bar vertices. This allows more efficient simulation.

  • save_result (bool, default True) – Whether to save the result to this object as self.simulation_result.

Returns

simulation_result –

A dictionary with the following keys and array shapes:
  • origin : shape (3, )

  • azimuth_range : shape (2, )

  • polar_range : shape (2, )

  • intersections : shape (12, n_rays, 3)

The first component of intersections has a size of 12, which comes from the 12 triangles that made up the rectangular bar (triangle mesh). Other functions like get_hit_positions() can be used to further simplify the intersection points.

Return type

dict

to_lab_coordinates(local_coordinates)

Converts coordinates from local frame to lab frame.

Always assume Cartesian coordinates in both frames.

Parameters

local_coordinates ((N, 3) or (3, ) array_like) – The local coordinates \((x', y', z')\) to be converted.

Returns

lab_coordinates – The lab coordinates \((x, y, z)\).

Return type

(N, 3) or (3, ) array_like

to_local_coordinates(lab_coordinates)

Converts coordinates from lab frame to local frame.

Always assume Cartesian coordinates in both frames.

Parameters

lab_coordinates ((N, 3) or (3, ) array_like) – The lab coordinates \((x, y, z)\) to be converted.

Returns

local_coordinates – The local coordinates \((x', y', z')\).

Return type

(N, 3) or (3, ) array_like

vertices

The vertices of the bar in lab frame (unit cm)

A length-8 dictionary of the form {(i, j, k): (x, y, z)}

Type

dict

loc_vertices

The vertices of the bar in local frame (unit cm)

A length-8 dictionary of the form {(i, j, k): (x', y', z')}

Type

dict

pca

The PCA of the bar vertices in lab frame

Type

sklearn.decomposition.PCA