# zvez-t/ddcm architecture

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

- Interactive diagram: https://gitdiagram.com/zvez-t/ddcm
- Repository: https://github.com/zvez-t/ddcm

## Overview

ddcm is an R package for specifying, solving, estimating, and analyzing dynamic discrete-choice models and dynamic games. The principal workflow runs from a user's formula and data through state-space and transition construction, utility specification, algorithm dispatch, model solution, and parameter estimation, ending in fitted-model summaries and predictions. The package also documents Bayesian, HMM, mixture, approximate-value-function, SBI, synthetic-data, and game-estimation capabilities. README statements establish most feature-level links; sampled C++ excerpts clarify the Bellman, likelihood, HMM, and shared-primitive layers, but many R-level calls were not sampled.

Main entry points: [`R/ddcm_api.R`](https://github.com/zvez-t/ddcm/blob/main/R/ddcm_api.R) (DDC interface), [`R/solver_nfxp.R`](https://github.com/zvez-t/ddcm/blob/main/R/solver_nfxp.R) (NFXP solver), [`R/dispatch.R`](https://github.com/zvez-t/ddcm/blob/main/R/dispatch.R) (Algorithm dispatch), [`src/bellman.cpp`](https://github.com/zvez-t/ddcm/blob/main/src/bellman.cpp) (Bellman iteration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Model specification"]
  node_model["DDC interface<br/>[ddcm_api.R]"]
  node_state["State space<br/>[state_space.R]"]
  node_transition["Transitions<br/>[transition_model.R]"]
  node_utility["Utility specification<br/>[utility.R]"]
end

subgraph group_solving["Solving and estimation"]
  node_dispatch["Algorithm dispatch<br/>[dispatch.R]"]
  node_nfxp["NFXP solver<br/>[solver_nfxp.R]"]
  node_ccp["CCP solver<br/>[solver_ccp.R]"]
  node_mpec["MPEC solver<br/>[solver_mpec.R]"]
  node_smm["SMM and GMM<br/>[solver_smm.R]"]
  node_fitted["Model results"]
  node_approx["Approximate values<br/>[approx_vf.R]"]
end

subgraph group_inference["Specialized inference"]
  node_hmm["Latent-state HMM<br/>[hmm.R]"]
  node_mixture["Finite mixtures<br/>[mixture.R]"]
  node_bayes["Bayesian inference<br/>[bayes.R]"]
  node_sbi["Simulation inference<br/>[sbi.R]"]
end

subgraph group_games["Games and simulation"]
  node_game["Dynamic games<br/>[game.R]"]
  node_equilibrium["Equilibrium methods<br/>[equilibrium.R]"]
  node_dgp["DGP laboratory<br/>[dgp.R]"]
end

subgraph group_engine["Computation engine"]
  node_bellman["Bellman iteration<br/>[bellman.cpp]"]
  node_accel["Bellman accelerators<br/>[bellman_accel.cpp]"]
  node_primitives["Shared C++ primitives<br/>[ddcm_internal.cpp]"]
  node_emax["Emax functions<br/>[emax.cpp]"]
  node_loglik["Likelihood kernel<br/>[loglik.cpp]"]
  node_hmmengine["HMM engine<br/>[hmm_filter.cpp]"]
  node_mpecengine["MPEC kernels<br/>[mpec.cpp]"]
  node_smmengine["SMM simulation kernel<br/>[smm.cpp]"]
end

node_user(("R analyst"))

node_user -->|"specifies model"| node_model
node_model -->|"builds states"| node_state
node_model -->|"uses transitions"| node_transition
node_model -->|"specifies utility"| node_utility
node_model -->|"selects algorithm"| node_dispatch
node_dispatch -->|"dispatches NFXP"| node_nfxp
node_dispatch -->|"dispatches CCP"| node_ccp
node_model -->|"supports MPEC"| node_mpec
node_model -->|"supports moments"| node_smm
node_nfxp -->|"returns estimates"| node_fitted
node_ccp -->|"returns estimates"| node_fitted
node_nfxp -->|"solves Bellman"| node_bellman
node_bellman -->|"uses primitives"| node_primitives
node_accel -->|"uses primitives"| node_primitives
node_bellman -->|"computes Emax"| node_emax
node_nfxp -->|"evaluates likelihood"| node_loglik
node_mpec -->|"uses kernels"| node_mpecengine
node_smm -->|"simulates moments"| node_smmengine
node_model -->|"supports hidden states"| node_hmm
node_hmm -->|"filters sequences"| node_hmmengine
node_model -->|"supports heterogeneity"| node_mixture
node_model -->|"offers posterior inference"| node_bayes
node_model -->|"offers SBI"| node_sbi
node_model -->|"supports approximate values"| node_approx
node_user -->|"specifies game"| node_game
node_game -->|"estimates equilibrium"| node_equilibrium
node_user -->|"builds synthetic data"| node_dgp

click node_model "https://github.com/zvez-t/ddcm/blob/main/R/ddcm_api.R"
click node_state "https://github.com/zvez-t/ddcm/blob/main/R/state_space.R"
click node_transition "https://github.com/zvez-t/ddcm/blob/main/R/transition_model.R"
click node_utility "https://github.com/zvez-t/ddcm/blob/main/R/utility.R"
click node_dispatch "https://github.com/zvez-t/ddcm/blob/main/R/dispatch.R"
click node_nfxp "https://github.com/zvez-t/ddcm/blob/main/R/solver_nfxp.R"
click node_ccp "https://github.com/zvez-t/ddcm/blob/main/R/solver_ccp.R"
click node_mpec "https://github.com/zvez-t/ddcm/blob/main/R/solver_mpec.R"
click node_smm "https://github.com/zvez-t/ddcm/blob/main/R/solver_smm.R"
click node_fitted "https://github.com/zvez-t/ddcm/blob/main/R/methods_ddcm_summary.R"
click node_bellman "https://github.com/zvez-t/ddcm/blob/main/src/bellman.cpp"
click node_accel "https://github.com/zvez-t/ddcm/blob/main/src/bellman_accel.cpp"
click node_primitives "https://github.com/zvez-t/ddcm/blob/main/src/ddcm_internal.cpp"
click node_emax "https://github.com/zvez-t/ddcm/blob/main/src/emax.cpp"
click node_loglik "https://github.com/zvez-t/ddcm/blob/main/src/loglik.cpp"
click node_hmm "https://github.com/zvez-t/ddcm/blob/main/R/hmm.R"
click node_hmmengine "https://github.com/zvez-t/ddcm/blob/main/src/hmm_filter.cpp"
click node_mixture "https://github.com/zvez-t/ddcm/blob/main/R/mixture.R"
click node_bayes "https://github.com/zvez-t/ddcm/blob/main/R/bayes.R"
click node_sbi "https://github.com/zvez-t/ddcm/blob/main/R/sbi.R"
click node_approx "https://github.com/zvez-t/ddcm/blob/main/R/approx_vf.R"
click node_game "https://github.com/zvez-t/ddcm/blob/main/R/game.R"
click node_equilibrium "https://github.com/zvez-t/ddcm/blob/main/R/equilibrium.R"
click node_dgp "https://github.com/zvez-t/ddcm/blob/main/R/dgp.R"
click node_mpecengine "https://github.com/zvez-t/ddcm/blob/main/src/mpec.cpp"
click node_smmengine "https://github.com/zvez-t/ddcm/blob/main/src/smm.cpp"

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_model,node_state,node_transition,node_utility toneBlue
class node_dispatch,node_nfxp,node_ccp,node_mpec,node_smm,node_fitted,node_approx toneAmber
class node_hmm,node_mixture,node_bayes,node_sbi toneMint
class node_game,node_equilibrium,node_dgp toneRose
class node_bellman,node_accel,node_primitives,node_emax,node_loglik,node_hmmengine,node_mpecengine,node_smmengine,node_user toneIndigo
```

## Components

### Model specification

- [DDC interface](https://github.com/zvez-t/ddcm/blob/main/R/ddcm_api.R): `R/ddcm_api.R`
- [State space](https://github.com/zvez-t/ddcm/blob/main/R/state_space.R): `R/state_space.R`
- [Transitions](https://github.com/zvez-t/ddcm/blob/main/R/transition_model.R): `R/transition_model.R`
- [Utility specification](https://github.com/zvez-t/ddcm/blob/main/R/utility.R): `R/utility.R`

### Solving and estimation

- [Algorithm dispatch](https://github.com/zvez-t/ddcm/blob/main/R/dispatch.R): `R/dispatch.R`
- [NFXP solver](https://github.com/zvez-t/ddcm/blob/main/R/solver_nfxp.R): `R/solver_nfxp.R`
- [CCP solver](https://github.com/zvez-t/ddcm/blob/main/R/solver_ccp.R): `R/solver_ccp.R`
- [MPEC solver](https://github.com/zvez-t/ddcm/blob/main/R/solver_mpec.R): `R/solver_mpec.R`
- [SMM and GMM](https://github.com/zvez-t/ddcm/blob/main/R/solver_smm.R): `R/solver_smm.R`
- [Model results](https://github.com/zvez-t/ddcm/blob/main/R/methods_ddcm_summary.R): `R/methods_ddcm_summary.R`
- [Approximate values](https://github.com/zvez-t/ddcm/blob/main/R/approx_vf.R): `R/approx_vf.R`

### Specialized inference

- [Latent-state HMM](https://github.com/zvez-t/ddcm/blob/main/R/hmm.R): `R/hmm.R`
- [Finite mixtures](https://github.com/zvez-t/ddcm/blob/main/R/mixture.R): `R/mixture.R`
- [Bayesian inference](https://github.com/zvez-t/ddcm/blob/main/R/bayes.R): `R/bayes.R`
- [Simulation inference](https://github.com/zvez-t/ddcm/blob/main/R/sbi.R): `R/sbi.R`

### Games and simulation

- [Dynamic games](https://github.com/zvez-t/ddcm/blob/main/R/game.R): `R/game.R`
- [Equilibrium methods](https://github.com/zvez-t/ddcm/blob/main/R/equilibrium.R): `R/equilibrium.R`
- [DGP laboratory](https://github.com/zvez-t/ddcm/blob/main/R/dgp.R): `R/dgp.R`

### Computation engine

- [Bellman iteration](https://github.com/zvez-t/ddcm/blob/main/src/bellman.cpp): `src/bellman.cpp`
- [Bellman accelerators](https://github.com/zvez-t/ddcm/blob/main/src/bellman_accel.cpp): `src/bellman_accel.cpp`
- [Shared C++ primitives](https://github.com/zvez-t/ddcm/blob/main/src/ddcm_internal.cpp): `src/ddcm_internal.cpp`
- [Emax functions](https://github.com/zvez-t/ddcm/blob/main/src/emax.cpp): `src/emax.cpp`
- [Likelihood kernel](https://github.com/zvez-t/ddcm/blob/main/src/loglik.cpp): `src/loglik.cpp`
- [HMM engine](https://github.com/zvez-t/ddcm/blob/main/src/hmm_filter.cpp): `src/hmm_filter.cpp`
- [MPEC kernels](https://github.com/zvez-t/ddcm/blob/main/src/mpec.cpp): `src/mpec.cpp`
- [SMM simulation kernel](https://github.com/zvez-t/ddcm/blob/main/src/smm.cpp): `src/smm.cpp`

### Other components

- **R analyst**

## Connections

- R analyst → DDC interface: specifies model (evidence: `README.md`)
- DDC interface → State space: builds states (evidence: `README.md`)
- DDC interface → Transitions: uses transitions (evidence: `README.md`)
- DDC interface → Utility specification: specifies utility (evidence: `README.md`)
- DDC interface → Algorithm dispatch: selects algorithm (evidence: `README.md`)
- Algorithm dispatch → NFXP solver: dispatches NFXP (evidence: `README.md`)
- Algorithm dispatch → CCP solver: dispatches CCP (evidence: `README.md`)
- DDC interface → MPEC solver: supports MPEC (evidence: `README.md`)
- DDC interface → SMM and GMM: supports moments (evidence: `README.md`)
- NFXP solver → Model results: returns estimates (evidence: `README.md`)
- CCP solver → Model results: returns estimates (evidence: `README.md`)
- NFXP solver → Bellman iteration: solves Bellman (evidence: `README.md`)
- Bellman iteration → Shared C++ primitives: uses primitives (evidence: `src/bellman.cpp`)
- Bellman accelerators → Shared C++ primitives: uses primitives (evidence: `src/bellman_accel.cpp`)
- Bellman iteration → Emax functions: computes Emax (evidence: `src/bellman.cpp`)
- NFXP solver → Likelihood kernel: evaluates likelihood (evidence: `src/loglik.cpp`)
- MPEC solver → MPEC kernels: uses kernels (evidence: `README.md`)
- SMM and GMM → SMM simulation kernel: simulates moments (evidence: `README.md`)
- DDC interface → Latent-state HMM: supports hidden states (evidence: `README.md`)
- Latent-state HMM → HMM engine: filters sequences (evidence: `README.md`)
- DDC interface → Finite mixtures: supports heterogeneity (evidence: `README.md`)
- DDC interface → Bayesian inference: offers posterior inference (evidence: `README.md`)
- DDC interface → Simulation inference: offers SBI (evidence: `README.md`)
- DDC interface → Approximate values: supports approximate values (evidence: `README.md`)
- R analyst → Dynamic games: specifies game (evidence: `README.md`)
- Dynamic games → Equilibrium methods: estimates equilibrium (evidence: `README.md`)
- R analyst → DGP laboratory: builds synthetic data (evidence: `README.md`)
