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)
# Exhibit 15-6 picks its threshold set by POSTED SPEED LIMIT, not average speed
los = highway.determine_segment_los(seg_num, highway.segments[seg_num].spl, 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.6.tar.gz (869.4 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.6-cp312-cp312-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.12Windows x86-64

transportations_library-0.3.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

transportations_library-0.3.6-cp312-cp312-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

transportations_library-0.3.6-cp311-cp311-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.11Windows x86-64

transportations_library-0.3.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

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

Uploaded CPython 3.11macOS 11.0+ ARM64

transportations_library-0.3.6-cp310-cp310-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.10Windows x86-64

transportations_library-0.3.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

transportations_library-0.3.6-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.6.tar.gz.

File metadata

  • Download URL: transportations_library-0.3.6.tar.gz
  • Upload date:
  • Size: 869.4 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.6.tar.gz
Algorithm Hash digest
SHA256 2dc58ae4d3b0a310c79d36870133416597b829633ad7cf48c588226a9f022844
MD5 a1922e135dd0d8229fa593c36e4f32ff
BLAKE2b-256 a38de987a0e3790a215892ead1c836c8a52038af7579639bac916bbaf4e9ad97

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 486487a8cbc221307b4298c5a6420e7c02152cb054f4e5c3c9f9649c7dd9f532
MD5 ce958167848d3507b91ee9f5470a2f73
BLAKE2b-256 4087d42e0858f2e0377cdd48c0ff5b19e7d42c4bd63198ae83504bd1c1d53667

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a7d94e6275dfd50b7b8b24ba474392dc2c7f17e3cf42fcafe65dfe357e03a506
MD5 b7e2b72918e4fa459f97dda6d57ed973
BLAKE2b-256 97a63c5a66891243f21ed630f4a18108d8b7e2ebf74b4735ea2c922a01f40099

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e0a6b9d7d7fed61ba93f68694f0db247b474810b2035ec9264fa0b8c4a389c03
MD5 fac0e5f63e51ac5941994a22bbbfafdd
BLAKE2b-256 346dcb3e0226ddd3a820b100f8e8ae86cd62dee8677e2f3a34e47b09d73cf9dd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 5ae9da4d18dc0648aed6516483e08b038781e1595a7ace13618db35893d7a825
MD5 9bfdbfc403b7c92b0443fd7789b352f8
BLAKE2b-256 1583dde0b642eb2bdeb90109afa4df71dbfeda2c85a4bf0069a65cd36cf4f4d8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c81cff56db0607d2a702e190bad514cdb9faedb195a162de758597b6b1c8bad9
MD5 96a8f8f338c293a2dd51f384a2d7c8dc
BLAKE2b-256 e89f6e489232f00792f1cd412c8035361d99283c0a4cc83f236decd51273765f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0111a3ae8c8490c8dc4c20bcaf43c34aea1b08b1a186174c53b6d38fcb7a73bb
MD5 29827ef8832e362fcaea531b0971a43a
BLAKE2b-256 932e455b92a894a905e695a5c9745325cad2a20347036b520925b88bd4c51493

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 7f9a9a3be91499f067e2b47c0eda7fd80d9d8011b3f4bedeec5b9a3e17fea811
MD5 0653c8cd63677141a3a4fa21fb18d926
BLAKE2b-256 8b9c870fcc6cb9229a884866d23381d79943d428a33adb8698da1e394c506286

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9d727a22fbdf57849f7e58c89da582cecf069f1bd4faba4c259db87e2388942e
MD5 491d96717f01f620a06c6e3c02c5786a
BLAKE2b-256 3bb992bfdca24be62faae97c40c04385ee950ae77d50a1787da195289d6d4915

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.6-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6aefb2ab18484a114a5ad18cb3b886b8e9519f22dd505041329dd90d106a4599
MD5 17fd61c5efadc845885f491bb898d433
BLAKE2b-256 a6bbeb573e4ac1ddf41bab14321327a09dcf2ce59514967ec93984ef0d072faa

See more details on using hashes here.

Provenance

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

This release

0.3.6 This release

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

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