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(pueo_mc_data: Path, run_number: int) -> ROOT.pueo.Dataset:
    """!Loads the "dual output" dataset whose interface is defined in
    [pueoEvent](https://github.com/PUEOCollaboration/pueoEvent) repository.
 
    @param[in] pueo_mc_data  The [directory](#effective_area.PUEO_MC_DATA)
                             that contains all the `run<run_number>/` subdirectories.
 
    @param[in] run_number  **Must** be discoverable inside @p pueo_mc_data,
                           else an assertion will cause the function to error out.
    @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` 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`.
 
    """
    # bare minimum error handling :)
    assert isinstance(pueo_mc_data, Path), "parameter pueo_mc_data needs to be a pathlib.Path object"
    _root_file = pueo_mc_data / f"run{run_number}" / f"SimulatedPueoEventFile{run_number}.root"
 
    assert _root_file.exists(), f"{_root_file} does not exist"
    os.environ["PUEO_MC_DATA"] = str(pueo_mc_data.resolve())
    print(f"The environment variable $PUEO_MC_DATA has been temporarily set to {pueo_mc_data}")
 
    dataset = ROOT.pueo.Dataset(run_number, ROOT.pueo.Dataset.PUEO_MC_DATA)
    return dataset
 
 
if __name__ == "__main__":
    d = load_pueoEvent_Dataset(pueo_mc_data=Path("/tmp"), run_number=0)