Compatibility with CmdStanR

Supported workflows

CmdStanR 1.0

This package follows CmdStanR 1.0. Code written for a development version from before the CmdStanR 1.0 port, which predates the first release, needs these changes:

• cmdstan_model() and new CmdStanModel() compile before they return. compile() and the compile argument are gone; use compile_stan_file() to build without a model object.
• stanFile and exeFile cannot be given together. Pass exeFile alone to use an existing executable, and dir to choose where a Stan program’s executable goes. A model from exeFile alone refuses build arguments.
• Running a model whose executable is out of date throws StaleExecutableException, so the Stan file must exist whenever the model runs.
• cppOptions entries must be named, and false turns an option off. stancOptions refuse flags that have their own argument, such as warn-pedantic (use pedantic) and include-paths (use includePaths).
• CmdStan 2.37 or newer is required.
• The deprecated arguments are removed. These are sample()‘s cores, num_cores, num_chains, num_warmup, num_samples, max_depth, stepsize, save_extra_diagnostics, and validate_csv, variational()’s output_samples (use draws), and jacobian_adjustment (use jacobian). Passing one to a fitting method is an unknown-option error. The model methods’ jacobianAdjustment argument is removed too, as are read_sample_csv() and write_stan_tempfile().
• Thread options are per method: threads_per_chain for sample() and generateQuantities(), and threads for the other methods. save_latent_dynamics is a sample() and variational() option only.
• Table data with string columns is refused instead of being coded in alphabetical order. Factors still become indices.
• lpApprox() returns one flat list in draw order. mle() leaves out lp__; read it with lp(). loo() defaults to rEff: false. metadata()['num_chains'] counts the chains.
• Output files are named <model>-<YYYYmmddHHMM>-<id>-<hex>.csv, or <output_basename>-<id>.csv, with chain ids padded to two digits. Saved files are padded too.
• variableSkeleton() is removed from fits. constrainVariables() returns tuples as lists of their elements and complex values as [re, im], and unconstrainVariables() accepts that structure.
• initModelMethods() takes data, seed, verbose, quiet, and model; the hessian argument is gone. saveDataFile() copies the data file and leaves the original.

The port differs from CmdStanR 1.0 in these deliberate ways:

• Concurrent builds of one model are serialized by a lock file, .<exe>.cmdstanphp.lock. CmdStanR has no lock, so a model built at the same moment by CmdStanR and CmdStanPHP is not protected.
• The build record is .<exe>.cmdstanphp.json, in CmdStanR’s format 1. CmdStanR writes .<exe>.cmdstanr.json, so a model built by both never has one record overwritten by the other.
• Before each run, a model compares the file status (inode, size, and modification and change times) of everything the build depends on. When none changed, it skips hashing and the stanc call.
• format() and format_stan_file() return the formatted program instead of printing it.
• The progress bar is drawn on stderr, without the progressr package.
• saveObject() uses PHP serialization; there is no qs2 format.
• There is no compilation spinner. cmdstanr_spinner is accepted and has no effect.
• cmdstanDefaults() names CmdStan’s defaults as this package’s options, and reportedFeatures() returns what the executable reports about its build.

PHP adaptations

R named lists become associative PHP arrays; numeric arrays must be rectangular zero-indexed lists. Complex numbers are [re, im] pairs and tuples are lists of their elements. R sparse matrices, NA, and automatic R object conversion have no PHP equivalent. Data frames and factors can come from phibble or any object with toModelData() or toColumns(), following the conventions in the API reference. code() returns one source string. Syntax errors throw exceptions rather than returning an R diagnostic list.

R posterior objects become PHP arrays with documented shapes. All array indices are zero-based; draw metadata is one-based. draws_array retains iteration/chain axes, draws_matrix concatenates chains, draws_df is associative rows, draws_list maps variables to values per chain, and draws_rvars nests each variable’s draws by its dimensions. R tibble, posterior, bayesplot, and ggplot2 classes are not emulated. The default draws format follows CmdStanR: draws_array for MCMC and generated quantities and draws_matrix for other methods.

Summary quantiles use linear interpolation (R’s default type 7). Scaled MAD uses 1.4826. The default MCMC summary delegates R-hat and bulk ESS to the installed CmdStan stansummary and computes tail ESS in PHP. Passing measures to summary() uses a PHP port of posterior’s summarise_draws(), including rank-normalized R-hat, bulk/tail ESS, and MCSE, so it does not need CmdStan. Results are checked against the installed reference R packages, but are not guaranteed bit-for-bit identical to every version of posterior. ADVI’s mean row is stored separately. ADVI and Laplace log_p__ columns are normalized to lp__ and their approximate densities to lp_approx__, matching CmdStanR. Non-MCMC convergence statistics are NAN.

metadata() returns one merged array with CmdStanR’s keys, such as iter_sampling, max_treedepth, and stan_variable_sizes, alongside CmdStan’s raw argument names. chainMetadata() returns the per-chain arrays. invMetric() returns matrices by default and reads metric JSON when every chain has one.

Model methods and exposed functions compile a shared library against the selected CmdStan and load it with PHP FFI. FFI is enabled for the CLI by default (ffi.enable=preload); web SAPIs need ffi.enable=true or preloading. Libraries are cached beside the Stan source with a fingerprint in the file name. Model methods drop constant terms and default to jacobian: true, as in CmdStanR. Unconstrained vectors are flat lists, and constrained variables are nested zero-based arrays with matrices as lists of rows, tuples as lists of their elements, and complex values as [re, im]. Fits serialize the library path, data, and seed, and reconnect on first use; the generated-quantities RNG then restarts from its seed.

Initialization from a fit follows CmdStanR 1.0’s process_init(). MCMC draws are resampled without replacement, an optimization estimate is repeated, and ADVI, Laplace, and Pathfinder draws are resampled with Pareto-smoothed importance weights over distinct parameter vectors. Draws that multi-path Pathfinder already resampled with PSIS are not reweighted, and repeated draws are merged with their weights summed. Resampling uses PHP’s seeded Mt19937 engine, so a given seed selects different draws than CmdStanR does.

Diagnostic checks are structured messages accessible with diagnosticWarnings(), rather than PHP runtime warnings. Console output is buffered. show_progress_bar: true draws one progress bar for all chains on stderr and leaves CmdStan’s iteration lines out of the output. There is no R interrupt integration; CmdStan processes still running when PHP shuts down are terminated. show_messages controls stdout, show_exceptions controls stderr. Pathfinder’s deprecated num_threads raises E_USER_DEPRECATED and maps to threads; giving both throws. Output files persist after garbage collection, so callers manage cleanup explicitly. Saving moves output files that a run created and copies imported CSVs and the data file; existing destinations are never overwritten. Saved fit objects use PHP serialization and embed parsed results; CSVs are still needed for downstream CmdStan commands.

options() and cmdstan_option() provide CmdStanR’s global options that have a PHP meaning: default output directory, Stan file directory, forced recompilation, draws format, initialization warnings, verbose compilation, printed rows, line numbers, compression, the progress bar, saving the metric and configuration, and mc.cores. cmdstanr_no_ver_check is accepted and has no effect because this package never checks for updates. cmdstanr_spinner is accepted and has no effect.

Algorithm parameters left null use CmdStan’s defaults. PHP-level defaults include four sample chains, sequential execution unless requested, and one MPI chain. CmdStanR defaults for automatically saving metric/configuration JSON are not imposed; request save_metric or save_cmdstan_config, or set the cmdstanr_save_metric and cmdstanr_save_config options. The installer defaults to one core where CmdStanR uses two. OpenCL and MPI require external toolchains/hardware. Windows has not been validated.

Moment matching follows loo::loo_moment_match() as CmdStanMCMC$loo() calls it, with corrections to the split step and relative efficiencies. loo’s development version adopted the split corrections in stan-dev/loo#405 on 2026-10-13; the differences below are from loo 2.10.1 and earlier development builds. The split uses the exact inverse of the accumulated affine map, where loo subtracts the shift after the inverse linear map. The split relative efficiency is the minimum over both halves, where loo uses the second half twice. Relative efficiencies use exp(log_lik − max), which avoids the NA that loo returns when every likelihood value is tiny. Without the split, and with the split when only shifts are accepted, elpd_loo and Pareto k match loo and CmdStanR. Accepted scale and covariance steps are composed in their original order, including cases where scaling follows a covariance map. A singular weighted covariance uses loo’s identity-map fallback while retaining the mean shift; its reason is recorded in covariance_fallbacks. Other numerical or model failures stop the observation at its last accepted state and record a reason. Covariances are never regularized. The LOO guide describes the result.

Not implemented

The following CmdStanR features have no implementation:

• expose_functions(global = TRUE). Functions are called as methods of the returned StanFunctions object. Functions ending in _lp and overloaded functions are listed but cannot be called.
• bayesplot’s other plots, including pairs, areas, NUTS energy, and posterior predictive checks. Figures are not ggplot2 objects and cannot be extended with ggplot2 layers or themes.
• Posterior rvar arithmetic and R session hooks beyond the options listed above.
• Windows toolchain repair (check_cmdstan_toolchain(fix = TRUE)). The PHP toolchain check reports missing tools and does not install them.
• Parity with every CmdStanR version’s error and warning messages.

No unsupported option is accepted silently. This repository’s tests validate the implemented contract against CmdStanR 1.0 and the installed posterior and loo packages; they are not the upstream CmdStanR test suite. Direct conformance tests run CmdStanR and PHP with the same seeds and compare draws, descriptive summaries, MCMC sampler diagnostics, CSV metadata, model methods, exposed functions, PSIS, LOO, WAIC, and posterior summary measures.