Standardise float precision to avoid f32↔f64 conversions in physics pipeline

[coderabbitai]

Problem

There are frequent f32↔f64 conversions between the physics helper functions and velocity components, leading to repetitive casts and potential subtle precision mismatches.

Context

The physics implementation introduced in PR #174 uses f64 in the physics helper functions but f32 in the ECS velocity components, requiring conversions at multiple boundaries.

Proposed Solution

Consider standardising on one float precision throughout the physics pipeline to:

• Eliminate repetitive casting operations
• Reduce risk of precision loss or subtle numerical differences
• Improve code clarity and maintainability

References

• PR: Add force-driven acceleration to DBSP circuit #174
• Discussion: Add force-driven acceleration to DBSP circuit #174 (comment)

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.

Once a decision has been made, apply the appropriate label.

If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

Please also provide an impact of the required changes.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue #175 details
gh issue view 175 --json title,body,labels,state,comments --jq '{title: .title, body: .body, state: .state, labels: .labels[].name, comments: .comments[].body}'

Length of output: 0

---

🏁 Script executed:

#!/bin/bash
# Fetch issue #175 details with simpler command
gh issue view 175

# Also try to get it in JSON format separately
echo "---JSON FORMAT---"
gh issue view 175 --json title,body,labels,state,comments

Length of output: 2888

---

🏁 Script executed:

#!/bin/bash
# Find physics-related files
echo "=== Finding physics-related files ==="
fd -e rs physics

# Search for velocity component definitions
echo -e "\n=== Searching for velocity components ==="
rg -n -C3 -t rust "struct.*Velocity|Velocity\s*\{|velocity.*f32|velocity.*f64"

# Search for f32/f64 conversions in physics code
echo -e "\n=== Searching for float conversions ==="
rg -n -C2 -t rust "as f32|as f64" | head -50

# Search for physics helper functions
echo -e "\n=== Searching for physics helper functions ==="
rg -n -C3 -t rust "fn.*physics|fn.*calculate.*velocity|fn.*apply.*velocity"

Length of output: 13271

---

🏁 Script executed:

#!/bin/bash
# Read the physics implementation file
echo "=== src/physics.rs ==="
cat src/physics.rs

# Read the DBSP sync output where conversions likely happen
echo -e "\n=== src/dbsp_sync/output.rs (conversion section) ==="
cat src/dbsp_sync/output.rs | head -80

# Read the numeric helper file
echo -e "\n=== src/numeric.rs ==="
cat src/numeric.rs

# Check for documentation about float precision
echo -e "\n=== Searching for documentation about float precision ==="
rg -n -C2 "f32|f64|precision|float" README.md docs/ 2>/dev/null || echo "No docs found"

Length of output: 19825

---

🏁 Script executed:

#!/bin/bash
# Look at the velocity sync code in output.rs
echo "=== Velocity sync code in output.rs ==="
rg -n -A20 "apply_velocities|velocity" src/dbsp_sync/output.rs

# Count how many conversion sites exist
echo -e "\n=== Counting f32/f64 conversion sites ==="
echo "f32_from_f64 calls:"
rg -c "f32_from_f64" src/
echo -e "\nexpect_f32 calls:"
rg -c "expect_f32" src/
echo -e "\n'as f32' casts:"
rg -c " as f32" src/
echo -e "\n'as f64' casts:"
rg -c " as f64" src/

# Check the input sync for velocity
echo -e "\n=== Velocity input sync ==="
rg -n -B5 -A10 "sync_velocities|velocity_in" src/dbsp_sync/input/

# Look at kinematics to see conversion patterns
echo -e "\n=== Kinematics velocity usage ==="
head -100 src/dbsp_circuit/streams/kinematics/mod.rs

Length of output: 10612

---

🏁 Script executed:

#!/bin/bash
# Apply the medium criticality label to the issue
gh issue edit 175 --add-label "medium"

# Verify the label was applied
echo "=== Verifying label application ==="
gh issue view 175 --json labels --jq '.labels[].name'

Length of output: 85

---

@leynos, I've analyzed the codebase and can confirm that issue #175 is still relevant. The f32↔f64 conversions are actively present in the physics pipeline.

Current State

The mixed precision architecture is still in place:

• VelocityComp (ECS component): Uses f32 fields (vx, vy, vz)
• Velocity (DBSP record): Uses OrderedFloat<f64>
• Physics functions: All use f64 for calculations (applied_acceleration, apply_ground_friction, etc.)

Conversions occur at two boundaries:

1. Input sync (Line 146-150, src/dbsp_sync/input/sync.rs): f32 → f64 when feeding ECS components into DBSP
2. Output sync (Line 85-109, src/dbsp_sync/output.rs): f64 → f32 when applying DBSP results back to ECS, with bounds checking via f32_from_f64()

Criticality Assessment: MEDIUM

Risk of user impact: LOW-MEDIUM

• Conversions are bounds-checked with warning logs for out-of-range values
• f32 provides sufficient precision for typical game coordinates and velocities
• Physics calculations correctly use f64 for numerical stability
• Unlikely to cause actual runtime bugs

Blast radius: MEDIUM

• Would require changes across multiple files:
  • src/components.rs (VelocityComp definition)
  • src/dbsp_sync/input/sync.rs and output.rs (conversion boundaries)
  • All test utilities and physics BDD tests
  • Potentially rendering systems that read velocity

Technical debt impact:

• Repetitive casting operations reduce code clarity
• Adds cognitive overhead for developers
• Small risk of precision loss in edge cases
• Maintenance burden from managing two precision levels

Documentation Status

There is no documentation explaining this design decision. The architecture documentation in docs/ mentions float types but doesn't address why mixed precision was chosen.

Impact of Required Changes

Code changes needed:

• Standardise VelocityComp to use f64 fields
• Remove f32_from_f64() conversion helpers
• Update sync macros to eliminate conversions
• Adjust test fixtures and assertions (e.g., tests/physics_bdd/support.rs)

Benefits:

• Eliminates repetitive casting operations
• Reduces risk of precision loss
• Improves code clarity and maintainability
• Consistent precision throughout physics pipeline

Trade-offs:

• Minor performance overhead (f64 arithmetic is slightly slower on some architectures)
• Small memory increase for velocity components
• Requires coordinated changes across multiple subsystems

I've applied the medium label to the issue. This is a code-level issue, not documentation-only, though documentation explaining the standardisation decision would be beneficial once implemented.