1use serde::{Deserialize, Serialize};
16
17use crate::record::EpistemicStatus;
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum WhoDensityCategory {
23 Normal,
25 Osteopenia,
27 Osteoporosis,
29 SevereOsteoporosis,
31}
32
33#[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#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
44#[serde(rename_all = "snake_case")]
45pub enum CallusHealingPhase {
46 Intact,
48 AcuteHematoma,
50 SoftCallus,
52 HardCallus,
54 Remodeling,
56}
57
58#[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 pub callus_modulus_mpa: f64,
74 pub strength_recovery_ratio: f64,
76 pub pain_guarding_coactivation: f64,
78}
79
80impl FractureCallusState {
81 pub fn from_stage(stage: u8) -> Result<Self, String> {
83 Self::from_stage_with_days(stage, None)
84 }
85
86 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 pub fn intact() -> Self {
121 Self::from_stage(0).expect("stage 0 is valid")
122 }
123
124 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
162pub struct SkeletalDensityProfile {
163 pub compartment_label: String,
164 pub cortical_apparent_density_g_cm3: f64,
166 pub cortical_thickness_mm: f64,
168 pub cortical_porosity_ratio: f64,
170 pub trabecular_apparent_density_g_cm3: f64,
172 pub trabecular_bv_tv: f64,
174 pub trabecular_thickness_um: f64,
176 pub trabecular_separation_um: f64,
178 pub trabecular_number_per_mm: f64,
180 pub trabecular_smi: f64,
182 pub fabric_eigenvalues: [f64; 3],
184 pub mineralization_degree_mu: f64,
187 pub ash_fraction: f64,
189 #[serde(default, skip_serializing_if = "Option::is_none")]
191 pub qct_volumetric_bmd_mg_ha_cm3: Option<f64>,
192 #[serde(default, skip_serializing_if = "Option::is_none")]
194 pub dexa_areal_bmd_g_cm2: Option<f64>,
195 #[serde(default, skip_serializing_if = "Option::is_none")]
197 pub dexa_t_score: Option<f64>,
198 #[serde(default, skip_serializing_if = "Option::is_none")]
200 pub dexa_z_score: Option<f64>,
201 #[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
211pub type SkeletalDensitometryProfile = SkeletalDensityProfile;
213
214impl SkeletalDensityProfile {
215 pub fn from_preset(preset: SpeciesDensitometryPreset) -> Self {
217 preset.to_profile()
218 }
219
220 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 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 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 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#[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 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 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#[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 pub muscle_radiodensity_hu: f64,
587 pub imat_fraction: f64,
589 pub neural_activation_factor: f64,
591 pub effective_quality_eta: f64,
593 pub epistemic_status: EpistemicStatus,
594}
595
596pub type MyologicalQualityProfile = MuscleQualityProfile;
598
599impl MuscleQualityProfile {
600 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 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 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 pub fn is_myosteatotic(&self) -> bool {
679 self.muscle_radiodensity_hu < 30.0 || self.imat_fraction >= 0.15
680 }
681}
682
683#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
686pub struct MobilityAndFractureRiskReport {
687 pub task_label: String,
688 pub joint_relative_effort_ratio: f64,
690 pub hof_margin_of_stability_m: f64,
692 pub vertebral_factor_of_risk_phi: f64,
694 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#[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
719pub 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}