Physics Parameters

BallProperties, EnvironmentConditions, and SurfaceMaterials configure the physical constants of the ball, atmosphere, and court surfaces in BallPhysicsEngine. All three are immutable dataclasses with standardized factory presets.

SurfaceMaterials Rebound Regimes: SLIDING, ROLLING, DAMPED
Effect of SurfaceMaterials friction (μ) and restitution (COR) across glass, sandy turf, and net/fence.

BallProperties

Defines the physical mass, radius, aerodynamic drag, and felt condition of a padel ball.

  • Name
    mass
    Type
    float
    Description

    Ball mass in kilograms (57.7 g FIP midpoint between 56.0 g and 59.4 g).

  • Name
    radius
    Type
    float
    Description

    Outer radius in meters (3.25 cm / 6.50 cm diameter).

  • Name
    base_drag_coeff
    Type
    float
    Description

    Base aerodynamic drag coefficient (Cd0) prior to felt nap contribution.

  • Name
    fuzz_factor
    Type
    float
    Description

    Additional drag coefficient from raised felt nap (0.04 new, 0.075 fluffed/worn).

  • Name
    cor_scale
    Type
    float
    Description

    Internal pressure multiplier scaling normal restitution (< 1.0 for depressurized/worn balls).

Ball Presets

classmethod
BallProperties
from padelkit import BallProperties

# New pressurized FIP tournament ball
ball_new = BallProperties.fip_standard()

# Fluffed felt & slightly depressurized after 2 sets
ball_worn = BallProperties.worn()

# Heavy humid/wet outdoor ball (61.5g)
ball_wet = BallProperties.wet()

EnvironmentConditions

Defines gravity, air density, temperature, altitude, and ambient wind velocity.

  • Name
    gravity
    Type
    float
    Description

    Gravitational acceleration in m/s^2.

  • Name
    air_density
    Type
    float
    Description

    Air density rho in kg/m^3 (1.204 kg/m^3 at sea level, 20°C).

  • Name
    temperature_c
    Type
    float
    Description

    Ambient temperature in degrees Celsius.

  • Name
    altitude_m
    Type
    float
    Description

    Elevation above sea level in meters.

  • Name
    relative_humidity
    Type
    float
    Description

    Relative humidity in [0.0, 1.0].

  • Name
    wind_velocity
    Type
    tuple[float, float, float]
    Description

    Ambient 3D wind vector (wx, wy, wz) in m/s.

Atmospheric Density

classmethod
EnvironmentConditions
from padelkit import EnvironmentConditions

# Sea-level standard conditions (rho = 1.204 kg/m^3)
env_sea = EnvironmentConditions.standard()

# High-altitude warm conditions (e.g. Madrid summer, 650m, 32°C)
# Automatically computes barometric + Tetens humid air density
env_madrid = EnvironmentConditions.from_atmosphere(
    temperature_c=32.0,
    altitude_m=650.0,
    relative_humidity=0.30,
)
print(f"Madrid air density: {env_madrid.air_density:.3f} kg/m^3")

Output

Madrid air density: 1.064 kg/m^3

SurfaceMaterials

Defines the normal Coefficient of Restitution (cor_*) and tangential Coulomb friction (friction_*) for each court surface type.

  • Name
    cor_floor / friction_floor
    Type
    float
    Description

    Textured synthetic turf floor restitution and friction.

  • Name
    cor_glass / friction_glass
    Type
    float
    Description

    Tempered glass walls (10-12 mm): high restitution and low friction (SLIDING regime).

  • Name
    cor_wall / friction_wall
    Type
    float
    Description

    Concrete or masonry wall segments (VenueVariant.TRADITIONAL).

  • Name
    cor_fence / friction_fence
    Type
    float
    Description

    Electro-welded metallic mesh fence segments.

  • Name
    cor_net / friction_net
    Type
    float
    Description

    Tensioned net mesh energy absorption.

Surface Presets

classmethod
SurfaceMaterials
from padelkit import SurfaceMaterials

# Standard FIP textured turf + tempered glass
surf_std = SurfaceMaterials.fip_standard()

# Fast indoor tournament turf (higher bounce, lower friction)
surf_fast = SurfaceMaterials.fast_indoor()

# Slow sandy outdoor turf (lower bounce, higher grip)
surf_slow = SurfaceMaterials.slow_sandy()
methodsto_dict / from_dict

Dictionary Serialization

All three parameter dataclasses (BallProperties, EnvironmentConditions, and SurfaceMaterials) implement .to_dict() and .from_dict(data) for lossless storage inside the Universal Match Format (.parquet) metadata header.

  • Name
    to_dict()
    Type
    dict[str, Any]
    Description

    Serializes the physical configuration dataclass to a JSON-compatible dictionary.

  • Name
    from_dict(data)
    Type
    BallProperties | EnvironmentConditions | SurfaceMaterials
    Description

    Classmethod that reconstructs the dataclass from a dictionary.

Serialize Physics Parameters

method
to_dict / from_dict
from padelkit import BallProperties, EnvironmentConditions, SurfaceMaterials

env = EnvironmentConditions.from_atmosphere(
    temperature_c=26.0,
    altitude_m=650.0,
    relative_humidity=0.40,
)
assert EnvironmentConditions.from_dict(env.to_dict()) == env
assert BallProperties.from_dict(BallProperties.fip_standard().to_dict()) == BallProperties.fip_standard()
assert SurfaceMaterials.from_dict(SurfaceMaterials.fip_standard().to_dict()) == SurfaceMaterials.fip_standard()

Was this page helpful?