Skip to main content

qualia_core_db/domains/biosphere/
funga_network.rs

1//! Fungal mycelial network, nutrient transport, and sporocarp phenology.
2//!
3//! Models hyphal nodes with moisture and nutrient pools (C, P, N), inter-node
4//! transport along conductive edges, sporocarp developmental stage transitions,
5//! and zero-heap NQuin state emission.
6
7use crate::foundation::frame_layout::pack_float_object;
8use crate::query::resolver::INLINE_TAG_INTEGER;
9use crate::{q_hash, NQuin};
10
11/// Phenological stages of sporocarp (fruiting body) development.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
13#[repr(u8)]
14pub enum SporocarpStage {
15    MycelialKnot = 0,
16    PrimordiumPinhead = 1,
17    ButtonVeilIntact = 2,
18    MaturePileusExpanded = 3,
19    SporeRelease = 4,
20    DeliquescentSenescent = 5,
21}
22
23/// A node in the mycelial network within substrate or soil matrix.
24#[derive(Debug, Clone, Copy, PartialEq)]
25#[repr(C)]
26pub struct HyphalNode {
27    pub node_id: u64,
28    pub substrate_moisture: f32,
29    pub carbon_mol_m3: f32,
30    pub phosphorus_mol_m3: f32,
31    pub nitrogen_mol_m3: f32,
32}
33
34/// Conductive edge connecting two hyphal nodes.
35#[derive(Debug, Clone, Copy, PartialEq)]
36#[repr(C)]
37pub struct HyphalEdge {
38    pub from_idx: u16,
39    pub to_idx: u16,
40    pub conductance: f32,
41    pub anastomosis_fused: bool,
42}
43
44/// Morphological and physiological state of a developing sporocarp.
45#[derive(Debug, Clone, Copy, PartialEq)]
46#[repr(C)]
47pub struct SporocarpState {
48    pub stage: SporocarpStage,
49    pub pileus_diameter_mm: f32,
50    pub stipe_height_mm: f32,
51    pub biomass_carbon_mol: f32,
52    pub age_hours: f32,
53}
54
55/// Errors occurring during fungal network evaluation.
56#[derive(Debug, Clone, PartialEq)]
57pub enum FungaError {
58    InvalidMoisture(f32),
59    NegativeNutrientFlux(f32),
60    NegativeConductance(f32),
61    NegativeNutrient(f32),
62    NegativeTimeStep(f32),
63    InvalidNodeIndex { index: u16, len: usize },
64    BufferOverflow { needed: usize, available: usize },
65}
66
67impl std::fmt::Display for FungaError {
68    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
69        match self {
70            Self::InvalidMoisture(m) => write!(f, "Invalid moisture {m}; must be in [0.0, 1.0]"),
71            Self::NegativeNutrientFlux(flux) => write!(f, "Negative nutrient flux: {flux}"),
72            Self::NegativeConductance(c) => write!(f, "Negative conductance: {c}"),
73            Self::NegativeNutrient(n) => write!(f, "Negative nutrient pool: {n}"),
74            Self::NegativeTimeStep(dt) => write!(f, "Negative time step: {dt}"),
75            Self::InvalidNodeIndex { index, len } => write!(f, "Node index {index} >= {len}"),
76            Self::BufferOverflow { needed, available } => write!(f, "Overflow: needed {needed}, got {available}"),
77        }
78    }
79}
80
81impl std::error::Error for FungaError {}
82
83pub const PRED_HYPHAL_MOISTURE: u64 = q_hash("qualia:biosphere#hyphalNodeMoisture");
84pub const PRED_HYPHAL_CARBON: u64 = q_hash("qualia:biosphere#hyphalNodeCarbon");
85pub const PRED_HYPHAL_PHOSPHORUS: u64 = q_hash("qualia:biosphere#hyphalNodePhosphorus");
86pub const PRED_HYPHAL_NITROGEN: u64 = q_hash("qualia:biosphere#hyphalNodeNitrogen");
87pub const PRED_SPOROCARP_STAGE: u64 = q_hash("qualia:biosphere#sporocarpStage");
88pub const PRED_SPOROCARP_PILEUS_DIAMETER: u64 = q_hash("qualia:biosphere#sporocarpPileusDiameter");
89pub const PRED_SPOROCARP_BIOMASS: u64 = q_hash("qualia:biosphere#sporocarpBiomass");
90pub const METADATA_PROVENANCE_SIMULATION: u64 = 1u64 << 28;
91
92/// Zero-heap step executing mycelial nutrient transport across network edges.
93pub fn step_mycelial_nutrient_transport_zero_heap(
94    nodes: &mut [HyphalNode],
95    edges: &[HyphalEdge],
96    dt_sec: f32,
97) -> Result<(), FungaError> {
98    if dt_sec < 0.0 || !dt_sec.is_finite() {
99        return Err(FungaError::NegativeTimeStep(dt_sec));
100    }
101    for n in nodes.iter() {
102        if n.substrate_moisture < 0.0 || n.substrate_moisture > 1.0 || !n.substrate_moisture.is_finite() {
103            return Err(FungaError::InvalidMoisture(n.substrate_moisture));
104        }
105        if n.carbon_mol_m3 < 0.0 || !n.carbon_mol_m3.is_finite()
106            || n.phosphorus_mol_m3 < 0.0 || !n.phosphorus_mol_m3.is_finite()
107            || n.nitrogen_mol_m3 < 0.0 || !n.nitrogen_mol_m3.is_finite()
108        {
109            return Err(FungaError::NegativeNutrient(n.carbon_mol_m3));
110        }
111    }
112    for e in edges.iter() {
113        if e.conductance < 0.0 || !e.conductance.is_finite() {
114            return Err(FungaError::NegativeConductance(e.conductance));
115        }
116        if e.from_idx as usize >= nodes.len() {
117            return Err(FungaError::InvalidNodeIndex { index: e.from_idx, len: nodes.len() });
118        }
119        if e.to_idx as usize >= nodes.len() {
120            return Err(FungaError::InvalidNodeIndex { index: e.to_idx, len: nodes.len() });
121        }
122    }
123
124    for e in edges.iter() {
125        let (u, v) = (e.from_idx as usize, e.to_idx as usize);
126        if u == v { continue; }
127        let cond = e.conductance * if e.anastomosis_fused { 1.5 } else { 1.0 };
128        if u < v {
129            let (left, right) = nodes.split_at_mut(v);
130            transfer_nutrients(&mut left[u], &mut right[0], cond, dt_sec);
131        } else {
132            let (left, right) = nodes.split_at_mut(u);
133            transfer_nutrients(&mut right[0], &mut left[v], cond, dt_sec);
134        }
135    }
136    Ok(())
137}
138
139#[inline(always)]
140fn transfer_pool(a: &mut f32, b: &mut f32, cond: f32, dt: f32) {
141    let diff = *a - *b;
142    let rate = diff * cond * dt;
143    let flux = if rate >= 0.0 { rate.min(*a * 0.5) } else { rate.max(-*b * 0.5) };
144    *a -= flux;
145    *b += flux;
146}
147
148fn transfer_nutrients(u: &mut HyphalNode, v: &mut HyphalNode, cond: f32, dt: f32) {
149    transfer_pool(&mut u.carbon_mol_m3, &mut v.carbon_mol_m3, cond, dt);
150    transfer_pool(&mut u.phosphorus_mol_m3, &mut v.phosphorus_mol_m3, cond, dt);
151    transfer_pool(&mut u.nitrogen_mol_m3, &mut v.nitrogen_mol_m3, cond, dt);
152}
153
154/// Evaluates phenological transitions of a sporocarp based on environmental factors.
155pub fn evaluate_sporocarp_transition_zero_heap(
156    state: &mut SporocarpState,
157    soil_moisture: f32,
158    temperature_c: f32,
159    available_carbon_mol: f32,
160    dt_hours: f32,
161) -> Result<bool, FungaError> {
162    if soil_moisture < 0.0 || soil_moisture > 1.0 || !soil_moisture.is_finite() {
163        return Err(FungaError::InvalidMoisture(soil_moisture));
164    }
165    if available_carbon_mol < 0.0 || !available_carbon_mol.is_finite() {
166        return Err(FungaError::NegativeNutrient(available_carbon_mol));
167    }
168    if dt_hours < 0.0 || !dt_hours.is_finite() {
169        return Err(FungaError::NegativeTimeStep(dt_hours));
170    }
171
172    state.age_hours += dt_hours;
173    match state.stage {
174        SporocarpStage::MycelialKnot => {
175            if soil_moisture >= 0.40 && (10.0..=28.0).contains(&temperature_c) && available_carbon_mol >= 0.05 {
176                state.stage = SporocarpStage::PrimordiumPinhead;
177                state.stipe_height_mm = 2.0;
178                state.pileus_diameter_mm = 1.5;
179                state.biomass_carbon_mol += 0.02;
180                return Ok(true);
181            }
182        }
183        SporocarpStage::PrimordiumPinhead => {
184            state.stipe_height_mm += 0.5 * dt_hours;
185            state.pileus_diameter_mm += 0.4 * dt_hours;
186            if state.age_hours >= 12.0 && soil_moisture >= 0.45 && available_carbon_mol >= 0.10 {
187                state.stage = SporocarpStage::ButtonVeilIntact;
188                state.biomass_carbon_mol += 0.05;
189                return Ok(true);
190            }
191        }
192        SporocarpStage::ButtonVeilIntact => {
193            state.stipe_height_mm += 1.0 * dt_hours;
194            state.pileus_diameter_mm += 1.2 * dt_hours;
195            if state.age_hours >= 36.0 && soil_moisture >= 0.35 && available_carbon_mol >= 0.15 {
196                state.stage = SporocarpStage::MaturePileusExpanded;
197                state.biomass_carbon_mol += 0.10;
198                return Ok(true);
199            }
200        }
201        SporocarpStage::MaturePileusExpanded => {
202            if state.age_hours >= 60.0 && soil_moisture >= 0.25 {
203                state.stage = SporocarpStage::SporeRelease;
204                return Ok(true);
205            }
206        }
207        SporocarpStage::SporeRelease => {
208            if state.age_hours >= 96.0 {
209                state.stage = SporocarpStage::DeliquescentSenescent;
210                return Ok(true);
211            }
212        }
213        SporocarpStage::DeliquescentSenescent => {}
214    }
215    Ok(false)
216}
217
218/// Emits parity-valid NQuins representing mycelial and sporocarp states into a caller buffer.
219pub fn emit_funga_state_quins_zero_heap(
220    network_did_hash: u64,
221    nodes: &[HyphalNode],
222    sporocarp: Option<&SporocarpState>,
223    is_simulation: bool,
224    out_quins: &mut [NQuin],
225) -> Result<usize, FungaError> {
226    let needed = nodes.len() * 4 + if sporocarp.is_some() { 3 } else { 0 };
227    if out_quins.len() < needed {
228        return Err(FungaError::BufferOverflow { needed, available: out_quins.len() });
229    }
230
231    let prov = if is_simulation { METADATA_PROVENANCE_SIMULATION } else { 0 };
232    let metadata = (0b01u64 << 61) | prov;
233    let mut idx = 0;
234
235    for n in nodes.iter() {
236        let subj = network_did_hash ^ n.node_id;
237        let props: [(u64, u64); 4] = [
238            (PRED_HYPHAL_MOISTURE, pack_float_object(n.substrate_moisture)),
239            (PRED_HYPHAL_CARBON, pack_float_object(n.carbon_mol_m3)),
240            (PRED_HYPHAL_PHOSPHORUS, pack_float_object(n.phosphorus_mol_m3)),
241            (PRED_HYPHAL_NITROGEN, pack_float_object(n.nitrogen_mol_m3)),
242        ];
243        for (pred, obj) in props {
244            let parity = NQuin::calculate_parity(subj, pred, obj, network_did_hash, metadata);
245            out_quins[idx] = NQuin { subject: subj, predicate: pred, object: obj, context: network_did_hash, metadata, parity };
246            idx += 1;
247        }
248    }
249
250    if let Some(sp) = sporocarp {
251        let subj = network_did_hash;
252        let props: [(u64, u64); 3] = [
253            (PRED_SPOROCARP_STAGE, INLINE_TAG_INTEGER | (sp.stage as u64)),
254            (PRED_SPOROCARP_PILEUS_DIAMETER, pack_float_object(sp.pileus_diameter_mm)),
255            (PRED_SPOROCARP_BIOMASS, pack_float_object(sp.biomass_carbon_mol)),
256        ];
257        for (pred, obj) in props {
258            let parity = NQuin::calculate_parity(subj, pred, obj, network_did_hash, metadata);
259            out_quins[idx] = NQuin { subject: subj, predicate: pred, object: obj, context: network_did_hash, metadata, parity };
260            idx += 1;
261        }
262    }
263
264    Ok(idx)
265}
266
267#[cfg(test)]
268mod tests {
269    use super::*;
270    use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
271
272    #[test]
273    fn test_nutrient_transport_conservation() {
274        let mut nodes = [
275            HyphalNode { node_id: 1, substrate_moisture: 0.6, carbon_mol_m3: 10.0, phosphorus_mol_m3: 2.0, nitrogen_mol_m3: 5.0 },
276            HyphalNode { node_id: 2, substrate_moisture: 0.5, carbon_mol_m3: 2.0, phosphorus_mol_m3: 0.5, nitrogen_mol_m3: 1.0 },
277        ];
278        let edges = [HyphalEdge { from_idx: 0, to_idx: 1, conductance: 0.1, anastomosis_fused: false }];
279
280        let (c0, p0, n0) = (nodes[0].carbon_mol_m3 + nodes[1].carbon_mol_m3, nodes[0].phosphorus_mol_m3 + nodes[1].phosphorus_mol_m3, nodes[0].nitrogen_mol_m3 + nodes[1].nitrogen_mol_m3);
281        step_mycelial_nutrient_transport_zero_heap(&mut nodes, &edges, 1.0).unwrap();
282        assert!(nodes[0].carbon_mol_m3 < 10.0);
283        assert!(nodes[1].carbon_mol_m3 > 2.0);
284        let (c1, p1, n1) = (nodes[0].carbon_mol_m3 + nodes[1].carbon_mol_m3, nodes[0].phosphorus_mol_m3 + nodes[1].phosphorus_mol_m3, nodes[0].nitrogen_mol_m3 + nodes[1].nitrogen_mol_m3);
285        assert!((c0 - c1).abs() < 1e-6);
286        assert!((p0 - p1).abs() < 1e-6);
287        assert!((n0 - n1).abs() < 1e-6);
288    }
289
290    #[test]
291    fn test_anastomosis_enhanced_conductance() {
292        let mut unfused = [
293            HyphalNode { node_id: 1, substrate_moisture: 0.5, carbon_mol_m3: 10.0, phosphorus_mol_m3: 2.0, nitrogen_mol_m3: 2.0 },
294            HyphalNode { node_id: 2, substrate_moisture: 0.5, carbon_mol_m3: 0.0, phosphorus_mol_m3: 0.0, nitrogen_mol_m3: 0.0 },
295        ];
296        let mut fused = unfused;
297        let e_unfused = [HyphalEdge { from_idx: 0, to_idx: 1, conductance: 0.05, anastomosis_fused: false }];
298        let e_fused = [HyphalEdge { from_idx: 0, to_idx: 1, conductance: 0.05, anastomosis_fused: true }];
299
300        step_mycelial_nutrient_transport_zero_heap(&mut unfused, &e_unfused, 1.0).unwrap();
301        step_mycelial_nutrient_transport_zero_heap(&mut fused, &e_fused, 1.0).unwrap();
302        assert!(fused[1].carbon_mol_m3 > unfused[1].carbon_mol_m3);
303    }
304
305    #[test]
306    fn test_negative_conductance_or_invalid_moisture_rejected() {
307        let mut nodes = [HyphalNode { node_id: 1, substrate_moisture: 1.2, carbon_mol_m3: 1.0, phosphorus_mol_m3: 1.0, nitrogen_mol_m3: 1.0 }];
308        let edges = [HyphalEdge { from_idx: 0, to_idx: 0, conductance: -0.1, anastomosis_fused: false }];
309        assert!(step_mycelial_nutrient_transport_zero_heap(&mut nodes, &edges, 1.0).is_err());
310    }
311
312    #[test]
313    fn test_sporocarp_phenology_progression() {
314        let mut sp = SporocarpState { stage: SporocarpStage::MycelialKnot, pileus_diameter_mm: 0.0, stipe_height_mm: 0.0, biomass_carbon_mol: 0.01, age_hours: 0.0 };
315        assert!(evaluate_sporocarp_transition_zero_heap(&mut sp, 0.55, 20.0, 0.1, 1.0).unwrap());
316        assert_eq!(sp.stage, SporocarpStage::PrimordiumPinhead);
317        evaluate_sporocarp_transition_zero_heap(&mut sp, 0.55, 20.0, 0.2, 12.0).unwrap();
318        assert_eq!(sp.stage, SporocarpStage::ButtonVeilIntact);
319    }
320
321    #[test]
322    fn test_emit_funga_state_quins_and_zero_heap() {
323        let nodes = [HyphalNode { node_id: 42, substrate_moisture: 0.65, carbon_mol_m3: 8.5, phosphorus_mol_m3: 1.2, nitrogen_mol_m3: 3.4 }];
324        let sp = SporocarpState { stage: SporocarpStage::MaturePileusExpanded, pileus_diameter_mm: 45.0, stipe_height_mm: 80.0, biomass_carbon_mol: 0.35, age_hours: 50.0 };
325        let mut out = [NQuin::default(); 7];
326        assert_zero_alloc("emit_funga_state_quins", || {
327            let count = emit_funga_state_quins_zero_heap(1001, &nodes, Some(&sp), true, &mut out).unwrap();
328            assert_eq!(count, 7);
329        });
330        for q in out.iter() {
331            assert!(q.verify_ecc_parity());
332            assert_eq!((q.metadata >> 28) & 1, 1);
333        }
334        let mut small_out = [NQuin::default(); 2];
335        let err = emit_funga_state_quins_zero_heap(1001, &nodes, Some(&sp), true, &mut small_out);
336        assert!(matches!(err, Err(FungaError::BufferOverflow { .. })));
337    }
338}