CmdStanPy

https://github.com/stan-dev/cmdstanpy
Admin
CmdStanPy is a lightweight Python interface to CmdStan that provides access to the Stan compiler and...
Tokens:267,018
Snippets:1,840
Trust Score:9.4
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Pathfinder start processing output

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/Pathfinder.ipynb

Example output from running the Pathfinder method, showing the start of processing for chain 1.

```text
19:23:52 - cmdstanpy - INFO - Chain [1] start processing
```

--------------------------------

### install_cmdstan

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/api.rst

Downloads and installs a CmdStan release from GitHub, builds executables, and tests the compiler by building an example model.

```APIDOC
## install_cmdstan

### Description
Download and install a CmdStan release from GitHub. Downloads the release tar.gz file to temporary storage. Retries GitHub requests in order to allow for transient network outages. Builds CmdStan executables and tests the compiler by building example model `bernoulli.stan`.

### Method
Function

### Signature
`cmdstanpy.install_cmdstan(version=None, dir=None, overwrite=False, compiler=False, progress=False, verbose=False, cores=1, interactive=False)`

### Parameters
- **version** (str | None) - Optional - CmdStan version string, e.g. "2.29.2". Defaults to latest CmdStan release. If `git` is installed, a git tag or branch of stan-dev/cmdstan can be specified, e.g. "git:develop".
- **dir** (str | None) - Optional - Path to install directory. Defaults to hidden directory `$HOME/.cmdstan`. If no directory is specified and the above directory does not exist, directory `$HOME/.cmdstan` will be created and populated.
- **overwrite** (bool) - Optional - Boolean value; when `True`, will overwrite and rebuild an existing CmdStan installation. Default is `False`.
- **compiler** (bool) - Optional - Boolean value; when `True` on WINDOWS ONLY, use the C++ compiler from the `install_cxx_toolchain` command or install one if none is found.
- **progress** (bool) - Optional - Boolean value; when `True`, show a progress bar for downloading and unpacking CmdStan. Default is `False`.
- **verbose** (bool) - Optional - Boolean value; when `True`, show console output from all installation steps, i.e., download, build, and test CmdStan release. Default is `False`.
- **cores** (int) - Optional - Integer, number of cores to use in the `make` command. Default is 1 core.
- **interactive** (bool) - Optional - Boolean value; if true, ignore all other arguments to this function and run in an interactive mode, prompting the user to provide the other information manually through the standard input. This flag should only be used in interactive environments, e.g. on the command line.

### Returns
Boolean value; `True` for success.

### Return Type
bool
```

--------------------------------

### Install CmdStan with custom directory and version

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/installation.rst

Use the -d and -v options to override the default install directory and version. The example installs version 2.36.0 into my_local_cmdstan and lists the contents.

```bash
install_cmdstan -d my_local_cmdstan -v 2.36.0
ls -F my_local_cmdstan
```

--------------------------------

### Run Installation Workflow

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Orchestrates the full installation process, including directory validation, version checking, downloading, and test compilation.

```python
def run_install(args: Union[InteractiveSettings, InstallationSettings]) -> None:
    """
    Run a (potentially interactive) installation
    """
    validate_dir(args.dir)
    print('CmdStan install directory: {}'.format(args.dir))

    # these accesses just 'warm up' the interactive install
    _ = args.progress
    _ = args.verbose

    if args.compiler:
        run_compiler_install(args.dir, args.verbose, args.progress)

    if 'git:' in args.version:
        tag = args.version.replace(':', '-').replace('/', '_')
        cmdstan_version = f'cmdstan-{tag}'
    else:
        cmdstan_version = f'cmdstan-{args.version}'
    with pushd(args.dir):
        already_installed = os.path.exists(cmdstan_version) and os.path.exists(
            os.path.join(
                cmdstan_version,
                'examples',
                'bernoulli',
                'bernoulli' + EXTENSION,
            )
        )
        if not already_installed or args.overwrite:
            if is_version_available(args.version):
                print('Installing CmdStan version: {}'.format(args.version))
            else:
                raise ValueError(
                    f'Version {args.version} cannot be downloaded. '
                    'Connection to GitHub failed. '
                    'Check firewall settings or ensure this version exists.'
                )
            shutil.rmtree(cmdstan_version, ignore_errors=True)
            retrieve_version(args.version, args.progress)
            install_version(
                cmdstan_version=cmdstan_version,
                overwrite=already_installed and args.overwrite,
                verbose=args.verbose,
                progress=args.progress,
                cores=args.cores,
            )
        else:
            print('CmdStan version {} already installed'.format(args.version))

        with pushd(cmdstan_version):
            print('Test model compilation')
            compile_example(args.verbose)
```

--------------------------------

### Install CmdStan with InstallationSettings or InteractiveSettings

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/utils/cmdstan.html

Handles CmdStan installation. If interactive is True, it warns and ignores other arguments, using InteractiveSettings. Otherwise, it uses InstallationSettings with the provided options. On failure, it logs a warning and returns False. On success, it sets the CmdStan path based on the version and directory.

```python
    logger = get_logger()
    try:
        from ..install_cmdstan import (
            InstallationSettings,
            InteractiveSettings,
            run_install,
        )

        args: Union[InstallationSettings, InteractiveSettings]

        if interactive:
            if any(
                [
                    version,
                    dir,
                    overwrite,
                    compiler,
                    progress,
                    verbose,
                    cores != 1,
                ]
            ):
                logger.warning(
                    "Interactive installation requested but other arguments"
                    " were used.\n\tThese values will be ignored!"
                )
            args = InteractiveSettings()
        else:
            args = InstallationSettings(
                version=version,
                overwrite=overwrite,
                verbose=verbose,
                compiler=compiler,
                progress=progress,
                dir=dir,
                cores=cores,
            )
        run_install(args)
    # pylint: disable=broad-except
    except Exception as e:
        logger.warning('CmdStan installation failed.\n%s', str(e))
        return False

    if 'git:' in args.version:
        folder = f"cmdstan-{args.version.replace(':', '-').replace('/', '_')}"
    else:
        folder = f"cmdstan-{args.version}"
    set_cmdstan_path(os.path.join(args.dir, folder))

    return True
```

--------------------------------

### Sample with optimize inits

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/VI as Sampler Inits.html

Runs model.sample() using the optimized_inits as initial values, with iter_warmup=75 and seed=12345. The output shows the CmdStan start processing log and the model version JSON lines.

```python
mcmc_optimize_inits_fit = model.sample(
    data=data_file, inits=optimized_inits, iter_warmup=75, seed=12345
)
```

```text
19:24:13 - cmdstanpy - INFO - CmdStan start processing
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "e647ad38564a4087b35c9da4095f52e4"}

{"version_major": 2, "version_minor": 0, "model_id": "50a16ac97599485cb99f70f48f0a830c"}

{"version_major": 2, "version_minor": 0, "model_id": "bbfe6aaade494af780cfa8689a05e56a"}

{"version_major": 2, "version_minor": 0, "model_id": "89b6aa392e134ed4b12a4dbbafad4b7e"}
```

```text
19:24:13 - cmdstanpy - INFO - CmdStan done processing.
```

--------------------------------

### Run Compiler Installation

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Detects existing RTools installations or triggers the installation of RTools40 if no compatible compiler is found.

```python
def run_compiler_install(dir: str, verbose: bool, progress: bool) -> None:
    from .install_cxx_toolchain import is_installed as _is_installed_cxx
    from .install_cxx_toolchain import run_rtools_install as _main_cxx
    from .utils import cxx_toolchain_path

    compiler_found = False
    rtools40_home = os.environ.get('RTOOLS40_HOME')
    for cxx_loc in ([rtools40_home] if rtools40_home is not None else []) + [
        home_cmdstan(),
        os.path.join(os.path.abspath("/"), "RTools40"),
        os.path.join(os.path.abspath("/"), "RTools"),
        os.path.join(os.path.abspath("/"), "RTools35"),
        os.path.join(os.path.abspath("/"), "RBuildTools"),
    ]:
        for cxx_version in ['40', '35']:
            if _is_installed_cxx(cxx_loc, cxx_version):
                compiler_found = True
                break
        if compiler_found:
            break
    if not compiler_found:
        print('Installing RTools40')
        # copy argv and clear sys.argv
        _main_cxx(
            {
                'dir': dir,
                'progress': progress,
                'version': None,
                'verbose': verbose,
            }
        )
        cxx_version = '40'
    # Add toolchain to $PATH
    cxx_toolchain_path(cxx_version, dir)
```

--------------------------------

### Compile example Bernoulli model

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Compiles the example Bernoulli model using the make command. Requires the current directory to be a CmdStan installation with the makefile, Stanc compiler, and libraries. Raises CmdStanInstallError if the build fails or the binary is not generated.

```python
def compile_example(verbose: bool = False) -> None:
    """
    Compile the example model.
    The current directory must be a cmdstan installation, i.e.,
    contains the makefile, Stanc compiler, and all libraries.

    :param verbose: Boolean value; when ``True``, show output from make command.
    """
    path = Path('examples', 'bernoulli', 'bernoulli').with_suffix(EXTENSION)
    if path.is_file():
        path.unlink()

    cmd = [MAKE, path.as_posix()]
    try:
        if verbose:
            do_command(cmd)
        else:
            do_command(cmd, fd_out=None)
    except RuntimeError as e:
        # pylint: disable=raise-missing-from
        raise CmdStanInstallError(f'Command "{" ".join(cmd)}" failed:\n{e}')

    if not path.is_file():
        raise CmdStanInstallError("Failed to generate example binary")
```

--------------------------------

### Install CmdStan with custom directory and version

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Overrides the default installation directory and version using -d and -v arguments. The ls command verifies the installation in the specified directory.

```bash
install_cmdstan -d my_local_cmdstan -v 2.33.0
ls -F my_local_cmdstan
```

--------------------------------

### Sample with laplace inits

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/VI as Sampler Inits.html

Runs model.sample() using the laplace_inits as initial values, with iter_warmup=75 and seed=12345. The output shows the CmdStan start processing log and the model version JSON lines.

```python
mcmc_laplace_inits_fit = model.sample(
    data=data_file, inits=laplace_inits, iter_warmup=75, seed=12345
)
```

```text
19:24:12 - cmdstanpy - INFO - CmdStan start processing
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "670a99e28233409887b2a8746295abd8"}

{"version_major": 2, "version_minor": 0, "model_id": "e87537e3a0bb4f2aba42f3a476225c4b"}

{"version_major": 2, "version_minor": 0, "model_id": "ffc6f05bb3a648748ad358a2d2ef985d"}

{"version_major": 2, "version_minor": 0, "model_id": "e786a1634b4140af870612109e2fba5a"}
```

```text
19:24:13 - cmdstanpy - INFO - CmdStan done processing.
```

--------------------------------

### Import CmdStanPy and instantiate Bernoulli model

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/Run Generated Quantities.ipynb.txt

Sets up the environment by importing CmdStanPy classes and the os module, then instantiates and compiles the Bernoulli model from the CmdStan examples directory. Prints the model code to verify the model definition.

```python
import os
from cmdstanpy import cmdstan_path, CmdStanModel, CmdStanMCMC, CmdStanGQ

bernoulli_dir = os.path.join(cmdstan_path(), 'examples', 'bernoulli')
stan_file = os.path.join(bernoulli_dir, 'bernoulli.stan')
data_file = os.path.join(bernoulli_dir, 'bernoulli.data.json')

# instantiate, compile bernoulli model
model = CmdStanModel(stan_file=stan_file)
print(model.code())
```

--------------------------------

### Install CmdStan from command line on Windows

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs CmdStan from the command line on Windows, including the C++ toolchain with --compiler. The dir command verifies the installation in the %HOME%/.cmdstan directory.

```bash
install_cmdstan --compiler
dir "%HOME%/.cmdstan"
```

--------------------------------

### Install CmdStan from command line on Linux/macOS

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs CmdStan from the command line on Linux or macOS. The ls command verifies the installation in the default ~/.cmdstan directory.

```bash
install_cmdstan
ls -F ~/.cmdstan
```

--------------------------------

### Install CmdStanPy with optional packages

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs CmdStanPy along with all optional packages, such as xarray.

```bash
pip install --upgrade cmdstanpy[all]
```

--------------------------------

### install_cmdstan

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/api.rst.txt

Function to install CmdStan.

```APIDOC
## install_cmdstan

### Description
Installs CmdStan if not already installed.
```

--------------------------------

### Define install_version function

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Starts the definition of the install_version function, which builds a specified CmdStan version by running Make on downloaded release source files. Assumes the current working directory is the parent of the release directory.

```python
def install_version(
    cmdstan_version: str,
    overwrite: bool = False,
    verbose: bool = False,
    progress: bool = True,
    cores: int = 1,
) -> None:
    """
    Build specified CmdStan version by spawning subprocesses to
    run the Make utility on the downloaded CmdStan release src files.
    Assumes that current working directory is parent of release dir.
    """
```

--------------------------------

### install_cmdstan CLI argument parsing and main entry point

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

The first function defines the command-line interface for the install_cmdstan script, parsing arguments such as --interactive, --version, --dir, --overwrite, --verbose, --progress, --cores, and (on Windows) --compiler. The second function is the entry point that calls parse_cmdline_args and then runs the installation with either InteractiveSettings or InstallationSettings depending on the interactive flag. The final block executes __main__ when the script is run directly.

```python
def parse_cmdline_args() -> dict[str, Any]:
    parser = argparse.ArgumentParser("install_cmdstan")
    parser.add_argument(
        '--interactive',
        '-i',
        action='store_true',
        help="Ignore other arguments and run the installation in "
        + "interactive mode",
    )
    parser.add_argument(
        '--version',
        '-v',
        help="version, defaults to latest release version. "
        "If git is installed, you can also specify a git tag or branch, "
        "e.g. git:develop",
    )
    parser.add_argument(
        '--dir', '-d', help="install directory, defaults to '$HOME/.cmdstan"
    )
    parser.add_argument(
        '--overwrite',
        action='store_true',
        help="flag, when specified re-installs existing version",
    )
    parser.add_argument(
        '--verbose',
        action='store_true',
        help="flag, when specified prints output from CmdStan build process",
    )
    parser.add_argument(
        '--progress',
        action='store_true',
        help="flag, when specified show progress bar for CmdStan download",
    )
    parser.add_argument(
        "--cores",
        default=1,
        type=int,
        help="number of cores to use while building",
    )
    if is_windows():
        # use compiler installed with install_cxx_toolchain
        # Install a new compiler if compiler not found
        # Search order is RTools40, RTools35
        parser.add_argument(
            '--compiler',
            '-c',
            dest='compiler',
            action='store_true',
            help="flag, add C++ compiler to path (Windows only)",
        )
    return vars(parser.parse_args(sys.argv[1:]))
```

```python
def __main__() -> None:
    args = parse_cmdline_args()
    if args.get('interactive', False):
        run_install(InteractiveSettings())
    else:
        run_install(InstallationSettings(**args))


if __name__ == '__main__':
    __main__()
```

--------------------------------

### Sampler progress hook setup with _wrap_sampler_progress_hook

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/model.html

This static method initializes tqdm progress bars for CmdStan sampler output. It parses iteration messages to update the progress state for single or multi-chain processes.

```python
    @staticmethod
    @progbar.wrap_callback
    def _wrap_sampler_progress_hook(
        chain_ids: list[int],
        total: int,
    ) -> Optional[Callable[[str, int], None]]:
        """
        Sets up tqdm callback for CmdStan sampler console msgs.
        CmdStan progress messages start with "Iteration", for single chain
        process, "Chain [id] Iteration" for multi-chain processing.
        For the latter, manage array of pbars, update accordingly.
        """
        chain_pat = re.compile(r'(Chain \[(\d+)\] )?Iteration:\s+(\d+)')
        pbars: dict[int, tqdm] = {
            chain_id: tqdm(
                total=total,
                desc=f'chain {chain_id}',
                postfix='(Warmup)',
                colour='yellow',
            )
            for chain_id in chain_ids
        }

        def progress_hook(line: str, idx: int) -> None:
            if line == "Done":
                for pbar in pbars.values():
                    pbar.set_postfix_str('(Sampling completed)')
                    pbar.update(total - pbar.n)
                    pbar.close()
            elif (match := chain_pat.match(line)) is not None:
                idx = int(match.group(2) or chain_ids[idx])
                current_iter = int(match.group(3))
```

--------------------------------

### Import required modules for Pathfinder example

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/users-guide/examples/Pathfinder.ipynb

Imports os and CmdStanModel, cmdstan_path from cmdstanpy. Required to set up the model and data paths.

```python
import os
from cmdstanpy import CmdStanModel, cmdstan_path
```

--------------------------------

### CmdStanPathfinder.column_names

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/api.html

Property to get the names of all outputs from the sampler.

```APIDOC
## CmdStanPathfinder.column_names (property)

### Description
Names of all outputs from the sampler, comprising sampler parameters and all components of all model parameters, transformed parameters, and quantities of interest. Corresponds to Stan CSV file header row, with names munged to array notation, e.g. beta[1] not beta.1.

### Method
column_names (property)

### Returns
- **tuple[str, ...]** - Tuple of column names.

### Example
```python
names = fit.column_names
```
```

--------------------------------

### InteractiveSettings class with cached properties

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Provides installation settings by prompting the user on first access. Each property asks for input with a default value and uses yes_no for boolean prompts. The compiler property only prompts on Windows.

```python
class InteractiveSettings:
    """
    Installation settings provided on-demand in an interactive format.

    This provides the same set of properties as the ``InstallationSettings``
    object, but rather than them being fixed by the constructor the user is
    asked for input whenever they are accessed for the first time.
    """

    @cached_property
    def version(self) -> str:
        latest = latest_version()
        print("Which version would you like to install?")
        print(f"Default: {latest}")
        answer = input("Type version or hit enter to continue: ")
        return answer if answer else latest

    @cached_property
    def dir(self) -> str:
        directory = home_cmdstan()
        print("Where would you like to install CmdStan?")
        print(f"Default: {directory}")
        answer = input("Type full path or hit enter to continue: ")
        return os.path.expanduser(answer) if answer else directory

    @cached_property
    def progress(self) -> bool:
        print("Show installation progress bars?")
        print("Default: y")
        answer = input("[y/n]: ")
        return yes_no(answer, True)

    @cached_property
    def verbose(self) -> bool:
        print("Show verbose output of the installation process?")
        print("Default: n")
        answer = input("[y/n]: ")
        return yes_no(answer, False)

    @cached_property
    def overwrite(self) -> bool:
        print("Overwrite existing CmdStan installation?")
        print("Default: n")
        answer = input("[y/n]: ")
        return yes_no(answer, False)

    @cached_property
    def compiler(self) -> bool:
        if not is_windows():
            return False
        print("Would you like to install the RTools40 C++ toolchain?")
        print("A C++ toolchain is required for CmdStan.")
        print(
            "If you are not sure if you need the toolchain or not, "
            "the most likely case is you do need it, and should answer 'y'."
        )
        print("Default: n")
        answer = input("[y/n]: ")
        return yes_no(answer, False)

    @cached_property
    def cores(self) -> int:
        max_cpus = os.cpu_count() or 1
        print(
            "How many CPU cores would you like to use for installing "
            "and compiling CmdStan?"
        )
        print(f"Default: 1, Max: {max_cpus}")
        answer = input("Enter a number or hit enter to continue: ")
        try:
            return min(max_cpus, max(int(answer), 1))
        except ValueError:
            return 1
```

--------------------------------

### Run Pathfinder on Bernoulli model

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/Pathfinder.ipynb.txt

Sets up the file paths for the Bernoulli example, compiles the model, and runs the Pathfinder algorithm. The `pathfinder` method returns a `CmdStanPathfinder` object.

```python
bernoulli_dir = os.path.join(cmdstan_path(), 'examples', 'bernoulli')
stan_file = os.path.join(bernoulli_dir, 'bernoulli.stan')
data_file = os.path.join(bernoulli_dir, 'bernoulli.data.json')
# instantiate, compile bernoulli model
model = CmdStanModel(stan_file=stan_file)
# run CmdStan's pathfinder method, returns object `CmdStanPathfinder`
pathfinder = model.pathfinder(data=data_file)
```

--------------------------------

### Pathfinder object and metadata output

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/Pathfinder.ipynb

Example output from printing the CmdStanPathfinder object and its metadata, showing the CSV file paths and configuration details.

```text
CmdStanPathfinder: model=bernoulli['method=pathfinder']
 csv_files:
	/tmp/tmp4bo8x5vs/bernoullibfo28m96/bernoulli-20251020192352.csv
 output_files:
	/tmp/tmp4bo8x5vs/bernoullibfo28m96/bernoulli-20251020192352_0-stdout.txt
Metadata:
{'stan_version_major': 2, 'stan_version_minor': 37, 'stan_version_patch': 0, 'model': 'bernoulli_model', 'start_datetime': '2025-10-20 19:23:52 UTC', 'method': 'pathfinder', 'init_alpha': 0.001, 'tol_obj': 1e-12, 'tol_rel_obj': 10000, 'tol_grad': 1e-08, 'tol_rel_grad': 10000000.0, 'tol_param': 1e-08, 'history_size': 5, 'num_psis_draws': 1000, 'num_paths': 4, 'save_single_paths': 0, 'psis_resample': 1, 'calculate_lp': 1, 'max_lbfgs_iters': 1000, 'num_draws': 1000, 'num_elbo_draws': 25, 'id': 1, 'data_file': '/home/runner/.cmdstan/cmdstan-2.37.0/examples/bernoulli/bernoulli.data.json', 'init': 2, 'seed': 95159, 'diagnostic_file': '', 'refresh': 100, 'sig_figs': 8, 'profile_file': 'profile.csv', 'save_cmdstan_config': 0, 'num_threads': 1, 'stanc_version': 'stanc3 v2.37.0', 'raw_header': 'lp_approx__,lp__,path__,theta', 'column_names': ('lp_approx__', 'lp__', 'path__', 'theta')}
```

--------------------------------

### Instantiate and compile bernoulli.stan with CmdStanPy

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/Run Generated Quantities.ipynb

Instantiates and compiles the CmdStan example model bernoulli.stan, then prints its Stan code. The output shows the model's data, parameters, and model blocks.

```python
import os
from cmdstanpy import cmdstan_path, CmdStanModel, CmdStanMCMC, CmdStanGQ

bernoulli_dir = os.path.join(cmdstan_path(), 'examples', 'bernoulli')
stan_file = os.path.join(bernoulli_dir, 'bernoulli.stan')
data_file = os.path.join(bernoulli_dir, 'bernoulli.data.json')

# instantiate, compile bernoulli model
model = CmdStanModel(stan_file=stan_file)
print(model.code())
```

```stan
data {
  int<lower=0> N;
  array[N] int<lower=0, upper=1> y;
}
parameters {
  real<lower=0, upper=1> theta;
}
model {
  theta ~ beta(1, 1); // uniform prior on interval 0,1
  y ~ bernoulli(theta);
}
```

--------------------------------

### cmdstan_path

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/api.rst.txt

Function to get the CmdStan installation path.

```APIDOC
## cmdstan_path

### Description
Returns the path to the CmdStan installation.
```

--------------------------------

### Rebuild CmdStan installation

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/install_cmdstan.html

Rebuilds an existing CmdStan installation by cleaning, building, and compiling the example model. Assumes CmdStan is already installed, not necessarily via CmdStanPy. Raises CmdStanInstallError if the rebuild fails.

```python
def rebuild_cmdstan(
    verbose: bool = False, progress: bool = True, cores: int = 1
) -> None:
    """
    Rebuilds the existing CmdStan installation.
    This assumes CmdStan has already been installed,
    though it need not be installed via CmdStanPy for
    this function to work.

    :param verbose: Boolean value; when ``True``, show output from make command.
        Default is ``False``.
    :param progress: Boolean value; when ``True`` display progress progress bar.
        Default is ``True``.
    :param cores: Integer, number of cores to use in the ``make`` command.
        Default is 1 core.
    """
    try:
        with pushd(cmdstan_path()):
            clean_all(verbose)
            build(verbose, progress, cores)
            compile_example(verbose)
    except ValueError as e:
        raise CmdStanInstallError(
            "Failed to rebuild CmdStan. Are you sure it is installed?"
        ) from e
```

--------------------------------

### Call pathfinder.create_inits() with default arguments

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/Pathfinder.ipynb.txt

Creates initial values using default settings (seed and chains=4). Prints the resulting inits.

```python
inits = pathfinder.create_inits()
print(inits)
```

--------------------------------

### Sample with Optimization Initializations

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/users-guide/examples/VI as Sampler Inits.ipynb

Uses the optimize method to generate initializations. Note that this initializes all chains at the same point, which is typically not ideal.

```python
optimized_inits = model.optimize(data=data_file, seed=123).create_inits()
```

```python
mcmc_optimize_inits_fit = model.sample(
    data=data_file, inits=optimized_inits, iter_warmup=75, seed=12345
)
```

```python
print(mcmc_optimize_inits_fit.diagnose())
```

--------------------------------

### Read the bernoulli.stan model file

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/cmdstanpy_tutorial.ipynb

Constructs the path to the bernoulli.stan file in the CmdStan examples directory and prints its contents. The cmdstan_path() function returns the path to the CmdStan installation.

```python
bernoulli_dir = os.path.join(cmdstan_path(), 'examples', 'bernoulli')
stan_file = os.path.join(bernoulli_dir, 'bernoulli.stan')
with open(stan_file, 'r') as f:
    print(f.read())
```

--------------------------------

### Sample with Default Random Initializations

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/users-guide/examples/VI as Sampler Inits.ipynb

Demonstrates that using default random initializations with insufficient warmup iterations leads to poor estimation of model parameters.

```python
mcmc_random_inits_fit = model.sample(data=data_file, iter_warmup=75, seed=12345)
```

```python
mcmc_random_inits_fit.summary()
```

```python
print(mcmc_random_inits_fit.diagnose())
```

--------------------------------

### cmdstanpy.rebuild_cmdstan(verbose=False, progress=True, cores=1)

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/api.rst

Rebuilds the existing CmdStan installation. Assumes CmdStan is already installed, and can work even if not installed via CmdStanPy.

```APIDOC
## cmdstanpy.rebuild_cmdstan(verbose=False, progress=True, cores=1)

### Description
Rebuilds the existing CmdStan installation. This assumes CmdStan has already been installed, though it need not be installed via CmdStanPy for this function to work.

### Parameters
- **verbose** (bool) - Optional - Boolean value; when `True`, show output from make command. Default is `False`.
- **progress** (bool) - Optional - Boolean value; when `True` display progress progress bar. Default is `True`.
- **cores** (int) - Optional - Integer, number of cores to use in the `make` command. Default is 1 core.

### Return Type
None
```

--------------------------------

### Sample with output_dir and list files

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/outputs.rst.txt

Runs sampling with a specified output directory and lists the generated files. If omitted, output files go to a temporary directory deleted at session end.

```python
fit = model.sample(data=data_file, output_dir="./outputs/")

!ls outputs/
```

--------------------------------

### Install CmdStanPy from PyPI

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs or upgrades CmdStanPy from PyPI using pip.

```bash
pip install --upgrade cmdstanpy
```

--------------------------------

### Create inits from Laplace sample

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/VI as Sampler Inits.ipynb.txt

Generates initial values using the Laplace approximation method.

```python
laplace_inits = model.laplace_sample(data=data_file, seed=123).create_inits()
```

--------------------------------

### Install CmdStan from Python

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs CmdStan from Python. The default location is a hidden .cmdstan directory in the user's home directory. The compiler=True argument is only valid on Windows and installs the C++ toolchain.

```python
import cmdstanpy
cmdstanpy.install_cmdstan()
cmdstanpy.install_cmdstan(compiler=True)  # only valid on Windows
```

--------------------------------

### CmdStanLaplace.create_inits

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/stanfit/laplace.html

Documentation for the create_inits method of the CmdStanLaplace class.

```APIDOC
## CmdStanLaplace.create_inits

### Description
Creates initial values for the model parameters by randomly selecting draws from the Laplace approximation. Returns a dictionary or list of dictionaries in the format expected for the `inits` argument of `CmdStanModel.sample`.

### Method
create_inits

### Signature
`create_inits(seed: Optional[int] = None, chains: int = 4) -> Union[list[dict[str, np.ndarray]], dict[str, np.ndarray]]`

### Parameters
- **seed** (Optional[int]) - Optional - Used for random selection, defaults to None.
- **chains** (int) - Optional - Number of initial values to return, defaults to 4.

### Returns
- If `chains` is 1, a dictionary is returned; otherwise a list of dictionaries is returned, in the format expected for the `inits` argument of `CmdStanModel.sample`.
```

--------------------------------

### Install CmdStanPy into existing conda environment

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs CmdStanPy and its dependencies into the currently active conda environment.

```bash
conda install -c conda-forge cmdstanpy
```

--------------------------------

### Install CmdStanPy from GitHub develop branch

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Installs the current develop branch of CmdStanPy directly from GitHub using pip.

```bash
pip install -e git+https://github.com/stan-dev/cmdstanpy@develop#egg=cmdstanpy
```

--------------------------------

### Sample with ADVI inits via model.sample()

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/VI as Sampler Inits.ipynb.txt

Runs MCMC sampling using ADVI-generated inits. Pass the `vb_inits` object to the `inits` kwarg; here only 75 warmup iterations are used with a fixed seed.

```python
mcmc_vb_inits_fit = model.sample(
    data=data_file, inits=vb_inits, iter_warmup=75, seed=12345
)
```

--------------------------------

### Sample with Pathfinder inits via model.sample()

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/VI as Sampler Inits.ipynb.txt

Runs MCMC sampling using Pathfinder-generated inits. Pass the `pathfinder_inits` object to the `inits` kwarg; here only 75 warmup iterations are used with a fixed seed.

```python
mcmc_pathfinder_inits_fit = model.sample(
    data=data_file, inits=pathfinder_inits, iter_warmup=75, seed=12345
)
```

--------------------------------

### Get metric type and inverse metric

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/cmdstanpy_tutorial.ipynb

Accesses metric_type and inv_metric properties to get the metric type and the metric used by the sampler for each chain.

```python
fit.metric_type,  fit.inv_metric
```

--------------------------------

### Create per-chain initializations from Pathfinder fit

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/VI as Sampler Inits.html

Uses .create_inits() to generate initial values for four chains (default) and prints each chain's init dictionary. The output shows the generated inits for beta and sigma.

```python
pathfinder_inits = pathfinder_fit.create_inits()
for chain_init in pathfinder_inits:
    print(chain_init)
```

```text
{'beta': array([1.0013605 , 0.99982007, 1.0013418 , 1.0015203 , 1.0024493 ]), 'sigma': array(0.91712333)}
{'beta': array([0.99892799, 1.000094  , 1.0015255 , 0.99978958, 1.0009933 ]), 'sigma': array(0.90733134)}
{'beta': array([0.99944904, 1.0001847 , 0.99985551, 1.002342  , 1.0015932 ]), 'sigma': array(0.85289529)}
{'beta': array([1.000951 , 1.0008332, 1.0017069, 1.0014231, 1.0048865]), 'sigma': array(1.0797625)}
```

--------------------------------

### Basic CmdStanPy workflow: compile, sample, and summarize

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/README.md

Shows the basic workflow: locate the Stan program and data files, instantiate a CmdStanModel (which compiles the Stan program by default), sample from the posterior with 4 chains, and summarize the results using fit.summary(), which wraps CmdStan's bin/stansummary.

```python
import os
from cmdstanpy import cmdstan_path, CmdStanModel

# specify locations of Stan program file and data
stan_file = os.path.join(cmdstan_path(), 'examples', 'bernoulli', 'bernoulli.stan')
data_file = os.path.join(cmdstan_path(), 'examples', 'bernoulli', 'bernoulli.data.json')

# instantiate a model; compiles the Stan program by default
model = CmdStanModel(stan_file=stan_file)

# obtain a posterior sample from the model conditioned on the data
fit = model.sample(chains=4, data=data_file)

# summarize the results (wraps CmdStan `bin/stansummary`):
fit.summary()
```

--------------------------------

### Set CmdStan path with set_cmdstan_path

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Sets and retrieves the CmdStan installation path when CMDSTAN environment variable is not set. Use this after manually installing CmdStan from a GitHub release or clone.

```python
from cmdstanpy import cmdstan_path, set_cmdstan_path

set_cmdstan_path(os.path.join('path','to','cmdstan'))
cmdstan_path()
```

--------------------------------

### Sample with Laplace Initializations

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/users-guide/examples/VI as Sampler Inits.ipynb

Constructs initializations for the MCMC sampler using the laplace method.

```python
laplace_inits = model.laplace_sample(data=data_file, seed=123).create_inits()
```

```python
mcmc_laplace_inits_fit = model.sample(
    data=data_file, inits=laplace_inits, iter_warmup=75, seed=12345
)
```

```python
print(mcmc_laplace_inits_fit.diagnose())
```

--------------------------------

### cmdstan_version

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/api.rst.txt

Function to get the CmdStan version.

```APIDOC
## cmdstan_version

### Description
Returns the version of the installed CmdStan.
```

--------------------------------

### Sample with Pathfinder Initializations

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/users-guide/examples/VI as Sampler Inits.ipynb

Uses the pathfinder method to generate initializations for the MCMC sampler, allowing for successful diagnostics with fewer warmup iterations.

```python
mcmc_pathfinder_inits_fit = model.sample(
    data=data_file, inits=pathfinder_inits, iter_warmup=75, seed=12345
)
```

```python
print(mcmc_pathfinder_inits_fit.diagnose())
```

```python
mcmc_pathfinder_inits_fit.summary()
```

--------------------------------

### get optimized_params_pd

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/stanfit/mle.html

Returns all final estimates from the optimizer as a pandas.DataFrame.

```APIDOC
## optimized_params_pd

### Description
Returns all final estimates from the optimizer as a pandas.DataFrame which contains all optimizer outputs, i.e., the value for `lp__` as well as all Stan program variables.

### Method
Property (getter)

### Return Value
- `pandas.DataFrame` - All final estimates from the optimizer.

### Behavior
- If `runset._check_retcodes()` is `False`, a warning is logged: 'Invalid estimate, optimization failed to converge.'

```

--------------------------------

### Call pathfinder.create_inits(chains=3)

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/Pathfinder.ipynb.txt

Creates initial values for 3 chains. The chains argument must match the number of sampler chains to run.

```python
inits = pathfinder.create_inits(chains=3)
print(inits)
```

--------------------------------

### Create Pathfinder inits with create_inits()

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/VI as Sampler Inits.ipynb.txt

Creates initial parameter values for MCMC sampling from a Pathfinder fit. The default creates inits for four chains, matching the sampling defaults; modify the `chains` keyword argument to request more or fewer.

```python
pathfinder_inits = pathfinder_fit.create_inits()
for chain_init in pathfinder_inits:
    print(chain_init)
```

--------------------------------

### get optimized_params_np

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/stanfit/mle.html

Returns all final estimates from the optimizer as a numpy.ndarray.

```APIDOC
## optimized_params_np

### Description
Returns all final estimates from the optimizer as a numpy.ndarray which contains all optimizer outputs, i.e., the value for `lp__` as well as all Stan program variables.

### Method
Property (getter)

### Return Value
- `numpy.ndarray` - All final estimates from the optimizer.

### Behavior
- If `converged` is `False`, a warning is logged: 'Invalid estimate, optimization failed to converge.'

```

--------------------------------

### Sampling with random initializations and 75 warmup iterations

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/VI as Sampler Inits.html

Fits the model using default random parameter initializations with only 75 warmup iterations. The output shows CmdStan processing messages and warnings about divergent transitions and potential convergence failure.

```python
mcmc_random_inits_fit = model.sample(data=data_file, iter_warmup=75, seed=12345)
```

```text
19:24:12 - cmdstanpy - INFO - CmdStan start processing
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "e9b72935704e4773a79c8ce6abc563e2"}
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "5742e1e2039b4f02853d270575a23803"}
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "d25e87bfaaad44138f1462a84f3b2623"}
```

```text
{"version_major": 2, "version_minor": 0, "model_id": "4cd604cd026145f8a9ef07c237107fba"}
```

```text
19:24:12 - cmdstanpy - INFO - CmdStan done processing.
19:24:12 - cmdstanpy - WARNING - Some chains may have failed to converge.
        Chain 1 had 10 divergent transitions (1.0%)
        Chain 3 had 180 divergent transitions (18.0%)
        Chain 4 had 94 divergent transitions (9.4%)
        Use the "diagnose()" method on the CmdStanMCMC object to see further information.
```

--------------------------------

### Activate conda environment

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/installation.rst.txt

Activates the conda environment named 'stan' after installation.

```bash
conda activate stan
```

--------------------------------

### Enable Visual Progress Bar

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/MCMC Sampling.ipynb

Run the sampler with show_progress=True to visualize progress during long-running fits.

```python
fit = model.sample(data='bernoulli.data.json', iter_warmup=100000, iter_sampling=100000, show_progress=True)
```

```text
Output:
16:17:57 - cmdstanpy - INFO - CmdStan start processing
```

```text
Result:
chain 1 |          | 00:00 Status
```

```text
Result:
chain 2 |          | 00:00 Status
```

```text
Result:
chain 3 |          | 00:00 Status
```

```text
Result:
chain 4 |          | 00:00 Status
```

```text
Output:
16:17:59 - cmdstanpy - INFO - CmdStan done processing.
```

--------------------------------

### Create inits from optimization

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/VI as Sampler Inits.ipynb.txt

Generates initial values using the optimize method. Note that this initializes all chains at the same point, which is not typically ideal.

```python
optimized_inits = model.optimize(data=data_file, seed=123).create_inits()
```

--------------------------------

### CmdStanPy Processing Logs

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/Run Generated Quantities.html

Logs showing the start and completion of processing chains.

```text
19:24:00 - cmdstanpy - INFO - Chain [1] start processing
19:24:00 - cmdstanpy - INFO - Chain [2] start processing
19:24:00 - cmdstanpy - INFO - Chain [1] done processing
19:24:00 - cmdstanpy - INFO - Chain [2] done processing
19:24:00 - cmdstanpy - INFO - Chain [3] start processing
19:24:00 - cmdstanpy - INFO - Chain [4] start processing
19:24:00 - cmdstanpy - INFO - Chain [3] done processing
19:24:00 - cmdstanpy - INFO - Chain [4] done processing
```

--------------------------------

### Get Pathfinder column names

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_sources/users-guide/examples/Pathfinder.ipynb.txt

Returns the column names of the Pathfinder sample.

```python
pathfinder.column_names
```

--------------------------------

### get optimized_params_dict

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/stanfit/mle.html

Returns all estimates from the optimizer, including lp__, as a Python Dict.

```APIDOC
## optimized_params_dict

### Description
Returns all estimates from the optimizer, including `lp__`, as a Python Dict. Only returns estimate from final iteration.

### Method
Property (getter)

### Return Value
- `Dict[str, numpy.float64]` - All estimates from the optimizer.

### Behavior
- If `runset._check_retcodes()` is `False`, a warning is logged: 'Invalid estimate, optimization failed to converge.'

```

--------------------------------

### show_versions

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docsrc/api.rst

Prints out system and dependency information for debugging.

```APIDOC
## show_versions

### Description
Prints out system and dependency information for debugging.

### Method
Function

### Signature
`cmdstanpy.show_versions(output=True)`

### Parameters
- **output** (bool) - Optional - Whether to print the information.

### Return Type
str
```

--------------------------------

### Jacobian Version Check

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/_modules/cmdstanpy/model.html

Validates that the Jacobian adjustment is supported by the installed CmdStan version.

```python
if jacobian and cmdstan_version_before(2, 32, self.exe_info()):
            raise ValueError(
                "Jacobian adjustment for optimization is only supported "
                "in CmdStan 2.32 and above."
            )
```

--------------------------------

### CmdStan Processing Log Output

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/examples/VI as Sampler Inits.html

Log output showing the start of CmdStan processing.

```text
19:24:13 - cmdstanpy - INFO - CmdStan start processing
```
Tokens:
Raw