Transportations Library

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

What this covers

Currently implements:

  • Highway Capacity Manual (HCM) Chapter 15: Two-Lane Highways analysis
  • Other chapters are to be added in future releases

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)

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 test the alpha release from Test PyPI, use:

pip install --no-cache-dir --verbose -i https://test.pypi.org/simple/ transportations-library==0.1.9a4

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.2.0.tar.gz (715.7 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.2.0-cp312-cp312-win_amd64.whl (970.9 kB view details)

Uploaded CPython 3.12Windows x86-64

transportations_library-0.2.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.2.0-cp312-cp312-macosx_11_0_arm64.whl (988.9 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

transportations_library-0.2.0-cp311-cp311-win_amd64.whl (971.6 kB view details)

Uploaded CPython 3.11Windows x86-64

transportations_library-0.2.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.2.0-cp311-cp311-macosx_11_0_arm64.whl (992.7 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

transportations_library-0.2.0-cp310-cp310-win_amd64.whl (977.8 kB view details)

Uploaded CPython 3.10Windows x86-64

transportations_library-0.2.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.2.0-cp310-cp310-macosx_11_0_arm64.whl (992.5 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for transportations_library-0.2.0.tar.gz
Algorithm Hash digest
SHA256 7cc66a09923a8c846d8c28554888f79292d4dc96973d3141a6dbd896cfbccfc4
MD5 fec48cd14f068857b2d2580b784b594e
BLAKE2b-256 2e42bb156eb48f9f0fb5b933b9db2fa7e35cf5a45141b0aeae7a11873dccd404

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 57e2e073e42284a0beb3f8114580243027b502f6857cc4d574dc5a92a3902a27
MD5 f54758e11a398dbd770cdbb4827ee8c3
BLAKE2b-256 b35f79c6015332c6803cb18415fc9e0932a8c8499cc55ecb60a908726e9ebae5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 30c736808173a6ecf34b21a94ddf93138b6d9865d2401f84de784225bff16ec8
MD5 6af3e7bb2cdf214620244404c6f8e376
BLAKE2b-256 fa6b396917220417a36eeb91cbae7031086ec039efffae0ce71dc6bcf67c65f4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 41a17b19668d27cc85239019630889c99a0a798788dc4580a6b1ffb1136ae76c
MD5 8e050392eb6d52c14c52fef1a50be94e
BLAKE2b-256 92a17f3d3fd17ff326a39c6f18be5a6d6e39975e32704dcd7491d357dd4751d3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 b21feb95c05b805c7a44f543dbc9ec18be7e1d831b98e4b2e9ba27d1f64fa6ec
MD5 e8965655db8fc1de0e8e74abb3a774ee
BLAKE2b-256 c35fdaebb5714ffebb54936f32ff88c63953af22931391171156bf7bafbc1bbd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c7d1687428cd444c4cd77ec7aef90da6bfc212c8986d627cd62d0997cd128ce3
MD5 b32dfc9a6c26a7b17bba21c339a4671d
BLAKE2b-256 02f3c0471351b874f88825aafaf455ac6dbbe2de134d6dfe155b918c5d49c900

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 de027124afc0cf0fa5ef1e68c0c3e5b307ed87fdb8c38af71d402ee27ab4f888
MD5 461b7cd0f1c889fff21439f0a270a36a
BLAKE2b-256 1a8c442445c4ee0fb30d05e741ec9cbd9a6babab31f4f67de448eb4287fb88cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 9ffaffdf48a372a6b00e3a0e637a00e71152c9c3a9f1efd19e614b6f84db640a
MD5 c38593d71582de960bddc21474453f86
BLAKE2b-256 d85e0d4ac90cd8e9c093732c28d67a402e58a42c7125b215eecb0cfc304d23a9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 78319dcfcfc468ab146ce04898a46dfec54f35065fa6e455201abe9ddeb35e7c
MD5 90555548d5a043b45f810ac63c755853
BLAKE2b-256 6cb409bc9771497f22b5d8bfde03d4ec1fccc8472646bebc69a2f429ddee6f9b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for transportations_library-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 45ef35c14c1de0de722f29d63c76a2121951906dbd3b3281a9dad570319c894c
MD5 dc6337fa19f79c9a1f5398522236658a
BLAKE2b-256 602d93aa74b5b1c5a0370cbc49f113b61e43ef74e58e2a2fcfafc9db96faa7c7

See more details on using hashes here.

Provenance

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

0.3.0

10 files

This release

0.2.0 This release

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