0
# Installation and Setup
1

2
Functions for installing, configuring, and managing the CmdStan installation that CmdStanPy depends on. CmdStan is the command-line interface to Stan that must be installed separately from CmdStanPy.
3

4
## Capabilities
5

6
### Installing CmdStan
7

8
Downloads, extracts, and builds CmdStan from GitHub releases, with support for custom versions and build configurations.
9

10
```python { .api }
11
def install_cmdstan(
12
    version=None,
13
    dir=None,
14
    overwrite=False,
15
    compiler=False,
16
    progress=False,
17
    verbose=False,
18
    cores=1,
19
    interactive=False
20
):
21
    """
22
    Download and install CmdStan.
23
    
24
    Parameters:
25
    - version (str, optional): CmdStan version to install. Defaults to latest stable release
26
    - dir (str, optional): Directory to install CmdStan. Defaults to user home directory
27
    - overwrite (bool): Overwrite existing CmdStan installation
28
    - compiler (bool): Install C++ compiler on Windows (requires internet)
29
    - progress (bool): Show progress bars during download and build
30
    - verbose (bool): Show build output during compilation
31
    - cores (int): Number of cores for parallel compilation
32
    - interactive (bool): Enable interactive installation mode
33
    
34
    Returns:
35
    None
36
    
37
    Raises:
38
    Exception: If download or build fails
39
    """
40
```
41

42
**Usage Example:**
43

44
```python
45
import cmdstanpy as csp
46

47
# Install latest version with defaults
48
csp.install_cmdstan()
49

50
# Install specific version with custom settings
51
csp.install_cmdstan(
52
    version="2.32.0", 
53
    dir="/opt/cmdstan",
54
    cores=4,
55
    verbose=True
56
)
57
```
58

59
### Setting CmdStan Path
60

61
Configure the path to an existing CmdStan installation.
62

63
```python { .api }
64
def set_cmdstan_path(path):
65
    """
66
    Set the path to CmdStan installation.
67
    
68
    Parameters:
69
    - path (str or PathLike): Path to CmdStan installation directory
70
    
71
    Returns:
72
    None
73
    
74
    Raises:
75
    ValueError: If path does not exist or is not a valid CmdStan installation
76
    """
77
```
78

79
**Usage Example:**
80

81
```python
82
import cmdstanpy as csp
83

84
# Set path to CmdStan installation
85
csp.set_cmdstan_path("/usr/local/cmdstan")
86

87
# Verify the path was set correctly
88
print("CmdStan path:", csp.cmdstan_path())
89
```
90

91
### Getting CmdStan Path
92

93
Retrieve the currently configured CmdStan installation path.
94

95
```python { .api }
96
def cmdstan_path():
97
    """
98
    Get the path to CmdStan installation.
99
    
100
    Returns:
101
    str: Path to CmdStan installation directory
102
    
103
    Raises:
104
    ValueError: If CmdStan path is not set or installation not found
105
    """
106
```
107

108
### Getting CmdStan Version
109

110
Get the version of the currently configured CmdStan installation.
111

112
```python { .api }
113
def cmdstan_version():
114
    """
115
    Get CmdStan version.
116
    
117
    Returns:
118
    str: CmdStan version string (e.g., "2.32.0")
119
    
120
    Raises:
121
    RuntimeError: If CmdStan installation not found or makefile cannot be read
122
    """
123
```
124

125
### Setting Make Environment
126

127
Configure environment variables for the make command used during model compilation.
128

129
```python { .api }
130
def set_make_env(make_env):
131
    """
132
    Set environment variables for make command.
133
    
134
    Parameters:
135
    - make_env (dict): Dictionary of environment variable names and values
136
    
137
    Returns:
138
    None
139
    """
140
```
141

142
**Usage Example:**
143

144
```python
145
import cmdstanpy as csp
146

147
# Set custom C++ compiler flags
148
csp.set_make_env({
149
    "CXX": "g++",
150
    "CXXFLAGS": "-O3 -march=native"
151
})
152
```
153

154
### Rebuilding CmdStan
155

156
Rebuild an existing CmdStan installation, useful after updating compiler settings or system changes.
157

158
```python { .api }
159
def rebuild_cmdstan(verbose=False, progress=True, cores=1):
160
    """
161
    Rebuild existing CmdStan installation.
162
    
163
    Parameters:
164
    - verbose (bool): Show build output during compilation
165
    - progress (bool): Show progress bar during build
166
    - cores (int): Number of cores for parallel compilation
167
    
168
    Returns:
169
    None
170
    
171
    Raises:
172
    RuntimeError: If CmdStan installation not found or build fails
173
    """
174
```
175

176
**Usage Example:**
177

178
```python
179
import cmdstanpy as csp
180

181
# Rebuild with maximum parallelism
182
import multiprocessing
183
csp.rebuild_cmdstan(cores=multiprocessing.cpu_count(), verbose=True)
184
```
185

186
## Common Setup Patterns
187

188
### First-Time Setup
189

190
```python
191
import cmdstanpy as csp
192

193
# Option 1: Automatic installation (recommended for most users)
194
csp.install_cmdstan()
195

196
# Option 2: Use existing installation
197
csp.set_cmdstan_path("/path/to/existing/cmdstan")
198

199
# Verify setup
200
print(f"CmdStan {csp.cmdstan_version()} installed at {csp.cmdstan_path()}")
201
```
202

203
### Advanced Configuration
204

205
```python
206
import cmdstanpy as csp
207

208
# Set up custom build environment
209
csp.set_make_env({
210
    "CXX": "clang++",
211
    "CXXFLAGS": "-O3 -flto -march=native",
212
    "LDFLAGS": "-flto"
213
})
214

215
# Install with specific configuration
216
csp.install_cmdstan(
217
    version="2.32.0",
218
    dir="./local-cmdstan", 
219
    cores=8,
220
    verbose=True
221
)
222
```
223

224
### Troubleshooting Setup
225

226
```python
227
import cmdstanpy as csp
228

229
# Check current configuration
230
csp.show_versions()
231

232
# Reinstall if needed
233
csp.install_cmdstan(overwrite=True, verbose=True)
234

235
# Rebuild after configuration changes
236
csp.rebuild_cmdstan(verbose=True)
237
```