Documentation

Install

AutoSim is a Python package (3.10+). The distribution name is autosim-av; the import name and CLI are autosim.

# From PyPI (public listing)
pip install autosim-av

# Or from the GitHub Release (available today)
pip install https://github.com/TalkDocInc/auto-talkdoc/releases/download/v0.2.0/autosim_av-0.2.0-py3-none-any.whl

autosim --help

Quickstart

Run a bundled example and gate on the result (exit code 0 = pass):

autosim examples                      # list bundled scenarios
autosim run aeb_stationary            # run one; exits non-zero if it fails
autosim run aeb_stationary --report report.html   # self-contained replay

 PASS  aeb_stationary_obstacle (duration)
  min TTC 1.67s   min gap 12.59m   peak decel 9.00 m/s²
    ✓ NoCollision
    ✓ MinDistance: 12.59m >= 0.5m
    ✓ MaxDeceleration: 9.0 <= 9.5 m/s²

Scenarios as code

A scenario is a readable YAML file that diffs in Git. Entities have an init (lane, position, speed), a dynamics model, and a controller. An optional story fires triggered actions; evaluation lists the pass/fail assertions.

scenario: {name: aeb_stationary, dt: 0.02, duration: 15.0}
road: {type: straight_highway, lanes: 2, length: 2000}   # or curved_highway
entities:
  - id: ego
    init: {lane: lane0, s: 0.0, speed: 22.0}
    controller:
      type: aeb
      ttc_brake: 1.8
      sensor: {type: object_list, max_range: 160, occlusion: true}
      base: {type: speed_keeper, lane: lane0, set_speed: 22.0}
  - id: obstacle
    init: {lane: lane0, s: 85.0, speed: 0.0}
evaluation:
  assertions:
    - {type: no_collision}
    - {type: min_distance, threshold: 0.5}
    - {type: max_deceleration, limit: 9.5}

Controllers: acc, aeb, lka, idm, speed_keeper, open_loop. Sensors: object_list (radar), lidar, camera — each with noise, dropout, FOV, and line-of-sight occlusion. Roads: straight_highway, curved_highway.

CLI reference

Command	Purpose
autosim run <scenario>	Run one scenario; exit non-zero on failure. --report, --json, --recording.
autosim sweep <scn> <sweep>	Parameter / Monte-Carlo campaign. --workers, --min-pass-rate, --report, --cloud.
autosim report <scenario>	Run and write a self-contained HTML report.
autosim replay <recording>	Build an HTML replay from a saved recording JSON.
autosim validate <scenario>	Load-check a scenario and report errors.
autosim examples	List bundled example scenarios.
autosim license {show,activate,verify}	Manage your license (see below).

Campaigns & sweeps

Map the safe envelope with a grid or Monte-Carlo campaign. Results aggregate to one pass rate and a pass/fail heatmap.

# sweep.yaml
mode: sample
samples: 10000
seed: 0
parameters:
  - {path: "entities[1].init.speed", range: [10.0, 30.0]}
  - {path: "entities[0].controller.ttc_brake", values: [1.2, 1.6, 2.0]}

autosim sweep acc_cutin sweep.yaml --workers 32 \
        --min-pass-rate 0.999 --report campaign.html

Free tier: up to 200 runs and 4 workers per campaign. Larger campaigns, --cloud, and unwatermarked reports require a Team license.

Metrics & assertions

Every run derives safety & comfort KPIs and evaluates declarative assertions:

Assertion	Checks
no_collision	No collision occurred.
min_ttc {threshold}	Minimum time-to-collision stayed above threshold.
min_thw {threshold}	Minimum time-headway.
min_distance {threshold}	Minimum bumper gap.
max_deceleration {limit}	Peak braking within comfort/limit.
max_jerk {limit}	Peak longitudinal jerk.
no_lane_departure / max_lateral_deviation {limit}	Lane keeping.
rss_safe / min_rss_margin {threshold}	Responsibility-Sensitive-Safety distance.

CI integration

Exit codes are meaningful, so a gate is one line in your pipeline:

# .github/workflows/adas-gate.yml
- run: pip install autosim-av
- run: autosim run scenarios/aeb_stationary.yaml
- run: autosim sweep scenarios/cutin.yaml scenarios/sweep.yaml --min-pass-rate 0.999
  env:
    AUTOSIM_LICENSE: ${{ secrets.AUTOSIM_LICENSE }}   # for large/cloud campaigns

License & tiers

Community is free and needs no key: the full local engine, CLI, and viewer, with campaigns up to 200 runs / 4 workers and a small watermark on reports. Team and Enterprise lift those limits and unlock cloud sweeps, unwatermarked evidence, NCAP packs, and more.

Start a free 14-day Team trial, then activate the key you receive:

autosim license activate <your-key>
autosim license show          # tier, seats, expiry, features
autosim license verify <key>  # offline signature + expiry check

The CLI reads a license from the AUTOSIM_LICENSE env var (handy for CI) or ~/.autosim/license. Verification is fully offline — an Ed25519 signature checked against a key embedded in the package; no phone-home.

Python API

The engine is Python-first — the CLI is a thin wrapper.

from autosim.scenario import run_scenario

result = run_scenario("aeb_stationary.yaml")
print(result.passed, result.kpi.min_ttc, result.kpi.max_decel)
for r in result.evaluation.results:
    print(r.name, r.passed, r.detail)

Subclass a controller, sensor model, or metric in plain Python and drop it into the same deterministic engine.