Skip to main content

Crate qualia_sim

Crate qualia_sim 

Source
Expand description

QualiaDB Deterministic Simulation Engine (qualia-sim).

Consolidated into etalon-sim and etalon-render (see docs/plans/etalon-sim-render-consolidation-uplift-2026-11-06.md). Preserves 100% backwards-compatible module and symbol paths while exposing the uplifted multi-domain simulation, physics, skeletal, camera, hydrological, and botanical capabilities.

Modules§

acoustics_continuum
3D Continuum Acoustic & Elastic Solvers, Helmholtz, Room Acoustics & Kramers-Kronig Dispersion.
animation
camera
character
Kinematic Character Controller Engine (character).
continuum_3d
Sector 3D Physics, Stress-Cleavage Fracture & Continuum Bridge (continuum_3d.rs).
differential_codec
ecs
Zero-Heap Fixed-Capacity SOA Archetype ECS (ecs).
environment
Environmental, Space Weather, Atmosphere, Fire Ecology & Geotechnical Mechanics
flora_archetype
ground_cover
hydro
input
Zero-Heap Bitset Input Engine & Mobile Touch Gestures (input).
kinematics
Rover & Vehicle Kinematics (kinematics.rs).
leaf_biophysics
maxwell_emf
etalon_sim::maxwell_emf — 3D Continuum Maxwell Vector Calculus, Cartesian Yee FDTD, Dispersive ADE Media, Poynting Energy Balance, and C02 Electromagnetic Oracles.
metamer_fspm
navigation
Unified 2D Grid & 2.5D Polygon Navigation Engine (navigation).
optics
physics3d
Unified Analytical SDF + B-Rep 3D Physics & ODE Response Engine (physics3d).
ripple
skeletal
Zero-Heap Skeletal Animation, ABSM, Blend Spaces, Motor IK & Dual-Quaternion Skinning (skeletal).
time
Unified Multi-Rate Time & Fixed-Tick Engine (time).
vegetation
Vegetation simulation, physical bending, leaf biophysics, FSPM metamers, and ground cover.
water_surface
Caller-buffered shoreline attributes, Gerstner spectra, buoyancy, optics, and ripples for open water.

Structs§

Aabb3D
3D Axis-Aligned Bounding Box ([min_x, min_y, min_z] .. [max_x, max_y, max_z]).
Added
Zero-heap iterator yielding (entity_id, &T) for rows whose added_tick is newer than last_run.
AeroelasticBranch
Aeroelastic branch oscillator with Vogel crown streamlining reconfiguration.
AgentState
Compact entity state in fixed-point space (millimeter coordinates).
AnimationStateMachine
Zero-heap animation state machine controller.
ArchimedesProxy
Multi-sphere proxy hull for volumetric character buoyancy.
ArticulatedRagdoll
Zero-heap articulated ragdoll controller for up to MAX_LIMBS bones.
AtmosphericElectricCircuit
Global Electric Circuit and atmospheric electrical state.
BallMotorJoint
Spherical ball-and-socket joint locking two local anchor points in world space.
BarometricState
Synoptic thermodynamic and barometric state of the air column.
BioGeoOpticalConstituents
Ecological and Geomorphic Bio-Geo-Optical constituents (CASE-2 Waters).
BoundaryLayerProfile
Atmospheric Boundary Layer (ABL) logarithmic wind profile.
BroadphaseBvh
Zero-heap dynamic broadphase BVH with fat-AABB hysteresis.
BuoyancyResult
Instantaneous buoyancy evaluation result.
BuoyancySphere
Sphere element of an Archimedes buoyancy hull.
Changed
Zero-heap iterator yielding (entity_id, &T) for rows whose changed_tick is newer than last_run.
CharacterConfig
Character controller movement configuration.
CharacterController
Zero-heap kinematic character controller.
CharacterState
Dynamic runtime state of the character.
ContactManifold3D
Persistent 4-point 3D contact manifold between body_a and body_b.
ContactPoint3D
A single contact point inside a ContactManifold3D.
ContinuumBridge3D
Two-way continuum coupling bridge coordinating Geomechanics, Hydrodynamics, and Botanical Biomechanics.
DeterministicPrng
Deterministic 64-bit pseudo-random number generator (xorshift64*).
DielectricVolumeIop
Inherent Optical Properties (IOP) of a dielectric medium or fluid volume.
DisocclusionForecaster
Predicts disocclusions k frames in advance using velocity vectors and frustum planes.
DrivenSpring
Stiffness and damping per unit mass: stiffness * (target - position) - damping * velocity.
EcotopePatch
A compact semantic ground-cover ecotope patch.
EntitySpatialBounds
A bounding box for a spatial entity in world space.
ExcavationVerdict
The physical outcome of a tool contact attempt on a soil stratum.
FirelineVerdict
Result of Byram fireline intensity evaluation.
FixedMotorJoint
Rigid weld joint preserving a fixed relative PGA [Motor] offset from body_a to body_b.
FixedTickWorld
Fixed-capacity multi-agent simulation world kernel (Zero Heap hot path).
FixedTimestepAccumulator
64 Hz Fixed Timestep Accumulator.
FixedVec2
2D vector in fixed-point millimeter space.
FloraArchetypeConfig
Continuous biophysical trait parameters defining any flora archetype.
FloraBiomechanicsEvaluator
Evaluator for stem mechanics and seasonal dieback across flora archetypes.
FlyCamera
6-DOF Free-flight camera with velocity damping for editor, debug, and free inspection.
ForestFuelStratum
Fuel stratum structural breakdown for an ecological vegetation community.
FractureMaterialProps
Physical material cleavage properties for principled .10d PROC1 stress-cleavage fracture.
FractureOutcome3D
Result of splitting a RigidBody3D along a principal tensile stress cleavage plane.
FuelMoistureState
Atmospheric and edaphic fuel dryness state.
GeomagneticStormState
Planetary geomagnetic storm state and auroral energy dissipation.
GerstnerWave
Individual Gerstner wave harmonic component.
HaleMagneticCycle
22-year Hale magnetic polarity cycle (two Schwabe cycles average).
HeliophysicalFireWeatherReport
Integrated multi-domain earth-system state report.
HydrologicalHysteresisGate
Hysteresis gate to filter high-frequency fluid noise before committing discrete transitions.
InteractiveRippleBuffer
A zero-heap 2D discrete wave heightfield solver.
KinematicExtrapolator
Evaluates analytical 6-DoF trajectory extrapolation forward in time.
LeafEconomicsProfile
Continuous Leaf Economics Spectrum (LES) profile.
LeafFlutterState
Aeroelastic leaf oscillator with Strouhal vortex-shedding flutter and petiole abscission.
LeafVascularSkeleton
Zero-heap planar leaf vascular skeleton with coupled biophysics.
Metamer
The atomic structural and hydraulic unit of a plant graph.
MetamerPlantGraph
Zero-heap whole-plant FSPM solver.
MultiRateSimClock
Multi-rate simulation clock coordinating 64 Hz continuous physics substeps with deterministic lockstep world-state ticks.
MultiTouchTracker
Fixed 10-slot multi-touch tracker without heap allocation.
NarrowphaseContact
Result of a narrowphase contact query between two 3D colliders.
NavPolygon
A single convex polygon in the navigation mesh.
NavigationGrid
Bounded deterministic 2D navigation grid.
OrbitCamera
Orbit inspection camera around a central pivot point.
ProgressiveMonteCarloGovernor
Phase 4: Manages static scene dwell, progressive Monte Carlo convergence, and power throttling.
Ray3D
A 3D ray with origin and normalized direction vector.
RayHit3D
Hit result returned by cast_ray.
RevoluteMotorJoint
1-DOF revolute hinge joint with angular limits and optional motor drive.
RigidBody3D
3D rigid body with PGA [Motor] pose and physical properties (HotZeroHeap).
RoverKinematics
Zero-heap rover vehicle simulator.
RoverState
Dynamic vehicle suspension state and kinematics wrapper for 4-wheel rover exploration.
SaliencePerceptualGovernor
Computes Quantization Parameter (QP) and ray budgets from D_9 semantic salience.
SchwabeSolarCycle
11-year Schwabe solar sunspot cycle and radiative output state.
SdfCollider
Analytical Signed Distance Field collision primitive for sector terrain landforms.
SectorPhysicsReceipt
Structured receipt verifying 3D physics, spatial queries, and continuum coupling in a sector.
SectorPhysicsWorld3D
Unified sector physics simulation world coordinating 3D XPBD rigid bodies, analytical SDF terrain, character controller, rover kinematics, ragdolls, dynamic fracture, and two-way continuum coupling.
ShapeCastHit3D
Hit result returned by cast_sphere and cast_capsule.
SimTable
Fixed-capacity SOA component table with dense storage and per-row change-detection ticks.
SimdGerstnerSpectrum
8-harmonic Gerstner wave spectrum for zero-allocation CPU water queries.
SimulationCommand
Simulation command intent submitted by an agent or user.
SoilMechanicsProfile
Canonical geotechnical soil failure and physical mechanics profile.
SolarWindState
Solar wind in-situ plasma parameters at L1 / Earth orbit.
SpringChaseCamera
2nd-order spring-damper critically damped pursuit camera.
SpringState
1D spring position and velocity state.
SpringSuspensionJoint
Compliant linear suspension strut connecting body_a (chassis) and body_b (wheel/bogie).
ThermalPhenology
Thermal time phenology tracker.
ThermalTargets
Two-channel driven thermal reservoir targets and relaxation rates ($s^{-1}$).
Tick
Monotonically advancing 32-bit change-detection tick.
ToolEffector
Kinematic tool effector parameters.
ToroidalGroundCoverClipmap
Zero-allocation toroidal clipmap buffer centered on the moving camera.
TouchContact
Touch contact point record for multi-touch finger gesture tracking.
Transform3D
3D affine transform representation (rotation stored as [x, y, z, w]).
VehicleChassisConfig
Vehicle chassis physical specifications.
VehicleState
Dynamic runtime state of a 4-wheel vehicle.
VeinEdge
A single vascular vein segment within the leaf dual-graph skeleton.
VirtualTouchStick
Virtual touch joystick for mobile phones and touchscreen devices.
WheelConfig
Wheel configuration parameters.
XpbdWorld3D
64 Hz deterministic Extended Position-Based Dynamics (XPBD) rigid-body physics world.
ZeroHeapButtonInput
Zero-heap bitset representing 256 discrete button states with single-frame transition events.
ZeroHeapNavMesh
Zero-heap navigation mesh container.
ZeroHeapSkeleton
Fixed-capacity skeletal rig (MAX_BONES = 64).

Enums§

ColliderShape3D
Unified 3D collider shape supporting analytical primitives, convex hulls, and analytical SDFs.
CommandPayload
Strongly typed command payload.
CommandReceipt
Deterministic receipt issued for every executed command.
FirelineRegime
Dynamic fireline behavior classification.
GroundCoverLod
4-tier continuous representation level.
MetamerOrgan
Botanical organ type borne by a metamer node.
MotorJoint3D
Unified 6-DOF PGA [Motor] joint enum.
PathResult
Detailed outcome of an A* pathfinding query.
RagdollMode
Operational mode of an ArticulatedRagdoll.
RaunkiaerLifeForm
Raunkiær life form based on the vertical height $z$ of surviving buds during the harsh season.
RejectionReason
Reason for rejecting a proposed command.
RigidBodyType3D
Kinematic / dynamic simulation class of a 3D rigid body.
SdfPrimitive
Analytical SDF primitive shapes evaluated in $O(1)$ local coordinates.
SimTableError
Errors returned by SimTable operations.
StemSupportRegime
Mechanical stem support regime.
SubmersionState
Locomotion and submersion mode of an entity.
ToolKind
Tool physical class distinguishing human implements, machinery, and abstract clicks.
TransitionMode
Animation state machine transition blend mode.

Constants§

BASELINE_TSI_W_M2
Baseline solar constant / Total Solar Irradiance at 1 AU in W/m².
BUTTON_MIDDLE
BUTTON_PRIMARY
BUTTON_SECONDARY
DEAD_FUEL_EXTINCTION_MOISTURE
Extinction fuel moisture fraction (fuels above this moisture content will not sustain flaming).
DEFAULT_MAX_SUBSTEPS
EUCALYPT_HEAT_YIELD_KJ_KG
Heat of combustion for Australian dry sclerophyll eucalypt fuels in kJ/kg (~18,600 kJ/kg).
FIXED_DELTA_NANOS
FIXED_DELTA_SECONDS
FIXED_HZ
FIXED_TIMESTEP_64HZ
Standard deterministic simulation timestep at 64 Hz ($1/64\text{ s} = 0.015625\text{ s}$).
GAS_CONSTANT_DRY_AIR
Gas constant for dry air in J/(kg·K).
GAS_CONSTANT_WATER_VAPOR
Gas constant for water vapor in J/(kg·K).
GRAVITY_M_S2
Gravity constant in m/s².
HALE_CYCLE_YEARS
Hale double magnetic cycle duration in Earth years (~22.10 years).
INPUT_WORDS_4
INVALID_ROW
Sentinel value indicating that an entity ID is not present in a SimTable.
KEY_A
KEY_ARROW_DOWN
KEY_ARROW_LEFT
KEY_ARROW_RIGHT
KEY_ARROW_UP
KEY_D
KEY_E
KEY_ESCAPE
KEY_Q
KEY_S
KEY_SHIFT
KEY_SPACE
KEY_TAB
KEY_W
MAX_BONES
Maximum bones supported per skeleton instance (fits in GPU uniform blocks).
MAX_BUOYANCY_SPHERES
Maximum number of buoyancy proxy spheres per character/rigid-body hull.
MAX_COMMANDS_PER_TICK
MAX_ENTITIES
Default capacity constants.
MAX_GERSTNER_HARMONICS
Maximum number of analytical wave components evaluated simultaneously.
MAX_METAMERS
MAX_NAVMESH_NODES
Maximum navigation polygons supported per local sector.
MAX_PATH_LENGTH
Maximum path length returned in a single query.
MAX_PATH_WAYPOINTS
Maximum waypoints returned in a single route.
MAX_PREDICTED_DISOCCLUSIONS
MAX_SECTOR_COLLIDERS
Maximum number of active colliders in a sector physics simulation world.
MAX_SECTOR_JOINTS
Maximum number of joint constraints in a single sector world.
MAX_SECTOR_MANIFOLDS
Maximum number of persistent contact manifolds allocated per sector.
MAX_TOUCH_POINTS
MAX_VEIN_EDGES
NAV_GRID_MAX_CELLS
NAV_GRID_MAX_DIM
Maximum dimensions for navigation grid.
NO_PARENT_METAMER
NO_PARENT_VEIN
PURE_WATER_ABSORPTION_RGB
Pure H2O molecular absorption coefficients in m⁻¹ at 20°C (Smith & Baker, 1981).
PURE_WATER_RAYLEIGH_RGB
Pure H2O molecular Rayleigh scattering coefficients in m⁻¹.
RIPPLE_GRID_DIM
RIPPLE_TOTAL_CELLS
SCHWABE_CYCLE_YEARS
Nominal solar cycle duration in Earth tropical years (~11.05 years).
SIMULATION_TICK_MS
SIMULATION_TICK_RATE_HZ
Simulation frequency (20 Hz = 50ms per tick).
STANDARD_MSLP_HPA
Standard atmospheric pressure at sea level in hPa.
TOROIDAL_GRID_DIM
TOROIDAL_TOTAL_CELLS
VON_KARMAN_KAPPA
von Kármán constant for boundary-layer turbulence.
WATER_DENSITY_KG_M3
Standard water density in kg/m³ (freshwater = 1000.0, ocean = 1025.0).
WAVELENGTH_BLUE_NM
WAVELENGTH_GREEN_NM
WAVELENGTH_RED_NM
Wavelength standards in nanometers: Red (650 nm), Green (532 nm), Blue (450 nm).

Functions§

cast_capsule
Casts a vertical 3D capsule (radius, half_height) along dir up to max_dist by sweeping 3 axial proxy spheres (bottom hemisphere, center, top hemisphere).
cast_ray
Casts a 3D ray through a BroadphaseBvh and collider slice, returning the closest RayHit3D.
cast_sphere
Casts a sphere of radius along dir up to max_dist by inflating target primitives by radius.
compute_boids_separation
Computes a continuous 2D boids / crowd separation steering vector for an agent given neighboring agent positions.
compute_narrowphase_contact
Evaluates narrowphase contact between two 3D colliders (HotZeroHeap).
couple_rigid_body_with_botanical_stem
Couples a 3D rigid-body impact against metamer_idx in a MetamerPlantGraph.
couple_rigid_body_with_hydro
Applies two-way 3D Archimedes buoyancy, wave-normal righting torque, and quadratic fluid drag between a RigidBody3D and a SimdGerstnerSpectrum wavefield.
couple_rigid_body_with_soil
Applies two-way geotechnical force coupling between a RigidBody3D (wheel, foot, boulder, or chassis) and a SoilMechanicsProfile.
critical_trench_depth_m
Critical maximum unsupported vertical trench wall depth before geotechnical collapse (Rankine slip).
evaluate_and_fracture_body
Evaluates whether an impact impulse impact_impulse_ns over contact_area_m2 fractures body, and if $\sigma = J / A \ge \text{tensile_strength}$, partitions the collider along the cleavage plane using evaluate_stress_cleavage_partition.
evaluate_dead_fine_fuel_moisture
Computes Dead Fine Fuel Moisture ($DFMC$) from ambient weather and solar exposure.
evaluate_excavation_pass
Evaluates Mckyes-Ali earthmoving cutting resistance and geotechnical failure.
evaluate_fireline_intensity
Evaluates Byram’s Fireline Intensity, distinguishing fuel load from weather-driven intensity.
evaluate_heliophysical_fire_weather
Evaluates integrated multi-domain heliophysical space weather, atmospheric thermodynamics, and fire weather coupling.
evaluate_soil_compaction
Evaluates topsoil compaction under vehicular tracks or footsteps.
evaluate_solar_cycle_phase
Computes the astronomical Schwabe and Hale solar cycle states for an absolute calendar year.
evaluate_space_weather_coupling
Evaluates real-time space weather coupling into Earth’s magnetosphere and Global Electric Circuit.
gjk_intersect
Zero-heap GJK intersection test on a fixed 4-vertex stack simplex.
overlap_aabb
Convenience wrapper returning all collider IDs overlapping query_aabb.
project_grid_path_to_waypoints
Projects a 2D integer grid path into continuous world-space waypoints (Point2D on XZ plane), centering each cell coordinate and scaling by cell_size_m.
run_sector_physics_verification_step
Executes a complete deterministic verification pass on the designated sector_id world:
spatial_hash_2d
Deterministic spatial hash generating consistent pseudo-random offsets from world position $(x, z)$.
step_character_3d
Convenience wrapper for CharacterController::step_character_3d.
step_spring
Steps a DrivenSpring over dt (0.0..=0.05 s), substepped at $\le 1/240$ s via Rk4Integrator4D.
step_thermal
Steps two thermal channels toward targets over dt (0.0..=0.05 s) via Rk4Integrator4D.
step_xpbd_world
Steps a slice of RigidBody3D bodies, contact manifolds, and MotorJoint3D constraints by one fixed timestep dt (typically $1/64 = 0.015625\text{ s}$) using substeps XPBD iterations.
unproject_screen_to_ray
Unprojects 2D screen coordinates into a 3D world ray using a $4 \times 4$ inverse view-projection matrix.

Type Aliases§

CommandReceiptStatus
Alias for RejectionReason.
EcopunkSectorPhysicsWorld
Type alias preserving 100% compatibility with downstream sector physics consumers.
EntityState
Ergonomic alias for AgentState.
Point2D
A 2D point [x, z] on the ground plane.
SimCommand
Ergonomic alias for SimulationCommand.
WorldState
Ergonomic alias for FixedTickWorld.