{"id":50370796,"url":"https://github.com/gemc/pygemc","last_synced_at":"2026-06-14T08:01:08.530Z","repository":{"id":359597427,"uuid":"1244705303","full_name":"gemc/pygemc","owner":"gemc","description":"API for gemc3 and analyzer scripts","archived":false,"fork":false,"pushed_at":"2026-06-06T19:04:24.000Z","size":161,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T21:06:16.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gemc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T14:13:28.000Z","updated_at":"2026-06-06T19:04:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gemc/pygemc","commit_stats":null,"previous_names":["gemc/pygemc"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/gemc/pygemc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fpygemc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fpygemc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fpygemc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fpygemc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gemc","download_url":"https://codeload.github.com/gemc/pygemc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fpygemc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34313515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T07:01:19.298Z","updated_at":"2026-06-14T08:01:08.524Z","avatar_url":"https://github.com/gemc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pygemc\n\n[![Tests][tests-badge]][tests]\n[![Python][python-badge]][pyproject]\n[![PyPI][pypi-badge]][pypi]\n[![License: GEMC][license-badge]][license]\n[![GEMC documentation][docs-badge]][docs]\n\n`pygemc` is the Python API used by [GEMC](https://github.com/gemc/src) to define detector geometry, materials, optical properties, mirrors, \nand lightweight output-analysis workflows. It lets users build GEMC databases with Python scripts, preview geometry \nwith PyVista, and inspect GEMC CSV or ROOT output without writing C++.\n\nThe package is installed with pip or as part of the GEMC source build.\n\n## Features\n\n- Python classes for GEMC geometry and material databases\n- `GVolume` helpers for common Geant4 solids such as boxes, tubes, cones, and trapezoids\n- `GVolume.g4placement_type` to select the `G4Transform3D` active or passive constructor\n- `GMaterial` helpers for chemical formulas, fractional-mass mixtures, and optical/scintillation properties\n- `GConfiguration` run, variation, factory, SQLite, ASCII, and PyVista configuration handling\n- `autogeometry()` convenience setup for detector scripts\n- SQLite and ASCII database output\n- PyVista rendering, interactive Qt display, and VTK.js `.vtksz` export for geometry inspection and documentation\n- `gemc-system-template` CLI for generating ready-to-run detector systems\n- Python code snippets for supported Geant4 solid constructors\n- `gemc-sqlite` CLI for creating and inspecting GEMC SQLite database files\n- `gemc-analyzer` CLI for summarizing and plotting GEMC CSV or ROOT output\n- Unit conversion helpers for length, angle, time, and energy strings\n- Pytest suite that does not require a compiled `gemc` binary\n\n\u003cbr/\u003e\n\n# Installation\n\n## Stable PyPI Install\n\nUse a Python virtual environment for direct `pip` installs. \nOn macOS with Homebrew use `/opt/homebrew/bin/python3` to ensure the correct interpreter is used:\n\n```shell\n/opt/homebrew/bin/python3 -m venv ~/venv/pygemc\nsource ~/venv/pygemc/bin/activate\npython -m pip install --upgrade pip\n```\n\nInstall [`pygemc` from PyPI](https://pypi.org/project/pygemc/) with:\n\n```shell\npython -m pip install pygemc\n```\nOptional ROOT-file analysis dependencies:\n\n```shell\npython -m pip install \"pygemc[root]\"\n```\n\n\n## Install with GEMC\n\nWhen GEMC is built from source, pygemc available in your scripts without \nany activation step or separate pip install and gemc and Python tools are available:\n\n```shell\ngemc -v\ngemc-system-template --help\ngemc-sqlite --help\ngemc-analyzer --help\n```\n\n\u003cbr/\u003e\n\n# Quickstart\n\nCreate a detector template:\n\n```shell\ngemc-system-template -s counter\ncd counter\n./counter.py\n```\n\nThe generated system contains:\n\n| File           | Purpose                                      |\n| -------------- | -------------------------------------------- |\n| `counter.py`   | Main geometry-builder script                 |\n| `geometry.py`  | Example volumes, including a flux detector   |\n| `materials.py` | Example methane-gas material                 |\n| `counter.yaml` | GEMC steering card                           |\n| `README.md`    | Placeholder notes for the generated detector |\n\nRun with PyVista visualization:\n\n```shell\n./counter.py -pv\n```\n\nExport a VTK.js scene:\n\n```shell\n./counter.py -pvvtk counter -pvz 0.25\n```\n\nUse a light flat background for documentation exports:\n\n```shell\n./counter.py -pvvtk counter -pvbg \"0.92 0.92 0.98\" -pvbgt none\n```\n\nRun the generated simulation with GEMC when the compiled `gemc` executable is available:\n\n```shell\ngemc counter.yaml\n```\n\nAnalyze output:\n\n```shell\ngemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50\n```\n\n\u003cbr/\u003e\n\n# Geometry API\n\nTypical geometry scripts create a configuration and publish volumes/materials to it:\n\n```python\nfrom pygemc import GMaterial, GVolume, autogeometry\n\ncfg = autogeometry(\"examples\", \"counter\")\n\ngas = GMaterial(\"methaneGas\")\ngas.description = \"methane gas CH4 0.000667 g/cm3\"\ngas.density = 0.000667\ngas.addNAtoms(\"C\", 1)\ngas.addNAtoms(\"H\", 4)\ngas.publish(cfg)\n\nflux = GVolume(\"flux_box\")\nflux.description = \"air flux box\"\nflux.make_box(40.0, 40.0, 2.0)\nflux.set_position(0, 0, 100)\nflux.material = \"G4_AIR\"\nflux.color = \"3399FF\"\nflux.style = 1\nflux.digitization = \"flux\"\nflux.set_identifier(\"box\", 2)\nflux.publish(cfg)\n```\n\n## Placement convention\n\n`GVolume.g4placement_type` selects which Geant4 placement convention GEMC should use for a volume:\n\n| Value     | Meaning                                                                                  |\n| --------- | ---------------------------------------------------------------------------------------- |\n| `active`  | Default; uses `G4Transform3D(rotation, translation)`                                     |\n| `passive` | Uses `G4PVPlacement(rotation, translation, ...)`, matching GEMC2/clas12Tags conventions |\n\nMost new GEMC3 geometry can use the default `active` convention. Detector systems ported from GEMC2 that rely on\nframe rotations should set:\n\n```python\ngvolume.g4placement_type = \"passive\"\n```\n\nThis field is written to SQLite geometry databases. Existing SQLite databases are upgraded with the missing\ncolumn when a geometry script publishes new rows.\n\nCommon command-line options accepted by geometry scripts:\n\n| Option              | Purpose                                                                       |\n| ------------------- | ----------------------------------------------------------------------------- |\n| `-f`, `--factory`   | Select `sqlite` or `ascii` output                                             |\n| `-v`, `--variation` | Select the geometry variation                                                 |\n| `-r`, `--run`       | Select the run number                                                         |\n| `-sql`, `--dbhost`  | Select the SQLite file path                                                   |\n| `-pv`               | Show a PyVista window                                                         |\n| `-pvb`              | Show a PyVistaQt background plotter                                           |\n| `-pvvtk`            | Export a VTK.js `.vtksz` scene                                                |\n| `-pvz`              | Set the VTK.js export zoom                                                    |\n| `-pvbg`             | Set the PyVista background color as a name, hex string, or `r g b` triple    |\n| `-pvbgt`            | Set the optional PyVista top gradient color; use `none` for a flat background |\n| `--read-yaml`       | Read `g4camera` direction and `g4view.background` settings from a GEMC YAML   |\n\n## PyVista Visualization\n\nPyVista support is central to `pygemc`: geometry scripts can display the detector as they build it,\nopen an interactive Qt viewer, or export a `.vtksz` scene that can be published in documentation.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eExample\u003c/th\u003e\n    \u003cth\u003ePreview\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eB1\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=/home/assets/images/examples/b1/b1.vtksz\"\u003e\n        \u003cimg src=\"https://gemc.github.io/home/assets/images/examples/b1/gemc_view.png\"\n             alt=\"B1 PyVista\" width=\"180\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eB2\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=/home/assets/images/examples/b2/b2.vtksz\"\u003e\n        \u003cimg src=\"https://gemc.github.io/home/assets/images/examples/b2/gemc_view.png\"\n             alt=\"B2 PyVista\" width=\"180\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eMaterials\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=/home/assets/images/examples/materials/material.vtksz\"\u003e\n        \u003cimg src=\"https://gemc.github.io/home/assets/images/examples/materials/gemc_view.png\"\n             alt=\"Materials PyVista\" width=\"180\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eSimple Flux\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://gemc.github.io/home/assets/vtkjs-viewer.html?fileURL=/home/assets/images/examples/simple_flux/simple_flux.vtksz\"\u003e\n        \u003cimg src=\"https://gemc.github.io/home/assets/images/examples/simple_flux/gemc_view.png\"\n             alt=\"Simple Flux PyVista\" width=\"180\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nOpen the linked interactive PyVista scenes generated from the GEMC examples.\n\nGitHub README pages cannot embed `.vtksz` files directly, so the preview image links to the hosted VTK.js viewer.\n\n## Command-Line Tools\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eCommand\u003c/th\u003e\n      \u003cth\u003eWhat it does\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-system-template -s counter\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eGenerate a detector skeleton named \u003ccode\u003ecounter\u003c/code\u003e.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-system-template -sl\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eList supported Geant4 solid snippets.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-system-template -gv G4Box\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003ePrint a volume-construction snippet for a \u003ccode\u003eG4Box\u003c/code\u003e.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-system-template -gv G4Tubs -write_to geometry.py -geo_sub build_tube\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eWrite a \u003ccode\u003eG4Tubs\u003c/code\u003e snippet to \u003ccode\u003egeometry.py\u003c/code\u003e.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-sqlite -n mydetector.sqlite\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eCreate a new SQLite database with the GEMC geometry and materials schema.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-sqlite -sql mydetector.sqlite -sv\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eOpen an existing database and list its volumes.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-sqlite -sql mydetector.sqlite -sm\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eOpen an existing database and list its materials.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\n        \u003ccode\u003egemc-sqlite -sql mydetector.sqlite -sv -ef examples -vf default -sf counter -rf 1\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003eFilter listed volumes by experiment, variation, system, and run number.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-analyzer counter_t0_digitized.csv --kind csv\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eSummarize a GEMC CSV output file.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003ePlot a digitized variable with 50 bins.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr style=\"background-color: #f6f8fa;\"\u003e\n      \u003ctd\u003e\n        \u003ccode\u003e\n          gemc-analyzer counter_t0_true_info.csv --kind csv --data true_info --plot yvsx --xlim -20 20\n          --ylim -20 20\n        \u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003ePlot true hit positions in the y-vs-x plane.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003egemc-analyzer out.root E --kind root --detector flux --save energy.png\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eSave a ROOT-based analyzer figure without opening a GUI.\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Tests\n\nRun the standalone Python tests:\n\n```shell\npytest\npytest tests/test_analyzer.py\npytest tests/test_cli.py\npytest tests/test_gconfiguration_yaml.py\npytest tests/test_geometry.py\npytest -v\npytest -k \"sqlite\"\n```\n\nThe tests cover analyzer plotting, CLI behavior, YAML-driven PyVista configuration, and geometry database\ngeneration. They intentionally do not require Geant4 or a compiled `gemc` executable; full simulation tests live\nin the parent GEMC Meson build.\n\n## Project Layout\n\n| Path                   | Purpose                                                                   |\n| ---------------------- | ------------------------------------------------------------------------- |\n| `src/pygemc/api/`      | Geometry, materials, units, SQLite output, PyVista support, and templates |\n| `src/pygemc/analyzer/` | CSV/ROOT readers, plotting, and analyzer CLI                              |\n| `tests/`               | Standalone pytest suite                                                   |\n| `releases/`            | Release notes                                                             |\n| `pyproject.toml`       | Python packaging metadata and console scripts                             |\n| `meson.build`          | Meson subproject integration used by GEMC                                 |\n\n## Documentation\n\n- [GEMC homepage](https://gemc.github.io/home/)\n- [Python API overview](https://gemc.github.io/home/documentation/api/pyvista_api.html)\n- [Quickstart](https://gemc.github.io/home/documentation/quickstart/)\n- [Examples](https://gemc.github.io/home/examples/)\n- [GEMC source repository](https://github.com/gemc/src)\n- [CLAS12 GEMC systems repository](https://github.com/gemc/clas12-systems)\n- [Documentation website repository](https://github.com/gemc/home)\n- [GEMC2 / CLAS12 repository](https://github.com/gemc/clas12Tags)\n\n## Contributing\n\nKeep 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.\n\n## License\n\n`pygemc` is distributed under the GEMC Software License, the same license used by the main GEMC source repository. See [`LICENSE.md`](LICENSE.md).\n\n[tests]: https://github.com/gemc/pygemc/actions/workflows/pygemc_tests.yml\n[tests-badge]: https://github.com/gemc/pygemc/actions/workflows/pygemc_tests.yml/badge.svg\n[python-badge]: https://img.shields.io/badge/python-3.10%2B-blue.svg\n[pypi]: https://pypi.org/project/pygemc/\n[pypi-badge]: https://img.shields.io/pypi/v/pygemc.svg?cacheSeconds=300\n[license]: LICENSE.md\n[license-badge]: https://img.shields.io/badge/license-GEMC-blue.svg\n[docs]: https://gemc.github.io/home/\n[docs-badge]: https://img.shields.io/badge/docs-gemc.github.io-blue.svg\n[pyproject]: pyproject.toml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemc%2Fpygemc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgemc%2Fpygemc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemc%2Fpygemc/lists"}