How activitysim/activitysim works
Project type and purpose
• This is ActivitySim, an open‐source, Python‐based activity‐based travel behavior modeling framework.
• It’s not a web service or UI but a CLI tool and library that orchestrates data ingestion, configuration, model execution (ABM and estimation), and outputs.
File structure
• Top‐level directories:
• activitysim/cli – command‐line interface entry points
• activitysim/core – core simulation engine, workflow runner, config, IO, and low‐level utilities
• activitysim/abm – modules implementing specific activity‐based model components (tour frequency, mode choice, etc.)
• activitysim/estimation – modules for parameter estimation (Larch)
• activitysim/workflows – YAML‐driven pipeline definitions and steps
• activitysim/examples – numerous example scenarios and data for running ActivitySim
• docs, other_resources – documentation and scripts
• Configuration files (.yaml/.cfg), conda env specs, GitHub workflows, tests validate each component.
• The design uses a plugin/pipeline pattern via “steps” and “workflows” modules in core/workflow.
README
• High‐level mission: deliver advanced, open‐source ABM software
• Links to docs, emphasis on consortium‐driven development and CLI usage.
Components
a. Main components
1. User (or scheduler) – invokes activitysim CLI
2. CLI Layer – activitysim/cli: parses commands (run, create, benchmark)
3. Configuration Loader – activitysim/core/config: reads YAML/CSV settings
4. Workflow Engine – activitysim/core/workflow: interprets YAML pipelines, orchestrates steps
5. ABM Modules – activitysim/abm/models and tables: each “step” is a model component or table builder
6. Estimation Modules (optional) – activitysim/estimation/larch: parameter estimation flows
7. Core Utilities – fast eval, interaction sample, I/O, skims, memory utilities
8. Data Stores – input data (households, landuse, skims OMx), intermediate caches, output traces & tables
9. External Services – file system, optional HPC/multiprocessing via activitysim/core/mp_tasks
b. Relationships and interactions
• CLI invokes Configuration Loader → Workflow Engine
• Workflow Engine sequences Steps: each Step loads data, invokes ABM model or utility, writes to Data Store
• ABM Modules communicate via shared Data Store (Pandas/HDF5 or in‐memory tables)
• Estimation modules may call core simulate routines and write results to disk
• Users inspect outputs (CSVs, HDF5, logs)
c. Architectural patterns & design principles
• Pipeline pattern: workflows defined in YAML, steps implemented in Python classes
• Plugin architecture: new models or steps drop into activitysim/abm or activitysim/workflows/steps
• Separation of concerns: CLI vs. core engine vs. model components vs. I/O
• Test‐driven: extensive test directories mirror each component
d. Key technologies/frameworks
• Python 3, Pandas, NumPy, YAML parsing, HDF5 or OMx for skims, multiprocessing
• Larch optimizer for estimation
• PyTest for testing, conda for env management
Elements
• Clear labels: “CLI”, “Config Loader”, “Workflow Engine”, “ABM Models”, “Estimation”, “Data Store”, “External FS”
• User → CLI → Workflow Engine
• Workflow Engine → (models steps) → Data Store
• Estimation Modules ↔ Core simulate routines
• CLI & entry: blue
• Core engine & workflow: green
• Model components (ABM/Estimation): orange
• Data stores & inputs/outputs: gray
• External services (FS, HPC): purple
Detailed capture of essential elements
• Layer 1 (Entry): User, activitysim CLI
• Layer 2 (Config & Orchestration): Config Loader, Workflow Runner
• Layer 3 (Processing Steps): ABM model modules, table generators, estimation modules
• Layer 4 (Data): Input data sources, intermediate caches, final outputs
• Cross‐cutting: multiprocessing, logging, error handling
• Block with the directory/package name.
• That any new plug‐in or step you add can be placed under the “Processing Steps” layer.
• Keep it high‐level enough to fit on one page but detailed enough to show key modules and patterns.