Skip to content

pybes3.detectors

Parsing methods

parse_mdc_gid(gid, with_pos=True)

Parse the gid of MDC wires. "gid" is the global ID of the wire, ranges from 0 to 6795. When gid is an ak.Array, the result is an ak.Array, otherwise it is a dict.

Keys of the output:

  • gid: Global ID of the wire.
  • layer: Layer number.
  • wire: Local wire number.
  • stereo: Stereo type. 0 for axial, -1 for phi_west < phi_east, 1 for phi_west > phi_east.
  • is_stereo: Whether the wire is a stereo wire.
  • superlayer: Superlayer number.

Optional keys of the output when with_pos is True:

  • mid_x: x position of the wire at z=0.
  • mid_y: y position of the wire at z=0.
  • west_x: x position of the west end of the wire.
  • west_y: y position of the west end of the wire.
  • west_z: z position of the west end of the wire.
  • east_x: x position of the east end of the wire.
  • east_y: y position of the east end of the wire.
  • east_z: z position of the east end of the wire.

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required
with_pos bool

Whether to include the position information.

 True

Returns:

Type Description
Union[IntLike, dict[str, IntLike]]

The parsed result.
Source code in src/pybes3/detectors/__init__.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def parse_mdc_gid(gid: IntLike, with_pos: bool = True) -> Union[IntLike, dict[str, IntLike]]:
    """
    Parse the gid of MDC wires. "gid" is the global ID of the wire, ranges from 0 to 6795.
    When `gid` is an `ak.Array`, the result is an `ak.Array`, otherwise it is a `dict`.

    Keys of the output:

    - `gid`: Global ID of the wire.
    - `layer`: Layer number.
    - `wire`: Local wire number.
    - `stereo`: Stereo type. 0 for axial, -1 for `phi_west < phi_east`, 1 for `phi_west > phi_east`.
    - `is_stereo`: Whether the wire is a stereo wire.
    - `superlayer`: Superlayer number.

    Optional keys of the output when `with_pos` is `True`:

    - `mid_x`: x position of the wire at `z=0`.
    - `mid_y`: y position of the wire at `z=0`.
    - `west_x`: x position of the west end of the wire.
    - `west_y`: y position of the west end of the wire.
    - `west_z`: z position of the west end of the wire.
    - `east_x`: x position of the east end of the wire.
    - `east_y`: y position of the east end of the wire.
    - `east_z`: z position of the east end of the wire.

    Parameters:
        gid: The gid of the wire.
        with_pos: Whether to include the position information.

    Returns:
        The parsed result.
    """
    layer = mdc_gid_to_layer(gid)
    wire = mdc_gid_to_wire(gid)

    res = {
        "gid": gid,
        "layer": layer,
        "wire": wire,
        "stereo": mdc_gid_to_stereo(gid),
        "is_stereo": mdc_gid_to_is_stereo(gid),
        "superlayer": mdc_gid_to_superlayer(gid),
    }

    if with_pos:
        west_x = mdc_gid_to_west_x(gid)
        west_y = mdc_gid_to_west_y(gid)
        east_x = mdc_gid_to_east_x(gid)
        east_y = mdc_gid_to_east_y(gid)
        res["mid_x"] = (west_x + east_x) / 2
        res["mid_y"] = (west_y + east_y) / 2
        res["west_x"] = west_x
        res["west_y"] = west_y
        res["west_z"] = mdc_gid_to_west_z(gid)
        res["east_x"] = east_x
        res["east_y"] = east_y
        res["east_z"] = mdc_gid_to_east_z(gid)

    if isinstance(gid, ak.Array):
        return ak.zip(res)
    else:
        return res

parse_mdc_digi_id(mdc_digi_id, with_pos=False)

Parse MDC digi ID.

When mdc_digi_id is an ak.Array, the result is an ak.Array, otherwise it is a dict.

Keys of the output:

  • gid: Global ID of the wire.
  • wire: Local wire number.
  • layer: Layer number.
  • stereo: Stereo type. 0 for axial, -1 for phi_west < phi_east, 1 for phi_west > phi_east.
  • is_stereo: Whether the wire is a stereo wire.
  • superlayer: Superlayer number.

Optional keys of the output when with_pos is True:

  • mid_x: x position of the wire at z=0.
  • mid_y: y position of the wire at z=0.
  • west_x: x position of the west end of the wire.
  • west_y: y position of the west end of the wire.
  • west_z: z position of the west end of the wire.
  • east_x: x position of the east end of the wire.
  • east_y: y position of the east end of the wire.
  • east_z: z position of the east end of the wire.

Parameters:

Name Type Description Default
mdc_digi_id IntLike

The MDC digi ID.

 required
with_pos bool

Whether to include the position information.

 False

Returns:

Type Description
Union[IntLike, dict[str, IntLike]]

The parsed result.
Source code in src/pybes3/detectors/__init__.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def parse_mdc_digi_id(
    mdc_digi_id: IntLike,
    with_pos: bool = False,
) -> Union[IntLike, dict[str, IntLike]]:
    """
    Parse MDC digi ID.

    When `mdc_digi_id` is an `ak.Array`, the result is an `ak.Array`, otherwise it is a `dict`.

    Keys of the output:

    - `gid`: Global ID of the wire.
    - `wire`: Local wire number.
    - `layer`: Layer number.
    - `stereo`: Stereo type. 0 for axial, -1 for `phi_west < phi_east`, 1 for `phi_west > phi_east`.
    - `is_stereo`: Whether the wire is a stereo wire.
    - `superlayer`: Superlayer number.

    Optional keys of the output when `with_pos` is `True`:

    - `mid_x`: x position of the wire at `z=0`.
    - `mid_y`: y position of the wire at `z=0`.
    - `west_x`: x position of the west end of the wire.
    - `west_y`: y position of the west end of the wire.
    - `west_z`: z position of the west end of the wire.
    - `east_x`: x position of the east end of the wire.
    - `east_y`: y position of the east end of the wire.
    - `east_z`: z position of the east end of the wire.

    Parameters:
        mdc_digi_id: The MDC digi ID.
        with_pos: Whether to include the position information.

    Returns:
        The parsed result.
    """
    wire = digi_id.mdc_id_to_wire(mdc_digi_id)
    layer = digi_id.mdc_id_to_layer(mdc_digi_id)
    gid = get_mdc_gid(layer, wire)
    return parse_mdc_gid(gid, with_pos)

parse_tof_digi_id(tof_digi_id, flat=False, library='ak')

Parse TOF digi ID. If library is ak, return ak.Record. If library is np, return dict[str, np.ndarray].

Available keys of the output:

  • part: The part number. 0,1,2 for scintillator endcap0, barrel, endcap1; 3,4 for MRPC endcap0, endcap1.
  • layer_or_module: The scintillator layer or MRPC module number, based on the part number.
  • phi_or_strip: The scintillator phi or MRPC strip ID, based on the part number.
  • end: The readout end ID.

The return value is based on the part number.

Rows where part < 3 are scintillator and layer_or_module represents layer number, phi_or_strip represents phi number.

Rows where part >= 3 are MRPC and layer_or_module represents module number, phi_or_strip represents strip ID.

Parameters:

Name Type Description Default
tof_digi_id IntLike

The TOF ID.

 required
flat bool

Whether to flatten the output.

 False
library Literal['ak', 'np']

The library to use as output.

 'ak'

Returns:

Type Description
Union[Record, dict[str, ndarray], dict[str, int_]]

The parsed TOF ID.
Source code in src/pybes3/detectors/__init__.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def parse_tof_digi_id(
    tof_digi_id: IntLike,
    flat: bool = False,
    library: Literal["ak", "np"] = "ak",
) -> Union[ak.Record, dict[str, np.ndarray], dict[str, np.int_]]:
    """
    Parse TOF digi ID.
    If `library` is `ak`, return `ak.Record`. If `library` is `np`, return `dict[str, np.ndarray]`.

    Available keys of the output:

    - `part`: The part number. `0,1,2` for scintillator endcap0, barrel, endcap1; `3,4` for MRPC endcap0, endcap1.
    - `layer_or_module`: The scintillator layer or MRPC module number, based on the part number.
    - `phi_or_strip`: The scintillator phi or MRPC strip ID, based on the part number.
    - `end`: The readout end ID.

    The return value is based on the part number.

    Rows where `part < 3` are scintillator and `layer_or_module` represents layer number, `phi_or_strip` represents phi number.

    Rows where `part >= 3` are MRPC and `layer_or_module` represents module number, `phi_or_strip` represents strip ID.

    Parameters:
        tof_digi_id: The TOF ID.
        flat: Whether to flatten the output.
        library: The library to use as output.

    Returns:
        The parsed TOF ID.

    """
    if library not in ["ak", "np"]:
        raise ValueError(f"Unsupported library: {library}")

    if flat and isinstance(tof_digi_id, ak.Array):
        tof_digi_id = ak.flatten(tof_digi_id)

    part = digi_id.tof_id_to_part(tof_digi_id)
    res = {
        "part": part,
        "layer_or_module": digi_id.tof_id_to_layer_or_module(tof_digi_id, part),
        "phi_or_strip": digi_id.tof_id_to_phi_or_strip(tof_digi_id, part),
        "end": digi_id.tof_id_to_end(tof_digi_id),
    }

    if library == "ak":
        return ak.zip(res)
    else:
        return res

parse_emc_digi_id(emc_digi_id, with_pos=False)

Parse EMC digi ID.

When emc_digi_id is an ak.Array, the result is an ak.Array, otherwise it is a dict.

Keys of the output:

  • gid: Global ID of the crystal.
  • part: Part number, 0 for endcap0, 1 for barrel, 2 for endcap1.
  • theta: Theta number.
  • phi: Phi number.

Optional keys of the output when with_pos is True:

  • front_center_x: x position of the front center of the crystal.
  • front_center_y: y position of the front center of the crystal.
  • front_center_z: z position of the front center of the crystal.
  • center_x: x position of the center of the crystal.
  • center_y: y position of the center of the crystal.
  • center_z: z position of the center of the crystal.

Info

The 8 points of the crystal will not be returned here. If you need the 8 points of the crystal, use emc_gid_to_point_x, emc_gid_to_point_y and emc_gid_to_point_z.

Parameters:

Name Type Description Default
emc_digi_id IntLike

The EMC digi ID.

 required
with_pos bool

Whether to include the position information.

 False

Returns:

Type Description
Union[IntLike, dict[str, IntLike]]

The parsed EMC digi ID.
Source code in src/pybes3/detectors/__init__.py 
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
def parse_emc_digi_id(
    emc_digi_id: IntLike,
    with_pos: bool = False,
) -> Union[IntLike, dict[str, IntLike]]:
    """
    Parse EMC digi ID.

    When `emc_digi_id` is an `ak.Array`, the result is an `ak.Array`, otherwise it is a `dict`.

    Keys of the output:

    - `gid`: Global ID of the crystal.
    - `part`: Part number, 0 for endcap0, 1 for barrel, 2 for endcap1.
    - `theta`: Theta number.
    - `phi`: Phi number.

    Optional keys of the output when `with_pos` is `True`:

    - `front_center_x`: x position of the front center of the crystal.
    - `front_center_y`: y position of the front center of the crystal.
    - `front_center_z`: z position of the front center of the crystal.
    - `center_x`: x position of the center of the crystal.
    - `center_y`: y position of the center of the crystal.
    - `center_z`: z position of the center of the crystal.

    !!! info
        The 8 points of the crystal will not be returned here.
        If you need the 8 points of the crystal, use `emc_gid_to_point_x`, `emc_gid_to_point_y`
        and `emc_gid_to_point_z`.

    Parameters:
        emc_digi_id: The EMC digi ID.
        with_pos: Whether to include the position information.

    Returns:
        The parsed EMC digi ID.

    """
    part = digi_id.emc_id_to_module(emc_digi_id)
    theta = digi_id.emc_id_to_theta(emc_digi_id)
    phi = digi_id.emc_id_to_phi(emc_digi_id)
    gid = get_emc_gid(part, theta, phi)
    return parse_emc_gid(gid, with_pos)

parse_muc_digi_id(muc_digi_id, flat=False, library='ak')

Parse MUC digi ID.

If library is ak, return ak.Record. If library is np, return dict[str, np.ndarray].

Available keys of the output:

  • part: The part number.
  • segment: The segment number.
  • layer: The layer number.
  • channel: The channel number.
  • gap: The gap number, which is equivalent to layer number.
  • strip: The strip number, which is equivalent to channel number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID.

 required
flat bool

Whether to flatten the output.

 False
library Literal['ak', 'np']

The library to use as output.

 'ak'

Returns:

Type Description
Union[Record, dict[str, ndarray], dict[str, int_]]

The parsed MUC digi ID.
Source code in src/pybes3/detectors/__init__.py 
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
def parse_muc_digi_id(
    muc_digi_id: IntLike,
    flat: bool = False,
    library: Literal["ak", "np"] = "ak",
) -> Union[ak.Record, dict[str, np.ndarray], dict[str, np.int_]]:
    """
    Parse MUC digi ID.

    If `library` is `ak`, return `ak.Record`. If `library` is `np`, return `dict[str, np.ndarray]`.

    Available keys of the output:

    - `part`: The part number.
    - `segment`: The segment number.
    - `layer`: The layer number.
    - `channel`: The channel number.
    - `gap`: The gap number, which is equivalent to layer number.
    - `strip`: The strip number, which is equivalent to channel number.

    Parameters:
        muc_digi_id: The MUC digi ID.
        flat: Whether to flatten the output.
        library: The library to use as output.

    Returns:
        The parsed MUC digi ID.
    """
    if library not in ["ak", "np"]:
        raise ValueError(f"Unsupported library: {library}")

    if flat and isinstance(muc_digi_id, ak.Array):
        muc_digi_id = ak.flatten(muc_digi_id)

    part = digi_id.muc_id_to_part(muc_digi_id)
    segment = digi_id.muc_id_to_segment(muc_digi_id)
    layer = digi_id.muc_id_to_layer(muc_digi_id)
    channel = digi_id.muc_id_to_channel(muc_digi_id)

    res = {
        "part": part,
        "segment": segment,
        "layer": layer,
        "channel": channel,
        "gap": layer,
        "strip": channel,
    }

    if library == "ak":
        return ak.zip(res)
    else:
        return res

parse_cgem_digi_id(cgem_digi_id, flat=False, library='ak')

Parse CGEM digi ID.

If library is ak, return ak.Record. If library is np, return dict[str, np.ndarray].

Available keys of the output:

  • layer: The layer number.
  • sheet: The sheet ID.
  • strip: The strip ID.
  • is_x_strip: Whether the strip is an X-strip.

Parameters:

Name Type Description Default
cgem_digi_id IntLike

The CGEM digi ID.

 required
flat bool

Whether to flatten the output.

 False
library Literal['ak', 'np']

The library to use as output.

 'ak'

Returns:

Type Description
Union[Record, dict[str, ndarray], dict[str, int_]]

The parsed CGEM digi ID.
Source code in src/pybes3/detectors/__init__.py 
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
def parse_cgem_digi_id(
    cgem_digi_id: IntLike,
    flat: bool = False,
    library: Literal["ak", "np"] = "ak",
) -> Union[ak.Record, dict[str, np.ndarray], dict[str, np.int_]]:
    """
    Parse CGEM digi ID.

    If `library` is `ak`, return `ak.Record`. If `library` is `np`, return `dict[str, np.ndarray]`.

    Available keys of the output:

    - `layer`: The layer number.
    - `sheet`: The sheet ID.
    - `strip`: The strip ID.
    - `is_x_strip`: Whether the strip is an X-strip.

    Parameters:
        cgem_digi_id: The CGEM digi ID.
        flat: Whether to flatten the output.
        library: The library to use as output.

    Returns:
        The parsed CGEM digi ID.
    """
    if library not in ["ak", "np"]:
        raise ValueError(f"Unsupported library: {library}")

    if flat and isinstance(cgem_digi_id, ak.Array):
        cgem_digi_id = ak.flatten(cgem_digi_id)

    res = {
        "layer": digi_id.cgem_id_to_layer(cgem_digi_id),
        "sheet": digi_id.cgem_id_to_sheet(cgem_digi_id),
        "strip": digi_id.cgem_id_to_strip(cgem_digi_id),
        "is_x_strip": digi_id.cgem_id_to_is_x_strip(cgem_digi_id),
    }

    if library == "ak":
        return ak.zip(res)
    else:
        return res

Geometry

get_mdc_wire_position(library='np')

Get the MDC wire position table.

Parameters:

Name Type Description Default
library Literal['np', 'ak', 'pd']

The library to return the data in. Choose from 'ak', 'np', 'pd'.

 'np'

Returns:

Type Description
Array | dict[str, ndarray] | DataFrame

The MDC wire position table.

Raises:

Type Description
ValueError

If the library is not 'ak', 'np', or 'pd'.
ImportError

If the library is 'pd' but pandas is not installed.
Source code in src/pybes3/detectors/geometry/mdc.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def get_mdc_wire_position(library: Literal["np", "ak", "pd"] = "np"):
    """
    Get the MDC wire position table.

    Parameters:
        library: The library to return the data in. Choose from 'ak', 'np', 'pd'.

    Returns:
        (ak.Array | dict[str, np.ndarray] | pd.DataFrame): The MDC wire position table.

    Raises:
        ValueError: If the library is not 'ak', 'np', or 'pd'.
        ImportError: If the library is 'pd' but pandas is not installed.
    """
    cp: dict[str, np.ndarray] = {k: v.copy() for k, v in _mdc_wire_position.items()}

    if library == "ak":
        return ak.Array(cp)
    elif library == "np":
        return cp
    elif library == "pd":
        try:
            import pandas as pd  # type: ignore
        except ImportError:
            raise ImportError("Pandas is not installed. Run `pip install pandas`.")
        return pd.DataFrame(cp)
    else:
        raise ValueError(f"Invalid library {library}. Choose from 'ak', 'np', 'pd'.")

get_mdc_gid(layer, wire)

Get MDC gid of given layer and wire.

Parameters:

Name Type Description Default
layer IntLike

The layer number.

 required
wire IntLike

The wire number.

 required

Returns:

Type Description
IntLike

The gid of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
@nb.vectorize(cache=True)
def get_mdc_gid(layer: IntLike, wire: IntLike) -> IntLike:
    """
    Get MDC gid of given layer and wire.

    Parameters:
        layer: The layer number.
        wire: The wire number.

    Returns:
        The gid of the wire.
    """
    return layer_start_gid[layer] + wire

mdc_gid_to_layer(gid)

Convert gid to layer.

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
IntLike

The layer number of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
120
121
122
123
124
125
126
127
128
129
130
131
@nb.vectorize(cache=True)
def mdc_gid_to_layer(gid: IntLike) -> IntLike:
    """
    Convert gid to layer.

    Parameters:
        gid: The gid of the wire.

    Returns:
        The layer number of the wire.
    """
    return _layer[gid]

mdc_gid_to_wire(gid)

Convert gid to wire.

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
IntLike

The wire number of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
134
135
136
137
138
139
140
141
142
143
144
145
@nb.vectorize(cache=True)
def mdc_gid_to_wire(gid: IntLike) -> IntLike:
    """
    Convert gid to wire.

    Parameters:
        gid: The gid of the wire.

    Returns:
        The wire number of the wire.
    """
    return _wire[gid]

mdc_gid_to_is_stereo(gid)

Convert gid to is_stereo.

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
BoolLike

The is_stereo of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
179
180
181
182
183
184
185
186
187
188
189
190
@nb.vectorize(cache=True)
def mdc_gid_to_is_stereo(gid: IntLike) -> BoolLike:
    """
    Convert gid to is_stereo.

    Parameters:
        gid: The gid of the wire.

    Returns:
        The is_stereo of the wire.
    """
    return _is_stereo[gid]

mdc_layer_to_is_stereo(layer)

Convert layer to is_stereo.

Parameters:

Name Type Description Default
layer IntLike

The layer number.

 required

Returns:

Type Description
BoolLike

The is_stereo of the layer.
Source code in src/pybes3/detectors/geometry/mdc.py 
165
166
167
168
169
170
171
172
173
174
175
176
@nb.vectorize(cache=True)
def mdc_layer_to_is_stereo(layer: IntLike) -> BoolLike:
    """
    Convert layer to is_stereo.

    Parameters:
        layer: The layer number.

    Returns:
        The is_stereo of the layer.
    """
    return is_layer_stereo[layer]

mdc_gid_to_east_x(gid)

Convert gid to east_x (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The east_x (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
235
236
237
238
239
240
241
242
243
244
245
246
@nb.vectorize(cache=True)
def mdc_gid_to_east_x(gid: IntLike) -> FloatLike:
    """
    Convert gid to east_x (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The east_x (cm) of the wire.
    """
    return _east_x[gid]

mdc_gid_to_east_y(gid)

Convert gid to east_y (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The east_y (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
249
250
251
252
253
254
255
256
257
258
259
260
@nb.vectorize(cache=True)
def mdc_gid_to_east_y(gid: IntLike) -> FloatLike:
    """
    Convert gid to east_y (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The east_y (cm) of the wire.
    """
    return _east_y[gid]

mdc_gid_to_east_z(gid)

Convert gid to east_z (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The east_z (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
263
264
265
266
267
268
269
270
271
272
273
274
@nb.vectorize(cache=True)
def mdc_gid_to_east_z(gid: IntLike) -> FloatLike:
    """
    Convert gid to east_z (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The east_z (cm) of the wire.
    """
    return _east_z[gid]

mdc_gid_to_west_x(gid)

Convert gid to west_x (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The west_x (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
193
194
195
196
197
198
199
200
201
202
203
204
@nb.vectorize(cache=True)
def mdc_gid_to_west_x(gid: IntLike) -> FloatLike:
    """
    Convert gid to west_x (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The west_x (cm) of the wire.
    """
    return _west_x[gid]

mdc_gid_to_west_y(gid)

Convert gid to west_y (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The west_y (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
207
208
209
210
211
212
213
214
215
216
217
218
@nb.vectorize(cache=True)
def mdc_gid_to_west_y(gid: IntLike) -> FloatLike:
    """
    Convert gid to west_y (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The west_y (cm) of the wire.
    """
    return _west_y[gid]

mdc_gid_to_west_z(gid)

Convert gid to west_z (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required

Returns:

Type Description
FloatLike

The west_z (cm) of the wire.
Source code in src/pybes3/detectors/geometry/mdc.py 
221
222
223
224
225
226
227
228
229
230
231
232
@nb.vectorize(cache=True)
def mdc_gid_to_west_z(gid: IntLike) -> FloatLike:
    """
    Convert gid to west_z (cm).

    Parameters:
        gid: The gid of the wire.

    Returns:
        The west_z (cm) of the wire.
    """
    return _west_z[gid]

mdc_gid_z_to_x(gid, z)

Get the x (cm) position of the wire at z (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required
z FloatLike

The z (cm) position.

 required

Returns:

Type Description
FloatLike

The x (cm) position of the wire at z (cm).
Source code in src/pybes3/detectors/geometry/mdc.py 
277
278
279
280
281
282
283
284
285
286
287
288
289
@nb.vectorize(cache=True)
def mdc_gid_z_to_x(gid: IntLike, z: FloatLike) -> FloatLike:
    """
    Get the x (cm) position of the wire at z (cm).

    Parameters:
        gid: The gid of the wire.
        z: The z (cm) position.

    Returns:
        The x (cm) position of the wire at z (cm).
    """
    return _west_x[gid] + dx_dz[gid] * (z - _west_z[gid])

mdc_gid_z_to_y(gid, z)

Get the y (cm) position of the wire at z (cm).

Parameters:

Name Type Description Default
gid IntLike

The gid of the wire.

 required
z FloatLike

The z (cm) position.

 required

Returns:

Type Description
FloatLike

The y (cm) position of the wire at z (cm).
Source code in src/pybes3/detectors/geometry/mdc.py 
292
293
294
295
296
297
298
299
300
301
302
303
304
@nb.vectorize(cache=True)
def mdc_gid_z_to_y(gid: IntLike, z: FloatLike) -> FloatLike:
    """
    Get the y (cm) position of the wire at z (cm).

    Parameters:
        gid: The gid of the wire.
        z: The z (cm) position.

    Returns:
        The y (cm) position of the wire at z (cm).
    """
    return _west_y[gid] + dy_dz[gid] * (z - _west_z[gid])

get_emc_crystal_position(library='np')

Get EMC crystal position table.

Parameters:

Name Type Description Default
library Literal['np', 'ak', 'pd']

The library to return the data in. Choose from 'ak', 'np', 'pd'.

 'np'

Returns:

Type Description
Array | dict[str, ndarray] | DataFrame

The EMC crystal position table.

Raises:

Type Description
ValueError

If the library is not 'ak', 'np', or 'pd'.
ImportError

If the library is 'pd' but pandas is not installed.
Source code in src/pybes3/detectors/geometry/emc.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def get_emc_crystal_position(library: Literal["np", "ak", "pd"] = "np"):
    """
    Get EMC crystal position table.

    Parameters:
        library: The library to return the data in. Choose from 'ak', 'np', 'pd'.

    Returns:
        (ak.Array | dict[str, np.ndarray] | pd.DataFrame): The EMC crystal position table.

    Raises:
        ValueError: If the library is not 'ak', 'np', or 'pd'.
        ImportError: If the library is 'pd' but pandas is not installed.
    """
    cp: dict[str, np.ndarray] = {k: v.copy() for k, v in _emc_geom.items()}

    res: dict[str, np.ndarray] = {}

    for k in [
        "gid",
        "center_x",
        "center_y",
        "center_z",
        "front_center_x",
        "front_center_y",
        "front_center_z",
    ]:
        res[k] = cp[k]

    # flatten crystal points
    for i in range(8):
        res[f"points_x_{i}"] = cp["points_x"][:, i]
        res[f"points_y_{i}"] = cp["points_y"][:, i]
        res[f"points_z_{i}"] = cp["points_z"][:, i]

    if library == "ak":
        return ak.Array(res)
    elif library == "np":
        return res
    elif library == "pd":
        try:
            import pandas as pd  # type: ignore
        except ImportError:
            raise ImportError("Pandas is not installed. Run `pip install pandas`.")
        return pd.DataFrame(res)
    else:
        raise ValueError(f"Invalid library {library}. Choose from 'ak', 'np', 'pd'.")

get_emc_gid(part, theta, phi)

Get EMC gid of given part, theta, and phi.

  • part 0: 0-479
    • theta 0: 0-63
    • theta 1: 64-127
    • theta 2: 128-207
    • theta 3: 208-287
    • theta 4: 288-383
    • theta 5: 384-479
  • part 1: 480-5759 (theta 0-47)
  • part 2: 5760-6239
    • theta 5: 5760-5855 (96)
    • theta 4: 5856-5951 (96)
    • theta 3: 5952-6031 (80)
    • theta 2: 6032-6111 (80)
    • theta 1: 6112-6175 (64)
    • theta 0: 6176-6239 (64)

Parameters:

Name Type Description Default
part IntLike

part number

 required
theta IntLike

theta number

 required
phi IntLike

phi number

 required

Returns:

Name Type Description
index IntLike

EMC index
Source code in src/pybes3/detectors/geometry/emc.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
@nb.vectorize(cache=True)
def get_emc_gid(part: IntLike, theta: IntLike, phi: IntLike) -> IntLike:
    """
    Get EMC gid of given part, theta, and phi.

    - part 0: 0-479
        - theta 0: 0-63
        - theta 1: 64-127
        - theta 2: 128-207
        - theta 3: 208-287
        - theta 4: 288-383
        - theta 5: 384-479
    - part 1: 480-5759 (theta 0-47)
    - part 2: 5760-6239
        - theta 5: 5760-5855 (96)
        - theta 4: 5856-5951 (96)
        - theta 3: 5952-6031 (80)
        - theta 2: 6032-6111 (80)
        - theta 1: 6112-6175 (64)
        - theta 0: 6176-6239 (64)

    Parameters:
        part: part number
        theta: theta number
        phi: phi number

    Returns:
        index: EMC index
    """
    if part == 0:
        res = 0
        if theta == 0 or theta == 1:
            return np.uint16(theta * ENDCAP_PHI_01 + phi)

        res += 2 * ENDCAP_PHI_01
        if theta == 2 or theta == 3:
            return np.uint16(res + (theta - 2) * ENDCAP_PHI_23 + phi)

        res += 2 * ENDCAP_PHI_23
        if theta == 4 or theta == 5:
            return np.uint16(res + (theta - 4) * ENDCAP_PHI_45 + phi)

    if part == 1:
        return np.uint16(ENDCAP_CRYSTALS + theta * BARREL_PHI + phi)

    if part == 2:
        res = ENDCAP_CRYSTALS + BARREL_CRYSTALS

        if theta == 4 or theta == 5:
            return np.uint16(res + (5 - theta) * ENDCAP_PHI_45 + phi)

        res += 2 * ENDCAP_PHI_45
        if theta == 2 or theta == 3:
            return np.uint16(res + (3 - theta) * ENDCAP_PHI_23 + phi)

        res += 2 * ENDCAP_PHI_23
        if theta == 0 or theta == 1:
            return np.uint16(res + (1 - theta) * ENDCAP_PHI_01 + phi)

    return np.uint16(65535)

emc_gid_to_center_x(gid)

Convert EMC gid to x coordinate of the crystal's center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The x coordinate of the crystal's center.
Source code in src/pybes3/detectors/geometry/emc.py 
244
245
246
247
248
249
250
251
252
253
254
255
@nb.vectorize(cache=True)
def emc_gid_to_center_x(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to x coordinate of the crystal's center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The x coordinate of the crystal's center.
    """
    return _center_x[gid]

emc_gid_to_center_y(gid)

Convert EMC gid to y coordinate of the crystal's center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The y coordinate of the crystal's center.
Source code in src/pybes3/detectors/geometry/emc.py 
258
259
260
261
262
263
264
265
266
267
268
269
@nb.vectorize(cache=True)
def emc_gid_to_center_y(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to y coordinate of the crystal's center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The y coordinate of the crystal's center.
    """
    return _center_y[gid]

emc_gid_to_center_z(gid)

Convert EMC gid to z coordinate of the crystal's center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The z coordinate of the crystal's center.
Source code in src/pybes3/detectors/geometry/emc.py 
272
273
274
275
276
277
278
279
280
281
282
283
@nb.vectorize(cache=True)
def emc_gid_to_center_z(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to z coordinate of the crystal's center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The z coordinate of the crystal's center.
    """
    return _center_z[gid]

emc_gid_to_front_center_x(gid)

Convert EMC gid to x coordinate of the crystal's front center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The x coordinate of the crystal's front center.
Source code in src/pybes3/detectors/geometry/emc.py 
286
287
288
289
290
291
292
293
294
295
296
297
@nb.vectorize(cache=True)
def emc_gid_to_front_center_x(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to x coordinate of the crystal's front center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The x coordinate of the crystal's front center.
    """
    return _front_center_x[gid]

emc_gid_to_front_center_y(gid)

Convert EMC gid to y coordinate of the crystal's front center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The y coordinate of the crystal's front center.
Source code in src/pybes3/detectors/geometry/emc.py 
300
301
302
303
304
305
306
307
308
309
310
311
@nb.vectorize(cache=True)
def emc_gid_to_front_center_y(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to y coordinate of the crystal's front center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The y coordinate of the crystal's front center.
    """
    return _front_center_y[gid]

emc_gid_to_front_center_z(gid)

Convert EMC gid to z coordinate of the crystal's front center.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
FloatLike

The z coordinate of the crystal's front center.
Source code in src/pybes3/detectors/geometry/emc.py 
314
315
316
317
318
319
320
321
322
323
324
325
@nb.vectorize(cache=True)
def emc_gid_to_front_center_z(gid: IntLike) -> FloatLike:
    """
    Convert EMC gid to z coordinate of the crystal's front center.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The z coordinate of the crystal's front center.
    """
    return _front_center_z[gid]

emc_gid_to_part(gid)

Convert EMC gid to part.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
IntLike

The part number of the crystal.
Source code in src/pybes3/detectors/geometry/emc.py 
157
158
159
160
161
162
163
164
165
166
167
168
@nb.vectorize(cache=True)
def emc_gid_to_part(gid: IntLike) -> IntLike:
    """
    Convert EMC gid to part.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The part number of the crystal.
    """
    return _part[gid]

emc_gid_to_phi(gid)

Convert EMC gid to phi.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
IntLike

The phi number of the crystal.
Source code in src/pybes3/detectors/geometry/emc.py 
185
186
187
188
189
190
191
192
193
194
195
196
@nb.vectorize(cache=True)
def emc_gid_to_phi(gid: IntLike) -> IntLike:
    """
    Convert EMC gid to phi.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The phi number of the crystal.
    """
    return _phi[gid]

emc_gid_to_point_x(gid, point)

Convert EMC gid to x coordinate of the point.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required
point IntLike

The point number, 0-7.

 required

Returns:

Type Description
FloatLike

The x coordinate of the point.
Source code in src/pybes3/detectors/geometry/emc.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
@nb.vectorize(cache=True)
def emc_gid_to_point_x(gid: IntLike, point: IntLike) -> FloatLike:
    """
    Convert EMC gid to x coordinate of the point.

    Parameters:
        gid: The gid of the crystal.
        point: The point number, 0-7.

    Returns:
        The x coordinate of the point.
    """
    return _points_x[gid, point]

emc_gid_to_point_y(gid, point)

Convert EMC gid to y coordinate of the point.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required
point IntLike

The point number, 0-7.

 required

Returns:

Type Description
FloatLike

The y coordinate of the point.
Source code in src/pybes3/detectors/geometry/emc.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
@nb.vectorize(cache=True)
def emc_gid_to_point_y(gid: IntLike, point: IntLike) -> FloatLike:
    """
    Convert EMC gid to y coordinate of the point.

    Parameters:
        gid: The gid of the crystal.
        point: The point number, 0-7.

    Returns:
        The y coordinate of the point.
    """
    return _points_y[gid, point]

emc_gid_to_point_z(gid, point)

Convert EMC gid to z coordinate of the point.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required
point IntLike

The point number, 0-7.

 required

Returns:

Type Description
FloatLike

The z coordinate of the point.
Source code in src/pybes3/detectors/geometry/emc.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
@nb.vectorize(cache=True)
def emc_gid_to_point_z(gid: IntLike, point: IntLike) -> FloatLike:
    """
    Convert EMC gid to z coordinate of the point.

    Parameters:
        gid: The gid of the crystal.
        point: The point number, 0-7.

    Returns:
        The z coordinate of the point.
    """
    return _points_z[gid, point]

emc_gid_to_theta(gid)

Convert EMC gid to theta.

Parameters:

Name Type Description Default
gid IntLike

The gid of the crystal.

 required

Returns:

Type Description
IntLike

The theta number of the crystal.
Source code in src/pybes3/detectors/geometry/emc.py 
171
172
173
174
175
176
177
178
179
180
181
182
@nb.vectorize(cache=True)
def emc_gid_to_theta(gid: IntLike) -> IntLike:
    """
    Convert EMC gid to theta.

    Parameters:
        gid: The gid of the crystal.

    Returns:
        The theta number of the crystal.
    """
    return _theta[gid]

Digi Identifier

check_mdc_id(mdc_digi_id)

Check if the MDC digi ID is valid.

Parameters:

Name Type Description Default
mdc_digi_id IntLike

The MDC digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the digi ID is valid.
Source code in src/pybes3/detectors/digi_id.py 
80
81
82
83
84
85
86
87
88
89
90
91
@nb.vectorize(cache=True)
def check_mdc_id(mdc_digi_id: IntLike) -> BoolLike:
    """
    Check if the MDC digi ID is valid.

    Parameters:
        mdc_digi_id: The MDC digi ID array or value.

    Returns:
        Whether the digi ID is valid.
    """
    return (mdc_digi_id & DIGI_FLAG_MASK) >> DIGI_FLAG_OFFSET == DIGI_MDC_FLAG

mdc_id_to_wire(mdc_digi_id)

Convert MDC digi ID to wire number.

Parameters:

Name Type Description Default
mdc_digi_id IntLike

MDC digi ID array or value.

 required

Returns:

Type Description
IntLike

The wire number.
Source code in src/pybes3/detectors/digi_id.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@nb.vectorize(cache=True)
def mdc_id_to_wire(mdc_digi_id: IntLike) -> IntLike:
    """
    Convert MDC digi ID to wire number.

    Parameters:
        mdc_digi_id: MDC digi ID array or value.

    Returns:
        The wire number.
    """
    return np.uint16((mdc_digi_id & DIGI_MDC_WIRE_MASK) >> DIGI_MDC_WIRE_OFFSET)

mdc_id_to_layer(mdc_digi_id)

Convert the MDC digi ID to the layer number.

Parameters:

Name Type Description Default
mdc_digi_id IntLike

The MDC digi ID array or value.

 required

Returns:

Type Description
IntLike

The layer number.
Source code in src/pybes3/detectors/digi_id.py 
108
109
110
111
112
113
114
115
116
117
118
119
@nb.vectorize(cache=True)
def mdc_id_to_layer(mdc_digi_id: IntLike) -> IntLike:
    """
    Convert the MDC digi ID to the layer number.

    Parameters:
        mdc_digi_id: The MDC digi ID array or value.

    Returns:
        The layer number.
    """
    return np.uint8((mdc_digi_id & DIGI_MDC_LAYER_MASK) >> DIGI_MDC_LAYER_OFFSET)

mdc_id_to_is_stereo(mdc_digi_id)

Convert the MDC digi ID to whether it is a stereo wire.

Parameters:

Name Type Description Default
mdc_digi_id IntLike

The MDC digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the wire is a stereo wire.
Source code in src/pybes3/detectors/digi_id.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
@nb.vectorize(cache=True)
def mdc_id_to_is_stereo(mdc_digi_id: IntLike) -> BoolLike:
    """
    Convert the MDC digi ID to whether it is a stereo wire.

    Parameters:
        mdc_digi_id: The MDC digi ID array or value.

    Returns:
        Whether the wire is a stereo wire.
    """
    return (
        mdc_digi_id & DIGI_MDC_WIRETYPE_MASK
    ) >> DIGI_MDC_WIRETYPE_OFFSET == DIGI_MDC_STEREO_WIRE

get_mdc_digi_id(wire, layer, wire_type)

Generate MDC digi ID based on the wire number, layer number, and wire type.

Parameters:

Name Type Description Default
wire IntLike

The wire number.

 required
layer IntLike

The layer number.

 required
wire_type IntLike

The wire type.

 required

Returns:

Type Description
IntLike

The MDC digi ID.
Source code in src/pybes3/detectors/digi_id.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
@nb.vectorize(cache=True)
def get_mdc_digi_id(
    wire: IntLike,
    layer: IntLike,
    wire_type: IntLike,
) -> IntLike:
    """
    Generate MDC digi ID based on the wire number, layer number, and wire type.

    Parameters:
        wire: The wire number.
        layer: The layer number.
        wire_type: The wire type.

    Returns:
        The MDC digi ID.
    """
    return np.uint32(
        ((wire << DIGI_MDC_WIRE_OFFSET) & DIGI_MDC_WIRE_MASK)
        | ((layer << DIGI_MDC_LAYER_OFFSET) & DIGI_MDC_LAYER_MASK)
        | ((wire_type << DIGI_MDC_WIRETYPE_OFFSET) & DIGI_MDC_WIRETYPE_MASK)
        | (DIGI_MDC_FLAG << DIGI_FLAG_OFFSET)
    )

check_tof_id(tof_digi_id)

Check if the TOF digi ID is valid.

Parameters:

Name Type Description Default
tof_digi_id IntLike

The TOF digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the digi ID is valid.
Source code in src/pybes3/detectors/digi_id.py 
166
167
168
169
170
171
172
173
174
175
176
177
@nb.vectorize(cache=True)
def check_tof_id(tof_digi_id: IntLike) -> BoolLike:
    """
    Check if the TOF digi ID is valid.

    Parameters:
        tof_digi_id: The TOF digi ID array or value.

    Returns:
        Whether the digi ID is valid.
    """
    return (tof_digi_id & DIGI_FLAG_MASK) >> DIGI_FLAG_OFFSET == DIGI_TOF_FLAG

tof_id_to_part(tof_digi_id)

Convert TOF digi ID to part number. 0, 1, 2 for scintillator endcap0/barrel/endcap1, 3, 4 for MRPC endcap0/endcap1.

Parameters:

Name Type Description Default
tof_digi_id IntLike

TOF digi ID array or value.

 required

Returns:

Type Description
IntLike

The part number.
Source code in src/pybes3/detectors/digi_id.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
@nb.vectorize(cache=True)
def tof_id_to_part(tof_digi_id: IntLike) -> IntLike:
    """
    Convert TOF digi ID to part number. 0, 1, 2 for scintillator endcap0/barrel/endcap1,
    3, 4 for MRPC endcap0/endcap1.

    Parameters:
        tof_digi_id: TOF digi ID array or value.

    Returns:
        The part number.
    """
    part = (tof_digi_id & DIGI_TOF_PART_MASK) >> DIGI_TOF_PART_OFFSET
    if part == 3:  # += MRPC endcap number
        part += (tof_digi_id & DIGI_TOF_MRPC_ENDCAP_MASK) >> DIGI_TOF_MRPC_ENDCAP_OFFSET
    return np.uint8(part)

tof_id_to_layer_or_module(tof_digi_id, part=None)

Convert the TOF digi ID to the scintillator layer or MRPC module number. If part < 3, it is scintillator and the return value is layer number. Otherwise, it is MRPC and the return value is module number.

Parameters:

Name Type Description Default
tof_digi_id IntLike

The TOF digi ID array or value.

 required
part Optional[IntLike]

The part number. If not provided, it will be calculated based on the TOF digi ID.

 None

Returns:

Type Description
IntLike

The scintillator layer or MRPC module number.
Source code in src/pybes3/detectors/digi_id.py 
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def tof_id_to_layer_or_module(
    tof_digi_id: IntLike,
    part: Optional[IntLike] = None,
) -> IntLike:
    """
    Convert the TOF digi ID to the scintillator layer or MRPC module number.
    If `part < 3`, it is scintillator and the return value is layer number. Otherwise, it is
    MRPC and the return value is module number.

    Parameters:
        tof_digi_id: The TOF digi ID array or value.
        part: The part number. If not provided, it will be calculated based on the TOF digi ID.

    Returns:
        The scintillator layer or MRPC module number.
    """
    if part is None:
        return _tof_id_to_layer_or_module_1(tof_digi_id)
    else:
        return _tof_id_to_layer_or_module_2(tof_digi_id, part)

tof_id_to_phi_or_strip(tof_digi_id, part=None)

Convert the TOF digi ID to the scintillator phi or MRPC strip number, based on the part number. If part < 3, it is scintillator and the return value is phi number. Otherwise, it is MRPC and the return value is strip number.

Parameters:

Name Type Description Default
tof_digi_id IntLike

The TOF digi ID array or value.

 required
part Optional[IntLike]

The part number. If not provided, it will be calculated based on the TOF digi ID.

 None

Returns:

Type Description
IntLike

The scintillator phi or MRPC strip number.
Source code in src/pybes3/detectors/digi_id.py 
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
def tof_id_to_phi_or_strip(
    tof_digi_id: IntLike,
    part: Optional[IntLike] = None,
) -> IntLike:
    """
    Convert the TOF digi ID to the scintillator phi or MRPC strip number, based on the part number.
    If `part < 3`, it is scintillator and the return value is phi number. Otherwise, it is
    MRPC and the return value is strip number.

    Parameters:
        tof_digi_id: The TOF digi ID array or value.
        part: The part number. If not provided, it will be calculated based on the TOF digi ID.

    Returns:
        The scintillator phi or MRPC strip number.
    """
    if part is None:
        return _tof_id_to_phi_or_strip_1(tof_digi_id)
    else:
        return _tof_id_to_phi_or_strip_2(tof_digi_id, part)

tof_id_to_end(tof_digi_id)

Convert the TOF digi ID to the readout end number.

Parameters:

Name Type Description Default
tof_digi_id IntLike

The TOF digi ID array or value.

 required

Returns:

Type Description
IntLike

The readout end number.
Source code in src/pybes3/detectors/digi_id.py 
198
199
200
201
202
203
204
205
206
207
208
209
@nb.vectorize(cache=True)
def tof_id_to_end(tof_digi_id: IntLike) -> IntLike:
    """
    Convert the TOF digi ID to the readout end number.

    Parameters:
        tof_digi_id: The TOF digi ID array or value.

    Returns:
        The readout end number.
    """
    return np.uint8(tof_digi_id % 2)

get_tof_digi_id(part, layer_or_module, phi_or_strip, end)

Generate TOF scintillator ID based on the part number, layer number, phi number, and readout end number.

Parameters:

Name Type Description Default
part IntLike

The part number.

 required
layer_or_module IntLike

The scintillator layer or MRPC module number.

 required
phi_or_strip IntLike

The scintillator phi or MRPC strip number.

 required
end IntLike

The readout end number.

 required

Returns:

Type Description
IntLike

The TOF digi ID.
Source code in src/pybes3/detectors/digi_id.py 
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
@nb.vectorize(cache=True)
def get_tof_digi_id(
    part: IntLike,
    layer_or_module: IntLike,
    phi_or_strip: IntLike,
    end: IntLike,
) -> IntLike:
    """
    Generate TOF scintillator ID based on the part number, layer number, phi number, and readout end number.

    Parameters:
        part: The part number.
        layer_or_module: The scintillator layer or MRPC module number.
        phi_or_strip: The scintillator phi or MRPC strip number.
        end: The readout end number.

    Returns:
        The TOF digi ID.
    """
    if part < 3:
        return np.uint32(
            ((part << DIGI_TOF_PART_OFFSET) & DIGI_TOF_PART_MASK)
            | ((layer_or_module << DIGI_TOF_SCINT_LAYER_OFFSET) & DIGI_TOF_SCINT_LAYER_MASK)
            | ((phi_or_strip << DIGI_TOF_SCINT_PHI_OFFSET) & DIGI_TOF_SCINT_PHI_MASK)
            | ((end << DIGI_TOF_END_OFFSET) & DIGI_TOF_END_MASK)
            | (DIGI_TOF_FLAG << DIGI_FLAG_OFFSET)
        )
    else:
        return np.uint32(
            ((3 << DIGI_TOF_PART_OFFSET) & DIGI_TOF_PART_MASK)
            | (((part - 3) << DIGI_TOF_MRPC_ENDCAP_OFFSET) & DIGI_TOF_MRPC_ENDCAP_MASK)
            | ((layer_or_module << DIGI_TOF_MRPC_MODULE_OFFSET) & DIGI_TOF_MRPC_MODULE_MASK)
            | ((phi_or_strip << DIGI_TOF_MRPC_STRIP_OFFSET) & DIGI_TOF_MRPC_STRIP_MASK)
            | ((end << DIGI_TOF_END_OFFSET) & DIGI_TOF_END_MASK)
            | (DIGI_TOF_FLAG << DIGI_FLAG_OFFSET)
        )

check_emc_id(emc_digi_id)

Check if the EMC digi ID is valid.

Parameters:

Name Type Description Default
emc_digi_id IntLike

The EMC digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the digi ID is valid.
Source code in src/pybes3/detectors/digi_id.py 
383
384
385
386
387
388
389
390
391
392
393
394
@nb.vectorize(cache=True)
def check_emc_id(emc_digi_id: IntLike) -> BoolLike:
    """
    Check if the EMC digi ID is valid.

    Parameters:
        emc_digi_id: The EMC digi ID array or value.

    Returns:
        Whether the digi ID is valid.
    """
    return (emc_digi_id & DIGI_FLAG_MASK) >> DIGI_FLAG_OFFSET == DIGI_EMC_FLAG

emc_id_to_module(emc_digi_id)

Convert EMC digi ID to module number

Parameters:

Name Type Description Default
emc_digi_id IntLike

EMC digi ID array or value.

 required

Returns:

Type Description
IntLike

The module number.
Source code in src/pybes3/detectors/digi_id.py 
397
398
399
400
401
402
403
404
405
406
407
408
@nb.vectorize(cache=True)
def emc_id_to_module(emc_digi_id: IntLike) -> IntLike:
    """
    Convert EMC digi ID to module number

    Parameters:
        emc_digi_id: EMC digi ID array or value.

    Returns:
        The module number.
    """
    return np.uint8((emc_digi_id & DIGI_EMC_MODULE_MASK) >> DIGI_EMC_MODULE_OFFSET)

emc_id_to_theta(emc_digi_id)

Convert the EMC digi ID to the theta number.

Parameters:

Name Type Description Default
emc_digi_id IntLike

The EMC digi ID array or value.

 required

Returns:

Type Description
IntLike

The theta number.
Source code in src/pybes3/detectors/digi_id.py 
411
412
413
414
415
416
417
418
419
420
421
422
@nb.vectorize(cache=True)
def emc_id_to_theta(emc_digi_id: IntLike) -> IntLike:
    """
    Convert the EMC digi ID to the theta number.

    Parameters:
        emc_digi_id: The EMC digi ID array or value.

    Returns:
        The theta number.
    """
    return np.uint8((emc_digi_id & DIGI_EMC_THETA_MASK) >> DIGI_EMC_THETA_OFFSET)

emc_id_to_phi(emc_digi_id)

Convert the EMC digi ID to the phi number.

Parameters:

Name Type Description Default
emc_digi_id IntLike

The EMC digi ID array or value.

 required

Returns:

Type Description
IntLike

The phi number.
Source code in src/pybes3/detectors/digi_id.py 
425
426
427
428
429
430
431
432
433
434
435
436
@nb.vectorize(cache=True)
def emc_id_to_phi(emc_digi_id: IntLike) -> IntLike:
    """
    Convert the EMC digi ID to the phi number.

    Parameters:
        emc_digi_id: The EMC digi ID array or value.

    Returns:
        The phi number.
    """
    return np.uint8((emc_digi_id & DIGI_EMC_PHI_MASK) >> DIGI_EMC_PHI_OFFSET)

get_emc_digi_id(module, theta, phi)

Generate EMC digi ID based on the module number, theta number, and phi number.

Parameters:

Name Type Description Default
module IntLike

The module number.

 required
theta IntLike

The theta number.

 required
phi IntLike

The phi number.

 required

Returns:

Type Description
IntLike

The EMC digi ID.
Source code in src/pybes3/detectors/digi_id.py 
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
@nb.vectorize(cache=True)
def get_emc_digi_id(
    module: IntLike,
    theta: IntLike,
    phi: IntLike,
) -> IntLike:
    """
    Generate EMC digi ID based on the module number, theta number, and phi number.

    Parameters:
        module: The module number.
        theta: The theta number.
        phi: The phi number.

    Returns:
        The EMC digi ID.
    """
    return np.uint32(
        ((module << DIGI_EMC_MODULE_OFFSET) & DIGI_EMC_MODULE_MASK)
        | ((theta << DIGI_EMC_THETA_OFFSET) & DIGI_EMC_THETA_MASK)
        | ((phi << DIGI_EMC_PHI_OFFSET) & DIGI_EMC_PHI_MASK)
        | (DIGI_EMC_FLAG << DIGI_FLAG_OFFSET)
    )

check_muc_id(muc_digi_id)

Check if the MUC digi ID is valid.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the digi ID is valid.
Source code in src/pybes3/detectors/digi_id.py 
467
468
469
470
471
472
473
474
475
476
477
478
@nb.vectorize(cache=True)
def check_muc_id(muc_digi_id: IntLike) -> BoolLike:
    """
    Check if the MUC digi ID is valid.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        Whether the digi ID is valid.
    """
    return (muc_digi_id & DIGI_FLAG_MASK) >> DIGI_FLAG_OFFSET == DIGI_MUC_FLAG

muc_id_to_part(muc_digi_id)

Convert MUC digi ID to part number

Parameters:

Name Type Description Default
muc_digi_id IntLike

MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The part number.
Source code in src/pybes3/detectors/digi_id.py 
481
482
483
484
485
486
487
488
489
490
491
492
@nb.vectorize(cache=True)
def muc_id_to_part(muc_digi_id: IntLike) -> IntLike:
    """
    Convert MUC digi ID to part number

    Parameters:
        muc_digi_id: MUC digi ID array or value.

    Returns:
        The part number.
    """
    return np.uint8((muc_digi_id & DIGI_MUC_PART_MASK) >> DIGI_MUC_PART_OFFSET)

muc_id_to_segment(muc_digi_id)

Convert the MUC digi ID to the segment number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The segment number.
Source code in src/pybes3/detectors/digi_id.py 
495
496
497
498
499
500
501
502
503
504
505
506
@nb.vectorize(cache=True)
def muc_id_to_segment(muc_digi_id: IntLike) -> IntLike:
    """
    Convert the MUC digi ID to the segment number.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        The segment number.
    """
    return np.uint8((muc_digi_id & DIGI_MUC_SEGMENT_MASK) >> DIGI_MUC_SEGMENT_OFFSET)

muc_id_to_layer(muc_digi_id)

Convert the MUC digi ID to the layer number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The layer number.
Source code in src/pybes3/detectors/digi_id.py 
509
510
511
512
513
514
515
516
517
518
519
520
@nb.vectorize(cache=True)
def muc_id_to_layer(muc_digi_id: IntLike) -> IntLike:
    """
    Convert the MUC digi ID to the layer number.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        The layer number.
    """
    return np.uint8((muc_digi_id & DIGI_MUC_LAYER_MASK) >> DIGI_MUC_LAYER_OFFSET)

muc_id_to_strip(muc_digi_id)

Convert the MUC digi ID to the strip number, which is equivalent to channel number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The strip number.
Source code in src/pybes3/detectors/digi_id.py 
578
579
580
581
582
583
584
585
586
587
588
def muc_id_to_strip(muc_digi_id: IntLike) -> IntLike:
    """
    Convert the MUC digi ID to the strip number, which is equivalent to channel number.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        The strip number.
    """
    return muc_id_to_channel(muc_digi_id)

muc_id_to_gap(muc_digi_id)

Convert the MUC digi ID to the gap ID, which is equivalent to layer number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The gap ID.
Source code in src/pybes3/detectors/digi_id.py 
565
566
567
568
569
570
571
572
573
574
575
def muc_id_to_gap(muc_digi_id: IntLike) -> IntLike:
    """
    Convert the MUC digi ID to the gap ID, which is equivalent to layer number.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        The gap ID.
    """
    return muc_id_to_layer(muc_digi_id)

muc_id_to_strip(muc_digi_id)

Convert the MUC digi ID to the strip number, which is equivalent to channel number.

Parameters:

Name Type Description Default
muc_digi_id IntLike

The MUC digi ID array or value.

 required

Returns:

Type Description
IntLike

The strip number.
Source code in src/pybes3/detectors/digi_id.py 
578
579
580
581
582
583
584
585
586
587
588
def muc_id_to_strip(muc_digi_id: IntLike) -> IntLike:
    """
    Convert the MUC digi ID to the strip number, which is equivalent to channel number.

    Parameters:
        muc_digi_id: The MUC digi ID array or value.

    Returns:
        The strip number.
    """
    return muc_id_to_channel(muc_digi_id)

get_muc_digi_id(part, segment, layer, channel)

Generate MUC digi ID based on the part number, segment number, layer number, and channel number.

Parameters:

Name Type Description Default
part IntLike

The part number.

 required
segment IntLike

The segment number.

 required
layer IntLike

The layer number.

 required
channel IntLike

The channel number.

 required

Returns:

Type Description
IntLike

The MUC digi ID.
Source code in src/pybes3/detectors/digi_id.py 
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
@nb.vectorize(cache=True)
def get_muc_digi_id(
    part: IntLike,
    segment: IntLike,
    layer: IntLike,
    channel: IntLike,
) -> IntLike:
    """
    Generate MUC digi ID based on the part number, segment number, layer number, and channel number.

    Parameters:
        part: The part number.
        segment: The segment number.
        layer: The layer number.
        channel: The channel number.

    Returns:
        The MUC digi ID.
    """
    return np.uint32(
        ((part << DIGI_MUC_PART_OFFSET) & DIGI_MUC_PART_MASK)
        | ((segment << DIGI_MUC_SEGMENT_OFFSET) & DIGI_MUC_SEGMENT_MASK)
        | ((layer << DIGI_MUC_LAYER_OFFSET) & DIGI_MUC_LAYER_MASK)
        | ((channel << DIGI_MUC_CHANNEL_OFFSET) & DIGI_MUC_CHANNEL_MASK)
        | (DIGI_MUC_FLAG << DIGI_FLAG_OFFSET)
    )

check_cgem_id(cgem_digi_id)

Check if the CGEM digi ID is valid.

Parameters:

Name Type Description Default
cgem_digi_id IntLike

The CGEM digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the digi ID is valid.
Source code in src/pybes3/detectors/digi_id.py 
594
595
596
597
598
599
600
601
602
603
604
605
@nb.vectorize(cache=True)
def check_cgem_id(cgem_digi_id: IntLike) -> BoolLike:
    """
    Check if the CGEM digi ID is valid.

    Parameters:
        cgem_digi_id: The CGEM digi ID array or value.

    Returns:
        Whether the digi ID is valid.
    """
    return (cgem_digi_id & DIGI_FLAG_MASK) >> DIGI_FLAG_OFFSET == DIGI_CGEM_FLAG

cgem_id_to_layer(cgem_digi_id)

Convert the CGEM digi ID to the layer number.

Parameters:

Name Type Description Default
cgem_digi_id IntLike

The CGEM digi ID array or value.

 required

Returns:

Type Description
IntLike

The layer number.
Source code in src/pybes3/detectors/digi_id.py 
608
609
610
611
612
613
614
615
616
617
618
619
@nb.vectorize(cache=True)
def cgem_id_to_layer(cgem_digi_id: IntLike) -> IntLike:
    """
    Convert the CGEM digi ID to the layer number.

    Parameters:
        cgem_digi_id: The CGEM digi ID array or value.

    Returns:
        The layer number.
    """
    return np.uint8((cgem_digi_id & DIGI_CGEM_LAYER_MASK) >> DIGI_CGEM_LAYER_OFFSET)

cgem_id_to_sheet(cgem_digi_id)

Convert the CGEM digi ID to the sheet number.

Parameters:

Name Type Description Default
cgem_digi_id IntLike

The CGEM digi ID array or value.

 required

Returns:

Type Description
IntLike

The sheet number.
Source code in src/pybes3/detectors/digi_id.py 
622
623
624
625
626
627
628
629
630
631
632
633
@nb.vectorize(cache=True)
def cgem_id_to_sheet(cgem_digi_id: IntLike) -> IntLike:
    """
    Convert the CGEM digi ID to the sheet number.

    Parameters:
        cgem_digi_id: The CGEM digi ID array or value.

    Returns:
        The sheet number.
    """
    return np.uint8((cgem_digi_id & DIGI_CGEM_SHEET_MASK) >> DIGI_CGEM_SHEET_OFFSET)

cgem_id_to_strip(cgem_digi_id)

Convert CGEM digi ID to strip number

Parameters:

Name Type Description Default
cgem_digi_id IntLike

CGEM digi ID array or value.

 required

Returns:

Type Description
IntLike

The strip number.
Source code in src/pybes3/detectors/digi_id.py 
636
637
638
639
640
641
642
643
644
645
646
647
@nb.vectorize(cache=True)
def cgem_id_to_strip(cgem_digi_id: IntLike) -> IntLike:
    """
    Convert CGEM digi ID to strip number

    Parameters:
        cgem_digi_id: CGEM digi ID array or value.

    Returns:
        The strip number.
    """
    return np.uint16((cgem_digi_id & DIGI_CGEM_STRIP_MASK) >> DIGI_CGEM_STRIP_OFFSET)

cgem_id_to_is_x_strip(cgem_digi_id)

Convert the CGEM digi ID to whether it is an X-strip.

Parameters:

Name Type Description Default
cgem_digi_id IntLike

The CGEM digi ID array or value.

 required

Returns:

Type Description
BoolLike

Whether the strip is an X-strip
Source code in src/pybes3/detectors/digi_id.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
@nb.vectorize(cache=True)
def cgem_id_to_is_x_strip(cgem_digi_id: IntLike) -> BoolLike:
    """
    Convert the CGEM digi ID to whether it is an X-strip.

    Parameters:
        cgem_digi_id: The CGEM digi ID array or value.

    Returns:
        Whether the strip is an X-strip
    """
    return (
        (cgem_digi_id & DIGI_CGEM_STRIPTYPE_MASK) >> DIGI_CGEM_STRIPTYPE_OFFSET
    ) == DIGI_CGEM_XSTRIP

get_cgem_digi_id(layer, sheet, strip, is_x_strip)

Generate CGEM digi ID based on the strip number, strip type, sheet number, and layer number.

Parameters:

Name Type Description Default
layer IntLike

The layer number.

 required
sheet IntLike

The sheet number.

 required
strip IntLike

The strip number.

 required
is_x_strip BoolLike

Whether the strip is an X-strip.

 required

Returns:

Type Description
IntLike

The CGEM digi ID.
Source code in src/pybes3/detectors/digi_id.py 
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
@nb.vectorize(cache=True)
def get_cgem_digi_id(
    layer: IntLike,
    sheet: IntLike,
    strip: IntLike,
    is_x_strip: BoolLike,
) -> IntLike:
    """
    Generate CGEM digi ID based on the strip number, strip type, sheet number, and layer number.

    Parameters:
        layer: The layer number.
        sheet: The sheet number.
        strip: The strip number.
        is_x_strip: Whether the strip is an X-strip.

    Returns:
        The CGEM digi ID.
    """
    return np.uint32(
        ((strip << DIGI_CGEM_STRIP_OFFSET) & DIGI_CGEM_STRIP_MASK)
        | ((~is_x_strip << DIGI_CGEM_STRIPTYPE_OFFSET) & DIGI_CGEM_STRIPTYPE_MASK)
        | ((sheet << DIGI_CGEM_SHEET_OFFSET) & DIGI_CGEM_SHEET_MASK)
        | ((layer << DIGI_CGEM_LAYER_OFFSET) & DIGI_CGEM_LAYER_MASK)
        | (DIGI_CGEM_FLAG << DIGI_FLAG_OFFSET)
    )