Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion crates/chemlab-core/src/acid_base.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
61 changes: 53 additions & 8 deletions crates/chemlab-core/src/aqueous_pipeline.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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
Expand All @@ -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)]
Expand Down
12 changes: 6 additions & 6 deletions crates/chemlab-core/src/dissolve_kinetics.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<CompositionEntry>,
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 {
Expand All @@ -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;
Expand Down
17 changes: 8 additions & 9 deletions crates/chemlab-core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand All @@ -37,14 +37,13 @@ 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,
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,
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,
};

/// Semantic version of the ChemLab core crate.
Expand Down
61 changes: 10 additions & 51 deletions crates/chemlab-core/src/scene.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -1896,7 +1892,10 @@ fn scale_entry(entry: &CompositionEntry, frac: f64) -> Option<CompositionEntry>
has_amount.then_some(scaled)
}

fn take_composition_fraction(source: &mut SceneItem, frac: f64) -> Vec<CompositionEntry> {
pub(crate) fn take_composition_fraction(
source: &mut SceneItem,
frac: f64,
) -> Vec<CompositionEntry> {
let frac = frac.clamp(0.0, 1.0);
if frac <= AMOUNT_EPS {
return Vec::new();
Expand Down Expand Up @@ -2047,7 +2046,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(
Expand All @@ -2060,47 +2059,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).
Expand Down
6 changes: 3 additions & 3 deletions crates/chemlab-core/src/scene_tests/h2so4.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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!(
Expand All @@ -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));
}
Loading