From 53b95a953c9eade14093af0593bbf0bc03e00e81 Mon Sep 17 00:00:00 2001
From: Tom Eichlersmith <31970302+tomeichlersmith@users.noreply.github.com>
Date: Tue, 23 Jan 2024 13:32:14 -0600
Subject: [PATCH] add notes on using libDetDescr with numpy

I figured this out since I was sick of doing the bit shifting myself. It is not as performant as the bit shifting but it works pretty well and avoids copying around magic numbers.
---
 DetDescr/README.md | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/DetDescr/README.md b/DetDescr/README.md
index 181416f8a..49c5d1b80 100644
--- a/DetDescr/README.md
+++ b/DetDescr/README.md
@@ -1,7 +1,7 @@
 # Accessing DetectorIDs from Python 
 
 <p align="center">
-    <img src="https://github.com/LDMX-Software/ldmx-software.github.io/blob/trunk/img/ldmx_logo_dark.png" width="500">
+    <img src="https://github.com/LDMX-Software/ldmx-software.github.io/blob/trunk/src/img/ldmx_logo_dark.png" width="500">
 </p>
 
 ## Building DetDescr with DetectorID binding support 
@@ -50,9 +50,28 @@ HcalDigiID [raw, section, layer, strip, end]  (411042050, 0, 1, 2, 0)
         ->HcalID [raw, section, layer, strip] (402654210, 0, 1, 2)
 ```
 
-## Getting documentation from within a Python session
-``` python
+### Usage with `numpy`
+Many python-based analyses use `numpy` or `numpy`-like libraries (e.g. `pandas` and `awkward`) which
+"vectorize" the operation of applying the same function to all of the elements of an array. We can do
+the same thing here in order to leverage the translation of raw ID numbers (which are stored in the data files)
+into different detector information. Below is an example of using this class to extract the layer index
+for each raw id.
+```python
+from libDetDescr import EcalID
+import numpy as np
+@np.vectorize
+def to_layer(rawid):
+    return EcalID(int(rawid)).layer()
+# id is a np.array of raw ID numbers e.g. read in from the EcalSimHits_test.id_ branch of LDMX_Events
+layer = to_layer(id)
 ```
+This isn't very performant on larger arrays; however, it does allow the user to use some internal
+optimizations that NumPy has and avoid a raw python `for` loop. We could look at incorporating
+numpy into our Python bindings
+(via [Boost.Python NumPy](https://live.boost.org/doc/libs/1_65_1/libs/python/doc/html/numpy/index.html))
+to make this as performant as possible.
+
+## Getting documentation from within a Python session
 
 Boost.Python will automatically generate some documentation for each kind of
 DetectorID that you can access through the built-in help system in Python.