Skip to content
Snippets Groups Projects
README.md 5.1 KiB
Newer Older
# NGT2.2-Toy-Simulation
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.
## Testing the Package  
### Setting up the Environment  
#### 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.  
## Using the Package  
### 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
```
Rafael Teixeira De Lima's avatar
Rafael Teixeira De Lima committed

## Setup environment at SLAC
```
source init_sing.sh
```