# activitysim/activitysim architecture

> Architecture diagram of the GitHub repository activitysim/activitysim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/activitysim/activitysim
- Repository: https://github.com/activitysim/activitysim

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1 Entry
    User["User"]:::external
    CLI_Layer["CLI Layer"]:::cli
    User -->|invokes| CLI_Layer

    subgraph "CLI Layer (activitysim/cli)" 
        direction TB
        cli_main["main.py"]:::cli
        cli_cli["cli.py"]:::cli
        run_py["run.py"]:::cli
        create_py["create.py"]:::cli
        benchmark_py["benchmark.py"]:::cli
    end
    CLI_Layer --> cli_cli

    %% Layer 2 Config & Orchestration
    Config_Loader["Config Loader"]:::core
    Workflow_Engine["Workflow Engine"]:::core
    CLI_Layer -->|loads config| Config_Loader
    CLI_Layer -->|starts workflow| Workflow_Engine

    subgraph "Configuration Loader (activitysim/core/config)" 
        direction TB
        config_py["config.py"]:::core
        base_py["base.py"]:::core
        filesystem_py["filesystem.py"]:::core
        logit_cfg_py["logit.py"]:::core
        network_cfg_py["network.py"]:::core
        top_cfg_py["top.py"]:::core
    end
    Config_Loader --> config_py

    subgraph "Workflow Engine (activitysim/core/workflow)" 
        direction TB
        runner_py["runner.py"]:::core
        steps_py["steps.py"]:::core
        state_py["state.py"]:::core
        accessor_py["accessor.py"]:::core
        util_py["util.py"]:::core
        dataset_py["dataset.py"]:::core
        checkpoint_py["checkpoint.py"]:::core
    end
    Workflow_Engine --> runner_py

    %% Layer 3 Processing Steps
    subgraph "Processing Steps"
        direction TB
        ABM_Models["ABM Models"]:::model
        Tables["Table Generators"]:::model
        Estimation["Estimation Modules"]:::model
    end
    Workflow_Engine --> ABM_Models
    Workflow_Engine --> Tables
    Workflow_Engine --> Estimation

    %% ABM Modules
    ABM_Models -->|models| abm_models["activitysim/abm/models/"]:::model
    ABM_Models -->|tables| abm_tables["activitysim/abm/tables/"]:::model

    %% Estimation Modules
    Estimation --> est_dir["activitysim/estimation/larch/"]:::model

    %% Core Utilities
    subgraph "Core Utilities" 
        direction TB
        fast_eval["fast_eval.py"]:::core
        expressions_py["expressions.py"]:::core
        fast_mapping_py["fast_mapping.py"]:::core
        interaction_sample_py["interaction_sample.py"]:::core
        interaction_sample_sim_py["interaction_sample_simulate.py"]:::core
        logit_py["logit.py"]:::core
        mem_py["mem.py"]:::core
        memory_sidecar_py["memory_sidecar.py"]:::core
        skim_dataset_py["skim_dataset.py"]:::core
        skim_dict_py["skim_dictionary.py"]:::core
        skim_factory_py["skim_dict_factory.py"]:::core
    end
    Workflow_Engine --> fast_eval

    %% Multiprocessing & Path
    mp_tasks["mp_tasks.py"]:::external
    pathbuilder_py["pathbuilder.py"]:::core
    pathbuilder_cache_py["pathbuilder_cache.py"]:::core
    Workflow_Engine --> mp_tasks

    %% Layer 4 Data
    subgraph "Data Stores & External"
        direction TB
        Input_Data["Input Data"]:::data
        Intermediate["Intermediate Cache"]:::data
        Outputs["Final Outputs"]:::data
        FS["File System / HPC"]:::external
    end
    fast_eval --> Input_Data
    Workflow_Engine --> Intermediate
    Workflow_Engine --> Outputs
    Workflow_Engine --> FS

    %% Click Events
    click User "https://github.com/activitysim/activitysim/blob/main/activitysim/__main__.py"
    click cli_main "https://github.com/activitysim/activitysim/blob/main/activitysim/cli/main.py"
    click cli_cli "https://github.com/activitysim/activitysim/blob/main/activitysim/cli/cli.py"
    click run_py "https://github.com/activitysim/activitysim/blob/main/activitysim/cli/run.py"
    click create_py "https://github.com/activitysim/activitysim/blob/main/activitysim/cli/create.py"
    click benchmark_py "https://github.com/activitysim/activitysim/blob/main/activitysim/cli/benchmark.py"
    click config_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/config.py"
    click base_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/configuration/base.py"
    click filesystem_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/configuration/filesystem.py"
    click logit_cfg_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/configuration/logit.py"
    click network_cfg_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/configuration/network.py"
    click top_cfg_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/configuration/top.py"
    click runner_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/runner.py"
    click steps_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/steps.py"
    click state_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/state.py"
    click accessor_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/accessor.py"
    click util_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/util.py"
    click dataset_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/dataset.py"
    click checkpoint_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/workflow/checkpoint.py"
    click abm_models "https://github.com/activitysim/activitysim/tree/main/activitysim/abm/models/"
    click abm_tables "https://github.com/activitysim/activitysim/tree/main/activitysim/abm/tables/"
    click est_dir "https://github.com/activitysim/activitysim/tree/main/activitysim/estimation/larch/"
    click fast_eval "https://github.com/activitysim/activitysim/blob/main/activitysim/core/fast_eval.py"
    click expressions_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/expressions.py"
    click fast_mapping_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/fast_mapping.py"
    click interaction_sample_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/interaction_sample.py"
    click interaction_sample_sim_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/interaction_sample_simulate.py"
    click logit_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/logit.py"
    click mem_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/mem.py"
    click memory_sidecar_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/memory_sidecar.py"
    click skim_dataset_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/skim_dataset.py"
    click skim_dict_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/skim_dictionary.py"
    click skim_factory_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/skim_dict_factory.py"
    click mp_tasks "https://github.com/activitysim/activitysim/blob/main/activitysim/core/mp_tasks.py"
    click pathbuilder_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/pathbuilder.py"
    click pathbuilder_cache_py "https://github.com/activitysim/activitysim/blob/main/activitysim/core/pathbuilder_cache.py"

    %% Styles
    classDef cli fill:#a8d0e6,stroke:#000,stroke-width:1px
    classDef core fill:#c3f584,stroke:#000,stroke-width:1px
    classDef model fill:#f5a25d,stroke:#000,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#cba6f7,stroke:#000,stroke-width:1px
```
