Title: Release v2.0.0: new v2 API, validation, docs, and tooling#3
Merged
Conversation
MeighenBergerS
commented
Jan 9, 2026
MeighenBergerS
commented
Owner
-
- add structured result containers (TrackYieldResult, EMYieldResult, HadronYieldResult) with pretty printing and particle names
- introduce v2 API methods (track_yields_v2, em_yields_v2, hadron_yields_v2) plus convenience helpers (quick_track, quick_cascade, calculate)
- enforce comprehensive input validation via fennel.validation with improved error messages and type hints
- document migration in UPGRADE_GUIDE_V2.md and new example notebook example_v2.ipynb; extend docstrings
- add GitHub Actions CI, pre-commit hooks, and MkDocs site
- note 100% backward compatibility with v1.x while bumping to version 2.0.0
- include PR workflow guidance in the changelog and link to the new PR guide from the README
- Add TrackYieldResult, EMYieldResult, HadronYieldResult classes for structured results - Implement comprehensive input validation with ValidationError - Add convenience methods: calculate(), quick_track(), quick_cascade() - Maintain 100% backward compatibility with v1.x API - Fix 8 failing tests to use public API instead of private methods - Fix longitudinal profile shape assertions in integration tests - Add complete test suite with 117 passing tests (6 skipped for JAX) - Add v2 API example notebook and upgrade guide - Add pre-commit hooks, CI/CD workflows, and documentation infrastructure - Add CHANGELOG.md, COMMIT_GUIDE.md for best practices All tests pass: 117 passed, 6 skipped
… cleaning Changes: - README.md: Added v2 installation sections (from source, from GitHub direct URL) - README.md: Clarified that current PyPI v1.3.4; master contains v2.0 - .gitignore: Added patterns for virtualenv directories (venv*/, .venv*/) - .pre-commit-config.yaml: Added nbstripout hook for automatic notebook cleaning - .pre-commit-config.yaml: Migrated to latest format (fixed deprecation warnings) - COMMIT_GUIDE.md: Documented notebook stripping in pre-commit section - All notebooks: Stripped outputs via nbstripout (outputs removed, metadata normalized) Impact: - Users can now install v2 from source or directly from GitHub - Developers can clone and install with pre-commit hooks enabled - Jupyter notebooks stay clean in version control (no cell outputs) - All pre-commit warnings resolved; ready for future updates BREAKING: None - documentation and tooling only
Changes: - .github/workflows/tests.yml: Remove branch restrictions from push and pull_request triggers - Tests now run on all branches (not just master/develop) - Helps catch issues early in feature branches via CI - Manual workflow_dispatch still available for on-demand runs Impact: - All branches now get tested across Python 3.8-3.11 - All OS platforms (Ubuntu, macOS, Windows) tested for each push - Faster feedback on feature branches during development
Changes: - .github/workflows/tests.yml: Update actions/upload-artifact from v3 to v4 - Fixes deprecation warning with runner 2.330.0+ - v4 is the current stable version - fennel/__init__.py: Add integrate_trapezoid() utility function - Wrapper around np.trapezoid (NumPy 2.0+) or np.trapz (NumPy <2.0) - Handles function name change across NumPy versions - Backward compatible with Python 3.8 and older numpy - Exported in __all__ for public use Impact: - GitHub Actions tests now run without deprecation warnings - Package works across all supported NumPy versions - Python 3.8+ users can use fennel with older numpy without trapezoid errors - All tests now pass on Python 3.8-3.11
- add trapezoid_compat helper in tests and replace np.trapezoid usage - update doc/examples to use integrate_trapezoid wrapper - keep CI artifact upload action at v4 (already updated)
There was a problem hiding this comment.
Pull request overview
This PR introduces Fennel v2.0.0, a major release that adds structured result containers, comprehensive input validation, enhanced documentation, and modern development tooling while maintaining 100% backward compatibility with the v1.x API.
Key Changes:
- New v2 API methods (
track_yields_v2,em_yields_v2,hadron_yields_v2) returning structured result containers with pretty printing - Comprehensive input validation with helpful error messages via
fennel.validationmodule - Convenience methods (
quick_track,quick_cascade,calculate) for simplified usage - Extensive test suite with physics regression tests to ensure numerical stability
- Documentation improvements including docstrings, MkDocs site configuration, and example notebook
- Development infrastructure: GitHub Actions CI, pre-commit hooks, pytest configuration
Reviewed changes
Copilot reviewed 54 out of 59 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_v2_api.py | Tests for new v2 API with result containers, validation, and backward compatibility |
| tests/test_tracks.py | Unit tests for Track class with NumPy and JAX backends |
| tests/test_physics_regression.py | Physics regression tests with reference values from v1.3.4 |
| tests/test_integration.py | Integration tests for full Fennel workflows |
| tests/test_hadron_cascades.py | Unit tests for Hadron_Cascade class |
| tests/test_em_cascades.py | Unit tests for EM_Cascade class |
| tests/test_config.py | Tests for configuration system |
| tests/conftest.py | Pytest fixtures and compatibility utilities |
| tests/reference_values_v1.3.4.json | Gold standard physics values for regression testing |
| tests/init.py | Test suite initialization |
| tests/README.md | Comprehensive testing documentation |
| fennel/validation.py | Input validation with helpful error messages |
| fennel/results.py | Result container dataclasses (TrackYieldResult, EMYieldResult, HadronYieldResult) |
| fennel/fennel.py | Main interface with v2 API methods and extensive documentation |
| fennel/tracks.py | Track calculations with improved docstrings and type hints |
| fennel/photons.py | Photon calculations with enhanced documentation |
| fennel/particle.py | Particle definitions with improved docstrings |
| fennel/hadron_cascades.py | Hadron cascade calculations with better documentation |
| fennel/em_cascades.py | EM cascade calculations with enhanced docstrings |
| fennel/main.py | Updated version to 2.0.0 |
| notebooks/example_v2.ipynb | Example notebook demonstrating v2 API features |
| pyproject.toml | Project configuration with dependencies and tooling |
| pytest.ini | Pytest configuration with test markers |
| mkdocs.yml | MkDocs documentation site configuration |
| docs-mkdocs/requirements.txt | Documentation build dependencies |
| docs-mkdocs/javascripts/mathjax.js | MathJax configuration for math rendering |
| docs-mkdocs/api/tracks.md | API documentation for Track class |
| scripts/generate_reference_values.py | Script to generate physics regression reference values |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Owner
Author
|
@copilot open a new pull request to apply changes based on the comments in this thread |
Contributor
|
@MeighenBergerS I've opened a new pull request, #4, to work on those changes. Once the pull request is ready, I'll request review from you. |
Co-authored-by: MeighenBergerS <18549087+MeighenBergerS@users.noreply.github.com>
Remove unused imports and variables flagged in code review
Owner
Author
|
After PR #4 the new version seems good and it passes all of the test. Merging into master. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.