0
# Model Building
1

2
Core functionality for building Stan models from program code, including data handling, caching, and compilation management. This module provides the primary entry point for creating executable Bayesian models from Stan probabilistic programming language code.
3

4
## Capabilities
5

6
### Model Compilation
7

8
Build and compile Stan programs into executable models with automatic caching and data integration.
9

10
```python { .api }
11
def build(program_code: str, data: Data = frozendict(), random_seed: Optional[int] = None) -> Model:
12
    """
13
    Build (compile) a Stan program.
14

15
    Arguments:
16
        program_code: Stan program code describing a Stan model
17
        data: A Python dictionary or mapping providing data for the model.
18
              Variable names are keys and values are their associated values.
19
              Default is an empty dictionary, suitable for Stan programs with no data block.
20
        random_seed: Random seed, a positive integer for random number generation.
21
                    Used to make sure that results can be reproduced.
22

23
    Returns:
24
        Model: An instance of Model ready for sampling
25

26
    Raises:
27
        ValueError: If Stan code contains syntax or semantic errors
28
        
29
    Notes:
30
        - C++ reserved words and Stan reserved words may not be used for variable names
31
        - See the Stan User's Guide for a complete list of reserved words
32
        - Models are automatically cached based on program code hash
33
        - Data must be JSON-serializable
34
    """
35
```
36

37
### Model Data Structure
38

39
The Model class encapsulates all information about a compiled Stan model.
40

41
```python { .api }
42
@dataclass(frozen=True)
43
class Model:
44
    """
45
    Stores data associated with and proxies calls to a Stan model.
46
    
47
    Users will not instantiate this class directly. Use stan.build() instead.
48
    """
49
    model_name: str  # Unique identifier for the compiled model
50
    program_code: str  # Original Stan program code  
51
    data: Data  # Data dictionary used for the model
52
    param_names: Tuple[str, ...]  # Names of model parameters
53
    constrained_param_names: Tuple[str, ...]  # Names of all constrained parameters
54
    dims: Tuple[Tuple[int, ...]]  # Dimensions of parameters
55
    random_seed: Optional[int]  # Random seed used
56
```
57

58
### Data Handling
59

60
Data structures and utilities for managing model data.
61

62
```python { .api }
63
# Type alias for model data
64
Data = Dict[str, Union[int, float, Sequence[Union[int, float]]]]
65

66
class frozendict(dict):
67
    """
68
    Immutable dictionary implementation for default parameters.
69
    
70
    Raises:
71
        TypeError: When attempting to modify after creation
72
    """
73
    def __setitem__(self, key, value):
74
        raise TypeError("'frozendict' object is immutable.")
75

76
class DataJSONEncoder(json.JSONEncoder):
77
    """
78
    JSON encoder with numpy array support for model data serialization.
79
    
80
    Handles:
81
        - numpy.ndarray: Converted to nested lists
82
        - numpy integer types: Converted to Python int
83
    """
84
    def default(self, obj): ...
85
```
86

87
## Usage Examples
88

89
### Basic Model Building
90

91
```python
92
import stan
93

94
# Simple normal model
95
program_code = """
96
parameters {
97
    real mu;
98
    real<lower=0> sigma;
99
}
100
model {
101
    mu ~ normal(0, 1);
102
    sigma ~ exponential(1);
103
}
104
"""
105

106
model = stan.build(program_code)
107
print(f"Model name: {model.model_name}")
108
print(f"Parameters: {model.param_names}")
109
```
110

111
### Model with Data
112

113
```python
114
import stan
115
import numpy as np
116

117
# Linear regression model
118
program_code = """
119
data {
120
    int<lower=0> N;
121
    vector[N] x;
122
    vector[N] y;
123
}
124
parameters {
125
    real alpha;
126
    real beta;
127
    real<lower=0> sigma;
128
}
129
model {
130
    y ~ normal(alpha + beta * x, sigma);
131
}
132
"""
133

134
# Prepare data
135
N = 100
136
x = np.random.normal(0, 1, N)
137
y = 2 + 3 * x + np.random.normal(0, 0.5, N)
138

139
data = {
140
    'N': N,
141
    'x': x.tolist(),
142
    'y': y.tolist()
143
}
144

145
model = stan.build(program_code, data=data, random_seed=123)
146
```
147

148
### Error Handling
149

150
```python
151
import stan
152

153
# Invalid Stan code
154
try:
155
    program_code = """
156
    parameters {
157
        real z
158
        real y
159
    }
160
    model {
161
        z ~ no_such_distribution();
162
    }
163
    """
164
    model = stan.build(program_code)
165
except ValueError as e:
166
    print(f"Stan compilation error: {e}")
167
```