Newer
Older
This project originates as a fork of the open-source project [Si-μ-lator](https://github.com/rateixei/si-mu-lator).
**Si-μ-lator** is a package designed for toy muon detector trigger simulations. It allows users to simulate muons passing through a detector with geometry defined in a YAML file. Detector channels may register hits due to muon interactions or random noise.
> **Note:** This package is under active development and includes remnants from previous iterations that require cleanup. Use it only for tested functionalities included in the Continuous Integration (CI) workflows.
## Table of Contents
1. [Getting Started](#getting-started)
2. [Testing the Package](#testing-the-package)
- [Setting up the Environment](#setting-up-the-environment)
- [Running Testing Scripts](#running-testing-scripts)
- [Configuration File (`config.py`)](#configuration-file-configpy)
3. [Using the Package](#using-the-package)
- [Initial Setup](#initial-setup)
4. [Contributing](#contributing)
5. [License](#license)
**Si-μ-lator** is a package designed for toy muon detector trigger simulations.
- **Features:**
- Geometry of detector defined in the detector cards in YAML format.
- Directives for simulation in the detector card.
- Random generation of muons in x-y plane and raandom Theta Phi angle, limits defined as parameters.
- Detector defined as planes of tubes or strips on configurable dimensions.
- Easily change of background noise, detector
- **Use Cases:** Scenarios where this tool can be useful.
- Fast simulation generation
- Simplified detector geometry
- Simulate reponse under changes on background noise and/or detector efficiency.
#### Using container
It is highly recommended to use the same container used for the CI or do a multistage building using that one as a base.
To set up the environment with all necessary dependencies, follow these steps:
1. Use the container image available at:
`gitlab-registry.cern.ch/rrojas/kubeflow_images/tf-hls4ml`
2. Refer to the [Kubeflow Images Project](https://gitlab.cern.ch/rrojas/kubeflow_images/) for details on how to build the image and set up your environment using Docker or Apptainer.
#### Install requirements
Alternatively, you can install the following list of packages. Note that in general, upgraded version should work fine, but success is not guaranteed.
**apt**
```
apt install -y graphviz
```
**pip packages**
```
h5py==3.9.0
hls4ml==0.8.1
iminuit==2.30.1
matplotlib==3.8.0
numpy==2.1.3
pandas==2.2.3
PyYAML==6.0.1
PyYAML==6.0.2
QKeras==0.9.0
scikit_learn==1.5.2
scipy==1.14.1
sympy==1.13.2
tensorflow==2.14.0
tensorflow_model_optimization==0.8.0
tqdm==4.66.5
```
### Running Testing Scripts
Testing scripts are located in the `scripts` folder and include:
- **`ci-test.sh`**:
Used in the GitLab CI. Accepts a card name as an argument, overwrites the configuration, and executes self-tests.
- **`self_test_sim*.py`**:
A collection of Python scripts for testing different simulation steps. Run with the `--help` flag for detailed usage. Requires a valid `config.py`.
- **`run_sim_in_condor.sh`**:
Sends jobs to the HTCondor infrastructure at CERN. Automatically generates the submit file and runs `condor_submit`. Ensure your environment and jobs have CVMFS access.
> **Tip:** The `ci-test.sh` script runs as part of the CI pipeline. Review the pipeline results for additional insights and expected outputs.
#### Configuration File (`config.py`)
This file is central to defining detector topologies and managing simulations.
- Detector configurations are stored in the `cards` folder.
- Use a single `config.py` file to ensure consistent settings across scripts.
- Avoid simultaneous work with multiple detector cards or modifying cards without rerunning simulations.
### Initial Setup
1. Copy the `config-template.py` file to `config.py`.
2. Update the paths and variables to match your setup.
3. When adding new variables, commit updates to `config-template.py` to maintain consistency.
![Si-μ-lator](logo/black@3x_cropped.png?raw=true "Title")
## Si-μ-lator: Package for toy muon detector trigger simulation
## Usage
```
usage: si_mu_late.py [-h] -d DETCARD -n NEVS [-m] [-x muxmin muxmax] [-y muymin muymax] [-a muamin muamax] [-b BKGR]
optional arguments:
-h, --help show this help message and exit
-d DETCARD, --detector DETCARD
Detector card
-n NEVS, --nevents NEVS
Number of events
-m, --addmuon Simulate muon
-x muxmin muxmax, --muonx muxmin muxmax
Generated muon window in X (leave empty for 0)
-y muymin muymax, --muony muymin muymax
Generated muon window in Y (leave empty for 0)
-a muamin muamax, --muona muamin muamax
Generated muon angle window (leave empty for 0)
-b BKGR, --bkgrate BKGR
Background rate (Hz) per plane
```
## Setup environment at SLAC
```
source init_sing.sh
```