# REDVID Software README

*dr. ir. Uraz Odyurt*


## Description
REDuced VIrtual Detector (REDVID) is a simulation framework and a synthetic data 
generator written in Python. The generator simulates the propagation of subatomic 
particles, inspired by the detectors installed at the Large Hadron Collider (LHC). The 
simulation model is complexity-reduced and is intended for generating source data for 
Machine Learning (ML) algorithms.

For further information, refer to the [REDVID website](https://virtualdetector.com/project/redvid/).


## Installation
There are no prerequisites beyond the Python packages used by the code. Package 
dependencies are minimal and are listed in the `requirements.txt` file.


## Documentation
To be generated.


## Usage and citation
The main script to be executed is `scripts/digital_detector.py`. Configuration is 
provided through a configuration file in the `config/` folder. An example file is 
included with the default filename `REDVID_config.ini`, which can be changed in the code. 
Alternatively, a configuration file in a different folder can be used by providing the 
folder path as an argument.

The most important configuration parameter affecting REDVID's execution is `anchor_path`. 
This path is the root of the data set hierarchy generated by REDVID.

If you use this software in your research or any publication, we kindly request you to 
cite the following paper:

```bibtex
@inproceedings{Odyurt:2024:REDVID,
    title = {{Reduced Simulations for High-Energy Physics, a Middle Ground for Data-Driven Physics Research}},
    author = {Uraz {Odyurt} and Stephen Nicholas {Swatman} and Ana-Lucia {Varbanescu} and Sascha {Caron}},
    booktitle = {Computational Science -- ICCS 2024},
    editor = {Franco, Leonardo and de Mulatier, Cl{\'e}lia and Paszynski, Maciej and Krzhizhanovskaya, Valeria V. and Dongarra, Jack J. and Sloot, Peter M. A.},
    year = {2024},
    publisher = {Springer Nature Switzerland},
    address = {Cham},
    pages = {84--99},
    isbn = {978-3-031-63751-3},
    doi = {10.1007/978-3-031-63751-3_6}
}

@misc{Odyurt:2024:REDVID:arXiv,
    title = {{Reduced Simulations for High-Energy Physics, a Middle Ground for Data-Driven Physics Research}}, 
    author = {Uraz {Odyurt} and Stephen Nicholas {Swatman} and Ana-Lucia {Varbanescu} and Sascha {Caron}},
    year = {2024},
    eprint = {2309.03780},
    archivePrefix = {arXiv},
    primaryClass = {hep-ex},
    doi = {10.48550/arXiv.2309.03780}
}
```

We put significant effort into composing this software and proper citation helps 
acknowledge and support the continued development of this resource.


## Support
Note that this open-source software is being shared on an "as is" basis, without any 
express or implied warranties or obligations of support. While we have made efforts to 
ensure the functionality and quality of the software, we cannot guarantee its fitness for 
any particular purpose or provide any form of ongoing support.

As the creators and sharers of this software, we are unable to offer any dedicated 
assistance or guidance for utilising or troubleshooting the software. We do not commit to 
addressing inquiries, resolving issues, or providing additional documentation or support 
material related to this software. Should you encounter any challenges or have questions, 
we recommend referring to the existing documentation.


## Roadmap
*Confidential*


## Authors and acknowledgements
The REDVID simulation framework and the generated data sets are authored by:

- *dr. ir. Uraz Odyurt* - Radboud University; Nikhef

The collaborating team includes:

- *dr. Sascha Caron* - Radboud University; Nikhef
- *prof. dr. ir. Ana-Lucia Varbanescu* - University of Twente; University of Amsterdam
- *dr. Roel Aaij* - Nikhef

Previous collaborating members:

- *MSc Stephen Nicholas Swatman* - University of Amsterdam; CERN


## Licence
REDVID is distributed under `BSD-3-Clause Licence`. Refer to the provided `LICENCE` file.
The authors would appreciate the proper citation of the original work upon use, as shown 
[above](#usage-and-citation).

If you have any questions regarding the licence or usage of the software, please contact 
the authors.

**Note:** The licence applies only to the software itself and not to any third-party content 
or documentation that may be included with the software. Please review any licences or 
terms of use associated with those components separately.

---