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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

transportations_library-0.3.2-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.2-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.2.tar.gz.

File metadata

  • Download URL: transportations_library-0.3.2.tar.gz
  • Upload date:
  • Size: 802.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.2.tar.gz
Algorithm Hash digest
SHA256 a1b347b8a2086c3340e9c908f8206aecaec3c4f312cb54f633b812f00f60a650
MD5 c979ab0545f816e3d345dbeea65f455f
BLAKE2b-256 4534104db62b04840ae4e40645f738accd3f1a730cb1b11824ce1ddef0549e7f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 dd0f61836af0f968ea30d6930b136f3d31e2a80f08f258329e8425081d24908f
MD5 eb9c86cf063b4ce0902fa482e17ef6e0
BLAKE2b-256 680378c2ef937c62651616f131013d25ecd95332bddef6469199d23aa46e87aa

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8d955f1eda40d264be9eade752412178398c45e2653165328c1a84dfc98c5ea2
MD5 764c95a3a91c4a6edfad17363e727543
BLAKE2b-256 893428702ba5bad4ec772f372daa13371d244e4f16a12d96521e5f536e096483

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a60d2e5b8ae53627bd13fba441bde7474d8feae5b12fe5a82b446a8c2163bf29
MD5 da212cf6539dddd4b78b278d58ac0d5e
BLAKE2b-256 ff00dd062ab70ce23748fd08b53efcb8b4b2552d39e8171306cf91db1ceddb43

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 0a7f54b4ba5fff4a5d2b967102c3e35366a9b0b260909a875162b7f48ad9d9d3
MD5 77b56713eee55b49788364e4a70bad6d
BLAKE2b-256 c84c479ff9078621d6223904b26dbe2a35f608867434777eda343310bb48cfc4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 44ee6383b935ddf4aab099366c5402bdefb42e31d50c78c9dd3fcb1cba1c3d11
MD5 e236c7a65524b111d79a0469d6d2cb41
BLAKE2b-256 cd385b9bad91c1a75209994ee0ef8882d45eea787bb0dbf89c12b8b43794c0b8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dbb22749212afbd398923a1379763667b5f71ce15c00c3084f41a58a134f28df
MD5 5e0093b8ffa6eacc87063de55aa30e23
BLAKE2b-256 7b78777978cb7e3d1ee6b97955c78df9c5e3549779ec5aa969c03f4f4ecca9d8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 bb6e311dab7a8d198d9d99ae07d34a931c11a8a188cfb800887c760323bed17a
MD5 9c614aab4dfebb1a23a9def16e34d6ef
BLAKE2b-256 73d14cead3f83e3d93ad76462436b3b11f06d6153915ee65a9683372ac0fa836

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 89482929882f209cbc477c9b943ae541dfdedf7310e0c4a14e51a30e6c72c189
MD5 111f701051d36859475df2558c02389f
BLAKE2b-256 7992993cb06ba19e5056385e63373a643c5b27dde755bf3279d6599b261eb1a0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.3.2-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 732c4ee40a55f9bfeb4bcc3324753a6313c569c2a180cddb977e18601d73c9a7
MD5 4c848202ad02d941349fdd512e6e3d38
BLAKE2b-256 25598ed2d057ce11e290246ec36d99ed1a3a73138cd22abe472e3bf9516a12e9

See more details on using hashes here.

Provenance

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

This release

0.3.2 This release

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