Transportations Library

A comprehensive Rust-based library implementing transportation engineering methodologies (e.g. the Highway Capacity Manual (HCM)) with Python bindings.

What this covers

Highway Capacity Manual 7th Edition computational chapters 10 through 24, with the supplemental chapters (25, 27, 28, 30, 31, 32, 33, 34, 35) they draw on:

Chapter Topic Chapter Topic
10 Freeway Facilities 18 Urban Street Segments
11 Freeway Reliability 19 Signalized Intersections
12 Basic Freeway and Multilane Segments 20 Two-Way STOP-Controlled Intersections
13 Freeway Weaving Segments 21 All-Way STOP-Controlled Intersections
14 Freeway Merge and Diverge Segments 22 Roundabouts
15 Two-Lane Highways 23 Ramp Terminals and Alternative Intersections
16 Urban Street Facilities 24 Off-Street Pedestrian and Bicycle Facilities
17 Urban Street Reliability

Methodologies are validated against the manual's own published example problems; see docs/hcm/procedures/ for per-chapter walkthroughs and docs/hcm/VERIFICATION.md for the places where the manual is ambiguous, self-contradictory, or not reproducible from its printed procedure.

Selecting an HCM edition

Edition 7.1 (November 2025) replaces Chapters 13, 14, 27, and 28 with new weaving, merge, and diverge methodologies. It does not supersede the rest of the manual, so the edition is selected per segment rather than globally, and defaults to the 7th Edition:

import json, transportations_library as tl

tl.hcm_versions()          # ["7", "7.1"]
tl.hcm_latest_version()    # "7.1"

seg = tl.WeavingSegment(version="7.1", length_short=1500.0, num_lanes=4, ffs=65.0,
                        v_ff=1815.0, v_fr=692.0, v_rf=1037.0, v_rr=1297.0,
                        phf=0.91, heavy_vehicle_pct=0.05,
                        lc_rf=0, lc_fr=1, nw_rf=2, nw_fr=1)
seg.run_analysis()                       # "C"
json.loads(seg.analysis_v7_1())["speed_avg"]   # 59.32 mi/h

The two editions are different models, not successive refinements: the same segment can land a full LOS letter apart between them. tl.hcm_version_changes_chapter("7.1", 19) returns False, because Edition 7.1 left Chapter 19 alone.

Installation

Prerequisites

  • Rust: Install from rustup.rs
  • Python: 3.10 or higher
  • UV: Modern Python package manager (recommended)

Using UV (Recommended)

# Clone the repository
git clone https://github.com/crosstraffic/transportations-library
cd transportations-library

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install maturin pytest
maturin develop --release

Using pip

# Install dependencies
pip install maturin pytest

# Build and install
maturin develop --release

From PyPI

pip install transportations-library

Quick Start

For Two Lane Highways.

Python Usage

import transportations_library as tl

# Create a highway segment
segment = tl.Segment(
    passing_type=0,     # Passing Constrained
    length=1.5,         # 1.5 miles
    grade=2.0,          # 2% grade
    spl=55.0,           # 55 mph speed limit
    volume=800.0,       # 800 veh/hr
    phf=0.95,           # Peak hour factor
    phv=5.0             # 5% heavy vehicles
)

# Create highway facility
highway = tl.TwoLaneHighways([segment])

# Perform complete analysis
seg_num = 0
demand_flow, opposing_flow, capacity = highway.determine_demand_flow(seg_num)
ffs = highway.determine_free_flow_speed(seg_num)
avg_speed, _ = highway.estimate_average_speed(seg_num)
percent_followers = highway.estimate_percent_followers(seg_num)
follower_density = highway.determine_follower_density_pc_pz(seg_num)
los = highway.determine_segment_los(seg_num, avg_speed, capacity)

print(f"Level of Service: {los}")
print(f"Average Speed: {avg_speed:.1f} mph")
print(f"Follower Density: {follower_density:.1f} followers/mile")

Subsegment sections.

# Highway with horizontal curves
subsegments = [
    tl.SubSegment(length=2640.0, design_rad=800.0, sup_ele=4.0),  # Curved section
    tl.SubSegment(length=2640.0, design_rad=0.0, sup_ele=0.0)     # Tangent section
]

segment_with_curves = tl.Segment(
    passing_type=0, length=1.0, grade=3.0, spl=55.0,
    is_hc=True,  # Has horizontal curves
    subsegments=subsegments,
    volume=900.0, phf=0.92, phv=8.0
)

highway = tl.TwoLaneHighways([segment_with_curves])
# ... perform analysis

Parameter Constraints

The library exports all HCM/AASHTO parameter constraints as JSON, which can be used by validators and knowledge graphs:

import transportations_library as tl
import json

# Get all constraints
constraints = json.loads(tl.get_constraints())
print(f"Version: {constraints['version']}")

# Access specific constraint
lane_width = constraints['two_lane_highways']['lane_width']
print(f"Lane width: {lane_width['min']}-{lane_width['max']} {lane_width['unit']}")
print(f"Source: {lane_width['source']}")
# Output: Lane width: 9.0-12.0 ft
# Output: Source: HCM 7th Edition, Exhibit 15-8

# Validate inputs directly
errors = tl.validate_input(lane_width=8.0)  # Invalid - below 9 ft
print(errors)
# Output: ['lane_width = 8 ft is outside valid range [9, 12]. Source: HCM 7th Edition, Exhibit 15-8']

Available constraints include:

  • lane_width, shoulder_width (range)
  • passing_type, horizontal_class, vertical_class (enum)
  • grade, phf, phv, speed_limit (range)
  • speed_radius (table lookup - AASHTO Table 3-7)

Using from Rust, Python, and JavaScript

The same compute core is reachable from three languages, and the mapping is mechanical:

  • Rust is the source of truth. Every chapter lives under src/hcm/, and the structs there (BasicFreeways, WeavingSegment, RampSegment, ...) are the API. Add the crate as a dependency and call the run_analysis/step methods directly.
  • Python bindings are generated from the same structs via PyO3 (src/copython/), built with maturin. Field names, defaults, and units are identical to the Rust side; constructors take the struct fields as keyword arguments, and enums map to strings (version="7.1", terrain="level"). A Rust method returning Option<T> returns None in Python.
  • JavaScript goes through WebAssembly, but not from this repo: cross-traffic-middleware wraps these structs in wasm_bindgen types (WasmBasicFreeways, WasmRampSegment, ...) and is built with wasm-pack. The same Option<T> becomes undefined. The web calculator is the reference consumer.

One convention to know when porting numbers between languages: percentages are percent in the UI-facing bindings and decimals in Rust where the HCM equation wants a proportion; each binding's docstring states which it takes. Editions, LOS letters, and every published-example value are identical across the three surfaces, and the integration tests assert the Rust and Python sides against the same JSON fixtures in tests/ExampleCases/.

Testing

Run Tests

# Rust tests
cargo test

# Python tests
pytest tests/

# With coverage
pytest tests/ --cov=transportations_library

# Integration tests for chapter 15
cargo test --test chapter15_integration

Note: If you want to have changes in the Rust code to be reflected in Python, you need to run cargo clean and maturin develop again after making changes.

Example Test Cases

The library includes comprehensive test cases based on HCM examples:

  • Case 1: Basic passing constrained segment
  • Case 2: Segment with horizontal curves
  • Case 3: Multi-segment facility with different passing types
  • Case 4: Steep grade conditions with heavy vehicles

Development

Project Structure

transportations-library/
├── src/
│   ├── hcm/
│   │   ├── chapter15/           # Two-lane highways implementation
│   │   └── common.rs            # Shared HCM utilities
│   ├── copython/                # Python bindings
│   ├── utils.rs                 # Mathematical utilities
│   └── lib.rs                   # Library root
├── tests/                       # Integration tests
├── examples/                    # Usage examples
└── Cargo.toml                   # Rust configuration

Building from Source

# Development build
cargo build

# Release build
cargo build --release

# Build Python wheel
maturin build --release

# Development install with changes
cargo clean && maturin develop --release

Pipeline

The project uses GitHub Actions for CI/CD, including:

  • Running tests on push and pull requests
  • Building and publishing to Test PyPI on alpha releases
  • Building and publishing to Cargo and PyPI on new releases

To install a pre-release from Test PyPI, use (replace the version as needed):

pip install --no-cache-dir --verbose -i https://test.pypi.org/simple/ transportations-library==<version>

Versioning follows Semantic Versioning.

Also, you can find the latest alpha releases on Test PyPI.

Citation

If you use transportations-library or CrossTraffic in your research, please cite it as follows:

@software{tamaru2025tralib,
  title = {Transportations Library: Transportation knowledge management platform},
  author = {Tamaru, Rei},
  year = {2025},
  url = {https://github.com/crosstraffic/transportations-library},
  doi = {10.5281/zenodo.17295792},
}

You can also use the DOI to cite a specific version: DOI

Alternatively, you can find the citation information in the CITATION.cff file in this repository, which follows the Citation File Format standard.

Note: This library implements established transportation engineering methodologies for educational and professional use. Users should verify results and apply appropriate engineering judgment for real-world applications.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.7)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for raynbowy23 from gravatar.com raynbowy23

Credits

Author: raynbowy23

Requires

Python <3.14, >=3.10

Provides Extra

pdf test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

transportations_library-0.3.0.tar.gz (780.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

transportations_library-0.3.0-cp312-cp312-win_amd64.whl (1.0 MB view details)

Uploaded CPython 3.12Windows x86-64

transportations_library-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

transportations_library-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (1.0 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

transportations_library-0.3.0-cp311-cp311-win_amd64.whl (1.0 MB view details)

Uploaded CPython 3.11Windows x86-64

transportations_library-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

transportations_library-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

transportations_library-0.3.0-cp310-cp310-win_amd64.whl (1.0 MB view details)

Uploaded CPython 3.10Windows x86-64

transportations_library-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

transportations_library-0.3.0-cp310-cp310-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file transportations_library-0.3.0.tar.gz.

File metadata

  • Download URL: transportations_library-0.3.0.tar.gz
  • Upload date:
  • Size: 780.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for transportations_library-0.3.0.tar.gz
Algorithm Hash digest
SHA256 a5b55e2b983954f65a2ce48e408722a140bb556a02b1d016d0eac04813b7504c
MD5 93b84e7f2f95a0033df9755a22061a84
BLAKE2b-256 044fcdd05bd9b132e25a3fcd2c52eee8f369495112604ef838625b341a484825

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0.tar.gz:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 491063b9734b85ae9b3e76bee04e12928cf1589ca1450057200e65a890df200c
MD5 3c64247969c0221f0f979f7e98de08dd
BLAKE2b-256 7ae94d67ffb8278d836c781c03a814562980f4d3307f074f4540241774abefdd

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp312-cp312-win_amd64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ecdadb420d1039ce1ebd4af2fa62736d76383d93f4e26266c0aa732f5236e345
MD5 d2fbd46c4a0134784c8aea208b3c581e
BLAKE2b-256 3a79fde9b5c166b6dec10f98cf87881ec2768ac40b70665cf45cfdb828254f26

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4a79a68fb8fc84266ccdf3e00ddea5f2afc41926cd70c984ebcd270c58933d83
MD5 b7c31268b7e9d96207c39c51a8059451
BLAKE2b-256 e91e6fec727847acb68211ce8c6537a022f488253ad6e1326d92ee10afbae02b

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 11c999553621ebea820f9649b672b25e4afdf00ad02e79ac6e8017d041aabcd3
MD5 f0fbe08566a494aad6b0e701d3199c2b
BLAKE2b-256 8f451a688b120bbe225352e1363c2290eb86c9a2d2578574fce1d5295f0a8964

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp311-cp311-win_amd64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3849eba42461a28138d10044148dd66d4d55d00be5191170896815102b3ce584
MD5 6523f4e22e37cdbb7ced2043b4cfb96c
BLAKE2b-256 89f97b62c6e1ba7c77b574e1582dcabc06dda6ec5c0ea55d6a7c40bb2858b408

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1298e7ad6d5008b9b5808f450aa54f004cb813beab6d4fb24f707c1eb2c78810
MD5 80d3c7e432a4fc38b5a22611d6def39a
BLAKE2b-256 87c49f1c68b28525812bf89c42b3ba2832e644857c40452f6675963a4f4da670

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 b67cdd6f472b20ded4d591bda7d43684418957e31e0e238bb38deabb985e2f77
MD5 3d2a1526a233e8a191ed12d17ed24004
BLAKE2b-256 fe9f6aef676f093e06ae6b033a04f70b5c10fd94c014422dcec63837e0648947

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp310-cp310-win_amd64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f351692d1caf37e8eb17f4f5c77986f5304ecd5d60608307944ca065573cd727
MD5 b2288a926e3e10f0a82dd0fb75b90265
BLAKE2b-256 aa329b28153e1766e31ebcde59b7bfbb26ae6446eaabff8e0ddb4d0e5a3fecd8

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file transportations_library-0.3.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 80100a375e68642f1158fabc080b9cb3f27e27faa773c7bee3929c0a9612a243
MD5 0f0f8e754bd71e7bd2bdf3e6b2e30d31
BLAKE2b-256 f3ed118e4c7b0346dc2fad960cf3375561558e68245835fb71cd29cd988214de

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yaml on crosstraffic/transportations-library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.7

10 files

0.3.6

10 files

0.3.5

10 files

0.3.4

10 files

0.3.3

10 files

0.3.2

10 files

0.3.1

10 files

This release

0.3.0 This release

10 files

0.2.0

10 files

0.1.12

2 files

0.1.11

10 files

0.1.10

12 files

Yanked

0.1.8

4 files

0.1.7

4 files

Yanked

0.1.6

4 files

Yanked

0.1.5

4 files

Yanked

0.1.4

1 file

Yanked

0.1.3

3 files

Yanked

0.1.2

3 files

Yanked

0.1.1

2 files

Yanked

0.1.0

2 files

Yanked reason: Early test version

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page