initialise.py

Go to the documentation of this file.

r"""!
@file initialise.py
@brief `main()` shows how to use [load_pueoEvent_Dataset()](#initialise.load_pueoEvent_Dataset),
       **start here!**.
 
* The script will first load the library `libpueoEvent.so` in `$PUEO_UTIL_INSTALL_DIR` as soon as you
  `import` it, even if you don't call the function
  [load_pueoEvent_Dataset()](#initialise.load_pueoEvent_Dataset),
  since the loading is done at the global scope.
  @note no need to set `LD_LIBRARY_PATH`
 
* As the script tries to load the library, it could error out if the library cannot be found,
  or if `$PUEO_UTIL_INSTALL_DIR` is not set
 
* The checks are done via `assert`s, which attempt to provide more meaningful error messages.
  You can turn them off by running
  ```
  python3 -O initialise.py
  ``` instead of
  ```
  python3 initialise.py
  ```
  which turns on optimzation.
 
* P.S. `initialise.py` with an "s" because I like to be annoying.
"""
 
import os
import ROOT
from pathlib import Path
 
puid = Path(os.environ["PUEO_UTIL_INSTALL_DIR"])
assert puid.exists() and not puid == Path("."), "$PUEO_UTIL_INSTALL_DIR has not been set"
 
# could be in lib or lib64, get the first match
library_path = next(Path(puid).rglob("lib*/libpueoEvent.so"), None)
assert library_path is not None, "failed to find libpueoEvent.so in your $PUEO_UTIL_INSTALL_DIR"
 
ROOT.gSystem.Load(str(library_path))
 
 
def load_pueoEvent_Dataset(run_number: int, MC=False) -> ROOT.pueo.Dataset:
    """!Loads the "dual output" dataset whose interface is defined in
    [pueoEvent](https://github.com/PUEOCollaboration/pueoEvent) repository.
 
    @param[in] run_number  **Must** be discoverable inside @p pueo_mc_data,
                           else an assertion will cause the function to error out.
    @param[in] MC  MC or real data
    @retval dataset        An instance of the class
                           [Dataset](https://github.com/PUEOCollaboration/pueoEvent/blob/main/src/pueo/Dataset.h)
 
    *   Some other functions (eg. #waveform_plots.load_waveforms) require you to
        **call this function first** to retrive the Dataset instance.
 
    @note
        *   The "dual output" parallels the "main output" of `simulatePueo`, namely the IceFinal files
            `IceFinal_<run_number>_allTree.root`.
        *   The dual ouput files mimic the real PUEO data format.
        *   ie. they are the `SimulatedPueo*File<run_number>.root` that live alongside the IceFinal file
            in the `run<run_number>/` directory.
        *   It might help to check out the
            [examples](https://github.com/PUEOCollaboration/pueoEvent/tree/main/examples)
            in the pueoEvent repository.
 
    *   Details:
        *   Technically, as intended by pueoEvent, `PUEO_MC_DATA` or `PUEO_ROOT_DATA` should be an environment variable.
        *   However, `pueo_mc_data` is a `Path` in this function.
        *   It is first used to verify whether
            `run<run_number>/SimulatedPueoEventFile<run_number>.root` exists.
        *   Then it is used to define a temporary environment variable within the python process,
            which will not persist beyond the program.
        *   In short, by using this script you are **not** actually using, nor affecting,
            the environment variable `PUEO_MC_DATA` which you might have defined in your `.bashrc`.
 
    """
    if MC:
        dataset = ROOT.pueo.Dataset(run_number, ROOT.pueo.Dataset.PUEO_MC_DATA)
    if not MC:
        dataset = ROOT.pueo.Dataset(run_number, ROOT.pueo.Dataset.PUEO_ROOT_DATA)
    return dataset
 
 
if __name__ == "__main__":
    d = load_pueoEvent_Dataset(run_number=797, MC=False)