feat: #1135 - [E5-F2-P2] Add non-isothermal mass transfer rate function with tests by Gorkowski · Pull Request #1144 · uncscode/particula

Gorkowski · 2026-03-03T21:22:32Z

Target Branch: main

Fixes #1135 | Workflow: 12b5f7df

Summary

Adds a latent-heat-aware mass transfer rate helper that preserves exact isothermal parity while applying the thermal resistance correction from Phase 1. Re-exports the function through particula.dynamics and extends the condensation tests to lock parity, magnitude reduction, broadcasting, and validation behaviors. Dev-plan and docs indices were refreshed to reflect the new non-isothermal capability.

What Changed

New Components

None

Modified Components

particula/dynamics/condensation/mass_transfer.py - Added get_mass_transfer_rate_latent_heat, applying the thermal resistance factor and preserving isothermal parity when latent heat is zero.
particula/dynamics/__init__.py - Re-exported get_mass_transfer_rate_latent_heat for public API access.
particula/dynamics/condensation/tests/mass_transfer_test.py - Added parity, reduction, broadcasting, and validation tests for the new function.
adw-docs/dev-plans/features/E5-F2-non-isothermal-mass-transfer.md and indices (adw-docs/dev-plans/README.md, adw-docs/dev-plans/features/index.md, docs/index.md, readme.md) - Documented the feature and links.

Tests Added/Updated

particula/dynamics/condensation/tests/mass_transfer_test.py - Isothermal parity (scalar/array), rate reduction for latent heat > 0, water 293 K reference, shape broadcasting mix, and validation error coverage for latent heat, temperature, and molar mass.

How It Works

get_mass_transfer_rate_latent_heat wraps the existing isothermal rate and divides by the thermal resistance factor baseline to preserve parity and apply latent-heat slowdown:

get_mass_transfer_rate_latent_heat()
    ├── get_thermal_resistance_factor(...)
    │       └── r_specific * T baseline when latent_heat = 0
    ├── correction = thermal_factor / (r_specific * temperature)
    ├── isothermal_rate = get_mass_transfer_rate(...)
    └── return isothermal_rate / correction  # dtype float64

Implementation Notes

Parity: When latent_heat = 0, correction = 1 so the result matches get_mass_transfer_rate to rtol=1e-15 (locked by tests).
Latent heat > 0 reduces magnitude for both condensation and evaporation; thermal factor stays positive so division is safe.
Full broadcasting via np.asarray on all inputs; validation through @validate_inputs mirrors existing constraints and adds thermal parameters.

Testing

Unit tests: pytest particula/dynamics/condensation/tests/mass_transfer_test.py
Manual verification: Not required (behavior locked by unit tests)

Add get_mass_transfer_rate_latent_heat using the thermal resistance factor and preserve isothermal parity when latent heat is zero. Export the function through particula.dynamics and expand mass_transfer tests to cover parity, rate reduction, broadcasting, and validation errors. Closes uncscode#1135 ADW-ID: 12b5f7df

Update E5-F2 planning docs and epic metadata to reflect the active P2 phase. Refresh public-facing docs and README highlights for latent-heat mass transfer utilities, and refine the mass-transfer docstring for consistency. Closes uncscode#1135 ADW-ID: 12b5f7df

Copilot

Pull request overview

Adds a latent-heat-aware (non-isothermal) mass transfer rate helper to the condensation dynamics utilities, re-exported through particula.dynamics, and expands unit test coverage to lock in isothermal parity and non-isothermal behavior.

Changes:

Added get_mass_transfer_rate_latent_heat() that applies the Phase 1 thermal resistance correction while preserving exact isothermal parity when latent_heat=0.
Re-exported the new helper from particula.dynamics for public API access.
Extended condensation mass transfer tests to cover parity, reduction, broadcasting, and validation; refreshed related docs/dev-plan indices.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
readme.md	Updates feature bullets to mention the new latent-heat mass transfer helper.
particula/dynamics/condensation/mass_transfer.py	Adds `get_mass_transfer_rate_latent_heat()` wrapping isothermal rate with thermal resistance correction.
particula/dynamics/init.py	Re-exports `get_mass_transfer_rate_latent_heat` via the public dynamics API.
particula/dynamics/condensation/tests/mass_transfer_test.py	Adds unit tests for parity, reduction, broadcasting, and validation of the new helper.
docs/index.md	Updates docs landing page to mention non-isothermal condensation support.
adw-docs/dev-plans/features/index.md	Marks E5-F2 as in progress.
adw-docs/dev-plans/features/E5-F2-non-isothermal-mass-transfer.md	Updates phase status/details and links to issue #1135.
adw-docs/dev-plans/epics/E5-non-isothermal-condensation.md	Refreshes epic status context with the in-progress phase reference.
adw-docs/dev-plans/README.md	Updates dev-plan index to show E5-F2 as in progress.

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

Copilot · 2026-03-03T21:25:55Z

particula/dynamics/condensation/mass_transfer.py

+    Args:
+        pressure_delta: Difference in partial pressure [Pa].
+        first_order_mass_transport: Mass transport coefficient K [m³/s].
+        temperature: Temperature T [K].
+        molar_mass: Molar mass M [kg/mol].
+        latent_heat: Latent heat of vaporization L [J/kg].
+        thermal_conductivity: Gas thermal conductivity kappa [W/(m·K)].
+        vapor_pressure_surface: Equilibrium vapor pressure at the surface
+            [Pa].
+        diffusion_coefficient: Vapor diffusion coefficient D [m²/s].
+
+    Returns:
+        Non-isothermal mass transfer rate [kg/s], matching the broadcasted
+        input shape.
+
+    Raises:
+        ValueError: If any validated inputs violate positive/nonnegative


Docstring section headers here use "Args:" while the surrounding functions in this module use the "Arguments:" / "Returns:" format (often with leading hyphen bullets). To keep the documentation style consistent (and avoid doc rendering inconsistencies), please align this docstring’s section headers/format with the rest of mass_transfer.py (e.g., change "Args:" to "Arguments:" and match bullet styling).

Suggested change

Args:

pressure_delta: Difference in partial pressure [Pa].

first_order_mass_transport: Mass transport coefficient K [m³/s].

temperature: Temperature T [K].

molar_mass: Molar mass M [kg/mol].

latent_heat: Latent heat of vaporization L [J/kg].

thermal_conductivity: Gas thermal conductivity kappa [W/(m·K)].

vapor_pressure_surface: Equilibrium vapor pressure at the surface

[Pa].

diffusion_coefficient: Vapor diffusion coefficient D [m²/s].

Returns:

Non-isothermal mass transfer rate [kg/s], matching the broadcasted

input shape.

Raises:

ValueError: If any validated inputs violate positive/nonnegative

Arguments:

- pressure_delta: Difference in partial pressure [Pa].

- first_order_mass_transport: Mass transport coefficient K [m³/s].

- temperature: Temperature T [K].

- molar_mass: Molar mass M [kg/mol].

- latent_heat: Latent heat of vaporization L [J/kg].

- thermal_conductivity: Gas thermal conductivity kappa [W/(m·K)].

- vapor_pressure_surface: Equilibrium vapor pressure at the surface

[Pa].

- diffusion_coefficient: Vapor diffusion coefficient D [m²/s].

Returns:

- Non-isothermal mass transfer rate [kg/s], matching the broadcasted

input shape.

Raises:

- ValueError: If any validated inputs violate positive/nonnegative

Gorkowski · 2026-03-03T21:26:03Z

ADW Code Review

PR: #1144 - feat: #1135 - [E5-F2-P2] Add non-isothermal mass transfer rate function with tests
Review Date: 2026-03-03
Reviewers: Code Quality, Correctness, Performance (C++/Python), Security

Summary

Severity	Count
Critical	0
Warning	4
Suggestion	2

Critical Issues (Must Fix)

None.

Warnings (Should Fix)

mass_transfer.py:~201 - Guard thermal_factor <= 0 to avoid invalid correction values.
mass_transfer.py:~201 - Update get_thermal_resistance_factor docstring to Google-style Args/Returns.
mass_transfer.py:(return in get_mass_transfer_rate_latent_heat) - Use np.asarray instead of np.array to avoid a copy.
tests - Add validation tests for diffusion_coefficient, thermal_conductivity, vapor_pressure_surface.

Suggestions (Overview)

Add an Examples section to get_mass_transfer_rate_latent_heat docstring.
Consider a fast-path to skip repeated np.asarray conversions in hot paths.

Positive Observations

Non-isothermal mass transfer rate functionality is clearly scoped.
Tests are included for the new behavior.

Inline Comments

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

mass_transfer.py:~201 - guard thermal_factor <= 0
mass_transfer.py:~201 - docstring Args/Returns format
mass_transfer.py:(return in get_mass_transfer_rate_latent_heat) - np.asarray vs np.array

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

Gorkowski · 2026-03-03T21:26:11Z

WARNING: Guard invalid thermal correction factor

thermal_factor can be <= 0, which will yield invalid correction values downstream.

Suggested fix:

if thermal_factor <= 0:
    raise ValueError("thermal_factor must be positive")

This ensures the correction remains physical and avoids divide-by-zero/negative factors.

Gorkowski · 2026-03-03T21:26:11Z

WARNING: Avoid extra copy in return

np.array(...) will copy; np.asarray(...) preserves existing arrays.

Suggested fix:

return np.asarray(result)

This reduces allocations in hot paths.

Gorkowski · 2026-03-03T21:26:11Z

WARNING: Docstring should use Google-style Args/Returns

get_thermal_resistance_factor docstring should include explicit Args: and Returns: blocks.

Suggested fix:

Args:
    ...
Returns:
    ...

This keeps docstrings consistent with repo conventions.

Gorkowski · 2026-03-04T00:22:36Z

🤖 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: 86e769a4
Current Phase: Workflow completed successfully
Current Step: Analyze actionable PR review comments and generate implementation plan
Started: 2026-03-04T00:22:35.152616Z
Last Update: 2026-03-04T00:38:34.180511Z

Current Status

✅ Workflow completed in 15m 57s

Workflow Plan

✅ Analyze PR Comments (at 2026-03-04T00:23:06.323866Z)
✅ Build Implementation (at 2026-03-04T00:25:58.460417Z)
✅ Validate Implementation and Fix Gaps (at 2026-03-04T00:26:31.807218Z)
✅ Polish Code (at 2026-03-04T00:27:28.846267Z)
✅ Run Tests (at 2026-03-04T00:37:19.935842Z)
✅ Format Code and Add Docstrings (at 2026-03-04T00:37:56.003138Z)
✅ Ship Fix (at 2026-03-04T00:38:32.459972Z)

📋 Recent Activity

[2026-03-04T00:26:31.807238Z] Completed step 3/7: Validate Implementation and Fix Gaps
[2026-03-04T00:26:33.580435Z] Starting step 4/7: Polish Code
[2026-03-04T00:27:28.846294Z] Completed step 4/7: Polish Code
[2026-03-04T00:27:30.429726Z] Starting step 5/7: Run Tests
[2026-03-04T00:37:19.935861Z] Completed step 5/7: Run Tests
[2026-03-04T00:37:21.674446Z] Starting step 6/7: Format Code and Add Docstrings
[2026-03-04T00:37:56.003159Z] Completed step 6/7: Format Code and Add Docstrings
[2026-03-04T00:37:57.720404Z] Starting step 7/7: Ship Fix
[2026-03-04T00:38:32.459988Z] Completed step 7/7: Ship Fix
[2026-03-04T00:38:34.178521Z] Workflow fix finished: 7/7 steps completed

🔍 Archived Updates

[2026-03-04T00:22:35.222046Z] Workflow fix started with 7 steps
[2026-03-04T00:22:37.307805Z] Starting step 1/7: Analyze PR Comments
[2026-03-04T00:23:06.323897Z] Completed step 1/7: Analyze PR Comments
[2026-03-04T00:23:08.031399Z] Starting step 2/7: Build Implementation
[2026-03-04T00:25:58.460435Z] Completed step 2/7: Build Implementation
[2026-03-04T00:26:00.051826Z] Starting step 3/7: Validate Implementation and Fix Gaps

This comment is automatically updated as the workflow progresses

Add a non-positive thermal factor check to prevent invalid non-isothermal corrections and update mass transfer helpers for consistent docstrings and array handling. Add validation coverage for diffusion, conductivity, and surface pressure inputs, and refresh dev-plan status notes. Closes uncscode#1144 ADW-ID: 86e769a4

Gorkowski · 2026-03-04T00:38:30Z

Fix Summary

Addressed actionable review feedback for non-isothermal mass transfer updates, including docstring alignment, validation guards, and test coverage for thermal inputs.

Changes Made

Aligned docstring section headers/bullets in mass_transfer.py and updated get_thermal_resistance_factor to Google-style Args/Returns.
Added guard for thermal_factor <= 0 with a clear ValueError.
Switched to np.asarray in get_mass_transfer_rate_latent_heat return path to avoid unnecessary copies.
Added validation tests for diffusion_coefficient, thermal_conductivity, and vapor_pressure_surface inputs.

Review Comments Addressed

Docstring formatting alignment for mass_transfer.py (reviewer: @Copilot).
Guarding invalid thermal_factor inputs.
np.asarray refactor in latent heat mass transfer helper.
New validation tests for thermal/diffusion inputs.

(Review comment IDs were not recorded in the workflow state; items are summarized from the spec plan.)

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 86e769a4

Gorkowski added 2 commits March 3, 2026 14:04

Copilot AI review requested due to automatic review settings March 3, 2026 21:22

Gorkowski added agent Created or managed by ADW automation blocked Blocked - review required before ADW can process labels Mar 3, 2026

Copilot started reviewing on behalf of Gorkowski March 3, 2026 21:23 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

Gorkowski added request:fix Request AI to implement review suggestions adw:in-progress ADW workflow actively processing - remove to re-trigger and removed blocked Blocked - review required before ADW can process labels Mar 4, 2026

Gorkowski merged commit ddf76c3 into uncscode:main Mar 4, 2026
7 checks passed

Gorkowski deleted the issue-1135-adw-12b5f7df branch March 4, 2026 00:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: #1135 - [E5-F2-P2] Add non-isothermal mass transfer rate function with tests#1144

feat: #1135 - [E5-F2-P2] Add non-isothermal mass transfer rate function with tests#1144
Gorkowski merged 3 commits intouncscode:mainfrom
Gorkowski:issue-1135-adw-12b5f7df

Gorkowski commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 4, 2026 •

edited

Loading

Uh oh!

Gorkowski commented Mar 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Gorkowski commented Mar 3, 2026

Summary

What Changed

New Components

Modified Components

Tests Added/Updated

How It Works

Implementation Notes

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Gorkowski commented Mar 3, 2026

ADW Code Review

Summary

Critical Issues (Must Fix)

Warnings (Should Fix)

Suggestions (Overview)

Positive Observations

Inline Comments

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 3, 2026

Uh oh!

Gorkowski commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Agent Developer Workflow

Current Status

Workflow Plan

Uh oh!

Gorkowski commented Mar 4, 2026

Fix Summary

Changes Made

Review Comments Addressed

Files Changed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Gorkowski commented Mar 4, 2026 •

edited

Loading