Skip to main content

wellfare_core/anatomy/
densitometry.rs

1//! Skeletal and muscular densitometry, fracture callus healing, and coupled
2//! mobility / fracture-risk evaluation across human clinical and comparative
3//! biological taxa (Spec §5.1–5.4, BIO-WP-05).
4//!
5//! **Honesty boundaries:**
6//! - Computed biomechanical metrics (`MobilityAndFractureRiskReport`, modulus,
7//!   yield strength) always carry [`EpistemicStatus::Hypothesis`], never a
8//!   clinical diagnosis.
9//! - Missing clinical measurements (such as DEXA `T-score`) stay `None`; WHO
10//!   classification returns `None` rather than fabricating a score.
11//! - Pure calculations mirror the closed-form equations in
12//!   `qualia_core_db::specialized_libs::medical_computing::clinical_formulas`
13//!   without pulling `qualia-core-db` (which would introduce a Cargo cycle).
14
15use serde::{Deserialize, Serialize};
16
17use crate::record::EpistemicStatus;
18
19/// WHO (1994) diagnostic classification for areal bone mineral density (DEXA).
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum WhoDensityCategory {
23    /// T-score >= -1.0.
24    Normal,
25    /// -2.5 < T-score < -1.0 (low bone mass).
26    Osteopenia,
27    /// T-score <= -2.5 without fragility fracture.
28    Osteoporosis,
29    /// T-score <= -2.5 with one or more fragility fractures.
30    SevereOsteoporosis,
31}
32
33/// Ontogenetic epiphyseal growth-plate (physis) fusion status (Spec §5.5, §9.1).
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
35#[serde(rename_all = "snake_case")]
36pub enum PhysealFusionStatus {
37    OpenCartilaginousPhysis,
38    PartiallyFused,
39    ClosedMatureDiaphysis,
40}
41
42/// Named phase corresponding to the 5 stages (`0..=4`) of [`FractureCallusState`].
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
44#[serde(rename_all = "snake_case")]
45pub enum CallusHealingPhase {
46    /// Stage 0: Unfractured intact structural support element.
47    Intact,
48    /// Stage 1: Acute fracture hematoma (`E_callus` ~ 0.1–1 MPa; high pain-guarding).
49    AcuteHematoma,
50    /// Stage 2: Intramembranous & endochondral soft callus (`E_callus` ~ 10–500 MPa).
51    SoftCallus,
52    /// Stage 3: Mineralizing woven-bone hard callus (`E_callus` ~ 1–5 GPa).
53    HardCallus,
54    /// Stage 4: Lamellar cortical remodeling (`E` -> 12–20 GPa).
55    Remodeling,
56}
57
58/// Five-stage (0..=4) mechanobiological fracture-healing state (Claes & Heigele 1999;
59/// Spec §5.3 & §9.1).
60///
61/// - `0` = `Intact`
62/// - `1` = `AcuteHematoma`
63/// - `2` = `SoftCallus`
64/// - `3` = `HardCallus`
65/// - `4` = `Remodeling`
66#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
67pub struct FractureCallusState {
68    pub stage: u8,
69    pub phase: CallusHealingPhase,
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub post_injury_days: Option<f32>,
72    /// Effective callus modulus in MPa (`E_callus`).
73    pub callus_modulus_mpa: f64,
74    /// Fraction of intact structural strength restored in `[0.0, 1.0]`.
75    pub strength_recovery_ratio: f64,
76    /// Nociceptive pain-guarding coactivation signal in `[0.0, 1.0]` for `aura`.
77    pub pain_guarding_coactivation: f64,
78}
79
80impl FractureCallusState {
81    /// Construct from canonical healing stage `0..=4`. Fails closed for `stage > 4`.
82    pub fn from_stage(stage: u8) -> Result<Self, String> {
83        Self::from_stage_with_days(stage, None)
84    }
85
86    /// Construct from canonical healing stage `0..=4` and optional days post-injury.
87    pub fn from_stage_with_days(
88        stage: u8,
89        post_injury_days: Option<f32>,
90    ) -> Result<Self, String> {
91        if let Some(d) = post_injury_days {
92            if !d.is_finite() || d < 0.0 {
93                return Err("post_injury_days must be finite and non-negative".into());
94            }
95        }
96        let (phase, callus_modulus_mpa, strength_recovery_ratio, pain_guarding_coactivation) =
97            match stage {
98                0 => (CallusHealingPhase::Intact, 16_000.0, 1.00, 0.00),
99                1 => (CallusHealingPhase::AcuteHematoma, 0.5, 0.02, 0.85),
100                2 => (CallusHealingPhase::SoftCallus, 200.0, 0.15, 0.55),
101                3 => (CallusHealingPhase::HardCallus, 2_500.0, 0.65, 0.20),
102                4 => (CallusHealingPhase::Remodeling, 15_000.0, 0.95, 0.05),
103                _ => {
104                    return Err(format!(
105                        "invalid fracture callus stage {stage}: expected 0..=4"
106                    ));
107                }
108            };
109        Ok(Self {
110            stage,
111            phase,
112            post_injury_days,
113            callus_modulus_mpa,
114            strength_recovery_ratio,
115            pain_guarding_coactivation,
116        })
117    }
118
119    /// Stage 0: unfractured intact bone.
120    pub fn intact() -> Self {
121        Self::from_stage(0).expect("stage 0 is valid")
122    }
123
124    /// Validate stage consistency and finite/bounded ratios.
125    pub fn validate(&self) -> Result<(), String> {
126        if self.stage > 4 {
127            return Err(format!(
128                "invalid fracture callus stage {}: expected 0..=4",
129                self.stage
130            ));
131        }
132        if !self.callus_modulus_mpa.is_finite() || self.callus_modulus_mpa < 0.0 {
133            return Err("callus_modulus_mpa must be finite and non-negative".into());
134        }
135        if !self.strength_recovery_ratio.is_finite()
136            || !(0.0..=1.0).contains(&self.strength_recovery_ratio)
137        {
138            return Err("strength_recovery_ratio must be in [0.0, 1.0]".into());
139        }
140        if !self.pain_guarding_coactivation.is_finite()
141            || !(0.0..=1.0).contains(&self.pain_guarding_coactivation)
142        {
143            return Err("pain_guarding_coactivation must be in [0.0, 1.0]".into());
144        }
145        if let Some(d) = self.post_injury_days {
146            if !d.is_finite() || d < 0.0 {
147                return Err("post_injury_days must be finite and non-negative".into());
148            }
149        }
150        Ok(())
151    }
152}
153
154impl Default for FractureCallusState {
155    fn default() -> Self {
156        Self::intact()
157    }
158}
159
160/// Multi-scale cortical and trabecular skeletal densitometry profile (Spec §5.1–5.3).
161#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
162pub struct SkeletalDensityProfile {
163    pub compartment_label: String,
164    /// Cortical apparent wet density `rho_app` in g/cm^3.
165    pub cortical_apparent_density_g_cm3: f64,
166    /// Cortical shell thickness `t_cort` in mm.
167    pub cortical_thickness_mm: f64,
168    /// Intracortical Haversian porosity `phi_cort` in `[0.0, 1.0]`.
169    pub cortical_porosity_ratio: f64,
170    /// Trabecular apparent density `rho_app` in g/cm^3.
171    pub trabecular_apparent_density_g_cm3: f64,
172    /// Trabecular Bone Volume Fraction `BV/TV` in `[0.0, 1.0]`.
173    pub trabecular_bv_tv: f64,
174    /// Trabecular thickness `Tb.Th` in micrometers.
175    pub trabecular_thickness_um: f64,
176    /// Trabecular separation `Tb.Sp` in micrometers.
177    pub trabecular_separation_um: f64,
178    /// Trabecular number `Tb.N` in mm^-1.
179    pub trabecular_number_per_mm: f64,
180    /// Structure Model Index `SMI` (0 = plate-like, 3 = rod-like).
181    pub trabecular_smi: f64,
182    /// Principal eigenvalues `[m1, m2, m3]` of the trabecular fabric tensor (`tr(M) = 3.0`).
183    pub fabric_eigenvalues: [f64; 3],
184    /// Matrix mineralization degree `mu_min` (`1.0` = healthy mineralized human bone;
185    /// `< 0.75` = osteomalacic/rachitic hypomineralization).
186    pub mineralization_degree_mu: f64,
187    /// Mineral ash fraction `alpha_ash` in `[0.0, 1.0]`.
188    pub ash_fraction: f64,
189    /// QCT / HR-pQCT volumetric BMD in mg HA/cm^3, if observed.
190    #[serde(default, skip_serializing_if = "Option::is_none")]
191    pub qct_volumetric_bmd_mg_ha_cm3: Option<f64>,
192    /// DEXA areal BMD in g/cm^2, if observed.
193    #[serde(default, skip_serializing_if = "Option::is_none")]
194    pub dexa_areal_bmd_g_cm2: Option<f64>,
195    /// DEXA T-score (SD vs young-adult peak), if observed/computed.
196    #[serde(default, skip_serializing_if = "Option::is_none")]
197    pub dexa_t_score: Option<f64>,
198    /// DEXA Z-score (SD vs age/sex/cohort reference), if observed/computed.
199    #[serde(default, skip_serializing_if = "Option::is_none")]
200    pub dexa_z_score: Option<f64>,
201    /// Trabecular Bone Score (TBS), if available.
202    #[serde(default, skip_serializing_if = "Option::is_none")]
203    pub trabecular_bone_score_tbs: Option<f64>,
204    pub has_fragility_fracture: bool,
205    pub physeal_fusion: PhysealFusionStatus,
206    pub fracture_callus: FractureCallusState,
207    pub has_orthopedic_implant: bool,
208    pub epistemic_status: EpistemicStatus,
209}
210
211/// Alias matching the name referenced in Spec §12.3 (`BIO-WP-05`).
212pub type SkeletalDensitometryProfile = SkeletalDensityProfile;
213
214impl SkeletalDensityProfile {
215    /// Construct a profile from one of the curated human clinical or comparative species presets.
216    pub fn from_preset(preset: SpeciesDensitometryPreset) -> Self {
217        preset.to_profile()
218    }
219
220    /// Fail-closed validation of physical bounds and finite numbers.
221    pub fn validate(&self) -> Result<(), String> {
222        if self.compartment_label.trim().is_empty() {
223            return Err("compartment_label must not be empty".into());
224        }
225        let non_neg_finite = [
226            (
227                "cortical_apparent_density_g_cm3",
228                self.cortical_apparent_density_g_cm3,
229            ),
230            ("cortical_thickness_mm", self.cortical_thickness_mm),
231            (
232                "trabecular_apparent_density_g_cm3",
233                self.trabecular_apparent_density_g_cm3,
234            ),
235            ("trabecular_thickness_um", self.trabecular_thickness_um),
236            ("trabecular_separation_um", self.trabecular_separation_um),
237            ("trabecular_number_per_mm", self.trabecular_number_per_mm),
238            ("mineralization_degree_mu", self.mineralization_degree_mu),
239        ];
240        for (name, v) in non_neg_finite {
241            if !v.is_finite() || v < 0.0 {
242                return Err(format!("{name} must be finite and non-negative"));
243            }
244        }
245        if !self.cortical_porosity_ratio.is_finite()
246            || !(0.0..=1.0).contains(&self.cortical_porosity_ratio)
247        {
248            return Err("cortical_porosity_ratio must be in [0.0, 1.0]".into());
249        }
250        if !self.trabecular_bv_tv.is_finite() || !(0.0..=1.0).contains(&self.trabecular_bv_tv) {
251            return Err("trabecular_bv_tv must be in [0.0, 1.0]".into());
252        }
253        if !self.ash_fraction.is_finite() || !(0.0..=1.0).contains(&self.ash_fraction) {
254            return Err("ash_fraction must be in [0.0, 1.0]".into());
255        }
256        if !self.trabecular_smi.is_finite() {
257            return Err("trabecular_smi must be finite".into());
258        }
259        let trace: f64 = self.fabric_eigenvalues.iter().sum();
260        if self
261            .fabric_eigenvalues
262            .iter()
263            .any(|m| !m.is_finite() || *m <= 0.0)
264            || (trace - 3.0).abs() > 0.05
265        {
266            return Err("fabric_eigenvalues must be positive and sum to ~3.0".into());
267        }
268        if let Some(t) = self.dexa_t_score {
269            if !t.is_finite() {
270                return Err("dexa_t_score must be finite".into());
271            }
272        }
273        if let Some(z) = self.dexa_z_score {
274            if !z.is_finite() {
275                return Err("dexa_z_score must be finite".into());
276            }
277        }
278        if let Some(abmd) = self.dexa_areal_bmd_g_cm2 {
279            if !abmd.is_finite() || abmd < 0.0 {
280                return Err("dexa_areal_bmd_g_cm2 must be finite and non-negative".into());
281            }
282        }
283        if let Some(vbmd) = self.qct_volumetric_bmd_mg_ha_cm3 {
284            if !vbmd.is_finite() || vbmd < 0.0 {
285                return Err("qct_volumetric_bmd_mg_ha_cm3 must be finite and non-negative".into());
286            }
287        }
288        self.fracture_callus.validate()
289    }
290
291    /// WHO (1994) classification from `dexa_t_score` + `has_fragility_fracture`.
292    /// Returns `None` if no T-score was measured/provided (never fabricates a score).
293    pub fn who_category(&self) -> Option<WhoDensityCategory> {
294        let t = self.dexa_t_score?;
295        if !t.is_finite() {
296            return None;
297        }
298        Some(if t >= -1.0 {
299            WhoDensityCategory::Normal
300        } else if t > -2.5 {
301            WhoDensityCategory::Osteopenia
302        } else if self.has_fragility_fracture {
303            WhoDensityCategory::SevereOsteoporosis
304        } else {
305            WhoDensityCategory::Osteoporosis
306        })
307    }
308
309    /// Carter & Hayes (1977) / Zysset (2003) effective cortical elastic modulus in GPa,
310    /// attenuated by fracture-callus stage when `fracture_callus.stage > 0`.
311    pub fn effective_cortical_modulus_gpa(&self, strain_rate_per_s: f64) -> Result<f64, String> {
312        self.validate()?;
313        if !strain_rate_per_s.is_finite() || strain_rate_per_s <= 0.0 {
314            return Err("strain_rate_per_s must be finite and positive".into());
315        }
316        let m_primary = self.fabric_eigenvalues[0];
317        let intact_gpa = 3.790
318            * self.mineralization_degree_mu
319            * self.cortical_apparent_density_g_cm3.powi(3)
320            * m_primary.powi(2)
321            * strain_rate_per_s.powf(0.06);
322        if self.fracture_callus.stage == 0 {
323            Ok(intact_gpa)
324        } else {
325            Ok(intact_gpa.min(self.fracture_callus.callus_modulus_mpa / 1000.0))
326        }
327    }
328
329    /// Gibson & Ashby (1997) effective trabecular yield strength in MPa, scaled by
330    /// mineralization `mu_min` and fracture-callus strength recovery ratio.
331    pub fn effective_trabecular_yield_mpa(&self) -> Result<f64, String> {
332        self.validate()?;
333        const SOLID_BONE_DENSITY_G_CM3: f64 = 1.85;
334        const SOLID_BONE_YIELD_MPA: f64 = 140.0;
335        let rel = (self.trabecular_apparent_density_g_cm3 / SOLID_BONE_DENSITY_G_CM3).max(0.0);
336        let intact_yield =
337            0.3 * SOLID_BONE_YIELD_MPA * self.mineralization_degree_mu * rel.powf(1.5);
338        Ok(intact_yield * self.fracture_callus.strength_recovery_ratio)
339    }
340}
341
342/// Curated comparative and human clinical densitometry presets (Spec §5.2–5.3).
343#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
344#[serde(rename_all = "snake_case")]
345pub enum SpeciesDensitometryPreset {
346    HumanYoungAdultFemale,
347    HumanPostmenopausalOsteoporotic,
348    AvianPneumaticFemur,
349    SirenianPachyosteoscleroticRib,
350    CetaceanOsteoporoticSpongiosa,
351    ElasmobranchTessellatedCartilage,
352    CrustaceanCalcifiedCuticle,
353    HardwoodSecondaryXylem,
354}
355
356impl SpeciesDensitometryPreset {
357    /// All 8 comparative and clinical presets.
358    pub const ALL: &'static [SpeciesDensitometryPreset] = &[
359        Self::HumanYoungAdultFemale,
360        Self::HumanPostmenopausalOsteoporotic,
361        Self::AvianPneumaticFemur,
362        Self::SirenianPachyosteoscleroticRib,
363        Self::CetaceanOsteoporoticSpongiosa,
364        Self::ElasmobranchTessellatedCartilage,
365        Self::CrustaceanCalcifiedCuticle,
366        Self::HardwoodSecondaryXylem,
367    ];
368
369    /// Materialize the canonical prior [`SkeletalDensityProfile`] for this preset.
370    pub fn to_profile(self) -> SkeletalDensityProfile {
371        match self {
372            Self::HumanYoungAdultFemale => SkeletalDensityProfile {
373                compartment_label: "human_young_adult_female_femoral_neck".into(),
374                cortical_apparent_density_g_cm3: 1.85,
375                cortical_thickness_mm: 4.2,
376                cortical_porosity_ratio: 0.04,
377                trabecular_apparent_density_g_cm3: 0.32,
378                trabecular_bv_tv: 0.24,
379                trabecular_thickness_um: 165.0,
380                trabecular_separation_um: 580.0,
381                trabecular_number_per_mm: 1.45,
382                trabecular_smi: 0.9,
383                fabric_eigenvalues: [1.15, 0.95, 0.90],
384                mineralization_degree_mu: 1.00,
385                ash_fraction: 0.65,
386                qct_volumetric_bmd_mg_ha_cm3: Some(310.0),
387                dexa_areal_bmd_g_cm2: Some(1.02),
388                dexa_t_score: Some(0.17),
389                dexa_z_score: Some(0.17),
390                trabecular_bone_score_tbs: Some(1.42),
391                has_fragility_fracture: false,
392                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
393                fracture_callus: FractureCallusState::intact(),
394                has_orthopedic_implant: false,
395                epistemic_status: EpistemicStatus::Hypothesis,
396            },
397            Self::HumanPostmenopausalOsteoporotic => SkeletalDensityProfile {
398                compartment_label: "human_postmenopausal_osteoporotic_femoral_neck".into(),
399                cortical_apparent_density_g_cm3: 1.62,
400                cortical_thickness_mm: 2.3,
401                cortical_porosity_ratio: 0.14,
402                trabecular_apparent_density_g_cm3: 0.15,
403                trabecular_bv_tv: 0.11,
404                trabecular_thickness_um: 112.0,
405                trabecular_separation_um: 890.0,
406                trabecular_number_per_mm: 0.98,
407                trabecular_smi: 2.3,
408                fabric_eigenvalues: [1.22, 0.92, 0.86],
409                mineralization_degree_mu: 0.96,
410                ash_fraction: 0.62,
411                qct_volumetric_bmd_mg_ha_cm3: Some(145.0),
412                dexa_areal_bmd_g_cm2: Some(0.64),
413                dexa_t_score: Some(-3.00),
414                dexa_z_score: Some(-1.40),
415                trabecular_bone_score_tbs: Some(1.14),
416                has_fragility_fracture: false,
417                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
418                fracture_callus: FractureCallusState::intact(),
419                has_orthopedic_implant: false,
420                epistemic_status: EpistemicStatus::Hypothesis,
421            },
422            Self::AvianPneumaticFemur => SkeletalDensityProfile {
423                compartment_label: "avian_pneumatic_femur".into(),
424                cortical_apparent_density_g_cm3: 1.78,
425                cortical_thickness_mm: 1.1,
426                cortical_porosity_ratio: 0.03,
427                trabecular_apparent_density_g_cm3: 0.12,
428                trabecular_bv_tv: 0.08,
429                trabecular_thickness_um: 140.0,
430                trabecular_separation_um: 1400.0,
431                trabecular_number_per_mm: 0.60,
432                trabecular_smi: 2.1,
433                fabric_eigenvalues: [1.40, 0.85, 0.75],
434                mineralization_degree_mu: 1.12,
435                ash_fraction: 0.72,
436                qct_volumetric_bmd_mg_ha_cm3: None,
437                dexa_areal_bmd_g_cm2: None,
438                dexa_t_score: None,
439                dexa_z_score: None,
440                trabecular_bone_score_tbs: None,
441                has_fragility_fracture: false,
442                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
443                fracture_callus: FractureCallusState::intact(),
444                has_orthopedic_implant: false,
445                epistemic_status: EpistemicStatus::Hypothesis,
446            },
447            Self::SirenianPachyosteoscleroticRib => SkeletalDensityProfile {
448                compartment_label: "sirenian_pachyosteosclerotic_rib".into(),
449                cortical_apparent_density_g_cm3: 2.02,
450                cortical_thickness_mm: 14.0,
451                cortical_porosity_ratio: 0.02,
452                trabecular_apparent_density_g_cm3: 1.85,
453                trabecular_bv_tv: 0.95,
454                trabecular_thickness_um: 480.0,
455                trabecular_separation_um: 40.0,
456                trabecular_number_per_mm: 2.20,
457                trabecular_smi: 0.1,
458                fabric_eigenvalues: [1.05, 1.00, 0.95],
459                mineralization_degree_mu: 1.04,
460                ash_fraction: 0.68,
461                qct_volumetric_bmd_mg_ha_cm3: None,
462                dexa_areal_bmd_g_cm2: None,
463                dexa_t_score: None,
464                dexa_z_score: None,
465                trabecular_bone_score_tbs: None,
466                has_fragility_fracture: false,
467                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
468                fracture_callus: FractureCallusState::intact(),
469                has_orthopedic_implant: false,
470                epistemic_status: EpistemicStatus::Hypothesis,
471            },
472            Self::CetaceanOsteoporoticSpongiosa => SkeletalDensityProfile {
473                compartment_label: "cetacean_osteoporotic_spongiosa".into(),
474                cortical_apparent_density_g_cm3: 1.55,
475                cortical_thickness_mm: 1.8,
476                cortical_porosity_ratio: 0.12,
477                trabecular_apparent_density_g_cm3: 0.24,
478                trabecular_bv_tv: 0.18,
479                trabecular_thickness_um: 135.0,
480                trabecular_separation_um: 680.0,
481                trabecular_number_per_mm: 1.15,
482                trabecular_smi: 1.6,
483                fabric_eigenvalues: [1.10, 1.00, 0.90],
484                mineralization_degree_mu: 0.95,
485                ash_fraction: 0.60,
486                qct_volumetric_bmd_mg_ha_cm3: None,
487                dexa_areal_bmd_g_cm2: None,
488                dexa_t_score: None,
489                dexa_z_score: None,
490                trabecular_bone_score_tbs: None,
491                has_fragility_fracture: false,
492                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
493                fracture_callus: FractureCallusState::intact(),
494                has_orthopedic_implant: false,
495                epistemic_status: EpistemicStatus::Hypothesis,
496            },
497            Self::ElasmobranchTessellatedCartilage => SkeletalDensityProfile {
498                compartment_label: "elasmobranch_tessellated_cartilage".into(),
499                cortical_apparent_density_g_cm3: 1.70,
500                cortical_thickness_mm: 1.5,
501                cortical_porosity_ratio: 0.08,
502                trabecular_apparent_density_g_cm3: 1.10,
503                trabecular_bv_tv: 0.10,
504                trabecular_thickness_um: 220.0,
505                trabecular_separation_um: 900.0,
506                trabecular_number_per_mm: 0.80,
507                trabecular_smi: 1.2,
508                fabric_eigenvalues: [1.10, 1.05, 0.85],
509                mineralization_degree_mu: 0.85,
510                ash_fraction: 0.20,
511                qct_volumetric_bmd_mg_ha_cm3: None,
512                dexa_areal_bmd_g_cm2: None,
513                dexa_t_score: None,
514                dexa_z_score: None,
515                trabecular_bone_score_tbs: None,
516                has_fragility_fracture: false,
517                physeal_fusion: PhysealFusionStatus::OpenCartilaginousPhysis,
518                fracture_callus: FractureCallusState::intact(),
519                has_orthopedic_implant: false,
520                epistemic_status: EpistemicStatus::Hypothesis,
521            },
522            Self::CrustaceanCalcifiedCuticle => SkeletalDensityProfile {
523                compartment_label: "crustacean_calcified_cuticle".into(),
524                cortical_apparent_density_g_cm3: 1.65,
525                cortical_thickness_mm: 2.2,
526                cortical_porosity_ratio: 0.05,
527                trabecular_apparent_density_g_cm3: 0.05,
528                trabecular_bv_tv: 0.05,
529                trabecular_thickness_um: 90.0,
530                trabecular_separation_um: 1200.0,
531                trabecular_number_per_mm: 0.50,
532                trabecular_smi: 1.5,
533                fabric_eigenvalues: [1.20, 1.00, 0.80],
534                mineralization_degree_mu: 0.90,
535                ash_fraction: 0.75,
536                qct_volumetric_bmd_mg_ha_cm3: None,
537                dexa_areal_bmd_g_cm2: None,
538                dexa_t_score: None,
539                dexa_z_score: None,
540                trabecular_bone_score_tbs: None,
541                has_fragility_fracture: false,
542                physeal_fusion: PhysealFusionStatus::ClosedMatureDiaphysis,
543                fracture_callus: FractureCallusState::intact(),
544                has_orthopedic_implant: false,
545                epistemic_status: EpistemicStatus::Hypothesis,
546            },
547            Self::HardwoodSecondaryXylem => SkeletalDensityProfile {
548                compartment_label: "hardwood_secondary_xylem".into(),
549                cortical_apparent_density_g_cm3: 0.78,
550                cortical_thickness_mm: 45.0,
551                cortical_porosity_ratio: 0.35,
552                trabecular_apparent_density_g_cm3: 0.62,
553                trabecular_bv_tv: 0.55,
554                trabecular_thickness_um: 60.0,
555                trabecular_separation_um: 120.0,
556                trabecular_number_per_mm: 4.50,
557                trabecular_smi: 0.6,
558                fabric_eigenvalues: [1.80, 0.60, 0.60],
559                mineralization_degree_mu: 0.45,
560                ash_fraction: 0.02,
561                qct_volumetric_bmd_mg_ha_cm3: None,
562                dexa_areal_bmd_g_cm2: None,
563                dexa_t_score: None,
564                dexa_z_score: None,
565                trabecular_bone_score_tbs: None,
566                has_fragility_fracture: false,
567                physeal_fusion: PhysealFusionStatus::OpenCartilaginousPhysis,
568                fracture_callus: FractureCallusState::intact(),
569                has_orthopedic_implant: false,
570                epistemic_status: EpistemicStatus::Hypothesis,
571            },
572        }
573    }
574}
575
576/// Skeletal muscle architectural and myosteatosis quality profile (Spec §5.4).
577#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
578pub struct MuscleQualityProfile {
579    pub muscle_group: String,
580    pub volume_cm3: f64,
581    pub optimal_fiber_length_cm: f64,
582    pub pennation_angle_rad: f64,
583    pub pcsa_cm2: f64,
584    pub specific_tension_n_cm2: f64,
585    /// CT skeletal muscle attenuation in Hounsfield Units (healthy: +40..+60 HU; myosteatosis < +30 HU).
586    pub muscle_radiodensity_hu: f64,
587    /// Intramuscular / intermuscular adipose fraction (`PDFF` / `IMAT`) in `[0.0, 1.0]`.
588    pub imat_fraction: f64,
589    /// Neuromuscular activation / neural drive factor in `[0.0, 1.0]`.
590    pub neural_activation_factor: f64,
591    /// Composite contractile quality multiplier `eta_myo` in `[0.0, 1.0]`.
592    pub effective_quality_eta: f64,
593    pub epistemic_status: EpistemicStatus,
594}
595
596/// Alias matching the name referenced in Spec §12.3 (`BIO-WP-05`).
597pub type MyologicalQualityProfile = MuscleQualityProfile;
598
599impl MuscleQualityProfile {
600    /// Construct and validate a muscle quality profile, computing `pcsa_cm2` and `effective_quality_eta`.
601    pub fn new(
602        muscle_group: impl Into<String>,
603        volume_cm3: f64,
604        optimal_fiber_length_cm: f64,
605        pennation_angle_rad: f64,
606        specific_tension_n_cm2: f64,
607        muscle_radiodensity_hu: f64,
608        imat_fraction: f64,
609        neural_activation_factor: f64,
610    ) -> Result<Self, String> {
611        let muscle_group = muscle_group.into();
612        if muscle_group.trim().is_empty() {
613            return Err("muscle_group must not be empty".into());
614        }
615        if !volume_cm3.is_finite()
616            || !optimal_fiber_length_cm.is_finite()
617            || !pennation_angle_rad.is_finite()
618            || !specific_tension_n_cm2.is_finite()
619            || !muscle_radiodensity_hu.is_finite()
620            || !imat_fraction.is_finite()
621            || !neural_activation_factor.is_finite()
622            || volume_cm3 < 0.0
623            || optimal_fiber_length_cm <= 0.0
624            || !(0.0..std::f64::consts::FRAC_PI_2).contains(&pennation_angle_rad)
625            || specific_tension_n_cm2 <= 0.0
626            || !(-1000.0..=3000.0).contains(&muscle_radiodensity_hu)
627            || !(0.0..=1.0).contains(&imat_fraction)
628            || !(0.0..=1.0).contains(&neural_activation_factor)
629        {
630            return Err("invalid muscle architecture or myosteatosis parameter".into());
631        }
632        let pcsa_cm2 = (volume_cm3 * pennation_angle_rad.cos()) / optimal_fiber_length_cm;
633        let hu_quality = ((muscle_radiodensity_hu + 20.0) / 60.0).clamp(0.0, 1.0);
634        let effective_quality_eta = (1.0 - imat_fraction) * hu_quality * neural_activation_factor;
635        Ok(Self {
636            muscle_group,
637            volume_cm3,
638            optimal_fiber_length_cm,
639            pennation_angle_rad,
640            pcsa_cm2,
641            specific_tension_n_cm2,
642            muscle_radiodensity_hu,
643            imat_fraction,
644            neural_activation_factor,
645            effective_quality_eta,
646            epistemic_status: EpistemicStatus::Hypothesis,
647        })
648    }
649
650    /// Recompute `effective_quality_eta` after field modification (e.g., physiological modifier).
651    pub fn recompute_quality_eta(&mut self) {
652        let hu_quality = ((self.muscle_radiodensity_hu + 20.0) / 60.0).clamp(0.0, 1.0);
653        self.effective_quality_eta =
654            (1.0 - self.imat_fraction.clamp(0.0, 1.0)) * hu_quality * self.neural_activation_factor.clamp(0.0, 1.0);
655    }
656
657    /// Peak isometric force in Newtons along the tendon line of action:
658    /// `F_max = PCSA * sigma_0 * cos(alpha) * eta_myo`.
659    pub fn effective_max_force_n(&self) -> Result<f64, String> {
660        if !self.pcsa_cm2.is_finite()
661            || !self.specific_tension_n_cm2.is_finite()
662            || !self.pennation_angle_rad.is_finite()
663            || !self.effective_quality_eta.is_finite()
664            || self.pcsa_cm2 < 0.0
665            || self.specific_tension_n_cm2 <= 0.0
666            || !(0.0..std::f64::consts::FRAC_PI_2).contains(&self.pennation_angle_rad)
667            || !(0.0..=1.0).contains(&self.effective_quality_eta)
668        {
669            return Err("invalid MuscleQualityProfile parameters".into());
670        }
671        Ok(self.pcsa_cm2
672            * self.specific_tension_n_cm2
673            * self.pennation_angle_rad.cos()
674            * self.effective_quality_eta)
675    }
676
677    /// True when radiodensity falls below +30 HU or IMAT >= 15%.
678    pub fn is_myosteatotic(&self) -> bool {
679        self.muscle_radiodensity_hu < 30.0 || self.imat_fraction >= 0.15
680    }
681}
682
683/// Coupled functional mobility, effort reserve, balance stability, and bone fracture-risk report
684/// (Spec §5.4). Always [`EpistemicStatus::Hypothesis`].
685#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
686pub struct MobilityAndFractureRiskReport {
687    pub task_label: String,
688    /// Joint Relative Effort Ratio `RER = |tau_required| / |tau_max|` (`>= 1.0` exceeds reserve).
689    pub joint_relative_effort_ratio: f64,
690    /// Hof (2005) Margin of Stability `MoS = bos_boundary - XCoM` in meters (`< 0` = unstable).
691    pub hof_margin_of_stability_m: f64,
692    /// Vertebral compressive Factor of Risk `Phi_vertebra = sigma_applied / sigma_yield`.
693    pub vertebral_factor_of_risk_phi: f64,
694    /// Femoral neck / hip Factor of Risk `Phi_hip = sigma_applied / sigma_yield`.
695    pub femoral_neck_factor_of_risk_phi: f64,
696    #[serde(default, skip_serializing_if = "Option::is_none")]
697    pub who_category: Option<WhoDensityCategory>,
698    pub myosteatosis_present: bool,
699    pub limiting_factors: Vec<String>,
700    pub epistemic_status: EpistemicStatus,
701    pub uncertainty_note: String,
702}
703
704/// Kinematic & external-load task inputs for [`evaluate_mobility_and_fracture_risk`].
705#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
706pub struct MobilityTaskInput {
707    pub task_label: String,
708    pub required_joint_torque_nm: f64,
709    pub muscle_moment_arm_m: f64,
710    pub com_pos_m: f64,
711    pub com_vel_m_s: f64,
712    pub pendulum_length_m: f64,
713    pub bos_boundary_m: f64,
714    pub gravity_m_s2: f64,
715    pub applied_vertebral_stress_mpa: f64,
716    pub applied_femoral_neck_stress_mpa: f64,
717}
718
719/// Evaluate coupled mobility effort (`RER`), dynamic balance (`MoS`), and skeletal
720/// factor-of-risk (`Phi`) from calibrated skeletal and muscle quality profiles.
721pub fn evaluate_mobility_and_fracture_risk(
722    bone: &SkeletalDensityProfile,
723    muscle: &MuscleQualityProfile,
724    task: &MobilityTaskInput,
725) -> Result<MobilityAndFractureRiskReport, String> {
726    bone.validate()?;
727    if task.task_label.trim().is_empty() {
728        return Err("task_label must not be empty".into());
729    }
730    if !task.required_joint_torque_nm.is_finite()
731        || !task.muscle_moment_arm_m.is_finite()
732        || !task.com_pos_m.is_finite()
733        || !task.com_vel_m_s.is_finite()
734        || !task.pendulum_length_m.is_finite()
735        || !task.bos_boundary_m.is_finite()
736        || !task.gravity_m_s2.is_finite()
737        || !task.applied_vertebral_stress_mpa.is_finite()
738        || !task.applied_femoral_neck_stress_mpa.is_finite()
739        || task.muscle_moment_arm_m <= 0.0
740        || task.pendulum_length_m <= 0.0
741        || task.gravity_m_s2 <= 0.0
742        || task.applied_vertebral_stress_mpa < 0.0
743        || task.applied_femoral_neck_stress_mpa < 0.0
744    {
745        return Err("invalid kinematic or stress task parameters".into());
746    }
747
748    let f_max = muscle.effective_max_force_n()?;
749    let max_torque_nm = f_max * task.muscle_moment_arm_m;
750    if max_torque_nm <= 0.0 {
751        return Err("effective max joint torque must be positive to compute RER".into());
752    }
753
754    let joint_relative_effort_ratio = task.required_joint_torque_nm.abs() / max_torque_nm;
755    let omega0 = (task.gravity_m_s2 / task.pendulum_length_m).sqrt();
756    let xcom = task.com_pos_m + task.com_vel_m_s / omega0;
757    let hof_margin_of_stability_m = task.bos_boundary_m - xcom;
758
759    let yield_mpa = bone.effective_trabecular_yield_mpa()?;
760    if yield_mpa <= 0.0 {
761        return Err("effective trabecular yield strength must be positive".into());
762    }
763    let vertebral_factor_of_risk_phi = task.applied_vertebral_stress_mpa / yield_mpa;
764    let femoral_neck_factor_of_risk_phi = task.applied_femoral_neck_stress_mpa / yield_mpa;
765
766    let who_category = bone.who_category();
767    let myosteatosis_present = muscle.is_myosteatotic();
768    let mut limiting_factors = Vec::new();
769    if joint_relative_effort_ratio >= 0.85 {
770        limiting_factors.push(format!(
771            "elevated relative effort on {} (RER={joint_relative_effort_ratio:.2})",
772            muscle.muscle_group
773        ));
774    }
775    if hof_margin_of_stability_m < 0.0 {
776        limiting_factors.push(format!(
777            "negative Hof margin of stability (MoS={hof_margin_of_stability_m:.3} m)"
778        ));
779    }
780    if vertebral_factor_of_risk_phi >= 1.0 {
781        limiting_factors.push(format!(
782            "vertebral factor of risk >= 1.0 (Phi={vertebral_factor_of_risk_phi:.2})"
783        ));
784    }
785    if femoral_neck_factor_of_risk_phi >= 1.0 {
786        limiting_factors.push(format!(
787            "femoral neck factor of risk >= 1.0 (Phi={femoral_neck_factor_of_risk_phi:.2})"
788        ));
789    }
790    if myosteatosis_present {
791        limiting_factors.push("myosteatosis present (reduced contractile quality)".into());
792    }
793    if bone.fracture_callus.stage > 0 && bone.fracture_callus.stage < 4 {
794        limiting_factors.push(format!(
795            "active fracture callus healing stage {}",
796            bone.fracture_callus.stage
797        ));
798    }
799
800    Ok(MobilityAndFractureRiskReport {
801        task_label: task.task_label.clone(),
802        joint_relative_effort_ratio,
803        hof_margin_of_stability_m,
804        vertebral_factor_of_risk_phi,
805        femoral_neck_factor_of_risk_phi,
806        who_category,
807        myosteatosis_present,
808        limiting_factors,
809        epistemic_status: EpistemicStatus::Hypothesis,
810        uncertainty_note: "Coupled biomechanical hypothesis derived from calibrated density/muscle inputs; not a clinical diagnosis.".into(),
811    })
812}
813
814#[cfg(test)]
815mod tests {
816    use super::*;
817
818    #[test]
819    fn all_eight_species_presets_validate_and_order_physically() {
820        for preset in SpeciesDensitometryPreset::ALL {
821            let p = SkeletalDensityProfile::from_preset(*preset);
822            p.validate().expect("preset must validate");
823        }
824        let young = SkeletalDensityProfile::from_preset(
825            SpeciesDensitometryPreset::HumanYoungAdultFemale,
826        );
827        let osteo = SkeletalDensityProfile::from_preset(
828            SpeciesDensitometryPreset::HumanPostmenopausalOsteoporotic,
829        );
830        let sirenian = SkeletalDensityProfile::from_preset(
831            SpeciesDensitometryPreset::SirenianPachyosteoscleroticRib,
832        );
833        let cetacean = SkeletalDensityProfile::from_preset(
834            SpeciesDensitometryPreset::CetaceanOsteoporoticSpongiosa,
835        );
836
837        assert_eq!(young.who_category(), Some(WhoDensityCategory::Normal));
838        assert_eq!(osteo.who_category(), Some(WhoDensityCategory::Osteoporosis));
839        assert_eq!(sirenian.who_category(), None);
840
841        let e_sir = sirenian.effective_cortical_modulus_gpa(0.01).unwrap();
842        let e_cet = cetacean.effective_cortical_modulus_gpa(0.01).unwrap();
843        assert!(e_sir > e_cet);
844        assert!(
845            young.effective_trabecular_yield_mpa().unwrap()
846                > osteo.effective_trabecular_yield_mpa().unwrap()
847        );
848    }
849
850    #[test]
851    fn fracture_callus_stages_0_through_4_progress_and_reject_out_of_bounds() {
852        assert!(FractureCallusState::from_stage(5).is_err());
853        let s0 = FractureCallusState::from_stage(0).unwrap();
854        let s1 = FractureCallusState::from_stage(1).unwrap();
855        let s2 = FractureCallusState::from_stage(2).unwrap();
856        let s3 = FractureCallusState::from_stage(3).unwrap();
857        let s4 = FractureCallusState::from_stage(4).unwrap();
858        assert_eq!(s0.phase, CallusHealingPhase::Intact);
859        assert_eq!(s1.phase, CallusHealingPhase::AcuteHematoma);
860        assert_eq!(s2.phase, CallusHealingPhase::SoftCallus);
861        assert_eq!(s3.phase, CallusHealingPhase::HardCallus);
862        assert_eq!(s4.phase, CallusHealingPhase::Remodeling);
863        assert!(s1.callus_modulus_mpa < s2.callus_modulus_mpa);
864        assert!(s2.callus_modulus_mpa < s3.callus_modulus_mpa);
865        assert!(s3.callus_modulus_mpa < s4.callus_modulus_mpa);
866        assert!(s1.pain_guarding_coactivation > s4.pain_guarding_coactivation);
867    }
868
869    #[test]
870    fn coupled_osteosarcopenia_raises_effort_and_fracture_risk() {
871        let young_bone = SkeletalDensityProfile::from_preset(
872            SpeciesDensitometryPreset::HumanYoungAdultFemale,
873        );
874        let osteo_bone = SkeletalDensityProfile::from_preset(
875            SpeciesDensitometryPreset::HumanPostmenopausalOsteoporotic,
876        );
877        let healthy_muscle =
878            MuscleQualityProfile::new("quadriceps", 420.0, 10.0, 0.24, 40.0, 52.0, 0.03, 1.0)
879                .unwrap();
880        let myo_muscle =
881            MuscleQualityProfile::new("quadriceps", 300.0, 10.0, 0.24, 40.0, 18.0, 0.24, 0.85)
882                .unwrap();
883
884        assert!(!healthy_muscle.is_myosteatotic());
885        assert!(myo_muscle.is_myosteatotic());
886
887        let task = MobilityTaskInput {
888            task_label: "sit_to_stand".into(),
889            required_joint_torque_nm: 65.0,
890            muscle_moment_arm_m: 0.05,
891            com_pos_m: 0.04,
892            com_vel_m_s: 0.15,
893            pendulum_length_m: 0.95,
894            bos_boundary_m: 0.14,
895            gravity_m_s2: 9.81,
896            applied_vertebral_stress_mpa: 1.8,
897            applied_femoral_neck_stress_mpa: 2.2,
898        };
899
900        let r_young = evaluate_mobility_and_fracture_risk(&young_bone, &healthy_muscle, &task).unwrap();
901        let r_osteo = evaluate_mobility_and_fracture_risk(&osteo_bone, &myo_muscle, &task).unwrap();
902
903        assert_eq!(r_young.epistemic_status, EpistemicStatus::Hypothesis);
904        assert!(r_osteo.joint_relative_effort_ratio > r_young.joint_relative_effort_ratio);
905        assert!(r_osteo.femoral_neck_factor_of_risk_phi > r_young.femoral_neck_factor_of_risk_phi);
906        assert!(r_osteo.myosteatosis_present);
907    }
908
909    #[test]
910    fn missing_t_score_never_fabricates_who_category() {
911        let mut p = SkeletalDensityProfile::from_preset(
912            SpeciesDensitometryPreset::HumanYoungAdultFemale,
913        );
914        p.dexa_t_score = None;
915        assert_eq!(p.who_category(), None);
916    }
917}