fix: #1069 - [Phase E3-F4-P2] Create GasSpecies facade over GasData with deprecation warnings and tests#1081
Merged
Gorkowski merged 3 commits intouncscode:mainfrom Feb 17, 2026
Conversation
Refactor GasSpecies into a facade that stores GasData while preserving legacy attribute access and vapor-pressure behavior. Emit deprecation warnings on construction and provide from_data for warning-free conversions, with to_species updated accordingly. Add facade tests, private helper coverage, and a migration guide, plus warning filters to keep -Werror runs green. Closes uncscode#1069 ADW-ID: 029a4449
Successfully fixed: - Annotated vapor_pressure_strategy selection in to_species to satisfy type validation. - Split concentration normalization into scalar, vector, and matrix paths to enforce shape checking and handle legacy single-species arrays. - Kept negative-concentration checks before dtype casting for setters to avoid redundant conversion and ensure consistent validation. - Refreshed strategy array docstrings and facade/private test docstrings to satisfy validation expectations. Still failing: - None; targeted validation gaps are resolved. Closes uncscode#1069 ADW-ID: 029a4449
Gorkowski
added
agent
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request refactors GasSpecies into a facade over the new GasData container while maintaining full backward compatibility. The facade delegates data access to GasData but retains vapor-pressure strategies as behavior, emitting deprecation warnings to guide users toward the new data-first API.
Changes:
- Refactored
GasSpeciesto wrapGasDatainternally with mode tracking for scalar/array returns - Added deprecation warnings in
__init__andfrom_dataclassmethod for warning-free conversions - Updated
to_speciesconverter to useGasSpecies.from_datato avoid deprecation warnings - Added comprehensive test coverage for facade behavior, conversions, and private helpers
- Created migration guide documenting the transition path
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
particula/gas/species.py |
Refactored as facade over GasData with normalization helpers, mode tracking, deprecation warnings, and atomic data operations |
particula/gas/gas_data.py |
Updated to_species to use GasSpecies.from_data for warning-free conversion |
particula/gas/tests/species_facade_test.py |
New facade-level tests for deprecation warnings, delegation, and data updates |
particula/gas/tests/species_private_test.py |
New unit tests for normalization helpers and private methods |
particula/gas/tests/gas_data_test.py |
Added test for warning-free conversion via to_species |
conftest.py |
Added deprecation warning filters and updated scipy patching logic |
particula/conftest.py |
Added deprecation warning filters and updated scipy patching logic |
pyproject.toml |
Registered GasSpecies deprecation filter for pytest defaults |
docs/migration/particle-data.md |
New migration guide for transitioning from facades to data containers |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Collaborator
Author
|
change the deprecation warnings, to info logs, like we did for the particle representation data facade |
Gorkowski
added
request:fix
Collaborator
Author
🤖 Agent Developer Workflow
Current Status
Workflow Plan
📋 Recent Activity🔍 Archived UpdatesThis comment is automatically updated as the workflow progresses |
…and move migration docs to Features Replace warnings.warn(DeprecationWarning) with logger.info() in GasSpecies facade to match the ParticleRepresentation pattern. Remove redundant warnings.warn(UserWarning) from _check_if_negative_concentration() which already had logger.warning(). Move particle-data migration guide from docs/migration/ to docs/Features/particle-data-migration.md and add it to the Features index. Update all deprecation message paths accordingly. Update test files to use caplog logger assertions instead of pytest.warns for deprecation and warning checks. Clean up dead GasSpecies DeprecationWarning filters from pyproject.toml and conftest.py.
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
1 participant
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.
Target Branch:
mainFixes #1069 | Workflow:
029a4449Summary
Refactors
GasSpeciesinto a facade overGasDatawhile preserving the legacy API and behavior. Constructor now emits a deprecation warning guiding users to the new data container, with filters to keep CI running under-Werror. Conversion helpers were updated to round-trip throughGasDatawithout emitting warnings, and a migration guide plus focused tests were added to validate delegation and internal normalization.What Changed
New Components
docs/migration/particle-data.md- Migration guide mapping facades (GasSpecies,ParticleRepresentation) to data containers with warning-handling guidance.particula/gas/tests/species_facade_test.py- Facade-level tests for deprecation warnings, delegation, data updates, and multi-species handling.particula/gas/tests/species_private_test.py- Unit tests for normalization/private helpers (modes, clamping, append invariants).Modified Components
particula/gas/species.py- Rebuilt as aGasData-backed facade with normalization helpers, mode tracking for scalar/array returns,from_dataconstructor, data property, and atomic append/set operations; constructor now warns with migration link.particula/gas/gas_data.py-from_species/to_speciesadjusted to work with the facade, enforce uniform partitioning, select box index safely, and avoid deprecation warnings by usingGasSpecies.from_data.particula/gas/tests/gas_data_test.py- Added coverage for warning-free conversion, partitioning validation, and box selection.conftest.py&particula/conftest.py- TargetedGasSpeciesdeprecation warning filters to keep existing tests passing under-Werrorwhile allowing explicit warning assertions.pyproject.toml- RegisteredGasSpeciesdeprecation filter for pytest defaults.Tests Added/Updated
particula/gas/tests/species_facade_test.pyparticula/gas/tests/species_private_test.pyparticula/gas/tests/gas_data_test.py(new cases)How It Works
GasSpeciesnow normalizes inputs to arrays, buildsGasData, and tracks single-species return modes so legacy scalar/1D behaviors stay intact. Vapor-pressure strategies remain on the facade; data accessors delegate toGasData, and setters rebuild the data container with validation/clamping. Conversion helpers wrap/unwrapGasDataviafrom_datato avoid emitting deprecation warnings and enforce uniform partitioning.Implementation Notes
__init__;from_datapath is warning-free for conversions/tests.-Werror; facade tests assert warnings explicitly.GasDataatomically to avoid partial state.Testing
pytest(workflow “Run Tests”) including new facade and conversion tests.