# rawatpranjal/econirl architecture

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

- Interactive diagram: https://gitdiagram.com/rawatpranjal/econirl
- Repository: https://github.com/rawatpranjal/econirl

## Overview

1. **What this repo is**
   - `econirl` is a Python package for structural dynamic discrete choice and inverse reinforcement learning.
   - The public API is sklearn-like: users load panel/trajectory data, fit an estimator, then run counterfactuals, inference, and visualization.

2. **Top-level architecture**
   - The codebase is split into a reusable library in `src/econirl/`, a validation harness in `validation/`, public examples in `examples/`, and docs/tests around that core.
   - The package is not a single-model project: it contains multiple estimator families sharing common primitives.

3. **Data and domain inputs**
   - `src/econirl/datasets/` provides loaders and packaged sample data for canonical case studies such as Rust bus, taxi/gridworld, citi bike, sepsis, supermarket, and others.
   - `src/econirl/environments/` defines the corresponding MDP/environment abstractions used by synthetic experiments and demonstrations.
   - Many examples and tests rely on these bundled datasets rather than external live services.

4. **Core modeling layer**
   - `src/econirl/core/` contains the shared mathematical machinery: Bellman operators, occupancy measures, optimizer utilities, sufficient statistics, reward specs, and type definitions.
   - This layer is the common dependency for both classical DDC estimators and IRL-style estimators, so it forms the main computational boundary of the package.

5. **Estimator families**
   - `src/econirl/estimators/` is the primary sklearn-style surface exposed to users; this is where `NFXP`, `CCP`, `MPEC`, `NNES`, `TDCCP`, `MCEIRL`, and neural variants live.
   - `src/econirl/estimation/` contains lower-level implementations and estimator orchestration logic, including adversarial methods like AIRL and AIRL-Het.
   - `src/econirl/contrib/` holds older or supplementary algorithms such as behavioral cloning, GAIL, max-margin IRL, max-ent IRL, Bayesian IRL, and Deep MaxEnt IRL.

6. **Model representation and preferences**
   - `src/econirl/forms/` handles how state/action/tabular/factored structures are represented and loaded.
   - `src/econirl/preferences/` defines reward/utility parameterizations, including linear, reward-based, action-utility, and neural cost forms.
   - These modules are the bridge between raw data and estimator-specific optimization targets.

7. **Training, optimization, and transition estimation**
   - `src/econirl/transitions.py` and `src/econirl/estimation/transitions.py` support estimating or working with transition dynamics.
   - `src/econirl/core/optimizer.py`, `src/econirl/core/solvers.py`, and neural-specific estimators provide the optimization backend for likelihood, fixed-point, and adversarial objectives.
   - `src/econirl/rl/ppo.py` is the one explicit RL training component, used mainly for imitation-learning style workflows.

8. **Inference and uncertainty**
   - `src/econirl/inference/` provides post-estimation analysis: standard errors, bootstrap, profile likelihood, fit metrics, hypothesis tests, identifiability, sensitivity, and result containers.
   - This layer is used after estimation, not during the core fit loop, and is important for the “structural” part of the package: recovering parameters and assessing uncertainty.

9. **Counterfactuals, simulation, and evaluation**
   - `src/econirl/simulation/` generates counterfactual and synthetic outcomes from fitted models.
   - `src/econirl/evaluation/` and `src/econirl/visualization/` turn fitted models into benchmark metrics, convergence summaries, policy/value plots, and diagnostic views.
   - A typical flow is: data in → estimator fit → counterfactual or policy simulation out → evaluation/visualization.

10. **Replication and case studies**
   - `src/econirl/replication/rust1987/` packages a Rust bus replication workflow with exports, Monte Carlo routines, and tables.
   - `examples/` contains reproducible case studies and showcases; many are one-off scripts for a specific estimator/data combination.
   - These examples act as architecture “integration points” showing how the library is intended to be composed in practice.

11. **Validation subsystem**
   - `validation/` is a separate, reproducible benchmark/validation harness with runners, metrics, and archived results JSON.
   - It provides the strongest evidence boundary in the repo: each estimator has scoped validation tasks and stored outputs, which are also referenced in the README’s public evidence table.
   - This means the repo distinguishes between the general-purpose library and the formal validation suite used to support claims about each method.

12. **Tests and quality gates**
   - `tests/` covers unit, integration, benchmark, and estimator-specific behavior across datasets, wrappers, convergence, identifiability, and API compatibility.
   - `.github/workflows/ci.yml`, `pyproject.toml`, and the `Makefile` define packaging and CI automation; `docs/` is built separately for Read the Docs.
   - The presence of both validation artifacts and tests indicates two distinct quality layers: correctness/regression testing and empirical method validation.

13. **Technology and runtime boundaries**
   - The package is pure Python at the repo level, with JAX configuration visible in `src/econirl/_jax_config.py`, suggesting JAX-backed numerical paths in some estimators.
   - The public interface is library-first rather than service-first: there is no web server or database boundary in the architecture.
   - External dependencies are mostly scientific-computing and plotting toolchains, with packaged data files and notebooks used for reproducibility rather than runtime integration.

Main entry points: [`src/econirl/estimators`](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/estimators) (Estimators), [`src/econirl/core`](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/core) (Core math), [`src/econirl/__init__.py`](https://github.com/rawatpranjal/econirl/blob/main/src/econirl/__init__.py) (econirl API), [`examples`](https://github.com/rawatpranjal/econirl/tree/main/examples) (Showcases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_src["Library"]
  node_n_api["econirl API<br/>package entry<br/>[__init__.py]"]
  node_n_core["Core math<br/>shared primitives"]
  node_n_forms["Forms<br/>state/action models"]
  node_n_prefs["Preferences<br/>reward parameterizations"]
  node_n_data[("Datasets<br/>packaged data")]
  node_n_envs["Environments"]
  node_n_est["Estimators"]
  node_n_est_impl["Estimation logic<br/>estimator orchestration"]
  node_n_contrib["Contrib IRL<br/>legacy algorithms"]
  node_n_trans["Transitions<br/>dynamics estimation<br/>[transitions.py]"]
  node_n_infer["Inference<br/>uncertainty analysis"]
  node_n_sim["Simulation<br/>counterfactuals"]
  node_n_eval["Evaluation<br/>metrics and diagnostics"]
  node_n_viz["Visualization<br/>plots"]
  node_n_rl["RL training<br/>ppo<br/>[ppo.py]"]
  node_n_rep["Rust replication<br/>case study"]
end

subgraph group_grp_val["Validation"]
  node_n_val_h["Validation harness<br/>benchmark runner<br/>[harness.py]"]
  node_n_val_res[("Validation results<br/>archived evidence")]
end

subgraph group_grp_examples["Examples"]
  node_n_ex_show["Showcases<br/>examples"]
end

subgraph group_grp_docs["Docs"]
  node_n_docs["Docs site<br/>documentation"]
end

node_n_api -->|"uses"| node_n_core
node_n_api -->|"exposes"| node_n_forms
node_n_api -->|"exposes"| node_n_prefs
node_n_api -->|"exports"| node_n_est
node_n_forms -->|"loads"| node_n_data
node_n_envs -->|"relies on"| node_n_core
node_n_est -->|"optimizes"| node_n_core
node_n_est -->|"fits dynamics"| node_n_trans
node_n_est -->|"analyzes"| node_n_infer
node_n_est -->|"simulates"| node_n_sim
node_n_est -->|"evaluates"| node_n_eval
node_n_est -->|"visualizes"| node_n_viz
node_n_est_impl -->|"implements"| node_n_est
node_n_contrib -->|"extends"| node_n_core
node_n_rl -->|"uses"| node_n_core
node_n_rep -->|"runs"| node_n_sim
node_n_val_h -->|"benchmarks"| node_n_est
node_n_val_h -->|"writes"| node_n_val_res
node_n_ex_show -->|"loads"| node_n_data
node_n_ex_show -->|"demonstrates"| node_n_est
node_n_ex_show -->|"demonstrates"| node_n_sim
node_n_docs -->|"documents"| node_n_est
node_n_docs -->|"reports"| node_n_val_h
node_n_docs -->|"showcases"| node_n_ex_show

click node_n_api "https://github.com/rawatpranjal/econirl/blob/main/src/econirl/__init__.py"
click node_n_core "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/core"
click node_n_forms "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/forms"
click node_n_prefs "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/preferences"
click node_n_data "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/datasets"
click node_n_envs "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/environments"
click node_n_est "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/estimators"
click node_n_est_impl "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/estimation"
click node_n_contrib "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/contrib"
click node_n_trans "https://github.com/rawatpranjal/econirl/blob/main/src/econirl/transitions.py"
click node_n_infer "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/inference"
click node_n_sim "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/simulation"
click node_n_eval "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/evaluation"
click node_n_viz "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/visualization"
click node_n_rl "https://github.com/rawatpranjal/econirl/blob/main/src/econirl/rl/ppo.py"
click node_n_rep "https://github.com/rawatpranjal/econirl/tree/main/src/econirl/replication/rust1987"
click node_n_val_h "https://github.com/rawatpranjal/econirl/blob/main/validation/benchmark/harness.py"
click node_n_val_res "https://github.com/rawatpranjal/econirl/tree/main/validation/results"
click node_n_ex_show "https://github.com/rawatpranjal/econirl/tree/main/examples"
click node_n_docs "https://github.com/rawatpranjal/econirl/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_api,node_n_core,node_n_forms,node_n_prefs,node_n_data,node_n_envs,node_n_est,node_n_est_impl,node_n_contrib,node_n_trans,node_n_infer,node_n_sim,node_n_eval,node_n_viz,node_n_rl,node_n_rep toneBlue
class node_n_val_h,node_n_val_res toneAmber
class node_n_ex_show toneMint
class node_n_docs toneRose
```

## Components

### Library

Reusable Python package under src/econirl

- [econirl API](https://github.com/rawatpranjal/econirl/blob/main/src/econirl/__init__.py): package entry · Public package surface and import entry point · `src/econirl/__init__.py`
- [Core math](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/core): shared primitives · Bellman operators, occupancy measures, solvers, rewards, and types · `src/econirl/core`
- [Forms](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/forms): state/action models · Tabular, factored, and grid representations plus loaders · `src/econirl/forms`
- [Preferences](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/preferences): reward parameterizations · Linear, action-utility, reward, and neural cost forms · `src/econirl/preferences`
- [Datasets](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/datasets): packaged data · Dataset loaders and bundled benchmark datasets · `src/econirl/datasets`
- [Environments](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/environments): MDP environments · Synthetic and demo environment abstractions · `src/econirl/environments`
- [Estimators](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/estimators): sklearn-style estimators · Primary user-facing estimator family surface · `src/econirl/estimators`
- [Estimation logic](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/estimation): estimator orchestration · Lower-level implementations and estimator workflows · `src/econirl/estimation`
- [Contrib IRL](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/contrib): legacy algorithms · Supplementary and older imitation/IRL methods · `src/econirl/contrib`
- [Transitions](https://github.com/rawatpranjal/econirl/blob/main/src/econirl/transitions.py): dynamics estimation · Transition-model utilities and estimation support · `src/econirl/transitions.py`
- [Inference](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/inference): uncertainty analysis · Standard errors, bootstrap, profile likelihood, tests, and sensitivity · `src/econirl/inference`
- [Simulation](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/simulation): counterfactuals · Synthetic and counterfactual outcome generation · `src/econirl/simulation`
- [Evaluation](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/evaluation): metrics and diagnostics · Benchmarking, convergence, and evaluation adapters · `src/econirl/evaluation`
- [Visualization](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/visualization): plots · Policy and value visualization helpers · `src/econirl/visualization`
- [RL training](https://github.com/rawatpranjal/econirl/blob/main/src/econirl/rl/ppo.py): ppo · Explicit reinforcement-learning training component · `src/econirl/rl/ppo.py`
- [Rust replication](https://github.com/rawatpranjal/econirl/tree/main/src/econirl/replication/rust1987): case study · Rust 1987 export, Monte Carlo, and tables workflow · `src/econirl/replication/rust1987`

### Validation

Benchmark harness and archived evidence

- [Validation harness](https://github.com/rawatpranjal/econirl/blob/main/validation/benchmark/harness.py): benchmark runner · Validation runner, metrics, and figures for estimator claims · `validation/benchmark/harness.py`
- [Validation results](https://github.com/rawatpranjal/econirl/tree/main/validation/results): archived evidence · Stored JSON outputs for estimator and simulation benchmarks · `validation/results`

### Examples

Reproducible case studies and showcase scripts

- [Showcases](https://github.com/rawatpranjal/econirl/tree/main/examples): examples · Estimator and case-study scripts demonstrating intended usage · `examples`

### Docs

User guide and API documentation

- [Docs site](https://github.com/rawatpranjal/econirl/tree/main/docs): documentation · User guide, estimator docs, and API reference · `docs`

## Connections

- econirl API → Core math: uses · Public API is built on the shared mathematical layer
- econirl API → Forms: exposes · Package surface exposes representation helpers
- econirl API → Preferences: exposes · Package surface exposes preference models
- econirl API → Estimators: exports · Top-level package exports sklearn-style estimators
- Forms → Datasets: loads · Form loaders consume bundled datasets and samples
- Environments → Core math: relies on · Environments use core MDP and Bellman primitives
- Estimators → Core math: optimizes · Estimators depend on Bellman, occupancy, and solver utilities
- Estimators → Transitions: fits dynamics · Some estimators estimate or adapt transition models
- Estimators → Inference: analyzes · Estimator outputs feed post-estimation inference
- Estimators → Simulation: simulates · Fitted estimators produce counterfactual simulations
- Estimators → Evaluation: evaluates · Estimator runs are benchmarked and summarized
- Estimators → Visualization: visualizes · Estimator outputs can be plotted as policies and values
- Estimation logic → Estimators: implements · Lower-level orchestration backs the public estimator surface
- Contrib IRL → Core math: extends · Older IRL methods reuse shared optimization and reward machinery
- RL training → Core math: uses · PPO-based training uses shared types and objectives
- Rust replication → Simulation: runs · Replication workflow uses simulation and counterfactual generation
- Validation harness → Estimators: benchmarks · Validation harness exercises estimators under controlled tasks
- Validation harness → Validation results: writes · Harness stores archived benchmark outputs
- Showcases → Datasets: loads · Examples commonly start from bundled datasets
- Showcases → Estimators: demonstrates · Examples show fitting and comparison of estimators
- Showcases → Simulation: demonstrates · Examples often generate counterfactuals and diagnostics
- Docs site → Estimators: documents · Docs explain estimator usage and internals
- Docs site → Validation harness: reports · Docs reference validation and evidence tables
- Docs site → Showcases: showcases · Docs link to example workflows and studies