Metadata-Version: 2.5
Name: ntsim
Version: 0.4.1
Summary: Neutrino Telescope Simulation
Project-URL: Documentation, https://git.jinr.ru/ntsim/ntsim#readme
Project-URL: Issues, https://git.jinr.ru/ntsim/ntsim/issues
Project-URL: Source, https://git.jinr.ru/ntsim/ntsim
Author: Sergey Zavyalov, Andrey Sheshukov, Daniil Zubchenko, Mikhail Lisitsin, Yuri Malyshkin
Author-email: Dmitry Naumov <dmitryvnaumov@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: astropy>=6.1.7
Requires-Dist: configargparse
Requires-Dist: g4camp>=0.1.23
Requires-Dist: h5py
Requires-Dist: lazy-loader>=0.6
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: particle
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: vegas-params>=0.3.1
Provides-Extra: extra
Requires-Dist: icosphere; extra == 'extra'
Requires-Dist: pvlib; extra == 'extra'
Requires-Dist: vector; extra == 'extra'
Provides-Extra: gui
Requires-Dist: k3d; extra == 'gui'
Requires-Dist: matplotlib; extra == 'gui'
Provides-Extra: nupropagator
Requires-Dist: nupropagator>=0.0.2; extra == 'nupropagator'
Description-Content-Type: text/markdown

# NeutrinoTelescopeSimulation

[![PyPI - Version](https://img.shields.io/pypi/v/ntsim.svg)](https://pypi.org/project/ntsim)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ntsim.svg)](https://pypi.org/project/ntsim)

-----

**Table of Contents**

- [Installation](#installation)
- [Simulation](#Simulation)
- [Output format](#Output-format)
- [3D Viewer](#3D-Viewer)
- [License](#License)

## Installation

```console
pip install ntsim
```

If you also want to run the GUI utils (see [#Viewer](#Viewer) section), you need to install the optional dependencies:
```shell
pip install ntsim[gui]

```
## Simulation

### Getting Started
Starting from the version `v0.4` NTSim has become a toolkit, so the user can define the simulation pipeline in a separate runnable python script.
Examples of such scripts are located in `ntsim/run/run_*.py`. 

Each of these scripts defines a command-line interface, allowing user to set some of the parameters with arguments.

Check the list of available options:
```shell
python run/run_toygen.py -h
```

For example, running a simulation of 10 events with 1 TeV protons and saving it to `"sim_proton_1TeV.h5"`:
```shell
python run/run_toygen.py -E 1000 --primary_gen.pdg=2212 -o "sim_proton_1TeV.h5" 10
```

For more detailed explanation see [Getting_started](documentation/docs/getting_started.md) in the documentation.

## Analysis
NTSim provides `h5Reader` to read the output files and obtain events from the file and analyze them:

Read the hdf5 file using **h5Reader**
```python
from ntsim.IO.h5Reader import h5Reader

with h5Reader('ntsim_run_smt.h5') as f:
    geometry = f.geometry
    for e in range(len(f.events)):
        event = f.events[e]
        primary = event.particles["Primary"]
        track0 = event.tracks["g4_tracks_0"]
        hits = event.hits["Hits"]
        ...
```

## Output format

The main output format is the hdf5 file with the following tree structure:

*  `Header/`:
    * `run_configuration/`: 
    * `geometry/`
        * `Geometry`: dataset describing the individual modules position and geometry
* `event_<n>/`: group for each simulated event
    * `header/` general event information (metadata)
        * `id`: event number
        * `timestamp`: time information (seconds since epoch)
    * `particles/` information about primary particles.
        * `Primary` dataset for primary particles, to be processed by ParticlePropagator
        *  `g4_cascade_starters_<n>` datasets, containing secondary particles which start the parametrized cascades
    * `tracks/g4_tracks_<n>` track segments, results of the Geant4 propagation
    * `photons/photons_<n>/` groups for photons information
    * `hits/Hits`: dataset with the hits in the sensitive detectors

## 3D Viewer

Viewer reads `ntsim_events.h5` file and displays information from file. It allows to watch animation of particles propagation in 3D, it also can build histograms of physical parametres. Viewer helps to analyse results of simulation.

### Running

```shell
python3 -m ntsim.Viewer  
```
this will run an "open file" dialog to choose the simulation file to display.

```shell
python3 -m ntsim.Viewer h5_output/events.h5 
```
This will open defaut file named `"h5_output/events.h5"` produced by __NTSim__.

#### Some Options
If the display works slow, try to set minimal track length bigger.
```shell
python3 -m ntsim.Viewer h5_output/events.h5 --min_length_for_tracks 1
```
This will show only tracks bigger than 1 m.

To increase speed of animation try to set less amount of frames.
```shell
python3 -m ntsim.Viewer h5_output/events.h5 --animation_frames 10 0 3000
```
This will show only 10 frames in time interval from 0 to 3000


## License

`ntsim` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
