Ball Aerodynamics & Contact Physics

The padelkit.physics module provides a high-fidelity 9-Dimensional (9D) physics engine for simulating padel ball flight, spin-dependent aerodynamics, and multi-surface rebound dynamics inside any Court enclosure.

9D State & Aerodynamic Forces

Unlike simplified parabolic models, padelkit.physics tracks the complete translational and rotational state of the ball at every step via BallState:

  • Name
    1. Position & Velocity (6D)
    Type
    (x, y, z) & (vx, vy, vz)
    Description

    3D position in meters and linear velocity in m/s in the standard centered court frame ((0, 0, 0) at the center of the net on the floor, +Z up).

  • Name
    2. Spin Vector (3D)
    Type
    (wx, wy, wz)
    Description

    Angular velocity vector in rad/s, decomposed naturally into topspin / backspin (transverse horizontal axis) and sidespin (vertical +Z axis).

  • Name
    3. Aerodynamic Drag (Fuzz Factor)
    Type
    F_drag
    Description

    Quadratic air resistance combining base sphere drag (Cd0 = 0.507 with high-speed boundary-layer transition) and felt nap resistance (fuzz_factor = 0.04). Supports atmospheric air density scaling via EnvironmentConditions.from_atmosphere().

  • Name
    4. Magnus Lift (Spindt Model)
    Type
    F_magnus
    Description

    Non-linear spin lift coefficient Cl = 1 / (2.022 + 0.981 / S) where S = (r * |w|) / |v| is the spin ratio. Accurately reproduces topspin dive (vibora, topspin smash) and backspin float (bandeja, chiquita).

9D Ball Aerodynamic Free-Body Forces
Free-body diagram of a spinning padel ball in flight showing velocity v, angular velocity ω, quadratic felt drag F_drag, gravity F_g, and Spindt Magnus lift F_magnus.

Impulse Contact Dynamics: Sliding vs. Rolling

When the ball impacts the turf floor, tempered glass walls, metallic mesh fence, or catenary net, BallPhysicsEngine resolves the rebound using an analytical Coulomb Sliding-to-Rolling transition model:

  • Name
    ContactRegime.SLIDING
    Type
    High Slip / Low Friction
    Description

    When tangential entry velocity and spin exceed the critical Coulomb threshold (mu < mu_crit), the ball slides throughout the entire contact duration (v_t' = v_t - s * mu * (1 + e) * v_n), losing partial tangential speed while picking up spin.

  • Name
    ContactRegime.ROLLING
    Type
    Grip / Bite
    Description

    When surface friction is sufficient (mu >= mu_crit), the ball grips the surface before leaving (v_t' = 5/7 * v_t + 2/7 * r * (w x n)). Heavy backspin grips sandy turf to produce a low, slow bounce (drop shot / bandeja), whereas low-friction glass (mu = 0.20) lets spin slide off the wall.

  • Name
    ContactRegime.DAMPED
    Type
    Net & Fence Absorption
    Description

    Elastic-plastic energy absorption when impacting the tensioned net mesh (e = 0.22) or galvanized metallic fence (e = 0.45).

Impulse Contact Rebound Regimes: SLIDING vs ROLLING vs DAMPED
Comparison of ContactRegime.SLIDING on low-friction glass, ContactRegime.ROLLING grip on sandy turf, and ContactRegime.DAMPED energy absorption on net/fence.

Quick Example: Simulating a Bandeja off the Back Glass

RK4 Spin Trajectory Comparison (Topspin Smash, Flat Drive, Backspin Bandeja)
Side-elevation trajectories simulated via BallPhysicsEngine.simulate() comparing Topspin Smash (+2400 RPM), Flat Drive (0 RPM), and Backspin Bandeja (-1800 RPM).

Create a shot using intuitive parameters (position, velocity, topspin_rpm, sidespin_rpm), simulate its full 3D trajectory with RK4 integration (dt = 0.002s), inspect every BounceEvent, and convert the result directly into a MatchTimeline for interactive 3D replay.

Simulate & Replay

guide
BallPhysicsEngine
from padelkit import BallPhysicsEngine, BallState

engine = BallPhysicsEngine()

# Cross-court bandeja with 1,800 RPM backspin
initial = BallState.from_shot(
    position=(-2.5, -2.0, 2.3),
    velocity=(3.5, 16.0, -2.5),
    topspin_rpm=-1800.0,
    sidespin_rpm=400.0,
)

traj = engine.simulate(initial, duration=2.5, dt=0.002)

for b in traj.bounces:
    print(f"{b.timestamp:.2f}s | {b.surface.value} ({b.regime.value})")

# Export to DataFrame or 3D MatchTimeline
df = traj.to_dataframe()
timeline = traj.to_timeline(fps=60.0)

Output

0.45s | floor (rolling)
0.72s | back_glass (sliding)
1.18s | floor (rolling)

Core Physics Components

  • Name
    BallPhysicsEngine
    Type
    class
    Description

    Main 9D physics engine with RK4 integration, multi-surface collision resolution, single-trajectory simulate(), and vectorized NumPy simulate_batch(). See BallPhysicsEngine.

  • Name
    BallState & BallTrajectory
    Type
    dataclass
    Description

    9D instantaneous ball state (from_shot, speed_kmh, spin_rpm), full trajectory history (positions, velocities, state_at, to_timeline), and BounceEvent records. See BallState & BallTrajectory.

  • Name
    Physics Parameters
    Type
    dataclass
    Description

    Physical configuration dataclasses: BallProperties (fip_standard, worn, wet), EnvironmentConditions (from_atmosphere), and SurfaceMaterials (fip_standard, fast_indoor, slow_sandy).

Was this page helpful?