From c457424a37554a3400ada7d151b91ea1475180f7 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 28 Sep 2026 15:33:14 +0000 Subject: [PATCH 1/2] refactor: home chemical-heat gate in aqueous_pipeline Move apply_chemical_heat and CHEMICAL_SPIT_FRAC out of scene so pipeline, acid_base, and dilution no longer call up into the mutator hub. Clean write-dead fluid_t mut and unused dissolve-heat T param. Co-authored-by: Arnoud --- crates/chemlab-core/src/acid_base.rs | 2 +- crates/chemlab-core/src/aqueous_pipeline.rs | 61 +++++++++++++++++--- crates/chemlab-core/src/dissolve_kinetics.rs | 12 ++-- crates/chemlab-core/src/lib.rs | 6 +- crates/chemlab-core/src/scene.rs | 58 +++---------------- crates/chemlab-core/src/scene_tests/h2so4.rs | 6 +- 6 files changed, 73 insertions(+), 72 deletions(-) diff --git a/crates/chemlab-core/src/acid_base.rs b/crates/chemlab-core/src/acid_base.rs index b4d4cc3..508fc63 100644 --- a/crates/chemlab-core/src/acid_base.rs +++ b/crates/chemlab-core/src/acid_base.rs @@ -172,7 +172,7 @@ pub fn speciate_aqueous_acid_base( if n_rxn > AMOUNT_EPS { add_water_ml(item, n_rxn * WATER_MOLAR_MASS_G_PER_MOL); let q = n_rxn * H_OH_NEUTRALIZATION_J_PER_MOL; - return crate::scene::apply_chemical_heat(item, q, allow_spit_mass); + return crate::aqueous_pipeline::apply_chemical_heat(item, q, allow_spit_mass); } } false diff --git a/crates/chemlab-core/src/aqueous_pipeline.rs b/crates/chemlab-core/src/aqueous_pipeline.rs index 79dc149..14c2402 100644 --- a/crates/chemlab-core/src/aqueous_pipeline.rs +++ b/crates/chemlab-core/src/aqueous_pipeline.rs @@ -4,11 +4,17 @@ //! depend on mutator-heavy `scene` helpers for ion writing. use crate::scene::{ - add_or_increase_mol_in, CompositionEntry, SceneItem, AMOUNT_EPS, CACL2_MOLAR_MASS_G_PER_MOL, - CASO4_MOLAR_MASS_G_PER_MOL, NA2SO4_MOLAR_MASS_G_PER_MOL, NACL_MOLAR_MASS_G_PER_MOL, - NAOH_MOLAR_MASS_G_PER_MOL, + add_or_increase_mol_in, effective_heat_capacity, take_composition_fraction, + vessel_boil_temperature_c, CompositionEntry, SceneItem, AMBIENT_TEMPERATURE_C, AMOUNT_EPS, + CACL2_MOLAR_MASS_G_PER_MOL, CASO4_MOLAR_MASS_G_PER_MOL, NA2SO4_MOLAR_MASS_G_PER_MOL, + NACL_MOLAR_MASS_G_PER_MOL, NAOH_MOLAR_MASS_G_PER_MOL, }; +/// School fraction of vessel composition discarded when chemical heat would boil. +/// +/// Lost as spray (not continuous evaporation). Mid-range of the 2–5% school band. +pub const CHEMICAL_SPIT_FRAC: f64 = 0.03; + /// Enthalpy of solution of NaCl at bench conditions (endothermic), J/mol. pub const NACL_DELTA_H_SOLUTION_J_PER_MOL: f64 = 3880.0; @@ -156,14 +162,13 @@ pub(crate) fn finalize_aqueous_vessel( /// Apply dissolution heat to the solvent vessel: ΔT = −(n·ΔH_sol) / C_eff. /// -/// Routes through [`crate::scene::apply_chemical_heat`] so boil/spit gating is -/// shared with dilution and neutralization. Returns `true` when spit mass was -/// discarded on this heat step. +/// Routes through [`apply_chemical_heat`] so boil/spit gating is shared with +/// dilution and neutralization. Returns `true` when spit mass was discarded on +/// this heat step. pub(crate) fn apply_dissolution_temperature_change( target: &mut SceneItem, moles: f64, delta_h_j_per_mol: f64, - _current_temperature_c: f64, allow_spit_mass: bool, ) -> bool { let water_ml = target @@ -177,7 +182,47 @@ pub(crate) fn apply_dissolution_temperature_change( return false; } let heat_j = moles * delta_h_j_per_mol; - crate::scene::apply_chemical_heat(target, heat_j, allow_spit_mass) + apply_chemical_heat(target, heat_j, allow_spit_mass) +} + +/// Apply instant chemical heat `q_j` (negative ⇒ exothermic): `ΔT = −Q / C_eff`. +/// +/// When the proposed temperature would reach or exceed [`vessel_boil_temperature_c`], +/// clamp at boil. When `allow_spit_mass` is true (action paths), also discard +/// [`CHEMICAL_SPIT_FRAC`] of composition and return `true` so the caller can emit +/// at most one silent `spit` event per action. Clock ticks pass `false` — clamp +/// only, no spray mass / event (spit is action-scoped). Burner continuous boil +/// stays on the thermal path. +pub(crate) fn apply_chemical_heat(target: &mut SceneItem, q_j: f64, allow_spit_mass: bool) -> bool { + if q_j.abs() <= AMOUNT_EPS { + return false; + } + let c_eff = effective_heat_capacity(target); + if c_eff <= AMOUNT_EPS { + return false; + } + let t = target + .properties + .temperature_c + .unwrap_or(AMBIENT_TEMPERATURE_C); + let t_proposed = t - q_j / c_eff; + let t_boil = vessel_boil_temperature_c(target); + // Already plateaued at boil from a prior chemical-heat step this action: + // clamp only — do not spit mass again. + if t + 1e-3 >= t_boil { + target.properties.temperature_c = Some(t_boil); + return false; + } + if t_proposed + 1e-6 < t_boil { + target.properties.temperature_c = Some(t_proposed); + return false; + } + target.properties.temperature_c = Some(t_boil); + if !allow_spit_mass { + return false; + } + let _discarded = take_composition_fraction(target, CHEMICAL_SPIT_FRAC); + true } #[cfg(test)] diff --git a/crates/chemlab-core/src/dissolve_kinetics.rs b/crates/chemlab-core/src/dissolve_kinetics.rs index aa381a0..968231a 100644 --- a/crates/chemlab-core/src/dissolve_kinetics.rs +++ b/crates/chemlab-core/src/dissolve_kinetics.rs @@ -151,7 +151,7 @@ fn apply_kinetic_dissolve_step(item: &mut SceneItem, tau_s: f64, allow_spit_mass if let Some((moles, delta_h)) = author_dissolved_salt_ions(&mut item.properties.composition, salt_id, m_diss) { - spit |= apply_dissolution_temperature_change(item, moles, delta_h, t, allow_spit_mass); + spit |= apply_dissolution_temperature_change(item, moles, delta_h, allow_spit_mass); } } spit @@ -160,12 +160,12 @@ fn apply_kinetic_dissolve_step(item: &mut SceneItem, tau_s: f64, allow_spit_mass /// Wash soluble solids from filter paper into a fluid parcel (same rate law). /// /// Updates `fluid` ions. Dissolve ΔH is returned as heat (J) for the caller to -/// apply via [`crate::scene::apply_chemical_heat`] on the destination vessel after -/// mix (shared boil/spit gate). Sand is never touched. +/// apply via [`crate::aqueous_pipeline::apply_chemical_heat`] on the destination +/// vessel after mix (shared boil/spit gate). Sand is never touched. pub(crate) fn wash_paper_solids_into_fluid( paper: &mut SceneItem, fluid: &mut Vec, - fluid_t: &mut f64, + fluid_t: f64, ) -> f64 { let v_fluid = crate::composition::solvent_water_ml_for_si_entries(fluid); if v_fluid <= AMOUNT_EPS { @@ -179,9 +179,9 @@ pub(crate) fn wash_paper_solids_into_fluid( .temperature_c .unwrap_or(AMBIENT_TEMPERATURE_C); let t_wash = if c_fluid + c_paper > AMOUNT_EPS { - (c_fluid * *fluid_t + c_paper * paper_t) / (c_fluid + c_paper) + (c_fluid * fluid_t + c_paper * paper_t) / (c_fluid + c_paper) } else { - *fluid_t + fluid_t }; let tau = FILTER_WASH_TAU_S_PER_ML * v_fluid; diff --git a/crates/chemlab-core/src/lib.rs b/crates/chemlab-core/src/lib.rs index cb845f7..4cb530d 100644 --- a/crates/chemlab-core/src/lib.rs +++ b/crates/chemlab-core/src/lib.rs @@ -16,7 +16,7 @@ mod scene; mod solubility; pub use aqueous_pipeline::{ - NA2SO4_DELTA_H_SOLUTION_J_PER_MOL, NACL_DELTA_H_SOLUTION_J_PER_MOL, + CHEMICAL_SPIT_FRAC, NA2SO4_DELTA_H_SOLUTION_J_PER_MOL, NACL_DELTA_H_SOLUTION_J_PER_MOL, NAOH_DELTA_H_SOLUTION_J_PER_MOL, }; pub use dissolve::{dissolve, DissolveError, DissolveOutcome}; @@ -37,8 +37,8 @@ pub use scene::{ ensure_default_bench_items, initial_bench_scene, initial_scene_for_mode, vessel_boil_temperature_c, water_mole_fraction, water_vapor_pressure_bar, Action, CompositionEntry, ItemProperties, Scene, SceneError, SceneEvent, SceneItem, - AMBIENT_TEMPERATURE_C, ATM_PRESSURE_BAR, BOILING_TEMPERATURE_C, BURNER_POWER_W, - CHEMICAL_SPIT_FRAC, CP_CACL2, CP_H2SO4_LIQUID, CP_NACL, CP_NAOH, CP_SAND, C_BEAKER, C_DISH, + AMBIENT_TEMPERATURE_C, ATM_PRESSURE_BAR, BOILING_TEMPERATURE_C, BURNER_POWER_W, CP_CACL2, + CP_H2SO4_LIQUID, CP_NACL, CP_NAOH, CP_SAND, C_BEAKER, C_DISH, DISH_CAPACITY_ML, DISH_EVAP_AREA_M2, DISH_MASS_TRANSFER_COEFF_ML_PER_S_M2, DISTILLED_WATER_CAPACITY_ML, DISTILLED_WATER_ID, FILTRATE_CAPACITY_ML, H_OH_NEUTRALIZATION_J_PER_MOL, MAIN_BEAKER_ID, PIPETTE_MIN_SOURCE_ML, PIPETTE_VOLUME_ML, diff --git a/crates/chemlab-core/src/scene.rs b/crates/chemlab-core/src/scene.rs index aa582bd..2165839 100644 --- a/crates/chemlab-core/src/scene.rs +++ b/crates/chemlab-core/src/scene.rs @@ -124,11 +124,6 @@ pub(crate) use crate::aqueous_pipeline::finalize_aqueous_vessel; /// Enthalpy of neutralization H⁺ + OH⁻ → H₂O (exothermic), J/mol. pub const H_OH_NEUTRALIZATION_J_PER_MOL: f64 = -55800.0; -/// School fraction of vessel composition discarded when chemical heat would boil. -/// -/// Lost as spray (not continuous evaporation). Mid-range of the 2–5% school band. -pub const CHEMICAL_SPIT_FRAC: f64 = 0.03; - /// Specific heat capacity of liquid water, J/(g·K). Mass of water ≈ volume in ml. pub const WATER_SPECIFIC_HEAT_J_PER_G_K: f64 = 4.184; @@ -1655,14 +1650,15 @@ fn apply_filter_pour(scene: &mut Scene, tool_idx: usize) -> Result<(), SceneErro // Deposit source solids onto paper first so this pour's soluble fraction is // eligible for wash with the fluid still about to enter the filtrate. let _ = mix_transfer_into(&mut scene.items[paper_idx], &solids, None); - let mut fluid_t = source_t; + let fluid_t = source_t; let wash_q = crate::dissolve_kinetics::wash_paper_solids_into_fluid( &mut scene.items[paper_idx], &mut fluid, - &mut fluid_t, + fluid_t, ); let spit_mix = mix_transfer_into(&mut scene.items[dest_idx], &fluid, Some(fluid_t)); - let spit_wash = apply_chemical_heat(&mut scene.items[dest_idx], wash_q, true); + let spit_wash = + crate::aqueous_pipeline::apply_chemical_heat(&mut scene.items[dest_idx], wash_q, true); // Wash already applied contact-time kinetics; finalize is SI/speciate only. let spit_src = finalize_aqueous_vessel(&mut scene.items[source_idx], 0.0, true); let spit_dest = finalize_aqueous_vessel(&mut scene.items[dest_idx], 0.0, true); @@ -1896,7 +1892,7 @@ fn scale_entry(entry: &CompositionEntry, frac: f64) -> Option has_amount.then_some(scaled) } -fn take_composition_fraction(source: &mut SceneItem, frac: f64) -> Vec { +pub(crate) fn take_composition_fraction(source: &mut SceneItem, frac: f64) -> Vec { let frac = frac.clamp(0.0, 1.0); if frac <= AMOUNT_EPS { return Vec::new(); @@ -2047,7 +2043,7 @@ fn apply_hcl_dilution_temperature( } let after = crate::hcl::HclInventory::from_item(target); let q = crate::hcl::hcl_dilution_heat_j(dest_before, added, after); - apply_chemical_heat(target, q, true) + crate::aqueous_pipeline::apply_chemical_heat(target, q, true) } fn apply_h2so4_dilution_temperature( @@ -2060,47 +2056,7 @@ fn apply_h2so4_dilution_temperature( } let after = crate::h2so4::H2so4Inventory::from_item(target); let q = crate::h2so4::h2so4_dilution_heat_j(dest_before, added, after); - apply_chemical_heat(target, q, true) -} - -/// Apply instant chemical heat `q_j` (negative ⇒ exothermic): `ΔT = −Q / C_eff`. -/// -/// When the proposed temperature would reach or exceed [`vessel_boil_temperature_c`], -/// clamp at boil. When `allow_spit_mass` is true (action paths), also discard -/// [`CHEMICAL_SPIT_FRAC`] of composition and return `true` so the caller can emit -/// at most one silent `spit` event per action. Clock ticks pass `false` — clamp -/// only, no spray mass / event (spit is action-scoped). Burner continuous boil -/// stays on the thermal path. -pub(crate) fn apply_chemical_heat(target: &mut SceneItem, q_j: f64, allow_spit_mass: bool) -> bool { - if q_j.abs() <= AMOUNT_EPS { - return false; - } - let c_eff = effective_heat_capacity(target); - if c_eff <= AMOUNT_EPS { - return false; - } - let t = target - .properties - .temperature_c - .unwrap_or(AMBIENT_TEMPERATURE_C); - let t_proposed = t - q_j / c_eff; - let t_boil = vessel_boil_temperature_c(target); - // Already plateaued at boil from a prior chemical-heat step this action: - // clamp only — do not spit mass again. - if t + 1e-3 >= t_boil { - target.properties.temperature_c = Some(t_boil); - return false; - } - if t_proposed + 1e-6 < t_boil { - target.properties.temperature_c = Some(t_proposed); - return false; - } - target.properties.temperature_c = Some(t_boil); - if !allow_spit_mass { - return false; - } - let _discarded = take_composition_fraction(target, CHEMICAL_SPIT_FRAC); - true + crate::aqueous_pipeline::apply_chemical_heat(target, q, true) } /// Push a silent spit event at most once per action (empty message; FE is visual-only). diff --git a/crates/chemlab-core/src/scene_tests/h2so4.rs b/crates/chemlab-core/src/scene_tests/h2so4.rs index 88f0e91..fd02c59 100644 --- a/crates/chemlab-core/src/scene_tests/h2so4.rs +++ b/crates/chemlab-core/src/scene_tests/h2so4.rs @@ -667,7 +667,7 @@ fn chemical_heat_clock_mode_clamps_without_spit_mass() { let v0 = crate::hcl::solution_volume_ml(&item); let c = effective_heat_capacity(&item); let q = -c * 20.0; // proposed T = 115 °C → overshoot - let spit = apply_chemical_heat(&mut item, q, false); + let spit = crate::aqueous_pipeline::apply_chemical_heat(&mut item, q, false); assert!(!spit); let t_boil = vessel_boil_temperature_c(&item); assert!( @@ -682,7 +682,7 @@ fn chemical_heat_clock_mode_clamps_without_spit_mass() { let mut item2 = item.clone(); item2.properties.temperature_c = Some(95.0); crate::solubility::sync_fill_ml(&mut item2); - let spit_action = apply_chemical_heat(&mut item2, q, true); + let spit_action = crate::aqueous_pipeline::apply_chemical_heat(&mut item2, q, true); assert!(spit_action); - assert!(crate::hcl::solution_volume_ml(&item2) < v0 * (1.0 - CHEMICAL_SPIT_FRAC * 0.5)); + assert!(crate::hcl::solution_volume_ml(&item2) < v0 * (1.0 - crate::CHEMICAL_SPIT_FRAC * 0.5)); } From b7d27484e9400e45b473c698a308c11d36cd5e4e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 28 Sep 2026 15:35:46 +0000 Subject: [PATCH 2/2] style: cargo fmt for chemical-heat move Co-authored-by: Arnoud --- crates/chemlab-core/src/lib.rs | 13 ++++++------- crates/chemlab-core/src/scene.rs | 5 ++++- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/crates/chemlab-core/src/lib.rs b/crates/chemlab-core/src/lib.rs index 4cb530d..f23c999 100644 --- a/crates/chemlab-core/src/lib.rs +++ b/crates/chemlab-core/src/lib.rs @@ -38,13 +38,12 @@ pub use scene::{ vessel_boil_temperature_c, water_mole_fraction, water_vapor_pressure_bar, Action, CompositionEntry, ItemProperties, Scene, SceneError, SceneEvent, SceneItem, AMBIENT_TEMPERATURE_C, ATM_PRESSURE_BAR, BOILING_TEMPERATURE_C, BURNER_POWER_W, CP_CACL2, - CP_H2SO4_LIQUID, CP_NACL, CP_NAOH, CP_SAND, C_BEAKER, C_DISH, - DISH_CAPACITY_ML, DISH_EVAP_AREA_M2, DISH_MASS_TRANSFER_COEFF_ML_PER_S_M2, - DISTILLED_WATER_CAPACITY_ML, DISTILLED_WATER_ID, FILTRATE_CAPACITY_ML, - H_OH_NEUTRALIZATION_J_PER_MOL, MAIN_BEAKER_ID, PIPETTE_MIN_SOURCE_ML, PIPETTE_VOLUME_ML, - RELATIVE_HUMIDITY, SPOON_SCOOP_MASS_G, UA_BEAKER, UA_DISH, WATER_ANTOINE_A, WATER_ANTOINE_B, - WATER_ANTOINE_C, WATER_CAPACITY_ML, WATER_LATENT_HEAT_J_PER_G, WATER_MOLAR_MASS_G_PER_MOL, - WATER_SPECIFIC_HEAT_J_PER_G_K, + CP_H2SO4_LIQUID, CP_NACL, CP_NAOH, CP_SAND, C_BEAKER, C_DISH, DISH_CAPACITY_ML, + DISH_EVAP_AREA_M2, DISH_MASS_TRANSFER_COEFF_ML_PER_S_M2, DISTILLED_WATER_CAPACITY_ML, + DISTILLED_WATER_ID, FILTRATE_CAPACITY_ML, H_OH_NEUTRALIZATION_J_PER_MOL, MAIN_BEAKER_ID, + PIPETTE_MIN_SOURCE_ML, PIPETTE_VOLUME_ML, RELATIVE_HUMIDITY, SPOON_SCOOP_MASS_G, UA_BEAKER, + UA_DISH, WATER_ANTOINE_A, WATER_ANTOINE_B, WATER_ANTOINE_C, WATER_CAPACITY_ML, + WATER_LATENT_HEAT_J_PER_G, WATER_MOLAR_MASS_G_PER_MOL, WATER_SPECIFIC_HEAT_J_PER_G_K, }; /// Semantic version of the ChemLab core crate. diff --git a/crates/chemlab-core/src/scene.rs b/crates/chemlab-core/src/scene.rs index 2165839..3d57577 100644 --- a/crates/chemlab-core/src/scene.rs +++ b/crates/chemlab-core/src/scene.rs @@ -1892,7 +1892,10 @@ fn scale_entry(entry: &CompositionEntry, frac: f64) -> Option has_amount.then_some(scaled) } -pub(crate) fn take_composition_fraction(source: &mut SceneItem, frac: f64) -> Vec { +pub(crate) fn take_composition_fraction( + source: &mut SceneItem, + frac: f64, +) -> Vec { let frac = frac.clamp(0.0, 1.0); if frac <= AMOUNT_EPS { return Vec::new();