feat: #1136 - [E5-F2-P3] Add latent heat energy release tracking function with tests

[Gorkowski]

Target Branch: main

Fixes #1136 | Workflow: e18c0b2d

Summary

Adds a diagnostic helper to convert condensed/evaporated mass into latent heat energy, matching the sign convention for condensation (>0) and evaporation (<0). Re-exports the helper through particula.dynamics and documents the non-isothermal utilities in the docs index/README. Comprehensive tests cover precision, broadcasting, and validation for invalid inputs.

What Changed

New/Modified Components

• particula/dynamics/condensation/mass_transfer.py — Added get_latent_heat_energy_released with validation, dtype normalization, and sign-preserving energy bookkeeping.
• particula/dynamics/__init__.py — Re-exported the new latent heat energy helper in the public API.
• particula/dynamics/condensation/tests/mass_transfer_test.py — Added precision, sign, zero-case, broadcasting, and validation tests for the new helper.
• readme.md, docs/index.md — Mentioned latent-heat utilities and energy bookkeeping in the feature highlights.

Tests Added/Updated

• mass_transfer_test.py — Precision (rtol 1e-14), sign convention, zero latent heat/mass transfer, broadcasting (1D/2D, scalar/array latent heat), and validation for negative latent heat and non-finite mass transfer.

How It Works

Latent heat energy bookkeeping multiplies step-level mass transfer by latent heat while preserving sign:

mass_transfer (kg/step)
    │
    └── get_latent_heat_energy_released
            │
            ▼
       Q = dm × L  →  energy released (>0) or absorbed (<0) [J]

Validation enforces finite mass_transfer and nonnegative latent_heat; outputs are normalized to np.float64 and broadcast according to NumPy rules.

Implementation Notes

• Follows existing condensation helper patterns: @validate_inputs, dtype normalization via np.asarray(..., dtype=np.float64), and sign-preserving multiplication.
• Public API parity maintained through particula.dynamics re-export.
• Docs updated to surface non-isothermal condensation utilities and the new energy bookkeeping helper.

Testing

• Unit tests: pytest particula/dynamics/condensation/tests/mass_transfer_test.py (new cases for energy helper covering precision, sign, broadcasting, zeros, and validation).
• Prior workflow: Full test suite ran in the workflow’s test phase; no new failures observed.

[Copilot]

Pull request overview

This PR adds a small diagnostic utility to track latent-heat energy exchange from condensation/evaporation steps (using the existing sign convention), exposes it via the particula.dynamics public API, and updates docs/README to surface the capability.

Changes:

• Added get_latent_heat_energy_released(mass_transfer, latent_heat) to compute latent heat energy bookkeeping as Q = dm * L with input validation.
• Re-exported the helper through particula.dynamics for public API access.
• Added unit tests covering precision, sign convention, zero cases, broadcasting, and invalid inputs; updated docs/README references.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
particula/dynamics/condensation/mass_transfer.py	Adds the latent heat energy bookkeeping helper with @validate_inputs and float64 output casting.
particula/dynamics/__init__.py	Re-exports the new helper in the particula.dynamics public API.
particula/dynamics/condensation/tests/mass_transfer_test.py	Adds test coverage for precision, sign, broadcasting, zeros, and validation errors for the new helper.
readme.md	Updates feature list to mention the new latent heat energy helper.
docs/index.md	Updates the homepage feature bullets to include latent-heat energy bookkeeping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Gorkowski]

ADW Code Review

PR: #1145 - feat: #1136 - [E5-F2-P3] Add latent heat energy release tracking function with tests
Review Date: 2026-03-03
Reviewers: Code Quality, Correctness, Performance (C++/Python), Security

---

Summary

Severity	Count
Critical	0
Warning	2
Suggestion	3

---

Critical Issues (Must Fix)

None.

---

Warnings (Should Fix)

• particula/dynamics/condensation/mass_transfer.py:~340–367 - Array-like inputs can multiply incorrectly before coercion to NumPy arrays (list repetition / TypeError risk).
• particula/dynamics/condensation/mass_transfer.py:~330 - Missing finiteness validation for latent_heat allows NaN/inf to propagate.

---

Suggestions (Overview)

• Add a public re-export path test for par.dynamics.get_latent_heat_energy_released.
• Add an Examples: section in the new public helper docstring illustrating usage/sign convention.
• Consider an overflow guard for extreme magnitudes (post-check or clamp) in user-facing contexts.

---

Positive Observations

• Consistent use of @validate_inputs on the new public helper.
• Tests cover sign convention, zero cases, broadcasting, and validation.
• Public API re-export aligns with established particula.dynamics patterns.

---

Inline Comments

Detailed feedback has been posted as inline comments on the following locations:

• particula/dynamics/condensation/mass_transfer.py:~340–367 - Coerce inputs before multiply
• particula/dynamics/condensation/mass_transfer.py:~330 - Add finite validation for latent_heat

---

This review was generated by ADW Multi-Agent Code Review System.
Reviewers: Quality, Correctness, C++ Performance, Python Performance, Security

[Gorkowski]

WARNING: Coerce array-like inputs before multiplication

mass_transfer * latent_heat runs before coercion, so list inputs can repeat ([1,2] * 2 -> [1,2,1,2]) or error (list * float).

Suggested fix:

mass_transfer = np.asarray(mass_transfer, dtype=np.float64)
latent_heat = np.asarray(latent_heat, dtype=np.float64)
return mass_transfer * latent_heat

This ensures elementwise math, consistent dtype, and predictable broadcasting.

[Gorkowski]

WARNING: Add finite validation for latent_heat

Validation currently allows NaN/inf values that can silently poison downstream calculations (e.g., 0 * inf -> NaN).

Suggested fix:

@validate_inputs(
    {
        "mass_transfer": "finite",
        "latent_heat": "finite",
        "latent_heat": "nonnegative",
    }
)

This prevents invalid numerical states from propagating.

[Gorkowski]

🤖 Agent Developer Workflow

• Description: Direct PR fix workflow triggered by request:fix label. Analyzes actionable review comments, generates fix plan, implements changes, validates, polishes, tests, formats, and ships fixes without creating intermediate GitHub issues.
• ADW ID: 8f9b9041
• Current Phase: Workflow completed successfully
• Current Step: Analyze actionable PR review comments and generate implementation plan
• Started: 2026-03-04T01:34:06.516808Z
• Last Update: 2026-03-04T01:49:45.730650Z

Current Status

• ✅ Workflow completed in 15m 37s

Workflow Plan

• ✅ Analyze PR Comments (at 2026-03-04T01:34:39.477911Z)
• ✅ Build Implementation (at 2026-03-04T01:37:18.125586Z)
• ✅ Validate Implementation and Fix Gaps (at 2026-03-04T01:37:58.728973Z)
• ✅ Polish Code (at 2026-03-04T01:38:46.214176Z)
• ✅ Run Tests (at 2026-03-04T01:48:35.889365Z)
• ✅ Format Code and Add Docstrings (at 2026-03-04T01:49:10.187103Z)
• ✅ Ship Fix (at 2026-03-04T01:49:43.881119Z)

📋 Recent Activity

[2026-03-04T01:37:58.728987Z] Completed step 3/7: Validate Implementation and Fix Gaps
[2026-03-04T01:38:00.389359Z] Starting step 4/7: Polish Code
[2026-03-04T01:38:46.214192Z] Completed step 4/7: Polish Code
[2026-03-04T01:38:47.904592Z] Starting step 5/7: Run Tests
[2026-03-04T01:48:35.889381Z] Completed step 5/7: Run Tests
[2026-03-04T01:48:37.525461Z] Starting step 6/7: Format Code and Add Docstrings
[2026-03-04T01:49:10.187124Z] Completed step 6/7: Format Code and Add Docstrings
[2026-03-04T01:49:11.931986Z] Starting step 7/7: Ship Fix
[2026-03-04T01:49:43.881145Z] Completed step 7/7: Ship Fix
[2026-03-04T01:49:45.728788Z] Workflow fix finished: 7/7 steps completed

🔍 Archived Updates

[2026-03-04T01:34:06.589170Z] Workflow fix started with 7 steps
[2026-03-04T01:34:08.551736Z] Starting step 1/7: Analyze PR Comments
[2026-03-04T01:34:39.477941Z] Completed step 1/7: Analyze PR Comments
[2026-03-04T01:34:41.319090Z] Starting step 2/7: Build Implementation
[2026-03-04T01:37:18.125607Z] Completed step 2/7: Build Implementation
[2026-03-04T01:37:19.736443Z] Starting step 3/7: Validate Implementation and Fix Gaps

---

This comment is automatically updated as the workflow progresses

[Gorkowski]

Fix Summary

Addressed PR #1145 conversation feedback by normalizing inputs for latent heat energy bookkeeping, tightening validation, adding public re-export coverage, and documenting usage/sign conventions.

Changes Made

• Coerced array-like inputs to np.asarray(..., dtype=np.float64) before multiplication to avoid list repetition/type errors.
• Added finiteness validation for latent_heat while retaining nonnegative constraints.
• Added a public re-export path test for par.dynamics.get_latent_heat_energy_released and expanded tests for precision/broadcasting/zero cases.
• Added an Examples: section to the helper docstring to document sign convention and usage.

Review Comments Addressed

• Input coercion to NumPy arrays before multiplication (np.asarray with float64).
• Finiteness validation for latent_heat while keeping nonnegative constraint.
• Public re-export path test and docstring Examples: section. (No explicit comment IDs recorded.)

Files Changed

• docs/index.md
• particula/dynamics/init.py
• particula/dynamics/condensation/mass_transfer.py
• particula/dynamics/condensation/tests/mass_transfer_test.py
• readme.md

---

Automated fix by ADW workflow 8f9b9041