fix(validate): address validation gaps for #1148

Successfully fixed:
- Refactored CondensationLatentHeat.step into helpers to reduce complexity and keep behavior intact.
- Sanitized non-finite pressure_delta values to mirror isothermal behavior.
- Validated volume/concentration inputs for norm_conc and raise clear errors.
- Normalized mass_transfer shape before latent heat energy accounting.
- Clamped gas concentration updates to nonnegative values.
- Documented latent heat energy units and expanded latent heat step tests.

Remaining issues: none.

Closes #1148

ADW-ID: 31535132

Author: Gorkowski

adw-docs/dev-plans/README.md

@@ -77,7 +77,7 @@ and rollout.
   - Scope: Thermal resistance factor and non-isothermal mass transfer rate
     pure functions with energy tracking.
 - [E5-F3: CondensationLatentHeat Strategy Class][e5-f3] — Status: In Progress
-  (P3, #1141)
+  (P1, #1139)
   - Scope: New condensation strategy with latent heat correction and energy
     diagnostics.
 - [E5-F4: Builder, Factory, and Exports][e5-f4] — Status: Planning

adw-docs/dev-plans/epics/E5-non-isothermal-condensation.md

@@ -284,7 +284,7 @@ L -> 0 as T -> T_c. Used in engineering thermodynamics and EOS-based models.
     relative), reduced rate when L > 0 (thermal resistance always slows
     condensation), array shapes for single and multi-species
 
-- [x] **E5-F3-P3**: Implement `step()` for particle-resolved with energy
+- [ ] **E5-F3-P3**: Implement `step()` for particle-resolved with energy
   tracking and tests
   - `step()` follows `CondensationIsothermal.step()` flow (lines 922-1040)
     with two additions:
@@ -623,4 +623,3 @@ class CondensationLatentHeat(CondensationStrategy):
 | 2026-03-02 | Initial epic creation | ADW |
 | 2026-03-02 | Split E5-F1-P3 into P3 (builders) + P4 (factory+exports); split E5-F3-P3 into P3 (particle-resolved step) + P4 (discrete+continuous) + P5 (data-only parity); added missing details: function signatures, file references, thermal conductivity source, vapor_pressure_surface parameter, test tolerances, literature targets | ADW |
 | 2026-03-04 | Noted E5-F3-P1 issue #1139 and logging expectations | ADW |
-| 2026-03-04 | Marked E5-F3-P3 complete for issue #1141 | ADW |

adw-docs/dev-plans/features/E5-F3-condensation-latent-heat-strategy.md

@@ -146,9 +146,9 @@ additions:
   - Tests: numerical parity with `CondensationIsothermal` when L=0 (< 1e-15
     relative), reduced rate when L > 0, array shapes for single/multi-species
 
-- [x] **E5-F3-P3**: Implement `step()` for particle-resolved with energy
+- [ ] **E5-F3-P3**: Implement `step()` for particle-resolved with energy
   tracking and tests
-  - Issue: #1141 | Size: M (~100 LOC) | Status: Complete
+  - Issue: TBD | Size: M (~100 LOC) | Status: Not Started
   - `step()` follows `CondensationIsothermal.step()` flow (lines 922-1040)
     with two additions:
     1. Uses `mass_transfer_rate` from P2 (includes thermal correction)
@@ -241,4 +241,3 @@ additions:
 |------|--------|--------|
 | 2026-03-02 | Initial feature document created from E5 epic | ADW |
 | 2026-03-04 | Marked P1 in progress for issue #1139 | ADW |
-| 2026-03-04 | Completed P3 step() implementation and tests (issue #1141) | ADW |

adw-docs/dev-plans/features/index.md

@@ -28,7 +28,7 @@ work, typically ~100 LOC per phase, that deliver user-facing functionality.
 |----|------|--------|----------|--------|
 | E5-F1 | [Latent Heat Strategy Pattern](E5-F1-latent-heat-strategy.md) | In Progress | P1 | 4 |
 | E5-F2 | [Non-Isothermal Mass Transfer Functions](E5-F2-non-isothermal-mass-transfer.md) | Planning | P1 | 3 |
-| E5-F3 | [CondensationLatentHeat Strategy Class](E5-F3-condensation-latent-heat-strategy.md) | In Progress (P3) | P1 | 5 |
+| E5-F3 | [CondensationLatentHeat Strategy Class](E5-F3-condensation-latent-heat-strategy.md) | In Progress | P1 | 5 |
 | E5-F4 | [Builder, Factory, and Exports](E5-F4-builder-factory-exports.md) | Planning | P1 | 2 |
 | E5-F5 | [Validation and Integration Tests](E5-F5-validation-integration-tests.md) | Planning | P1 | 2 |
 | E5-F6 | [Documentation and Examples](E5-F6-documentation-examples.md) | Planning | P2 | 3 |

docs/Features/condensation_strategy_system.md

@@ -165,13 +165,16 @@ particle, gas = latent.step(
     time_step=1.0,
     dynamic_viscosity=1.8e-5,
 )
-energy_released = latent.last_latent_heat_energy
+energy_released = latent.last_latent_heat_energy  # total energy [J]
 ```
 
 When no latent heat strategy is configured (or a nonpositive scalar is
 provided), the step follows the isothermal path and reports
 `last_latent_heat_energy = 0.0`.
 
+`last_latent_heat_energy` records the total latent heat released per step
+(sum of dm × L), not an energy density.
+
 ### CondensationIsothermalStaggered (two-pass Gauss-Seidel)
 
 `CondensationIsothermalStaggered` splits each timestep into two passes. Theta

particula/dynamics/condensation/condensation_strategies.py

@@ -1762,7 +1762,7 @@ class CondensationLatentHeat(CondensationStrategy):
     Attributes:
         latent_heat_strategy_input: Strategy input provided at initialization.
         latent_heat_input: Raw latent heat value provided at initialization.
-        last_latent_heat_energy: Net latent heat energy released in the most
+        last_latent_heat_energy: Total latent heat energy released in the most
             recent step [J]. Positive values indicate condensation and
             negative values indicate evaporation. Overwritten each call.
     """
@@ -1955,11 +1955,9 @@ def mass_transfer_rate(
         pressure_delta = self.calculate_pressure_delta(
             particle, gas_species, temperature, radius_with_fill
         )
-        if not np.all(np.isfinite(pressure_delta)):
-            raise ValueError(
-                "Non-finite pressure_delta computed for latent-heat "
-                "condensation."
-            )
+        pressure_delta = np.nan_to_num(
+            pressure_delta, posinf=0.0, neginf=0.0, nan=0.0
+        )
 
         if self._latent_heat_strategy is None:
             return get_mass_transfer_rate(
@@ -2062,6 +2060,98 @@ def _update_latent_heat_energy(
             )
         )
 
+    def _calculate_norm_conc(
+        self, volume: float, concentration: NDArray[np.float64]
+    ) -> NDArray[np.float64]:
+        """Validate inputs and compute normalized concentration.
+
+        Args:
+            volume: Particle volume for the single box [m^3].
+            concentration: Particle concentration array.
+
+        Returns:
+            Normalized concentration (concentration / volume).
+
+        Raises:
+            ValueError: If volume or concentration inputs are invalid.
+        """
+        if not np.isfinite(volume) or volume <= 0.0:
+            raise ValueError("volume must be finite and positive.")
+        if not np.all(np.isfinite(concentration)) or np.any(
+            concentration < 0.0
+        ):
+            raise ValueError(
+                "concentration must be finite and nonnegative for norm_conc."
+            )
+        return concentration / volume
+
+    def _normalize_mass_transfer_shape(
+        self,
+        mass_transfer: NDArray[np.float64],
+        species_mass: NDArray[np.float64],
+    ) -> NDArray[np.float64]:
+        """Normalize mass transfer shape to match species count.
+
+        Args:
+            mass_transfer: Per-particle mass transfer array.
+            species_mass: Particle mass array used to infer species count.
+
+        Returns:
+            Mass transfer array with consistent species dimension.
+        """
+        species_count = 1 if species_mass.ndim == 1 else species_mass.shape[1]
+        if mass_transfer.ndim == 1:
+            return mass_transfer.reshape(-1, species_count)
+        if mass_transfer.shape[1] > species_count:
+            return mass_transfer[:, :species_count]
+        if mass_transfer.shape[1] < species_count:
+            return np.broadcast_to(
+                mass_transfer, (mass_transfer.shape[0], species_count)
+            )
+        return mass_transfer
+
+    def _apply_mass_transfer_to_particles(
+        self,
+        particle_data: ParticleData,
+        mass_transfer: NDArray[np.float64],
+        norm_conc: NDArray[np.float64],
+    ) -> None:
+        """Apply mass transfer to particle data in place."""
+        if mass_transfer.ndim == 2:
+            nonzero_mask = norm_conc != 0
+            denom = norm_conc[:, np.newaxis]
+            where_mask = nonzero_mask[:, np.newaxis]
+        else:
+            denom = norm_conc
+            where_mask = norm_conc != 0
+        per_particle = np.divide(
+            mass_transfer,
+            denom,
+            out=np.zeros_like(mass_transfer),
+            where=where_mask,
+        )
+        np.add(
+            particle_data.masses[0],
+            per_particle,
+            out=particle_data.masses[0],
+        )
+        np.maximum(particle_data.masses[0], 0.0, out=particle_data.masses[0])
+
+    def _apply_mass_transfer_to_gas(
+        self, gas_data: GasData, mass_transfer: NDArray[np.float64]
+    ) -> None:
+        """Apply mass transfer to gas concentrations in place."""
+        np.subtract(
+            gas_data.concentration[0],
+            mass_transfer.sum(axis=0),
+            out=gas_data.concentration[0],
+        )
+        np.maximum(
+            gas_data.concentration[0],
+            0.0,
+            out=gas_data.concentration[0],
+        )
+
     # pylint: disable=too-many-positional-arguments, too-many-arguments
     @overload  # type: ignore[override]
     def step(
@@ -2101,8 +2191,8 @@ def step(
         The mass transfer rate is computed, optional skip-partitioning applied,
         and both the particle and gas states are updated while respecting
         inventory limits. The per-step latent heat release is stored in
-        ``last_latent_heat_energy`` (positive for condensation, negative for
-        evaporation) and overwritten on every call.
+        ``last_latent_heat_energy`` [J] (positive for condensation, negative
+        for evaporation) and overwritten on every call.
 
         Args:
             particle: Particle representation to update.
@@ -2130,18 +2220,16 @@ def step(
             dynamic_viscosity=dynamic_viscosity,
         )
 
-        if isinstance(mass_rate, (int, float)):
-            mass_rate_array = np.array([mass_rate])
-        else:
-            mass_rate_array = mass_rate
+        mass_rate_array = np.atleast_1d(np.asarray(mass_rate, dtype=np.float64))
 
         mass_rate_array = self._apply_skip_partitioning(mass_rate_array)
 
         gas_mass_array: NDArray[np.float64] = np.atleast_1d(
             np.asarray(gas_data.concentration[0], dtype=np.float64)
         )
         volume = particle_data.volume[0]
-        norm_conc = particle_data.concentration[0] / volume
+        concentration = particle_data.concentration[0]
+        norm_conc = self._calculate_norm_conc(volume, concentration)
         mass_transfer = get_mass_transfer(
             mass_rate=mass_rate_array,
             time_step=time_step,
@@ -2150,45 +2238,28 @@ def step(
             particle_concentration=norm_conc,
         )
 
-        self._update_latent_heat_energy(mass_transfer, temperature)
+        mass_transfer = self._normalize_mass_transfer_shape(
+            mass_transfer,
+            particle_data.masses[0],
+        )
 
-        species_mass = particle_data.masses[0]
-        if species_mass.ndim == 1:
-            species_count = 1
-        else:
-            species_count = species_mass.shape[1]
-        if mass_transfer.ndim == 1:
-            mass_transfer = mass_transfer.reshape(-1, species_count)
-        elif mass_transfer.shape[1] > species_count:
-            mass_transfer = mass_transfer[:, :species_count]
-        elif mass_transfer.shape[1] < species_count:
-            mass_transfer = np.broadcast_to(
-                mass_transfer, (mass_transfer.shape[0], species_count)
-            )
+        self._update_latent_heat_energy(mass_transfer, temperature)
 
         if particle_is_legacy:
             particle.add_mass(added_mass=mass_transfer)  # type: ignore[union-attr]
         else:
-            per_particle = np.divide(
+            self._apply_mass_transfer_to_particles(
+                particle_data,
                 mass_transfer,
-                norm_conc[:, np.newaxis]
-                if mass_transfer.ndim == 2
-                else norm_conc,
-                out=np.zeros_like(mass_transfer),
-                where=norm_conc[:, np.newaxis] != 0
-                if mass_transfer.ndim == 2
-                else norm_conc != 0,
-            )
-            particle_data.masses[0] = np.maximum(
-                particle_data.masses[0] + per_particle, 0.0
+                norm_conc,
             )
         if self.update_gases:
             if gas_is_legacy:
                 gas_species.add_concentration(  # type: ignore[union-attr]
                     added_concentration=-mass_transfer.sum(axis=0)
                 )
             else:
-                gas_data.concentration[0] -= mass_transfer.sum(axis=0)
+                self._apply_mass_transfer_to_gas(gas_data, mass_transfer)
         if particle_is_legacy:
             return cast(
                 Tuple[ParticleRepresentation, GasSpecies],