A Python package for simulating Cherenkov light yields from particle tracks and cascades in ice or water. The v2 API adds structured results, validation, and convenience helpers while keeping the classic v1 tuple API fully supported.
- What's New in v2.0.0
- Features
- Documentation
- Installation
- Quickstart (v2 API)
- Testing
- Development
- Citation
- Support
- Beta projects
π Major release with backward-compatible API improvements!
- Structured Results: New result container classes (
TrackYieldResult,EMYieldResult,HadronYieldResult) with named attributes and pretty printing - Convenience Methods: One-line calculations with
quick_track(),quick_cascade(), andcalculate() - Input Validation: Comprehensive validation with helpful error messages via
ValidationError - Enhanced Documentation: Complete MkDocs site with user guides, API reference, and examples
- 100% Backward Compatible: All v1.x methods continue to work identically
See the full Changelog and Upgrade Guide for details.
Note: The v2.0.0 release is currently only available via GitHub installation. PyPI still hosts v1.3.4.
- Muon Tracks: Energy loss mechanisms (ionization, bremsstrahlung, pair production) with wavelength-dependent yields
- EM Cascades: Electron, positron, and photon-initiated showers with longitudinal profiles and angular distributions
- Hadron Cascades: Pion, kaon, proton, and neutron showers with EM fraction tracking and muon production
- Validated Physics: Reference values from GEANT4 simulations ensure accuracy
- High Performance: NumPy-based calculations optimized for CPU efficiency
- GPU Acceleration: Optional JAX backend for massive speedups on large batches
- User-Friendly API: Intuitive interface with comprehensive type hints and documentation
- Flexible Configuration: YAML or dictionary-based configuration system
- Wavelength Grids: Customizable wavelength bins for spectral analysis
π Full Documentation Site (MkDocs)
-
Getting Started
- Installation Guide - PyPI, GitHub, and development setups
- Quickstart Tutorial - Your first calculations
- Basic Examples - Common use cases
-
User Guides
- Configuration - YAML and dictionary setup
- Muon Tracks - Track yield calculations
- EM Cascades - Electromagnetic showers
- Hadron Cascades - Hadronic showers
- Advanced Usage - JAX, batching, and optimization
-
API Reference
- Fennel Core API - Main interface
- Results Containers - v2 result objects
- Configuration - Config management
-
Development
- Contributor Guide - How to contribute
- PR Guide - PR guidelines and workflow
- Upgrade Guide - Migration from v1 to v2
- Changelog - Version history
- MkDocs sources: docs-mkdocs/ directory
- Build locally:
mkdocs serve(see docs-mkdocs/README.md)
PyPI (v1.3.4): Stable release with classic tuple-based API
GitHub (v2.0.0): Latest release with new structured API and convenience methods
PyPI is currently on v1.3.4 and uses the classic tuple API. For the new v2.0.0 API with structured results, validation, and convenience methods, install from GitHub until the PyPI package is updated.
pip install fennel_seedThis version uses tuple returns and is production-stable. Perfect if you need stability or have existing v1 code.
β Recommended for new projects - includes all v2 features while remaining 100% backward compatible.
# Base install
pip install "fennel_seed @ git+https://github.com/MeighenBergerS/fennel.git@master"
# With JAX for GPU acceleration
pip install "fennel_seed[jax] @ git+https://github.com/MeighenBergerS/fennel.git@master"
# With interactive/notebook features
pip install "fennel_seed[interactive] @ git+https://github.com/MeighenBergerS/fennel.git@master"π More installation options: Installation Guide
git clone https://github.com/MeighenBergerS/fennel.git
cd fennel
python3 -m venv .venv && source .venv/bin/activate
# Editable install
pip install -e .
# With development tools (testing, docs, linting)
pip install -e .[dev]Verify installation:
python -c "import fennel; print(f'Fennel {fennel.__version__} ready!')"Quick functionality check:
from fennel import Fennel
f = Fennel()
# v2 API
result = f.quick_track(energy=100.0, interaction="total")
print(f"Track result: {result.photons.sum():.2e} photons")
# v1 API (still works)
_, photons = f.track_yields(energy=100.0, particle=13)
print(f"Legacy API: {photons.sum():.2e} photons")
f.close()from fennel import Fennel
f = Fennel()
# π― Quick track calculation (100 GeV muon)
track = f.quick_track(energy=100.0, interaction="total")
print(f"Energy: {track.energy} GeV")
print(f"Particle: {track.particle_name}")
print(f"Total photons: {track.photons.sum():.2e}")
print(f"Yield shape: {track.dcounts.shape}")
# π― Quick cascade (automatically detects EM vs hadron)
cascade = f.quick_cascade(energy=1000.0, particle=11) # electron
print(f"Cascade from {cascade.particle_name}")
print(f"Profile: {cascade.longitudinal_profile.shape}")
# π― Universal calculator (auto-detects everything)
result = f.calculate(energy=500.0, particle=211) # Ο+ (hadron)
print(f"Type: {result.interaction}")
if hasattr(result, 'em_fraction'):
print(f"EM fraction: {result.em_fraction:.2%}")
f.close()# Structured results with named attributes
track = f.track_yields_v2(energy=100.0, particle=13, interaction="total")
print(track.wavelengths) # Named attribute instead of tuple unpacking
print(track.photons)
print(track.dcounts)
# Pretty printing
print(track) # Shows all contained data
# Legacy v1 API (100% compatible)
wavelengths, photons = f.track_yields(energy=100.0, particle=13)
print(f"v1 API: {photons.sum():.2e} photons")- π Full Quickstart Tutorial
- π Example Notebooks -
example_v2.ipynb,example.ipynb - π User Guides - Detailed usage for each feature
Fennel has comprehensive test coverage (123+ tests) covering API, validation, physics, and backward compatibility.
# Run all tests
pytest tests/
# Specific test suites
pytest tests/test_v2_api.py # v2 API features
pytest tests/test_physics_regression.py # Physics validation
pytest tests/test_integration.py # End-to-end tests
# With coverage report
pytest --cov=fennel tests/See TEST_SETUP_COMPLETE.md for test infrastructure details.
Contributions are welcome! Please see CONTRIBUTING.md for:
- How to set up your development environment
- Code style and testing guidelines
- Pull request process
- Commit conventions
Also see:
- Testing Guide - Running and writing tests
- PR Guide - Pull request workflow
- Commit Guide - Commit conventions
This repository uses pre-commit hooks for code quality and notebook cleanliness.
# Install hooks
pip install pre-commit
pre-commit install
# Run on all files
pre-commit run --all-files
# Specific hooks
pre-commit run nbstripout --all-files # Clean notebook outputsBuild and serve documentation locally:
# Install MkDocs
pip install -r docs-mkdocs/requirements.txt
# Serve locally (with live reload)
mkdocs serve
# Build static site
mkdocs buildDocumentation source: docs-mkdocs/
If you use Fennel in your research, please cite:
@software{fennel2024,
author = {Meighen-Berger, Stephan},
title = {Fennel: Cherenkov Light Yield Simulation},
url = {https://github.com/MeighenBergerS/fennel},
version = {2.0.0},
year = {2024}
}Fennel uses the Aachen parametrization based on GEANT4 simulations. Please also cite:
RΓ€del, L., & Wiebusch, C. (2012). Calculation of the Cherenkov light yield from low energetic secondary particles accompanying high-energy muons in ice and water with Geant4 simulations. Astroparticle Physics, 38, 53-67. doi:10.1016/j.astropartphys.2012.09.008
Additional references: Citation Guide
- π Documentation: https://meighenbergers.github.io/fennel/
- π Bug Reports: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π§ Contact: Open an issue or discussion for questions
Common issues and solutions:
- Import errors: Ensure you have Python 3.8+ and all dependencies installed
- Version confusion: Check
fennel.__version__to verify which version you have - JAX issues: JAX is optional; install with
pip install fennel_seed[jax] - Validation errors: v2 API provides detailed error messages - read them carefully!
For more help, see the documentation or open an issue.
Fennel includes experimental subprojects available in the repository:
A GEANT4-based interface for generating and validating parametrizations.
- Location: seed/ directory
- Requirements: GEANT4 installation (tested on Linux)
- Documentation: See seed/README.md
- Examples: Included in seed/examples/
License: MIT - See LICENSE.txt for details