biwipy

biwipy is a Python library for cycling performance simulation and route analysis with wind-aware physics.

It combines GPX processing, GRIB weather interpolation, and cyclist physics to replay rides or simulate future scenarios.

The devlopement of biwipy was largely assisted by AI based on an previous conventionally designed wind model.

Features

• Physics-based speed and power simulation (CdA, Cr, slope, mass, wind)
• Route preprocessing and segment analysis from GPX files
• WindScore and scenario comparison utilities
• GRIB weather integration (GFS/IFS workflows)
• Interactive map visualization for route and wind exploration

Project layout

biwipy/
├── biwipy/
│   ├── core/
│   ├── analysis/
│   ├── weather/
│   └── visualization/
├── docs/
├── pyproject.toml
└── README.md

Installation

Using Conda

The easiest way to install biwipy and dependencies is via Conda:

conda install-c conda-forge biwipy

From PyPI

pip install biwipy

pygrib is a required dependency of biwipy.

On Windows, you must install pygrib via conda-forge before using pip. This is because pygrib requires the ECCODES C library which conda provides automatically. Therefore, it is preferable to use the conda installation directly for biwipy.

If you encounter boot.def errors, set this environment variable:

conda env config vars set ECCODES_DEFINITION_PATH=$env:CONDA_PREFIX\Library\share\eccodes\definitions
conda deactivate
conda activate biwipy-env

From source

pip install .

Quick start

from datetime import timedelta, datetime, timezone
from zoneinfo import ZoneInfo
import os

from biwipy.core import Simulator
from biwipy.core.cyclist_params import CyclistBehavior
from biwipy.weather import WeatherProvider
from biwipy.weather.grib_finder import build_grib_list
from biwipy.analysis import RouteAnalyzer

# Load and process GPX file
analyzer = RouteAnalyzer()
gpx_result = analyzer.process_gpx("my_ride.gpx")

# Set ride start time and max duration example : (now + 24h)  4h  
start_ride = datetime.now(timezone.utc) + timedelta(hours=24)
duration_hours = 4

# Load weather data (GRIB files from current directory or will auto-download)
gribs_list = build_grib_list(".", start_ride, 1, duration_hours)
weather = WeatherProvider(gribs_list)

# Create cyclist profile and simulator
behavior = CyclistBehavior(uphill='realistic', downhill='realistic', corner='realistic')
sim = Simulator(weather.grib, behavior=behavior, CdA=0.50, Cr=0.005, m=85.0)

# Simulate the ride (v0 in m/s: 30 km/h = 30/3.6 m/s)
result = sim.simulate_future(gpx_result.segments, start_ride, v0=30/3.6)

# Display results
print(f"Average speed: {result.speed.avg:.2f} km/h")
print(f"Average power: {result.power.avg:.2f} W")
print(f"Windscore: {result.wind_score.grade}")

Documentation

Online documentation: https://jacme31.github.io/biwipy/

Build docs from repository root:

cd docs
make html

On Windows (PowerShell):

./build_docs.ps1

With options:

./build_docs.ps1 -Clean              # Clean and rebuild
./build_docs.ps1 -Open               # Build and open in browser
./build_docs.ps1 -Clean -Open        # Clean, rebuild, and open

Main docs entry point is generated at docs/build/html/index.html.

Development

Install development extras:

pip install -e ".[dev]"

To also build the documentation locally:

pip install -e ".[dev,docs]"

Build package artifacts:

python -m build
python -m twine check dist/*

License

This project is released under the MIT License. See LICENSE.