Skip to main content

qualia_core_db/bundle/
species_meta.rs

1//! Domain metadata schemas for `.hmc` holistic entity digital twins.
2//!
3//! Provides CBOR-serializable representations for flora, fauna, and mechanical
4//! assembly species metadata, enabling biological growth/phyllotaxis,
5//! musculoskeletal biomechanics, and kinematic/fatigue lifespans in `.hmc` bundles.
6
7use serde::{Deserialize, Serialize};
8
9use super::format::BundleError;
10
11pub const SPECIES_META_ENTRY_KEY: &str = "manifest/species_meta.cbor";
12pub const SPECIES_META_KIND: &str = "species_meta";
13
14fn default_phyllotaxis() -> f32 {
15    137.50776
16}
17
18fn default_murray() -> f32 {
19    2.49
20}
21
22fn default_wbe_radius() -> f32 {
23    0.33333334
24}
25
26fn default_wbe_length() -> f32 {
27    0.6666667
28}
29
30fn default_bark_scale() -> f32 {
31    1.0
32}
33
34fn default_chlorophyll() -> [f32; 2] {
35    [430.0, 660.0]
36}
37
38/// Botanical growth and morphology parameters for flora entity twins.
39#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
40pub struct FloraSpeciesMeta {
41    /// Canonical taxonomic identifier (e.g. "urn:taxon:quercus_robur").
42    pub taxon_id: String,
43    /// Golden phyllotaxis divergence angle in degrees (default 137.50776°).
44    #[serde(default = "default_phyllotaxis")]
45    pub phyllotaxis_divergence_deg: f32,
46    /// Murray's law vascular branching exponent (default 2.49).
47    #[serde(default = "default_murray")]
48    pub murray_exponent: f32,
49    /// West-Brown-Enquist (WBE) metabolic radius scaling exponent (default 1/3).
50    #[serde(default = "default_wbe_radius")]
51    pub west_brown_enquist_radius_exp: f32,
52    /// WBE length scaling exponent (default 2/3).
53    #[serde(default = "default_wbe_length")]
54    pub wbe_length_exp: f32,
55    /// Bark Voronoi surface irregularity scale.
56    #[serde(default = "default_bark_scale")]
57    pub bark_voronoi_scale: f32,
58    /// Chlorophyll a/b peak absorption wavelength range in nanometers [a, b].
59    #[serde(default = "default_chlorophyll")]
60    pub chlorophyll_band_nm: [f32; 2],
61    /// Chronological list of seasonal phenology stages (e.g. Dormant, BudBreak, FullCanopy).
62    #[serde(default)]
63    pub seasonal_phenology_stages: Vec<String>,
64}
65
66impl Default for FloraSpeciesMeta {
67    fn default() -> Self {
68        Self {
69            taxon_id: String::new(),
70            phyllotaxis_divergence_deg: default_phyllotaxis(),
71            murray_exponent: default_murray(),
72            west_brown_enquist_radius_exp: default_wbe_radius(),
73            wbe_length_exp: default_wbe_length(),
74            bark_voronoi_scale: default_bark_scale(),
75            chlorophyll_band_nm: default_chlorophyll(),
76            seasonal_phenology_stages: Vec::new(),
77        }
78    }
79}
80
81impl FloraSpeciesMeta {
82    pub fn new(taxon_id: impl Into<String>) -> Self {
83        Self {
84            taxon_id: taxon_id.into(),
85            ..Self::default()
86        }
87    }
88}
89
90fn default_pga_motor() -> bool {
91    true
92}
93
94fn default_isometric_force() -> f32 {
95    1000.0
96}
97
98fn default_optimal_fiber() -> f32 {
99    0.1
100}
101
102fn default_contraction_velocity() -> f32 {
103    10.0
104}
105
106fn default_dimorphism() -> [f32; 3] {
107    [1.0, 1.0, 1.0]
108}
109
110/// Musculoskeletal and anatomical parameters for fauna entity twins.
111#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
112pub struct FaunaSpeciesMeta {
113    /// Canonical taxonomic identifier (e.g. "urn:taxon:canis_lupus").
114    pub taxon_id: String,
115    /// Number of skeletal articulation joints in the base rig.
116    #[serde(default)]
117    pub skeleton_joint_count: u32,
118    /// Whether Projective Geometric Algebra (PGA) motor skinning is enabled.
119    #[serde(default = "default_pga_motor")]
120    pub pga_motor_skinning: bool,
121    /// Number of simulated Hill-type muscle-tendon units.
122    #[serde(default)]
123    pub hill_muscle_count: u32,
124    /// Maximum isometric force in Newtons (F0).
125    #[serde(default = "default_isometric_force")]
126    pub max_isometric_force_n: f32,
127    /// Optimal muscle fiber resting length in meters (l0_m).
128    #[serde(default = "default_optimal_fiber")]
129    pub optimal_fiber_length_m: f32,
130    /// Maximum contraction velocity in optimal fiber lengths per second (v_max / l0_m).
131    #[serde(default = "default_contraction_velocity")]
132    pub max_contraction_velocity_l0_s: f32,
133    /// Sexual dimorphism volumetric scale multipliers [x, y, z].
134    #[serde(default = "default_dimorphism")]
135    pub sexual_dimorphism_scale: [f32; 3],
136    /// Exact bundle entry key for the species vocalization audio asset, if any.
137    ///
138    /// The Rust field retains its legacy spelling for source compatibility. CBOR
139    /// writes the canonical QAC name and accepts either spelling on input; entry
140    /// key values (including legacy `.q4au` filenames) are preserved verbatim.
141    #[serde(
142        default,
143        rename = "vocalization_qac_key",
144        alias = "vocalization_q4au_key",
145        skip_serializing_if = "Option::is_none"
146    )]
147    pub vocalization_q4au_key: Option<String>,
148}
149
150impl Default for FaunaSpeciesMeta {
151    fn default() -> Self {
152        Self {
153            taxon_id: String::new(),
154            skeleton_joint_count: 0,
155            pga_motor_skinning: default_pga_motor(),
156            hill_muscle_count: 0,
157            max_isometric_force_n: default_isometric_force(),
158            optimal_fiber_length_m: default_optimal_fiber(),
159            max_contraction_velocity_l0_s: default_contraction_velocity(),
160            sexual_dimorphism_scale: default_dimorphism(),
161            vocalization_q4au_key: None,
162        }
163    }
164}
165
166impl FaunaSpeciesMeta {
167    /// Return the exact vocalization bundle entry key, without renaming it.
168    pub fn vocalization_qac_key(&self) -> Option<&str> {
169        self.vocalization_q4au_key.as_deref()
170    }
171
172    /// Set or clear the vocalization bundle entry key, preserving its exact value.
173    pub fn set_vocalization_qac_key(&mut self, key: Option<String>) {
174        self.vocalization_q4au_key = key;
175    }
176
177    pub fn new(taxon_id: impl Into<String>) -> Self {
178        Self {
179            taxon_id: taxon_id.into(),
180            ..Self::default()
181        }
182    }
183}
184
185fn default_basquin_coeff() -> f32 {
186    500.0
187}
188
189fn default_basquin_exp() -> f32 {
190    -0.1
191}
192
193fn default_paris_c() -> f32 {
194    1e-11
195}
196
197fn default_paris_m() -> f32 {
198    3.0
199}
200
201fn default_temp_range() -> [f32; 2] {
202    [233.15, 353.15]
203}
204
205/// Kinematic and structural fatigue parameters for mechanical assemblies.
206#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
207pub struct MechanicalAssemblyMeta {
208    /// Unique assembly or part catalog identifier (e.g. "urn:part:turbopump_mk4").
209    pub assembly_id: String,
210    /// Number of kinematic pairs (revolute, prismatic, spherical joints).
211    #[serde(default)]
212    pub kinematic_pair_count: u32,
213    /// Basquin high-cycle fatigue strength coefficient in MPa (sigma_f').
214    #[serde(default = "default_basquin_coeff")]
215    pub basquin_fatigue_strength_coeff_mpa: f32,
216    /// Basquin fatigue strength exponent (b).
217    #[serde(default = "default_basquin_exp")]
218    pub basquin_fatigue_exponent_b: f32,
219    /// Paris-Erdogan crack propagation coefficient (C).
220    #[serde(default = "default_paris_c")]
221    pub paris_erdogan_c: f32,
222    /// Paris-Erdogan crack propagation exponent (m).
223    #[serde(default = "default_paris_m")]
224    pub paris_erdogan_m: f32,
225    /// Operational temperature range in Kelvin [min_k, max_k].
226    #[serde(default = "default_temp_range")]
227    pub operating_temp_kelvin_range: [f32; 2],
228    /// Bundle entry key for the precise CAD B-Rep STEP model, if present.
229    #[serde(default, skip_serializing_if = "Option::is_none")]
230    pub cad_brep_step_key: Option<String>,
231}
232
233impl Default for MechanicalAssemblyMeta {
234    fn default() -> Self {
235        Self {
236            assembly_id: String::new(),
237            kinematic_pair_count: 0,
238            basquin_fatigue_strength_coeff_mpa: default_basquin_coeff(),
239            basquin_fatigue_exponent_b: default_basquin_exp(),
240            paris_erdogan_c: default_paris_c(),
241            paris_erdogan_m: default_paris_m(),
242            operating_temp_kelvin_range: default_temp_range(),
243            cad_brep_step_key: None,
244        }
245    }
246}
247
248impl MechanicalAssemblyMeta {
249    pub fn new(assembly_id: impl Into<String>) -> Self {
250        Self {
251            assembly_id: assembly_id.into(),
252            ..Self::default()
253        }
254    }
255}
256
257/// Polymorphic container for domain-specific species and assembly metadata.
258#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
259pub enum HolisticSpeciesMeta {
260    Flora(FloraSpeciesMeta),
261    Fauna(FaunaSpeciesMeta),
262    Mechanical(MechanicalAssemblyMeta),
263}
264
265impl HolisticSpeciesMeta {
266    /// Serialise the metadata record to CBOR bytes.
267    pub fn encode_to_cbor(&self) -> Result<Vec<u8>, BundleError> {
268        let mut buf = Vec::new();
269        ciborium::into_writer(self, &mut buf).map_err(|e| BundleError::Cbor(e.to_string()))?;
270        Ok(buf)
271    }
272
273    /// Deserialise a metadata record from CBOR bytes.
274    pub fn decode_from_cbor(bytes: &[u8]) -> Result<Self, BundleError> {
275        ciborium::from_reader(bytes).map_err(|e| BundleError::Cbor(e.to_string()))
276    }
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282
283    #[test]
284    fn flora_meta_roundtrip() {
285        let mut flora = FloraSpeciesMeta::new("urn:taxon:sequoia_sempervirens");
286        flora.seasonal_phenology_stages = vec!["SpringFlush".into(), "Dormant".into()];
287        let meta = HolisticSpeciesMeta::Flora(flora.clone());
288
289        let bytes = meta.encode_to_cbor().expect("cbor encode");
290        let decoded = HolisticSpeciesMeta::decode_from_cbor(&bytes).expect("cbor decode");
291        match decoded {
292            HolisticSpeciesMeta::Flora(f) => {
293                assert_eq!(f.taxon_id, "urn:taxon:sequoia_sempervirens");
294                assert_eq!(f.phyllotaxis_divergence_deg, 137.50776);
295                assert_eq!(f.murray_exponent, 2.49);
296                assert_eq!(f.seasonal_phenology_stages.len(), 2);
297            }
298            _ => panic!("expected Flora variant"),
299        }
300    }
301
302    #[test]
303    fn fauna_meta_roundtrip() {
304        let mut fauna = FaunaSpeciesMeta::new("urn:taxon:panthera_leo");
305        fauna.skeleton_joint_count = 64;
306        fauna.hill_muscle_count = 120;
307        fauna.vocalization_q4au_key = Some("audio/lion_roar.q4au".into());
308        let meta = HolisticSpeciesMeta::Fauna(fauna);
309
310        let bytes = meta.encode_to_cbor().expect("cbor encode");
311        let decoded = HolisticSpeciesMeta::decode_from_cbor(&bytes).expect("cbor decode");
312        match decoded {
313            HolisticSpeciesMeta::Fauna(f) => {
314                assert_eq!(f.taxon_id, "urn:taxon:panthera_leo");
315                assert_eq!(f.skeleton_joint_count, 64);
316                assert_eq!(f.hill_muscle_count, 120);
317                assert!(f.pga_motor_skinning);
318                assert_eq!(
319                    f.vocalization_q4au_key.as_deref(),
320                    Some("audio/lion_roar.q4au")
321                );
322            }
323            _ => panic!("expected Fauna variant"),
324        }
325    }
326
327    #[test]
328    fn mechanical_meta_roundtrip() {
329        let mut mech = MechanicalAssemblyMeta::new("urn:part:centrifugal_pump_100");
330        mech.kinematic_pair_count = 4;
331        mech.cad_brep_step_key = Some("cad/pump.step".into());
332        let meta = HolisticSpeciesMeta::Mechanical(mech);
333
334        let bytes = meta.encode_to_cbor().expect("cbor encode");
335        let decoded = HolisticSpeciesMeta::decode_from_cbor(&bytes).expect("cbor decode");
336        match decoded {
337            HolisticSpeciesMeta::Mechanical(m) => {
338                assert_eq!(m.assembly_id, "urn:part:centrifugal_pump_100");
339                assert_eq!(m.kinematic_pair_count, 4);
340                assert_eq!(m.basquin_fatigue_strength_coeff_mpa, 500.0);
341                assert_eq!(m.cad_brep_step_key.as_deref(), Some("cad/pump.step"));
342            }
343            _ => panic!("expected Mechanical variant"),
344        }
345    }
346}
347
348#[cfg(test)]
349#[path = "species_meta_qac_tests.rs"]
350mod qac_tests;