1use super::schemas::{evaluate_calibration, i64_at, EpistemicClass};
7use super::spectrum::ELECTRON_VOLT_JOULE;
8use super::*;
9use crate::container_10d::crc32c::crc32c;
10use core::f64::consts::PI;
11
12pub const DOSE_PROFILE: &str = "ionizing_radiation_v1";
13pub const DOSE_MODEL_URI: &str = "urn:qualia:emf:ionizing_radiation_v1";
14pub const BIOFIELD_PROFILE: &str = "bioelectric_dipole_v1";
15pub const BIOFIELD_MODEL_URI: &str = "urn:qualia:emf:bioelectric_dipole_v1";
16
17pub const DOSE_VALID_PHOTON_ENERGY: u32 = 1 << 0;
18pub const DOSE_VALID_LINEAR_ATTEN: u32 = 1 << 1;
19pub const DOSE_VALID_MASS_ATTEN: u32 = 1 << 2;
20pub const DOSE_VALID_FLUENCE: u32 = 1 << 3;
21pub const DOSE_VALID_ABSORBED_GY: u32 = 1 << 4;
22pub const DOSE_VALID_EQUIVALENT_SV: u32 = 1 << 5;
23pub const DOSE_VALID_LET: u32 = 1 << 6;
24pub const DOSE_VALID_UNCERTAINTY: u32 = 1 << 7;
25pub const DOSE_ALL_VALID_MASK: u32 = 0xFF;
26
27pub const BIO_FLAG_POTENTIAL: u32 = 1 << 0;
28pub const BIO_FLAG_CARRIER: u32 = 1 << 1;
29pub const BIO_FLAG_UNCERTAINTY: u32 = 1 << 2;
30
31#[derive(Clone, Copy, Debug, PartialEq, Eq)]
32pub enum TransportSpecies {
33 Photon,
34 Electron,
35 Positron,
36 Proton,
37 Alpha,
38 Neutron,
39 HeavyIon,
40}
41
42impl TransportSpecies {
43 pub fn parse(name: &str) -> Result<Self, Error> {
44 match name {
45 "photon" | "gamma" | "x-ray" | "xray" => Ok(Self::Photon),
46 "electron" | "e-" => Ok(Self::Electron),
47 "positron" | "e+" => Ok(Self::Positron),
48 "proton" | "p+" | "H1" => Ok(Self::Proton),
49 "alpha" | "He4" => Ok(Self::Alpha),
50 "neutron" | "n0" => Ok(Self::Neutron),
51 "heavy_ion" => Ok(Self::HeavyIon),
52 _ => Err(Error::UnsupportedProfile),
53 }
54 }
55
56 pub const fn is_uncharged_photon(self) -> bool {
57 matches!(self, Self::Photon)
58 }
59
60 pub const fn is_charged_particle(self) -> bool {
61 matches!(
62 self,
63 Self::Electron | Self::Positron | Self::Proton | Self::Alpha | Self::HeavyIon
64 )
65 }
66}
67
68#[derive(Clone, Copy, Debug, PartialEq)]
69pub struct DoseTransportRecord {
70 pub position_m: [f64; 3],
71 pub tick: i64,
72 pub photon_energy_j: Option<f64>,
73 pub linear_attenuation_per_m: Option<f64>,
74 pub mass_attenuation_m2_per_kg: Option<f64>,
75 pub photon_fluence_per_m2: Option<f64>,
76 pub absorbed_dose_gy: Option<f64>,
77 pub equivalent_dose_sv: Option<f64>,
78 pub linear_energy_transfer_j_per_m: Option<f64>,
79 pub uncertainty: Option<f64>,
80 pub material_entry: u32,
81 pub calibration_ref: u32,
82 pub model_ref: u32,
83 pub validity_flags: u32,
84}
85
86fn opt_lane(bytes: &[u8], off: usize, present: bool, positive_only: bool) -> Result<Option<f64>, Error> {
87 if !present {
88 zeros(&bytes[off..off + 8])?;
89 return Ok(None);
90 }
91 let val = f64_at(bytes, off);
92 if !val.is_finite() {
93 return Err(Error::NonFinite);
94 }
95 if val < 0.0 || (positive_only && val <= 0.0) {
96 return Err(Error::Value);
97 }
98 Ok(Some(val))
99}
100
101impl DoseTransportRecord {
102 pub fn parse(bytes: &[u8], valid: bool) -> Result<Option<Self>, Error> {
103 if bytes.len() != 128 {
104 return Err(Error::Shape);
105 }
106 zeros(&bytes[112..124])?;
107 if crc32c(&bytes[..124]) != u32_at(bytes, 124) {
108 return Err(Error::Reserved);
109 }
110 if !valid {
111 zeros(&bytes[..24])?;
112 zeros(&bytes[32..112])?;
113 return Ok(None);
114 }
115 finite(bytes, 0, 24)?;
116 finite(bytes, 32, 96)?;
117 let vflags = u32_at(bytes, 108);
118 if vflags & !DOSE_ALL_VALID_MASK != 0 {
119 return Err(Error::Flags);
120 }
121 let photon_energy_j = opt_lane(bytes, 32, vflags & DOSE_VALID_PHOTON_ENERGY != 0, true)?;
122 let linear_attenuation_per_m =
123 opt_lane(bytes, 40, vflags & DOSE_VALID_LINEAR_ATTEN != 0, false)?;
124 let mass_attenuation_m2_per_kg =
125 opt_lane(bytes, 48, vflags & DOSE_VALID_MASS_ATTEN != 0, false)?;
126 let photon_fluence_per_m2 = opt_lane(bytes, 56, vflags & DOSE_VALID_FLUENCE != 0, false)?;
127 let absorbed_dose_gy = opt_lane(bytes, 64, vflags & DOSE_VALID_ABSORBED_GY != 0, false)?;
128 let equivalent_dose_sv =
129 opt_lane(bytes, 72, vflags & DOSE_VALID_EQUIVALENT_SV != 0, false)?;
130 let linear_energy_transfer_j_per_m =
131 opt_lane(bytes, 80, vflags & DOSE_VALID_LET != 0, false)?;
132 let uncertainty = opt_lane(bytes, 88, vflags & DOSE_VALID_UNCERTAINTY != 0, false)?;
133
134 Ok(Some(Self {
135 position_m: triple(bytes, 0),
136 tick: i64_at(bytes, 24),
137 photon_energy_j,
138 linear_attenuation_per_m,
139 mass_attenuation_m2_per_kg,
140 photon_fluence_per_m2,
141 absorbed_dose_gy,
142 equivalent_dose_sv,
143 linear_energy_transfer_j_per_m,
144 uncertainty,
145 material_entry: u32_at(bytes, 96),
146 calibration_ref: u32_at(bytes, 100),
147 model_ref: u32_at(bytes, 104),
148 validity_flags: vflags,
149 }))
150 }
151
152 pub fn encode(&self, valid: bool, out: &mut [u8; 128]) -> Result<(), Error> {
153 *out = [0u8; 128];
154 if valid {
155 if self.validity_flags & !DOSE_ALL_VALID_MASK != 0 {
156 return Err(Error::Flags);
157 }
158 if self.position_m.iter().any(|v| !v.is_finite()) {
159 return Err(Error::NonFinite);
160 }
161 for (i, v) in self.position_m.iter().enumerate() {
162 out[i * 8..i * 8 + 8].copy_from_slice(&v.to_le_bytes());
163 }
164 out[24..32].copy_from_slice(&self.tick.to_le_bytes());
165
166 let lanes: [(Option<f64>, u32, usize, bool); 8] = [
167 (self.photon_energy_j, DOSE_VALID_PHOTON_ENERGY, 32, true),
168 (self.linear_attenuation_per_m, DOSE_VALID_LINEAR_ATTEN, 40, false),
169 (self.mass_attenuation_m2_per_kg, DOSE_VALID_MASS_ATTEN, 48, false),
170 (self.photon_fluence_per_m2, DOSE_VALID_FLUENCE, 56, false),
171 (self.absorbed_dose_gy, DOSE_VALID_ABSORBED_GY, 64, false),
172 (self.equivalent_dose_sv, DOSE_VALID_EQUIVALENT_SV, 72, false),
173 (self.linear_energy_transfer_j_per_m, DOSE_VALID_LET, 80, false),
174 (self.uncertainty, DOSE_VALID_UNCERTAINTY, 88, false),
175 ];
176 let mut computed_flags = 0u32;
177 for (opt, bit, off, pos_only) in lanes {
178 if let Some(v) = opt {
179 if !v.is_finite() {
180 return Err(Error::NonFinite);
181 }
182 if v < 0.0 || (pos_only && v <= 0.0) {
183 return Err(Error::Value);
184 }
185 if self.validity_flags & bit == 0 {
186 return Err(Error::Flags);
187 }
188 computed_flags |= bit;
189 out[off..off + 8].copy_from_slice(&v.to_le_bytes());
190 } else if self.validity_flags & bit != 0 {
191 return Err(Error::Flags);
192 }
193 }
194 out[96..100].copy_from_slice(&self.material_entry.to_le_bytes());
195 out[100..104].copy_from_slice(&self.calibration_ref.to_le_bytes());
196 out[104..108].copy_from_slice(&self.model_ref.to_le_bytes());
197 out[108..112].copy_from_slice(&computed_flags.to_le_bytes());
198 } else {
199 out[24..32].copy_from_slice(&self.tick.to_le_bytes());
200 }
201 let c = crc32c(&out[..124]);
202 out[124..128].copy_from_slice(&c.to_le_bytes());
203 Ok(())
204 }
205
206 pub fn validate_against_blocks(
208 &self,
209 cal: Block<'_>,
210 model: Block<'_>,
211 ) -> Result<(TransportSpecies, EpistemicClass), Error> {
212 if cal.schema_type() != 107 || model.schema_type() != 134 {
213 return Err(Error::Shared(semantics::Error::ReferenceSchema));
214 }
215 if self.calibration_ref != cal.id() || self.model_ref != model.id() {
216 return Err(Error::Descriptor);
217 }
218 let species = TransportSpecies::parse(text(required(model, 9)?)?)?;
219 let epistemic = EpistemicClass::parse(text(required(model, 8)?)?)?;
220 let int_ticks = required(model, 10)?.value();
222 let t_start = i64_at(int_ticks, 0);
223 let t_end = i64_at(int_ticks, 8);
224 if self.tick < t_start || self.tick > t_end {
225 return Err(Error::Time);
226 }
227 let _ = evaluate_calibration(cal, 1.0, Some(self.tick))?;
228 if self.equivalent_dose_sv.is_some() && field(model, 11).is_none() {
229 return Err(Error::Descriptor);
231 }
232 if self.uncertainty.is_some() && field(model, 5).is_none() {
233 return Err(Error::Descriptor);
234 }
235 if species.is_charged_particle()
236 && (self.linear_attenuation_per_m.is_some() || self.mass_attenuation_m2_per_kg.is_some())
237 {
238 return Err(Error::UnsupportedProfile);
240 }
241 Ok((species, epistemic))
242 }
243}
244
245pub fn encode_dose_records(
246 records: &[DoseTransportRecord],
247 valid: Option<&[bool]>,
248 out: &mut [u8],
249) -> Result<usize, Error> {
250 if let Some(v) = valid {
251 if v.len() != records.len() {
252 return Err(Error::Shape);
253 }
254 }
255 let needed = records.len().checked_mul(128).ok_or(Error::Overflow)?;
256 if out.len() < needed {
257 return Err(Error::Shape);
258 }
259 for (idx, rec) in records.iter().enumerate() {
260 let is_valid = valid.is_none_or(|v| v[idx]);
261 let dst: &mut [u8; 128] = (&mut out[idx * 128..idx * 128 + 128])
262 .try_into()
263 .map_err(|_| Error::Shape)?;
264 rec.encode(is_valid, dst)?;
265 }
266 Ok(needed)
267}
268
269#[inline]
270pub fn kev_to_joules(energy_kev: f64) -> Result<f64, Error> {
271 if !energy_kev.is_finite() {
272 return Err(Error::NonFinite);
273 }
274 if energy_kev <= 0.0 {
275 return Err(Error::Value);
276 }
277 Ok(energy_kev * 1.0e3 * ELECTRON_VOLT_JOULE)
278}
279
280#[inline]
281pub fn linear_from_mass_attenuation(
282 mass_attenuation_m2_per_kg: f64,
283 density_kg_per_m3: f64,
284) -> Result<f64, Error> {
285 if !mass_attenuation_m2_per_kg.is_finite() || !density_kg_per_m3.is_finite() {
286 return Err(Error::NonFinite);
287 }
288 if mass_attenuation_m2_per_kg < 0.0 || density_kg_per_m3 <= 0.0 {
289 return Err(Error::Value);
290 }
291 Ok(mass_attenuation_m2_per_kg * density_kg_per_m3)
292}
293
294pub fn photon_uncollided_fluence(
297 species: TransportSpecies,
298 incident_fluence_per_m2: f64,
299 linear_attenuation_per_m: f64,
300 thickness_m: f64,
301) -> Result<f64, Error> {
302 if !species.is_uncharged_photon() {
303 return Err(Error::UnsupportedProfile);
304 }
305 if !incident_fluence_per_m2.is_finite()
306 || !linear_attenuation_per_m.is_finite()
307 || !thickness_m.is_finite()
308 {
309 return Err(Error::NonFinite);
310 }
311 if incident_fluence_per_m2 < 0.0 || linear_attenuation_per_m < 0.0 || thickness_m < 0.0 {
312 return Err(Error::Value);
313 }
314 Ok(incident_fluence_per_m2 * (-linear_attenuation_per_m * thickness_m).exp())
315}
316
317#[inline]
318pub fn absorbed_dose_gy(deposited_energy_j: f64, target_mass_kg: f64) -> Result<f64, Error> {
319 if !deposited_energy_j.is_finite() || !target_mass_kg.is_finite() {
320 return Err(Error::NonFinite);
321 }
322 if deposited_energy_j < 0.0 || target_mass_kg <= 0.0 {
323 return Err(Error::Value);
324 }
325 Ok(deposited_energy_j / target_mass_kg)
326}
327
328#[inline]
329pub fn equivalent_dose_sv(absorbed_gy: f64, radiation_weighting_factor: f64) -> Result<f64, Error> {
330 if !absorbed_gy.is_finite() || !radiation_weighting_factor.is_finite() {
331 return Err(Error::NonFinite);
332 }
333 if absorbed_gy < 0.0 || radiation_weighting_factor <= 0.0 {
334 return Err(Error::Value);
335 }
336 Ok(absorbed_gy * radiation_weighting_factor)
337}
338
339#[derive(Clone, Copy, Debug, PartialEq)]
340pub struct BiofieldRecord {
341 pub position_m: [f64; 3],
342 pub current_dipole_moment_a_m: [f64; 3],
343 pub extracellular_potential_v: Option<f64>,
344 pub tick: i64,
345 pub carrier_hz: Option<f64>,
346 pub uncertainty: Option<f64>,
347 pub anatomy_metadata_ref: u32,
348 pub model_ref: u32,
349 pub calibration_ref: u32,
350 pub consent_provenance_ref: u32,
351 pub flags: u32,
352}
353
354impl BiofieldRecord {
355 pub fn parse(bytes: &[u8], valid: bool) -> Result<Option<Self>, Error> {
356 if bytes.len() != 128 {
357 return Err(Error::Shape);
358 }
359 zeros(&bytes[100..124])?;
360 if crc32c(&bytes[..124]) != u32_at(bytes, 124) {
361 return Err(Error::Reserved);
362 }
363 if !valid {
364 zeros(&bytes[..56])?;
365 zeros(&bytes[64..100])?;
366 return Ok(None);
367 }
368 finite(bytes, 0, 56)?;
369 finite(bytes, 64, 80)?;
370 let flags = u32_at(bytes, 96);
371 if flags & !(BIO_FLAG_POTENTIAL | BIO_FLAG_CARRIER | BIO_FLAG_UNCERTAINTY) != 0 {
372 return Err(Error::Flags);
373 }
374 let extracellular_potential_v = if flags & BIO_FLAG_POTENTIAL != 0 {
375 Some(f64_at(bytes, 48))
376 } else {
377 zeros(&bytes[48..56])?;
378 None
379 };
380 let carrier_hz = opt_lane(bytes, 64, flags & BIO_FLAG_CARRIER != 0, true)?;
381 let uncertainty = opt_lane(bytes, 72, flags & BIO_FLAG_UNCERTAINTY != 0, false)?;
382
383 Ok(Some(Self {
384 position_m: triple(bytes, 0),
385 current_dipole_moment_a_m: triple(bytes, 24),
386 extracellular_potential_v,
387 tick: i64_at(bytes, 56),
388 carrier_hz,
389 uncertainty,
390 anatomy_metadata_ref: u32_at(bytes, 80),
391 model_ref: u32_at(bytes, 84),
392 calibration_ref: u32_at(bytes, 88),
393 consent_provenance_ref: u32_at(bytes, 92),
394 flags,
395 }))
396 }
397
398 pub fn encode(&self, valid: bool, out: &mut [u8; 128]) -> Result<(), Error> {
399 *out = [0u8; 128];
400 if valid {
401 if self.flags & !(BIO_FLAG_POTENTIAL | BIO_FLAG_CARRIER | BIO_FLAG_UNCERTAINTY) != 0 {
402 return Err(Error::Flags);
403 }
404 if self.position_m.iter().any(|v| !v.is_finite())
405 || self.current_dipole_moment_a_m.iter().any(|v| !v.is_finite())
406 {
407 return Err(Error::NonFinite);
408 }
409 for i in 0..3 {
410 out[i * 8..i * 8 + 8].copy_from_slice(&self.position_m[i].to_le_bytes());
411 out[24 + i * 8..32 + i * 8]
412 .copy_from_slice(&self.current_dipole_moment_a_m[i].to_le_bytes());
413 }
414 if let Some(phi) = self.extracellular_potential_v {
415 if !phi.is_finite() {
416 return Err(Error::NonFinite);
417 }
418 if self.flags & BIO_FLAG_POTENTIAL == 0 {
419 return Err(Error::Flags);
420 }
421 out[48..56].copy_from_slice(&phi.to_le_bytes());
422 } else if self.flags & BIO_FLAG_POTENTIAL != 0 {
423 return Err(Error::Flags);
424 }
425 out[56..64].copy_from_slice(&self.tick.to_le_bytes());
426 if let Some(f) = self.carrier_hz {
427 if !f.is_finite() {
428 return Err(Error::NonFinite);
429 }
430 if f <= 0.0 {
431 return Err(Error::Value);
432 }
433 if self.flags & BIO_FLAG_CARRIER == 0 {
434 return Err(Error::Flags);
435 }
436 out[64..72].copy_from_slice(&f.to_le_bytes());
437 } else if self.flags & BIO_FLAG_CARRIER != 0 {
438 return Err(Error::Flags);
439 }
440 if let Some(u) = self.uncertainty {
441 if !u.is_finite() {
442 return Err(Error::NonFinite);
443 }
444 if u < 0.0 {
445 return Err(Error::Value);
446 }
447 if self.flags & BIO_FLAG_UNCERTAINTY == 0 {
448 return Err(Error::Flags);
449 }
450 out[72..80].copy_from_slice(&u.to_le_bytes());
451 } else if self.flags & BIO_FLAG_UNCERTAINTY != 0 {
452 return Err(Error::Flags);
453 }
454 out[80..84].copy_from_slice(&self.anatomy_metadata_ref.to_le_bytes());
455 out[84..88].copy_from_slice(&self.model_ref.to_le_bytes());
456 out[88..92].copy_from_slice(&self.calibration_ref.to_le_bytes());
457 out[92..96].copy_from_slice(&self.consent_provenance_ref.to_le_bytes());
458 out[96..100].copy_from_slice(&self.flags.to_le_bytes());
459 } else {
460 out[56..64].copy_from_slice(&self.tick.to_le_bytes());
461 }
462 let c = crc32c(&out[..124]);
463 out[124..128].copy_from_slice(&c.to_le_bytes());
464 Ok(())
465 }
466
467 pub fn validate_against_blocks(
468 &self,
469 anatomy: Block<'_>,
470 model: Block<'_>,
471 cal: Block<'_>,
472 consent_prov: Block<'_>,
473 require_consent_receipt: bool,
474 ) -> Result<EpistemicClass, Error> {
475 if anatomy.schema_type() != 137
476 || model.schema_type() != 134
477 || cal.schema_type() != 107
478 || consent_prov.schema_type() != 4
479 {
480 return Err(Error::Shared(semantics::Error::ReferenceSchema));
481 }
482 if self.anatomy_metadata_ref != anatomy.id()
483 || self.model_ref != model.id()
484 || self.calibration_ref != cal.id()
485 || self.consent_provenance_ref != consent_prov.id()
486 {
487 return Err(Error::Descriptor);
488 }
489 if self.uncertainty.is_some() && field(model, 5).is_none() {
490 return Err(Error::Descriptor);
491 }
492 let _ = evaluate_calibration(cal, 1.0, Some(self.tick))?;
493 if require_consent_receipt {
494 let receipt = field(consent_prov, 6).ok_or(Error::Descriptor)?;
495 if receipt.value().len() != 32 || receipt.value().iter().all(|&b| b == 0) {
496 return Err(Error::Descriptor);
497 }
498 }
499 EpistemicClass::parse(text(required(model, 8)?)?)
500 }
501}
502
503pub fn encode_biofield_records(
504 records: &[BiofieldRecord],
505 valid: Option<&[bool]>,
506 out: &mut [u8],
507) -> Result<usize, Error> {
508 if let Some(v) = valid {
509 if v.len() != records.len() {
510 return Err(Error::Shape);
511 }
512 }
513 let needed = records.len().checked_mul(128).ok_or(Error::Overflow)?;
514 if out.len() < needed {
515 return Err(Error::Shape);
516 }
517 for (idx, rec) in records.iter().enumerate() {
518 let is_valid = valid.is_none_or(|v| v[idx]);
519 let dst: &mut [u8; 128] = (&mut out[idx * 128..idx * 128 + 128])
520 .try_into()
521 .map_err(|_| Error::Shape)?;
522 rec.encode(is_valid, dst)?;
523 }
524 Ok(needed)
525}
526
527pub fn dipole_potential_infinite_homogeneous(
531 source_pos_m: [f64; 3],
532 moment_a_m: [f64; 3],
533 obs_pos_m: [f64; 3],
534 conductivity_s_per_m: f64,
535) -> Result<f64, Error> {
536 if source_pos_m.iter().any(|v| !v.is_finite())
537 || moment_a_m.iter().any(|v| !v.is_finite())
538 || obs_pos_m.iter().any(|v| !v.is_finite())
539 || !conductivity_s_per_m.is_finite()
540 {
541 return Err(Error::NonFinite);
542 }
543 if conductivity_s_per_m <= 0.0 {
544 return Err(Error::Value);
545 }
546 let dr = [
547 obs_pos_m[0] - source_pos_m[0],
548 obs_pos_m[1] - source_pos_m[1],
549 obs_pos_m[2] - source_pos_m[2],
550 ];
551 let r = ((dr[0] * dr[0] + dr[1] * dr[1]) + dr[2] * dr[2]).sqrt();
552 if r <= 1.0e-12 {
553 return Err(Error::Value);
554 }
555 let q_dot_r = moment_a_m[0] * dr[0] + moment_a_m[1] * dr[1] + moment_a_m[2] * dr[2];
556 Ok(q_dot_r / (4.0 * PI * conductivity_s_per_m * r * r * r))
557}
558
559pub fn verify_empirical_join_allowed(model_block: Block<'_>) -> Result<EpistemicClass, Error> {
562 if model_block.schema_type() != 134 || model_block.revision() != 1 {
563 return Err(Error::Shared(semantics::Error::ReferenceSchema));
564 }
565 let class = EpistemicClass::parse(text(required(model_block, 8)?)?)?;
566 if class.is_speculative() {
567 return Err(Error::UnsupportedProfile);
568 }
569 Ok(class)
570}