Skip to main content

Transportations Library

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

Transportation engineering knowledge is siloed. The methods live in PDF manuals, agency spreadsheets, and closed desktop tools, and every consumer re-implements them, so the same HCM procedure yields different numbers in different shops with no way to trace which one follows the book. This library is the source-of-truth layer of the CrossTraffic stack. Each methodology is implemented once, with the equation or exhibit it implements cited at the definition, validated against the manual's published example problems, and released under a matched version line so the downstream surfaces (the Python bindings here, the WASM middleware, the MCP server, the web calculator) integrate one canonical computation instead of maintaining diverging copies. Data management concerns that usually stay implicit are handled explicitly. Edition differences are selectable rather than silently mixed, published errata are applied and documented, and the places where the manual is ambiguous or not reproducible from its printed procedure are recorded rather than papered over.

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.

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.1.tar.gz (783.6 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.1-cp312-cp312-win_amd64.whl (1.0 MB view details)

Uploaded CPython 3.12Windows x86-64

transportations_library-0.3.1-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.1-cp312-cp312-macosx_11_0_arm64.whl (1.0 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

transportations_library-0.3.1-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.1-cp311-cp311-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

transportations_library-0.3.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: transportations_library-0.3.1.tar.gz
  • Upload date:
  • Size: 783.6 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.1.tar.gz
Algorithm Hash digest
SHA256 cfe0a4db245b8382b2b28ceff614073d9b494574b3a5279936259b2e7519d9a1
MD5 fbdb0c2233c1c6d0db500c05c8b1efcc
BLAKE2b-256 8366beed1426dff7f6d0c4b838f2eee2f3287bde3dc341a46e1c82186a24a185

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1.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.1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 ec11337dcb1823850cea19cacc48b2d1e64dace112137304cd43da0303a6e665
MD5 261b7d501efa249f2a9d398fb350236a
BLAKE2b-256 0f2db4ee64898ff185015fb1e1b01f94c7ce80a1ba95c96f8bef247498bd66e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d46233530970a7cdf090eb8f51ba7eee39b07175a5dbb1b7603b6694af93c11e
MD5 8424001bd26f24a1d3dad4d6c955e7ca
BLAKE2b-256 609d6278187f8044a0a278b5a8268e0083854fdc156f844f9aa21fecee084a56

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 070efdd6f5f35196bc887dfb5a836e7bcfe5eab345ff192e40f3aef672a9fc95
MD5 a10074b8ca8bcfffe4bcb34e4f9da419
BLAKE2b-256 c1339f46b40b49a03d4a6292d05dd905460f0466a2ee23943eb16f5918498fd3

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 dedfed042fed05541598394f6925e4ab7012036017c8fbf3f32fb0039ff888e8
MD5 eaa7da6b90b3cb82fcc98d4c0b417539
BLAKE2b-256 dc8be9612476efad147c53d0cea7c498b8ed325bb5163b1d655e0812c3c3748a

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 63e1d5fee7aa16c480f2f2c05523faf0c7a4a9855ddf73d521de746b77c703f7
MD5 b55b99b5cc0f7e04272b8c2c73ec6af8
BLAKE2b-256 3117b0ee537f286cef52913562b85915ce384f65d98ff521f35158770848683d

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 426eed6dc48100c3cf91654fb764c11fbbb8fef3a0b006dbd053c7cbd343eb6b
MD5 89deda279fcb88e0258aa2c81b42c0a3
BLAKE2b-256 09a7a726ad542f62f0c8e34d9bcbfb08054c6737242404bb1c4cd91c112faf0e

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 e26543995f6870f36c532420e4c881640ae56605b127cf6159213beb33b0a319
MD5 9b002954ac6a815ed5baf98dfa7ca203
BLAKE2b-256 be7833894dc4da37a537a07b1e0ef6260d05d29824425f5c7a76ecc743ad24d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9865e897f3c6f365821663d47b3408be213cb4ef8e73431fe8b110dbae9ed1ec
MD5 df862c96966284b6ee3e56adfb0f3206
BLAKE2b-256 8500576b8685a22aec7a321bc0258ae38d021c27f098b33453653f31a49ba5b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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.1-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for transportations_library-0.3.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 26858144d85a11236e9794e709cb70070c31590369c1cde2881ada3b280b60c1
MD5 409de48fdfd0afcb0de503ef047f52cf
BLAKE2b-256 0e64f0167e8c0f8725e7b34ea04b828da86afc252d1518abde6703f31ba1ff05

See more details on using hashes here.

Provenance

The following attestation bundles were made for transportations_library-0.3.1-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

This release

0.3.1 This release

10 files

0.3.0

10 files

0.2.0

10 files

0.1.12

2 files

0.1.11

10 files

0.1.10

12 files

0.1.8

4 files

0.1.7

4 files

0.1.6

4 files

0.1.5

4 files

0.1.4

1 file

0.1.3

3 files

0.1.2

3 files

0.1.1

2 files

0.1.0

2 files

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