Metadata-Version: 2.4
Name: pygemc
Version: 0.2.0
Summary: Python API for GEMC geometry definition and output analysis
Project-URL: Homepage, https://gemc.github.io/home/
Project-URL: Repository, https://github.com/gemc/pygemc
Author-email: Maurizio Ungaro <ungaro@jlab.org>
License: ---
        layout: default
        permalink: /license/
        ---
        
        {% include mynotes.html %}
        
        [//]: # (Notice: I copied the content of src/LICENSE.md here to have it rendered by Jekyll)
        
        # GEMC Software License
        
        *Version 1.0, May 28, 2026*
        
        > [!WARNING]
        > Copyright (c) 2006–2026,
        > Maurizio Ungaro and Thomas Jefferson National Accelerator Facility (`Jefferson Lab`).
        > <br/>
        > All rights not expressly granted under this license are reserved.
        
        <br/>
        This software includes voluntary contributions made to the GEMC project.
        Additional information about GEMC may be provided in the accompanying
        documentation or repository.
        
        Installation, use, reproduction, display, modification, and redistribution of
        this software, with or without modification, in source and binary forms, are
        permitted on a non-exclusive basis. Any exercise of rights by you under this
        license is subject to the following conditions:
        
        <br/><br/>
        
        
        ## 1\. Redistributions
        
        Redistributions of this software, in whole or in part, with or without
        modification, must reproduce the above copyright notice and these license
        conditions in (a) the source code, (b) the user documentation, and (c) any
        other materials provided with the redistributed software.
        
        <br/>
        
        
        ## 2\. User Documentation
        
        The user documentation, if any, included with a redistribution, must
        include the following notice:
        
        ```
        This product includes the GEMC software developed by Maurizio Ungaro
        at Thomas Jefferson National Accelerator Facility (Jefferson Lab).
        ```
        
        If that is where third-party acknowledgments normally appear, this
        acknowledgment must also be reproduced in any modified version of this
        software itself.
        
        <br/>
        
        
        ## 3\. Scientific Citation
        
        Publications or presentations that use this software
        or results produced with it must include the following citation:
        
        ```bash
        M. Ungaro, Geant4 Monte-Carlo (GEMC): A database-driven simulation program, 
        EPJ Web of Conferences 295, 05005 (2024),
        https://doi.org/10.1051/epjconf/202429505005
        ```
        
        ```latex
        \bibitem{2024EPJWC.29505005U}
        {Ungaro}, M.: Geant4 Monte-Carlo (GEMC) A database-driven simulation program.
        \newblock European Physical Journal Web of Conferences \textbf{295}, 05005 (2024).
        \newblock \doi{10.1051/epjconf/202429505005}
        ```
        
        ```bibtex 
        @INPROCEEDINGS{2024EPJWC.29505005U,
               author = { {Ungaro}, Maurizio,
                title = "{Geant4 Monte-Carlo (GEMC) A database-driven simulation program}",
            booktitle = {European Physical Journal Web of Conferences},
                 year = 2024,
               series = {European Physical Journal Web of Conferences},
               volume = {295},
                month = may,
                  eid = {05005},
                pages = {05005},
                  doi = {10.1051/epjconf/202429505005},
               adsurl = {https://ui.adsabs.harvard.edu/abs/2024EPJWC.29505005U},
              adsnote = {Provided by the SAO/NASA Astrophysics Data System}
        }
        ```
        
        <br/>
        
        
        ## 4\. Names and Endorsement
        
        The names `GEMC` and `GEMC: Geant4 Monte-Carlo` may not be used to endorse or promote
        software or products derived from this software except with prior written permission
        from the copyright holders. For permissions, contact: [gemc@jlab.org](mailto: gemc@jlab.org).
        If this software is redistributed in a modified form, the name and reference of the modified
        version must be clearly distinguishable from that of this software.
        
        <br/>
        
        
        ## 5\. Modifications
        
        You are under no obligation to provide anyone with any modifications of this software
        that you may develop, including but not limited to bug fixes, patches, upgrades, or other
        enhancements or derivatives of features, functionality, or performance.
        However, if you publish or distribute your modifications without contemporaneously
        requiring users to enter into a separate written license agreement, then you are deemed to
        have granted Maurizio Ungaro, Jefferson Lab, and all contributors to GEMC a license to your
        modifications, including modifications protected by any patent owned or controlled by you,
        under the conditions of this license.
        
        <br/>
        
        
        ## 6\. Patents
        
        You may not include this software, in whole or in part, in any patent or
        patent application in respect of any modification of this software developed
        by you.
        
        <br/>
        
        ## 7\. Third-Party Software
        
        This software may be distributed with or may require third-party components (including,
        without limitation, Geant4, CLHEP, Qt, ROOT, SQLite, Assimp, and others) that are separately
        licensed. Such components are provided under their respective licenses, and you must comply
        with those licenses in addition to this one. Where required (for example, by the Geant4
        license), you must reproduce the applicable notices and acknowledgments in your redistribution.
        
        <br/>
        
        
        ## 8\. DISCLAIMER
        
        **THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
        MERCHANTABILITY, SATISFACTORY QUALITY, AND FITNESS FOR A PARTICULAR PURPOSE OR USE
        ARE DISCLAIMED. THE COPYRIGHT HOLDERS AND CONTRIBUTORS MAKE NO REPRESENTATION THAT
        THE SOFTWARE, OR MODIFICATIONS THEREOF, WILL NOT INFRINGE ANY PATENT, COPYRIGHT,
        TRADE SECRET, OR OTHER PROPRIETARY RIGHT.**
        
        <br/>
        
        
        ## 9\. LIMITATION OF LIABILITY
        
        **IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
        INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES OF ANY
        CHARACTER INCLUDING, WITHOUT LIMITATION, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES,
        LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION, HOWEVER CAUSED AND ON ANY THEORY
        OF CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY, OR OTHERWISE,
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
        OF SUCH DAMAGES.**
        
        <br/>
        
        
        ## 10\. Termination
        
        This license shall terminate with immediate effect and without notice if you fail
        to comply with any of its terms, or if you institute litigation against any copyright
        holder or contributor with regard to this software.
License-File: LICENSE.md
Keywords: detector,geant4,gemc,physics,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyqt6
Requires-Dist: pyvista
Requires-Dist: pyvistaqt
Requires-Dist: vtk
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: root
Requires-Dist: awkward; extra == 'root'
Requires-Dist: uproot; extra == 'root'
Description-Content-Type: text/markdown

# pygemc

[![Tests][tests-badge]][tests]
[![Python][python-badge]][pyproject]
[![PyPI][pypi-badge]][pypi]
[![License: GEMC][license-badge]][license]
[![GEMC documentation][docs-badge]][docs]

`pygemc` is the Python API used by [GEMC](https://github.com/gemc/src) to define detector geometry, materials, optical properties, mirrors, geometry variations, and lightweight output-analysis workflows. It lets users build GEMC databases with Python scripts, preview geometry with PyVista, and inspect GEMC CSV or ROOT output without writing C++.

The package is installed as part of the GEMC source build and can also be developed as a standalone Python project.

## Features

- Python classes for GEMC geometry and material databases
- `GVolume` helpers for common Geant4 solids such as boxes, tubes, cones, and trapezoids
- `GMaterial` helpers for chemical formulas, fractional-mass mixtures, and optical/scintillation properties
- `GConfiguration` run, variation, factory, SQLite, ASCII, and PyVista configuration handling
- `autogeometry()` convenience setup for detector scripts
- SQLite and ASCII database output
- PyVista rendering, interactive Qt display, and VTK.js `.vtksz` export for geometry inspection and documentation
- `gemc-system-template` CLI for generating ready-to-run detector systems
- Python code snippets for supported Geant4 solid constructors
- `gemc-analyzer` CLI for summarizing and plotting GEMC CSV or ROOT output
- Unit conversion helpers for length, angle, time, and energy strings
- Pytest suite that does not require a compiled `gemc` binary

## Installation

Use a Python virtual environment for direct `pip` installs:

```shell
python3 -m venv ~/venv/pygemc
source ~/venv/pygemc/bin/activate
python -m pip install --upgrade pip
```

### Stable PyPI Install

Install `pygemc` with:

```shell
python -m pip install pygemc
```

Optional ROOT-file analysis dependencies:

```shell
python -m pip install "pygemc[root]"
```

### Development Snapshot

Install the moving GitHub `dev` prerelease with:

```shell
python -m pip install "pygemc @ git+https://github.com/gemc/pygemc.git@dev"
```

Use this when you need the latest development version before the next stable PyPI release.

### Local Clone Development Install

Use this when you are editing `pygemc` from a local clone:

```shell
git clone https://github.com/gemc/pygemc.git
cd pygemc
python -m pip install -e ".[dev]"
```

Optional ROOT-file analysis dependencies for local development:

```shell
python -m pip install -e ".[dev,root]"
```

The package requires Python 3.10 or newer and depends on NumPy, VTK, PyVista, PyVistaQt, PyQt6, pandas, and matplotlib.

### Installed with GEMC

When GEMC is built from source, the parent Meson project installs `pygemc` into the GEMC Python environment. After adding the GEMC Python environment to `PATH`, the commands below are available:

```shell
gemc-system-template --help
gemc-analyzer --help
```

## Quickstart

Create a detector template:

```shell
gemc-system-template -s counter
cd counter
./counter.py
```

The generated system contains:

| File | Purpose |
| --- | --- |
| `counter.py` | Main geometry-builder script |
| `geometry.py` | Example volumes, including a flux detector |
| `materials.py` | Example methane-gas material |
| `counter.yaml` | GEMC steering card |
| `README.md` | Placeholder notes for the generated detector |

Run with PyVista visualization:

```shell
./counter.py -pv
```

Export a VTK.js scene:

```shell
./counter.py -pvvtk counter -pvz 0.25
```

Run the generated simulation with GEMC when the compiled `gemc` executable is available:

```shell
gemc counter.yaml
```

Analyze output:

```shell
gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50
```

## Geometry API

Typical geometry scripts create a configuration and publish volumes/materials to it:

```python
from pygemc import GMaterial, GVolume, autogeometry

cfg = autogeometry("examples", "counter")

gas = GMaterial("methaneGas")
gas.description = "methane gas CH4 0.000667 g/cm3"
gas.density = 0.000667
gas.addNAtoms("C", 1)
gas.addNAtoms("H", 4)
gas.publish(cfg)

flux = GVolume("flux_box")
flux.description = "air flux box"
flux.make_box(40.0, 40.0, 2.0)
flux.set_position(0, 0, 100)
flux.material = "G4_AIR"
flux.color = "3399FF"
flux.style = 1
flux.digitization = "flux"
flux.set_identifier("box", 2)
flux.publish(cfg)
```

Common command-line options accepted by geometry scripts:

| Option | Purpose |
| --- | --- |
| `-f`, `--factory` | Select `sqlite` or `ascii` output |
| `-v`, `--variation` | Select the geometry variation |
| `-r`, `--run` | Select the run number |
| `-sql`, `--dbhost` | Select the SQLite file path |
| `-pv` | Show a PyVista window |
| `-pvb` | Show a PyVistaQt background plotter |
| `-pvvtk` | Export a VTK.js `.vtksz` scene |
| `-pvz` | Set the VTK.js export zoom |

## PyVista Visualization

PyVista support is central to `pygemc`: geometry scripts can display the detector as they build it, open an interactive Qt viewer, or export a `.vtksz` scene that can be published in documentation.

<!-- PyVista gallery setting: edit width="300" height="300" below to resize all thumbnails. -->
| B1 | B2 |
| --- | --- |
| <a href="https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=https://gemc.github.io/home/assets/images/examples/b1/b1.vtksz"><img src="https://gemc.github.io/home/assets/images/examples/b1/geometry.png" alt="B1 PyVista geometry" width="300" height="300"></a> | <a href="https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=https://gemc.github.io/home/assets/images/examples/b2/b2.vtksz"><img src="https://gemc.github.io/home/assets/images/examples/b2/geometry.png" alt="B2 PyVista geometry" width="300" height="300"></a> |
| Materials | Simple Flux |
| <a href="https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=https://gemc.github.io/home/assets/images/examples/materials/material.vtksz"><img src="https://gemc.github.io/home/assets/images/examples/materials/geometry.png" alt="Materials PyVista geometry" width="300" height="300"></a> | <a href="https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=https://gemc.github.io/home/assets/images/examples/simple_flux/simple_flux.vtksz"><img src="https://gemc.github.io/home/assets/images/examples/simple_flux/geometry.png" alt="Simple Flux PyVista geometry" width="300" height="300"></a> |

Open the linked interactive PyVista scenes generated from the GEMC examples.

GitHub README pages cannot embed `.vtksz` files directly, so the preview image links to the hosted VTK.js viewer.

## Command-Line Tools

### `gemc-system-template`

Generate a detector skeleton:

```shell
gemc-system-template -s counter
```

List supported solid snippets:

```shell
gemc-system-template -sl
```

Print a volume-construction snippet:

```shell
gemc-system-template -gv G4Box
```

Write a snippet to a file:

```shell
gemc-system-template -gv G4Tubs -write_to geometry.py -geo_sub build_tube
```

### `gemc-analyzer`

Summarize an output file:

```shell
gemc-analyzer counter_t0_digitized.csv --kind csv
```

Plot a variable:

```shell
gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50
```

Save a figure without opening a GUI:

```shell
gemc-analyzer out.root E --kind root --detector flux --save energy.png
```

Analyzer inputs:

- CSV output files or CSV root names
- ROOT files when `pygemc[root]` dependencies are installed
- Digitized and true-information data streams

## Tests

Run the standalone Python tests:

```shell
pytest
pytest tests/test_cli.py
pytest tests/test_geometry.py
pytest -v
pytest -k "sqlite"
```

The tests cover CLI behavior and geometry database generation. They intentionally do not require Geant4 or a compiled `gemc` executable; full simulation tests live in the parent GEMC Meson build.

## Project Layout

| Path | Purpose |
| --- | --- |
| `src/pygemc/api/` | Geometry, materials, units, SQLite output, PyVista support, and templates |
| `src/pygemc/analyzer/` | CSV/ROOT readers, plotting, and analyzer CLI |
| `tests/` | Standalone pytest suite |
| `releases/` | Release notes |
| `pyproject.toml` | Python packaging metadata and console scripts |
| `meson.build` | Meson subproject integration used by GEMC |

## Documentation

- [GEMC homepage](https://gemc.github.io/home/)
- [Python API overview](https://gemc.github.io/home/documentation/api/pyvista_api.html)
- [Quickstart](https://gemc.github.io/home/documentation/quickstart/)
- [Examples](https://gemc.github.io/home/examples/)
- [GEMC source repository](https://github.com/gemc/src)

## Contributing

Keep patches focused and run the relevant pytest targets before opening a pull request. If a change affects the integrated GEMC build, also run the parent repository Meson tests for the affected examples or modules.

## License

`pygemc` is distributed under the GEMC Software License, the same license used by the main GEMC source repository. See [`LICENSE.md`](LICENSE.md).

[tests]: https://github.com/gemc/pygemc/actions/workflows/pygemc_tests.yml
[tests-badge]: https://github.com/gemc/pygemc/actions/workflows/pygemc_tests.yml/badge.svg
[python-badge]: https://img.shields.io/badge/python-3.10%2B-blue.svg
[pypi]: https://pypi.org/project/pygemc/
[pypi-badge]: https://img.shields.io/pypi/v/pygemc.svg
[license]: LICENSE.md
[license-badge]: https://img.shields.io/badge/license-GEMC-blue.svg
[docs]: https://gemc.github.io/home/
[docs-badge]: https://img.shields.io/badge/docs-gemc.github.io-blue.svg
[pyproject]: pyproject.toml
