Skip to main content

qualia_core_db/audio/qac/numerical/
fdtd_fluid.rs

1//! QAC Mode `0x0000` (`pressure_velocity_continuum`) Wire Adapter & 3D Staggered Fluid FDTD Facade.
2//!
3//! Re-exports the canonical 3D staggered-grid fluid FDTD/CPML solver and Mode `0x0000` 64-byte
4//! wire record types from [`etalon_sim::acoustics_continuum::fdtd_fluid`] and the WGSL compute
5//! kernels from [`etalon_wgsl_forge::numerical::physics::acoustic_fdtd`], adding QAC batch wire
6//! codecs and `f64` $\leftrightarrow$ `f32` GPU state buffer adapters.
7
8pub use etalon_sim::acoustics_continuum::fdtd_fluid::{
9    collocate_fluid_cell, evaluate_direct_energy_and_intensity, step_fluid_fdtd_in_place,
10    FluidBoundaryCondition, FluidFdtdConfig, FluidFdtdState, FluidMedium, NumericalError,
11    PressureVelocityRecord, StaggeredFluidOffsets, MODE_PRESSURE_VELOCITY_CONTINUUM,
12    PRESSURE_VELOCITY_RECORD_STRIDE, PV_DEFINED_VALIDITY_MASK, PV_VALID_ENERGY_DENSITY,
13    PV_VALID_INTENSITY, PV_VALID_POSITION, PV_VALID_PRESSURE, PV_VALID_VELOCITY,
14};
15#[cfg(feature = "gpu-runtime")]
16pub use etalon_wgsl_forge::numerical::physics::acoustic_fdtd::{
17    acoustic_fluid_fdtd_step_cpu, acoustic_fluid_fdtd_step_gpu,
18    acoustic_fluid_fdtd_step_with_context, AcousticFluidFdtdGpuParams, AcousticFluidGpuBoundary,
19    ACOUSTIC_FLUID_CELL_STRIDE, ACOUSTIC_FLUID_FDTD_ENTRY, ACOUSTIC_FLUID_FDTD_WGSL,
20};
21
22/// Encode a slice of Mode `0x0000` [`PressureVelocityRecord`] values into contiguous 64-byte wire records.
23pub fn encode_pressure_velocity_records(
24    records: &[PressureVelocityRecord],
25) -> Result<Vec<u8>, NumericalError> {
26    let mut out = Vec::with_capacity(records.len() * PRESSURE_VELOCITY_RECORD_STRIDE);
27    for rec in records {
28        let bytes = rec.to_wire_bytes()?;
29        out.extend_from_slice(&bytes);
30    }
31    Ok(out)
32}
33
34/// Decode a contiguous byte slice of 64-byte Mode `0x0000` wire records into [`PressureVelocityRecord`] values.
35pub fn decode_pressure_velocity_records(
36    bytes: &[u8],
37) -> Result<Vec<PressureVelocityRecord>, NumericalError> {
38    if bytes.len() % PRESSURE_VELOCITY_RECORD_STRIDE != 0 {
39        return Err(NumericalError::WireEncoding(
40            "PressureVelocityRecord stream byte length must be a multiple of 64",
41        ));
42    }
43    let count = bytes.len() / PRESSURE_VELOCITY_RECORD_STRIDE;
44    let mut out = Vec::with_capacity(count);
45    for i in 0..count {
46        let off = i * PRESSURE_VELOCITY_RECORD_STRIDE;
47        out.push(PressureVelocityRecord::from_wire_bytes(
48            &bytes[off..off + PRESSURE_VELOCITY_RECORD_STRIDE],
49        )?);
50    }
51    Ok(out)
52}
53
54/// Convert a [`FluidFdtdConfig`] into [`AcousticFluidFdtdGpuParams`] for WGSL compute execution.
55#[cfg(feature = "gpu-runtime")]
56pub fn fluid_config_to_gpu_params(
57    cfg: &FluidFdtdConfig,
58) -> Result<AcousticFluidFdtdGpuParams, NumericalError> {
59    cfg.validate()?;
60    let boundary = match cfg.boundary {
61        FluidBoundaryCondition::Periodic => AcousticFluidGpuBoundary::Periodic,
62        FluidBoundaryCondition::Rigid
63        | FluidBoundaryCondition::EngquistMajdaFirstOrder
64        | FluidBoundaryCondition::Cpml { .. } => AcousticFluidGpuBoundary::Rigid,
65        FluidBoundaryCondition::PressureRelease => AcousticFluidGpuBoundary::PressureRelease,
66    };
67    Ok(AcousticFluidFdtdGpuParams {
68        dims: [cfg.dims[0] as u32, cfg.dims[1] as u32, cfg.dims[2] as u32],
69        spacing_m: [
70            cfg.spacing_m[0] as f32,
71            cfg.spacing_m[1] as f32,
72            cfg.spacing_m[2] as f32,
73        ],
74        dt_s: cfg.dt_s as f32,
75        density_kg_m3: cfg.medium.density_kg_m3 as f32,
76        bulk_modulus_pa: cfg.medium.bulk_modulus_pa as f32,
77        damping_per_s: cfg.medium.damping_per_s as f32,
78        boundary,
79    })
80}
81
82/// Pack a [`FluidFdtdState`] into the flat `f32` storage buffer layout (`[p, vx, vy, vz]` per cell)
83/// consumed by [`ACOUSTIC_FLUID_FDTD_WGSL`].
84#[cfg(feature = "gpu-runtime")]
85pub fn pack_fluid_fdtd_state_f32(state: &FluidFdtdState) -> Vec<f32> {
86    let n = state.p.len();
87    let mut out = Vec::with_capacity(n * ACOUSTIC_FLUID_CELL_STRIDE);
88    for i in 0..n {
89        out.push(state.p[i] as f32);
90        out.push(state.vx[i] as f32);
91        out.push(state.vy[i] as f32);
92        out.push(state.vz[i] as f32);
93    }
94    out
95}
96
97/// Unpack a flat `f32` storage buffer (`[p, vx, vy, vz]` per cell) back into a [`FluidFdtdState`].
98#[cfg(feature = "gpu-runtime")]
99pub fn unpack_fluid_fdtd_state_f32(
100    flat: &[f32],
101    state: &mut FluidFdtdState,
102) -> Result<(), NumericalError> {
103    let n = state.p.len();
104    if flat.len() != n * ACOUSTIC_FLUID_CELL_STRIDE {
105        return Err(NumericalError::BufferLengthMismatch {
106            buffer: "unpack_fluid_fdtd_state_f32",
107            expected: n * ACOUSTIC_FLUID_CELL_STRIDE,
108            actual: flat.len(),
109        });
110    }
111    state.prev_vx.copy_from_slice(&state.vx);
112    state.prev_vy.copy_from_slice(&state.vy);
113    state.prev_vz.copy_from_slice(&state.vz);
114    for i in 0..n {
115        let base = i * ACOUSTIC_FLUID_CELL_STRIDE;
116        state.p[i] = flat[base] as f64;
117        state.vx[i] = flat[base + 1] as f64;
118        state.vy[i] = flat[base + 2] as f64;
119        state.vz[i] = flat[base + 3] as f64;
120    }
121    state.step_index += 1;
122    Ok(())
123}