### Compile Example Model

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

Compiles the example 'bernoulli' model. Assumes the current directory is a CmdStan installation. Optionally shows verbose output from the make command.

```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")
```

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

### Run Compiler Installation

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

Initiates the installation of the C++ toolchain for CmdStan, checking for existing installations and RTools on Windows. This function is part of the compiler setup process.

```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"),
```

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

### Run CmdStan installation

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

Executes the installation process for CmdStan, handling version checks, directory setup, and model 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 from Command Line (Windows)

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

Execute the installation script with the compiler flag and verify the installation directory on Windows.

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

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

### Install CmdStan from Command Line (Linux/MacOS)

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

Execute the installation script and verify the installation directory on Unix-like systems.

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

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

### Install CmdStan with Custom Options

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

Use flags to specify a custom installation directory and version.

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

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

### Execute main installation entry point

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

Initializes the installation process by parsing arguments and selecting between interactive or automated modes.

```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__()
```

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

### Install CmdStanPy from GitHub

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

Command to install the development branch directly from the repository.

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

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

### install_cmdstan

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

Downloads and installs a specific CmdStan release from GitHub, builds the executables, and verifies the installation.

```APIDOC
## install_cmdstan

### Description
Downloads and installs a CmdStan release from GitHub. It handles downloading the tar.gz file, building the executables, and testing the compiler using the bernoulli.stan example model.

### Parameters
#### Arguments
- **version** (str) - Optional - CmdStan version string (e.g., "2.29.2") or git reference (e.g., "git:develop"). Defaults to latest release.
- **dir** (str) - Optional - Path to install directory. Defaults to $HOME/.cmdstan.
- **overwrite** (bool) - Optional - If True, overwrites and rebuilds an existing installation. Default is False.
- **compiler** (bool) - Optional - If True (Windows only), uses or installs the C++ toolchain. Default is False.
- **progress** (bool) - Optional - If True, displays a progress bar. Default is False.
- **verbose** (bool) - Optional - If True, shows console output for installation steps. Default is False.
- **cores** (int) - Optional - Number of cores to use for the make command. Default is 1.
- **interactive** (bool) - Optional - If True, ignores other arguments and runs in interactive mode via stdin.

### Response
- **return** (bool) - Returns True if the installation was successful.
```

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

### Install CmdStan from Python

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

Use `cmdstanpy.install_cmdstan()` to download and build CmdStan. On Windows, set `compiler=True` to also install the C++ toolchain.

```python
import cmdstanpy
cmdstanpy.install_cmdstan()
```

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

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

### Install Xcode Command Line Tools

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

Run this command on macOS to install the necessary build tools.

```bash
xcode-select --install
```

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

### Install CmdStan with Custom Path and Version

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

Override default installation directory and CmdStan version using `-d` and `-v` arguments. Verify the custom installation.

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

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

### Manage CmdStan Installation

Source: https://context7.com/stan-dev/cmdstanpy/llms.txt

Functions for installing, configuring, and maintaining the CmdStan backend.

```python
from cmdstanpy import (
    install_cmdstan,
    cmdstan_path,
    set_cmdstan_path,
    cmdstan_version,
    rebuild_cmdstan,
    show_versions
)

# Install CmdStan (default: latest version to ~/.cmdstan)
install_cmdstan()

# Install specific version
install_cmdstan(version='2.34.0')

# Install with custom options
install_cmdstan(
    version='2.34.0',
    dir='/path/to/install',
    overwrite=True,
    cores=4,
    verbose=True,
    progress=True,
    compiler=True  # Windows only: install C++ toolchain
)

# Interactive installation
install_cmdstan(interactive=True)

# Get current CmdStan path
print(cmdstan_path())  # e.g., '/home/user/.cmdstan/cmdstan-2.34.0'

# Set custom CmdStan path
set_cmdstan_path('/custom/path/to/cmdstan')

# Get CmdStan version
version = cmdstan_version()  # Returns tuple, e.g., (2, 34)

# Rebuild existing installation
rebuild_cmdstan(verbose=True, cores=4)

# Show all version information
show_versions()  # Prints Python, CmdStanPy, CmdStan, and dependency versions
```

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

### Interactive Installation Settings

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

Provides an interactive way to configure CmdStan installation settings. Prompts the user for input when properties are accessed for the first time.

```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
```

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

### Setup Sampler Progress Hook

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

Configures a tqdm callback to monitor CmdStan sampler progress messages.

```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,
```

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

### Install CmdStan via Command Line

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

Commands to install CmdStan and verify the installation directory on different operating systems.

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

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

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

### install_cmdstan

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

Downloads and installs a specific CmdStan release from GitHub, including building executables.

```APIDOC
## install_cmdstan

### Description
Download and install a CmdStan release from GitHub. Builds CmdStan executables and tests the compiler.

### Parameters
#### Request Body
- **version** (str | None) - Optional - CmdStan version string. Defaults to latest release.
- **dir** (str | None) - Optional - Path to install directory. Defaults to $HOME/.cmdstan.
- **overwrite** (bool) - Optional - If True, will overwrite and rebuild an existing installation. Default is False.
- **compiler** (bool) - Optional - If True on Windows, use or install C++ toolchain. Default is False.
- **progress** (bool) - Optional - If True, show a progress bar. Default is False.
- **verbose** (bool) - Optional - If True, show console output. Default is False.
- **cores** (int) - Optional - Number of cores to use in make. Default is 1.
- **interactive** (bool) - Optional - If true, ignore other arguments and run in interactive mode.

### Response
#### Success Response (200)
- **result** (bool) - Returns True for success.
```

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

### Install CmdStan Version

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

Builds a specified CmdStan version by running Make on the downloaded source files. Supports overwriting existing installations and controlling verbosity and progress display.

```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.

    :param cmdstan_version: CmdStan release, corresponds to release dirname.
    :param overwrite: when ```True```, run ```make clean-all``` before building.
    :param verbose: Boolean value; when ```True```, show output from make command.
    """
    with pushd(cmdstan_version):
        print(
            'Building version {}, may take several minutes, ' 
            'depending on your system.'.format(cmdstan_version)
        )
        if overwrite and os.path.exists('.'):
            print(
                'Overwrite requested, remove existing build ' 
                'of version {}'.format(cmdstan_version)
            )
            clean_all(verbose)
            print('Rebuilding version {}'.format(cmdstan_version))
        build(verbose, progress=progress, cores=cores)
    print('Installed {}'.format(cmdstan_version))
```

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

### Install CmdStanPy via PyPI

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

Commands to install the package using pip, including an option for all optional dependencies.

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

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

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

### GET show_versions

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

Prints or returns system and dependency information for debugging purposes.

```APIDOC
## GET show_versions

### Description
Prints out system and dependency information for debugging. This includes Python version, OS details, CmdStan version, and versions of key dependencies like pandas, xarray, and numpy.

### Method
GET

### Parameters
#### Query Parameters
- **output** (bool) - Optional - If True, prints the information to stdout and returns a space. If False, returns the information as a string.
```

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

### CmdStanPy INFO: Chain processing start

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

This output indicates the start of processing for a chain in CmdStanPy.

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

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

### Install CmdStan via Python

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

Use the install_cmdstan function to download and build CmdStan from within a Python environment.

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

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

### Clean CmdStan Installation

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

Runs the 'make clean-all' command to clean the CmdStan installation directory. Optionally shows verbose output from the make command.

```python
def clean_all(verbose: bool = False) -> None:
    """
    Run `make clean-all` in the current directory (must be a cmdstan library).

    :param verbose: Boolean value; when `True`, show output from make command.
    """
    cmd = [MAKE, 'clean-all']
    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 "make clean-all" failed\n{str(e)}')
```

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

### Install CmdStan Release

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

Downloads, builds, and tests a CmdStan release. Use the interactive flag for command-line prompts.

```python
def install_cmdstan(
    version: Optional[str] = None,
    dir: Optional[str] = None,
    overwrite: bool = False,
    compiler: bool = False,
    progress: bool = False,
    verbose: bool = False,
    cores: int = 1,
    *,
    interactive: bool = False,
) -> bool:
    """
    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``.

    :param version: 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".

    :param dir: 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.

    :param overwrite:  Boolean value; when ``True``, will overwrite and
        rebuild an existing CmdStan installation.  Default is ``False``.

    :param compiler: Boolean value; when ``True`` on WINDOWS ONLY, use the
        C++ compiler from the ``install_cxx_toolchain`` command or install
        one if none is found.

    :param progress: Boolean value; when ``True``, show a progress bar for
        downloading and unpacking CmdStan.  Default is ``False``.

    :param verbose: Boolean value; when ``True``, show console output from all
        intallation steps, i.e., download, build, and test CmdStan release.
        Default is ``False``.
    :param cores: Integer, number of cores to use in the ``make`` command.
        Default is 1 core.

    :param interactive: 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.

    :return: Boolean value; ``True`` for success.
    """
    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))
```

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

### CmdStan Progress Bar Output

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

Example output showing the progress bar status for multiple chains.

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

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

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

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

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

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

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

### Rebuild CmdStan Installation

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

Rebuilds the existing CmdStan installation. This function assumes CmdStan is already installed and cleans, builds, and compiles the example model.

```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
```

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

### CmdStan Path Management

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

Functions for setting, getting, and validating the CmdStan installation path.

```APIDOC
## GET /cmdstanpy/cmdstan_path

### Description
Retrieves the validated path to the CmdStan installation directory.

### Method
GET

### Endpoint
/cmdstanpy/cmdstan_path

### Parameters
None

### Response
#### Success Response (200)
- **path** (string) - The absolute path to the CmdStan installation.

#### Response Example
```json
{
  "path": "/home/user/.cmdstan/cmdstan-2.25.0"
}
```
```

```APIDOC
## POST /cmdstanpy/set_cmdstan_path

### Description
Sets and validates the CmdStan directory path. This function ensures the provided path points to a valid CmdStan installation.

### Method
POST

### Endpoint
/cmdstanpy/set_cmdstan_path

### Parameters
#### Request Body
- **path** (string) - Required - The path to the CmdStan directory.

### Request Example
```json
{
  "path": "/path/to/your/cmdstan"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the path has been set.

#### Response Example
```json
{
  "message": "CmdStan path set successfully."
}
```
```

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

### CmdStanPy processing output logs

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

Example log output indicating the start and completion of the sampling process.

```text
16:18:30 - cmdstanpy - INFO - CmdStan start processing
```

```text
16:18:30 - cmdstanpy - INFO - CmdStan done processing.
```

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

### Get CmdStan Directory Path

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

Retrieves the validated CmdStan directory path. It checks the CMDSTAN environment variable first, then looks for a default installation in the user's home directory. Raises ValueError if no installation is found.

```python
def cmdstan_path() -> str:
    """
    Validate, then return CmdStan directory path.
    """
    cmdstan = ''
    if 'CMDSTAN' in os.environ and len(os.environ['CMDSTAN']) > 0:
        cmdstan = os.environ['CMDSTAN']
    else:
        cmdstan_dir = os.path.expanduser(os.path.join('~', _DOT_CMDSTAN))
        if not os.path.exists(cmdstan_dir):
            raise ValueError(
                'No CmdStan installation found, run command "install_cmdstan"'
                'or (re)activate your conda environment!'
            )
        latest_cmdstan = get_latest_cmdstan(cmdstan_dir)
        if latest_cmdstan is None:
            raise ValueError(
                'No CmdStan installation found, run command "install_cmdstan"'
                'or (re)activate your conda environment!'
            )
        cmdstan = os.path.join(cmdstan_dir, latest_cmdstan)
        os.environ['CMDSTAN'] = cmdstan
    validate_cmdstan_path(cmdstan)
    return os.path.normpath(cmdstan)
```

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

### Get Stanc Executable Path

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

Returns the full path to the 'stanc' executable within the CmdStan installation. Raises ValueError if the executable is not found.

```python
def stanc_path() -> str:
    """
    Returns the path to the stanc executable in the CmdStan installation.
    """
    cmdstan = cmdstan_path()
    stanc_exe = os.path.join(cmdstan, 'bin', 'stanc' + EXTENSION)
    if not os.path.exists(stanc_exe):
        raise ValueError(
            f'stanc executable not found in CmdStan installation: {cmdstan}.\n'
            'You may need to re-install or re-build CmdStan.',
        )
    return stanc_exe
```

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

### Get CmdStan Version

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

Parses the CmdStan version from the makefile. Returns a tuple of (Major, Minor) version integers. Logs a warning and returns None if the installation is not found or the version cannot be parsed.

```python
def cmdstan_version() -> Optional[tuple[int, ...]]:
    """
    Parses version string out of CmdStan makefile variable CMDSTAN_VERSION,
    returns Tuple(Major, minor).

    If CmdStan installation is not found or cannot parse version from makefile
    logs warning and returns None.  Lenient behavoir required for CI tests,
    per comment:
    https://github.com/stan-dev/cmdstanpy/pull/321#issuecomment-733817554
    """
    try:
        makefile = os.path.join(cmdstan_path(), 'makefile')
    except ValueError as e:
        get_logger().info('No CmdStan installation found.')
        get_logger().debug("%s", e)
        return None

    with open(makefile, 'r') as fd:
        contents = fd.read()

    start_idx = contents.find('CMDSTAN_VERSION := ')
    if start_idx < 0:
        get_logger().info(
            'Cannot parse version from makefile: %s.',
            makefile,
        )
        return None

    start_idx += len('CMDSTAN_VERSION := ')
    end_idx = contents.find('\n', start_idx)

    version = contents[start_idx:end_idx]
    splits = version.split('.')
    if len(splits) != 3:
        get_logger().info(
            'Cannot parse version, expected "<major>.<minor>.<patch>", '
            'found: "%s".',
            version,
        )
        return None
    return tuple(int(x) for x in splits[0:2])
```

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

### Get Generated Quantities Draws as xarray Dataset

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

Returns generated quantities draws as an xarray Dataset. This method is only available for fits made through sampling and requires the 'xarray' package to be installed. It can optionally include warmup draws if they were saved during the MCMC run.

```python
def draws_xr(
        self,
        vars: Union[str, list[str], None] = None,
        inc_warmup: bool = False,
        inc_sample: bool = False,
    ) -> "xr.Dataset":
        """
        Returns the generated quantities draws as a xarray Dataset.

        This method can only be called when the underlying fit was made
        through sampling, it cannot be used on MLE or VB outputs.

        :param vars: optional list of variable names.

        :param inc_warmup: When `True` and the warmup draws are present in
            the MCMC sample, then the warmup draws are included.
            Default value is `False`.

        See Also
        --------
        CmdStanGQ.draws
        CmdStanGQ.draws_pd
        CmdStanMCMC.draws_xr
        """
        if not XARRAY_INSTALLED:
            raise RuntimeError(
                'Package "xarray" is not installed, cannot produce draws array.'
            )
        if not isinstance(self.previous_fit, CmdStanMCMC):
            raise RuntimeError(
                'Method "draws_xr" is only available when '
                'original fit is done via Sampling.'
            )
        mcmc_vars_list = []
        dup_vars = []
        if vars is not None:
            if isinstance(vars, str):
                vars_list = [vars]
            else:
                vars_list = vars
            for var in vars_list:
                if var not in self._metadata.stan_vars:
                    if inc_sample and (
                        var in self.previous_fit._metadata.stan_vars
                    ):
                        mcmc_vars_list.append(var)
                        dup_vars.append(var)
                    else:
                        raise ValueError('Unknown variable: {}'.format(var))
        else:
            vars_list = list(self._metadata.stan_vars.keys())
            if inc_sample:
                for var in self.previous_fit._metadata.stan_vars.keys():
                    if var not in vars_list and var not in mcmc_vars_list:
                        mcmc_vars_list.append(var)
        for var in dup_vars:
            vars_list.remove(var)

        self._assemble_generated_quantities()

        num_draws = self.previous_fit.num_draws_sampling
        sample_config = self.previous_fit._metadata.cmdstan_config
        attrs: MutableMapping[Hashable, Any] = {
            "stan_version": f"{sample_config['stan_version_major']}.
```

```python
f"{sample_config['stan_version_minor']}.
```

```python
f"{sample_config['stan_version_patch']}",
            "model": sample_config["model"],
            "num_draws_sampling": num_draws,
        }
        if inc_warmup and sample_config['save_warmup']:
            num_draws += self.previous_fit.num_draws_warmup
            attrs["num_draws_warmup"] = self.previous_fit.num_draws_warmup

        data: MutableMapping[Hashable, Any] = {}
        coordinates: MutableMapping[Hashable, Any] = {
            "chain": self.chain_ids,
            "draw": np.arange(num_draws),
        }

        for var in vars_list:
            build_xarray_data(
                data,
                self._metadata.stan_vars[var],
                self.draws(inc_warmup=inc_warmup),
            )
        if inc_sample:
            for var in mcmc_vars_list:
                build_xarray_data(
                    data,
                    self.previous_fit._metadata.stan_vars[var],
                    self.previous_fit.draws(inc_warmup=inc_warmup),
                )

        return xr.Dataset(data, coords=coordinates, attrs=attrs).transpose(
            'chain', 'draw', ...
        )
```

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

### Install CmdStan after Pip Installation

Source: https://context7.com/stan-dev/cmdstanpy/llms.txt

Installs CmdStan automatically after CmdStanPy has been installed via pip.

```python
python -c "import cmdstanpy; cmdstanpy.install_cmdstan()"
```

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

### Import CmdStanPy classes

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

Initializes the necessary components for model management and path resolution.

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

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

### Install CmdStanPy with Pip

Source: https://context7.com/stan-dev/cmdstanpy/llms.txt

Installs CmdStanPy using pip. The second command installs with optional xarray support. CmdStan must be installed separately.

```bash
pip install --upgrade cmdstanpy
pip install --upgrade cmdstanpy[all]  # with optional xarray support
```

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

### CmdStanVB.create_inits

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

Generates initial values for model parameters by sampling from the variational approximation.

```APIDOC
## create_inits

### Description
Create initial values for the parameters of the model by randomly selecting draws from the variational approximation draws.

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

### Response
#### Success Response (200)
- **result** (list[dict[str, ndarray]] | dict[str, ndarray]) - The initial values for the parameters of the model.
```

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

### CmdStanArgs Initialization and Method Argument Handling

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

Details on initializing CmdStanArgs and how method-specific arguments are handled.

```APIDOC
## CmdStanArgs Class

### Description
Container for CmdStan command line arguments. Consists of arguments common to all methods and an object which contains the method-specific arguments.

### Method
Constructor

### Endpoint
N/A (Class definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
None

## CmdStanArgs.__init__

### Description
Initializes the CmdStanArgs object with common and method-specific arguments.

### Method
__init__

### Endpoint
N/A (Class method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
None

### Notes
Determines the CmdStan method based on the type of `method_args` provided (SamplerArgs, OptimizeArgs, etc.) and validates the arguments.
```

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

### CmdStanPy Sampling Output - Start

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

This output indicates the start of CmdStan processing for sampling.

```text
16:18:30 - cmdstanpy - INFO - CmdStan start processing

```

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

### Sample with Pathfinder initializations

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

Uses the generated Pathfinder initializations to perform MCMC sampling.

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

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

### show_versions

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

Prints out system and dependency information for debugging purposes.

```APIDOC
## show_versions

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

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

### Response
- **Return Type** (str) - Returns the system and dependency information as a string.
```

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

### Fit a model using CmdStanPy sample method

Source: https://github.com/stan-dev/cmdstanpy/blob/develop/docs/users-guide/hello_world.html

Demonstrates specifying a data file path and running the HMC-NUTS sampler to fit a model.

```python
# specify data file
In [7]: data_file = os.path.join('users-guide', 'examples', 'bernoulli.data.json')

# fit the model
In [8]: fit = model.sample(data=data_file)
```

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

### Summarize random initialization fit

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

Display summary statistics for the fit using random initializations.

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

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

### Configure Download Progress Hook

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

Wraps a tqdm progress bar to track the status of URL downloads.

```python
@progbar.wrap_callback
def wrap_url_progress_hook() -> Optional[Callable[[int, int, int], None]]:
    """Sets up tqdm callback for url downloads."""
    pbar: tqdm = tqdm(
        unit='B',
        unit_scale=True,
        unit_divisor=1024,
        colour='blue',
        leave=False,
    )

    def download_progress_hook(
        count: int, block_size: int, total_size: int
    ) -> None:
        if pbar.total is None:
            pbar.total = total_size
            pbar.reset()
        downloaded_size = count * block_size
        pbar.update(downloaded_size - pbar.n)
        if pbar.n >= total_size:
            pbar.close()

    return download_progress_hook
```

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

### Install CmdStanPy with Conda

Source: https://context7.com/stan-dev/cmdstanpy/llms.txt

Installs CmdStanPy, CmdStan, and the C++ toolchain using Conda. Activates the created Conda environment.

```bash
conda create -n stan -c conda-forge cmdstanpy
conda activate stan
```

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

### CmdStanLaplace.create_inits

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

Generates initial values for model parameters by randomly selecting draws from the Laplace approximation.

```APIDOC
## create_inits

### Description
Creates initial values for the parameters of the model by randomly selecting draws from the Laplace approximation.

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

### Response
- **return** (Union[list[dict[str, np.ndarray]], dict[str, np.ndarray]]) - The initial values for the parameters of the model. If chains is 1, a dictionary is returned, otherwise a list of dictionaries is returned.
```

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

### Install CmdStanPy via Conda

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

Use these commands to install CmdStanPy, CmdStan, and the C++ toolchain into a new or existing Conda environment.

```bash
conda create -n stan -c conda-forge cmdstanpy
```

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

```bash
conda activate stan
```

```bash
conda info -e
```

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

### Determine draw start index

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

Calculates the starting index for draws based on the fit type and whether warmup iterations should be included.

```python
    def _draws_start(self, inc_warmup: bool) -> tuple[int, int]:
        draw1 = 0
        p_fit = self.previous_fit
        if isinstance(p_fit, CmdStanMCMC):
            num_draws = p_fit.num_draws_sampling
            if p_fit._save_warmup:
                if inc_warmup:
                    num_draws += p_fit.num_draws_warmup
                else:
                    draw1 = p_fit.num_draws_warmup

        elif isinstance(p_fit, CmdStanMLE):
            num_draws = 1
            if p_fit._save_iterations:
```

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

### SamplerArgs Class Initialization

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

Initializes the arguments for the NUTS adaptive sampler.

```APIDOC
## SamplerArgs Initialization

### Description
Initializes the configuration for the NUTS adaptive sampler.

### Parameters
#### Request Body
- **iter_warmup** (int) - Optional - Number of warmup iterations.
- **iter_sampling** (int) - Optional - Number of sampling iterations.
- **save_warmup** (bool) - Optional - Whether to save warmup iterations.
- **thin** (int) - Optional - Thinning interval.
- **max_treedepth** (int) - Optional - Maximum tree depth.
- **metric_type** (str) - Optional - Type of mass matrix.
- **metric_file** (str|list[str]) - Optional - Path to metric file.
- **step_size** (float|list[float]) - Optional - Step size.
- **adapt_engaged** (bool) - Optional - Whether adaptation is engaged.
- **adapt_delta** (float) - Optional - Adaptation target acceptance rate.
- **adapt_init_phase** (int) - Optional - Adaptation initial phase.
- **adapt_metric_window** (int) - Optional - Adaptation metric window.
- **adapt_step_size** (int) - Optional - Adaptation step size.
- **fixed_param** (bool) - Optional - Whether to use fixed parameters.
- **num_chains** (int) - Optional - Number of chains.
```

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

### Full Configuration Optimization

Source: https://context7.com/stan-dev/cmdstanpy/llms.txt

Runs optimization with detailed configuration including algorithm choice (LBFGS, BFGS, Newton), iteration limits, convergence tolerances, step size, history size, saving iterations, seed, and whether to compute the Jacobian for MAP estimation.

```python
mle = model.optimize(
    data=data,
    algorithm='LBFGS',  # 'LBFGS', 'BFGS', or 'Newton'
    iter=2000,
    init_alpha=0.001,
    tol_obj=1e-12,
    tol_grad=1e-8,
    tol_param=1e-8,
    history_size=10,
    save_iterations=True,
    seed=42,
    jacobian=True,  # MAP estimate instead of MLE
    output_dir='./output'
)
```

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

### CmdStanMLE.__init__

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

Initializes the CmdStanMLE object with a RunSet, validating that the runset method is OPTIMIZE.

```APIDOC
## CmdStanMLE.__init__

### Description
Initialize object.

### Method
N/A

### Endpoint
N/A

### Parameters
* **runset** (RunSet) - The RunSet object containing optimization results.

### Request Example
N/A

### Response
N/A
```

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

### Display Summary of VB Initialization

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

Displays the summary statistics for a fit object initialized via variational inference.

```python
mcmc_vb_inits_fit.summary()
```

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

### rebuild_cmdstan

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

Rebuilds an existing CmdStan installation.

```APIDOC
## rebuild_cmdstan

### Description
Rebuilds the existing CmdStan installation using the make command.

### Parameters
#### Request Body
- **verbose** (bool) - Optional - If True, show output from make command. Default is False.
- **progress** (bool) - Optional - If True, display progress bar. Default is True.
- **cores** (int) - Optional - Number of cores to use. Default is 1.

### Response
#### Success Response (200)
- **None** (None) - Function returns no value.
```

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

### Configure CmdStanPy Methods from Dictionary

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

Parses a configuration dictionary to instantiate argument objects and result sets for MCMC, optimization, variational inference, and Laplace approximation.

```python
num_samples: int = config_dict['num_samples']  # type: ignore
num_warmup: int = config_dict['num_warmup']  # type: ignore
thin: int = config_dict['thin']  # type: ignore
sampler_args = SamplerArgs(
    iter_sampling=num_samples,
    iter_warmup=num_warmup,
    thin=thin,
    save_warmup=save_warmup,
)
# bugfix 425, check for fixed_params output
try:
    check_sampler_csv(
        csvfiles[0],
        iter_sampling=num_samples,
        iter_warmup=num_warmup,
        thin=thin,
        save_warmup=save_warmup,
    )
except ValueError:
    try:
        check_sampler_csv(
            csvfiles[0],
            iter_sampling=num_samples,
            iter_warmup=num_warmup,
            thin=thin,
            save_warmup=save_warmup,
        )
        sampler_args = SamplerArgs(
            iter_sampling=num_samples,
            iter_warmup=num_warmup,
            thin=thin,
            save_warmup=save_warmup,
            fixed_param=True,
        )
    except ValueError as e:
        raise ValueError(
            'Invalid or corrupt Stan CSV output file, '
        ) from e

cmdstan_args = CmdStanArgs(
    model_name=model,
    model_exe=model,
    chain_ids=[x + 1 for x in range(chains)],
    method_args=sampler_args,
)
runset = RunSet(args=cmdstan_args, chains=chains)
runset._csv_files = csvfiles
for i in range(len(runset._retcodes)):
    runset._set_retcode(i, 0)
fit = CmdStanMCMC(runset)
fit.draws()
return fit
elif config_dict['method'] == 'optimize':
    if 'algorithm' not in config_dict:
        raise ValueError(
            "Cannot find optimization algorithm in file {}.".format(
                csvfiles[0]
            )
        )
    algorithm: str = config_dict['algorithm']  # type: ignore
    save_iterations = config_dict['save_iterations'] == 1
    jacobian = config_dict.get('jacobian', 0) == 1

    optimize_args = OptimizeArgs(
        algorithm=algorithm,
        save_iterations=save_iterations,
        jacobian=jacobian,
    )
    cmdstan_args = CmdStanArgs(
        model_name=model,
        model_exe=model,
        chain_ids=None,
        method_args=optimize_args,
    )
    runset = RunSet(args=cmdstan_args)
    runset._csv_files = csvfiles
    for i in range(len(runset._retcodes)):
        runset._set_retcode(i, 0)
    return CmdStanMLE(runset)
elif config_dict['method'] == 'variational':
    if 'algorithm' not in config_dict:
        raise ValueError(
            "Cannot find variational algorithm in file {}.".format(
                csvfiles[0]
            )
        )
    variational_args = VariationalArgs(
        algorithm=config_dict['algorithm'],  # type: ignore
        iter=config_dict['iter'],  # type: ignore
        grad_samples=config_dict['grad_samples'],  # type: ignore
        elbo_samples=config_dict['elbo_samples'],  # type: ignore
        eta=config_dict['eta'],  # type: ignore
        tol_rel_obj=config_dict['tol_rel_obj'],  # type: ignore
        eval_elbo=config_dict['eval_elbo'],  # type: ignore
        output_samples=config_dict['output_samples'],  # type: ignore
    )
    cmdstan_args = CmdStanArgs(
        model_name=model,
        model_exe=model,
        chain_ids=None,
        method_args=variational_args,
    )
    runset = RunSet(args=cmdstan_args)
    runset._csv_files = csvfiles
    for i in range(len(runset._retcodes)):
        runset._set_retcode(i, 0)
    return CmdStanVB(runset)
elif config_dict['method'] == 'laplace':
    jacobian = config_dict['jacobian'] == 1
    laplace_args = LaplaceArgs(
        mode=config_dict['mode'],  # type: ignore
        draws=config_dict['draws'],  # type: ignore
        jacobian=jacobian,
    )
```

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

### GET method_variables

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

Retrieves all sampler diagnostic variables.

```APIDOC
## GET method_variables

### Description
Returns a dictionary of all sampler variables (output column names ending in __). Maps each column name to a numpy.ndarray containing per-draw diagnostic values.
```