CmdStanModel

CmdStanModel is a Python class in the CmdStanPy library that represents a Stan model compiled into a CmdStan executable. It provides a wrapper around the CmdStan binary, enabling users to compile Stan code and run sampling, optimization, and variational inference workflows from Python.

Instantiation can be performed with a Stan file path via stan_file or with a string of Stan code via stan_code. The constructor may accept optional model_name and cpp_options. On creation, CmdStanModel triggers the compilation of the model using CmdStan, guided by the provided C++ options. A working CmdStan installation and a compatible C++ toolchain are required.

Once compiled, the model object exposes methods such as sample, optimize, variational, and generate_quantities. The sample method executes one or more Markov chains, with parameters such as chains, parallel_chains, iter_warmup, iter_sampling, and seed. The method returns a results object containing draws, diagnostics, and summaries. Data can be supplied as a Python dict, a JSON file, or a data file.

Outputs are written to a specified output_dir, including CSV files for draws and a JSON file with metadata and diagnostics. CmdStanModel can cache the compiled executable to avoid repeated compilations across runs, depending on configuration.

In the CmdStanPy ecosystem, CmdStanModel integrates with CmdStan to provide a Pythonic interface to Stan models, complementing other interfaces in the ecosystem. It is designed to be language- and workflow-neutral, focusing on reproducibility and interoperability with CmdStan’s tooling. See also CmdStan, CmdStanPy, Stan.