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.

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.3.tar.gz (813.0 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.3-cp312-cp312-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.12Windows x86-64

transportations_library-0.3.3-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.3-cp312-cp312-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

transportations_library-0.3.3-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.3-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.3.tar.gz.

File metadata

  • Download URL: transportations_library-0.3.3.tar.gz
  • Upload date:
  • Size: 813.0 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.3.tar.gz
Algorithm Hash digest
SHA256 62ced2040a514ed9a0f1467b6aedcc15ac5b6b39a3f523464123727fb8b424f5
MD5 6155333502d4a4792173009ebc229007
BLAKE2b-256 a0f87bb58c85226bf9bef1aa7167eeee4079519c19ea163be2a808edde5aa63b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 199d8e3f1814e266c047ef550b17bacbc3442b2199df3a142bad0a26e12706a0
MD5 40628c823a6ffc7cd4b1c83742ad5e2c
BLAKE2b-256 34ed29e75c1ef0ab96254aef5898b781da324227149c5e9771d076a09f0aebbb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d1cde6488a63a3d7b036e86c8855ddeb2a1b3ecda2c0438df1dbb2a9bfce26c9
MD5 cc0eb775c7ee74d96956659ab6da6bcc
BLAKE2b-256 0e747a93699cfec2b52d93dd17694255d6cbac9ef52e16a390c645a9b874c459

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4a17d5af36358141e83871dd99ef49a718abd154e6d3e3e1aad7ea125296b1e0
MD5 7e8aac66a77ee938a93bfcd2eccf569b
BLAKE2b-256 46463d894c73251e6b6e2846b89bf07277bab453021803e3a9a611605b655fc3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 74c45a86d64830cde11e5cf9983209e4c2b9d0f44c9f747806fd6e49e5c659b4
MD5 d5d837c1bf469ce7c36c164244d2f816
BLAKE2b-256 e5ec2e897065fa899000c909164058a3ca8ff4d362e7935063c1645e061ea8a4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1b2dad96171ebcac233683f5262ed22724879a9912acccab3549a026e26a6536
MD5 8a0146066dcc54e1b05a8b981b085403
BLAKE2b-256 958789a80e80bbb8caea13c9b4d6b55497d4686da3e6a25df46d9cf3acd2450d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 916418680e3acbf434aee89e0f0bb94b69eac5b55fc1af07c6aba4a012623ea8
MD5 13d42f4df44ad8d9e71cbd010973313f
BLAKE2b-256 27dc51ddf4a87b0a5b2fcc1fc736fbf00dcbc922286b79aa5a2d1e9a18aadde6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 ae1a7c2a5a5d692d9cc922bd90e67d6b14251456dc771eafca9f9b6d90df546f
MD5 7eb6615e6a525e24a626ba65169694db
BLAKE2b-256 3d5fa13eea1bcb962c31a5279569fddf4b66a278d232571ae0a2fe9e6aa7ae30

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e556bf08f51b6407dd1e0e70c707201f3eabb87550ff25c4a2ca2187da107e2f
MD5 0b0d29abb70f3e770a6b828302ee4019
BLAKE2b-256 df08a92e7ee5bae50b6be69c86f4a3319eb9acbc494ab2204f5f5b6030f71157

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.3-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7ea19a1568cdb0fd3ee706b7bf852eb353d263e7a22f9aa9591d7cd0838cf709
MD5 1c17d3373bbb1ee4f7b4367e8a183e57
BLAKE2b-256 226ce8ae7f3610028dba7f650178766f21f8e79c0bf675b8bea1aaaaef73911a

See more details on using hashes here.

Provenance

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

This release

0.3.3 This release

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

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