0
# Model Loading and Translation
1

2
PySD's model loading capabilities enable translation of System Dynamics models from Vensim (.mdl) and XMILE (.xml) formats into executable Python code. The translation process preserves model behavior while enabling integration with Python's data science ecosystem.
3

4
## Capabilities
5

6
### Loading Vensim Models
7

8
Translates Vensim .mdl files into PySD Model objects, supporting various encoding formats, split views for large models, and external data integration.
9

10
```python { .api }
11
def read_vensim(mdl_file, data_files=None, data_files_encoding=None,
12
                initialize=True, missing_values="warning", split_views=False,
13
                encoding=None, **kwargs):
14
    """
15
    Construct a model from Vensim .mdl file.
16

17
    Parameters:
18
    - mdl_file: str or pathlib.Path - Path to Vensim .mdl file
19
    - data_files: dict or list or str or None - External data files for TabData
20
    - data_files_encoding: str or dict or None - Encoding for data files
21
    - initialize: bool - Whether to initialize model on load (default True)
22
    - missing_values: str - How to handle missing values ("warning", "error", "ignore", "keep")
23
    - split_views: bool - Parse model views into separate Python files
24
    - encoding: str or None - Source model file encoding
25
    - subview_sep: list - Characters for separating views/subviews
26
    - **kwargs: Additional translation keyword arguments
27

28
    Returns:
29
        Model: PySD Model object ready for simulation
30

31
    Raises:
32
        ImportError: If model was compiled with incompatible PySD version
33
        FileNotFoundError: If model file doesn't exist
34
        UnicodeDecodeError: If encoding issues occur
35
    """
36
```
37

38
#### Usage Examples
39

40
Basic Vensim model loading:
41

42
```python
43
import pysd
44

45
# Load simple model
46
model = pysd.read_vensim('population_model.mdl')
47

48
# Load with custom encoding
49
model = pysd.read_vensim('model.mdl', encoding='utf-8')
50

51
# Load with external data files
52
model = pysd.read_vensim('model.mdl', 
53
                        data_files=['data.xlsx', 'lookup_table.csv'])
54
```
55

56
Advanced loading with split views:
57

58
```python
59
# Load large model with view splitting
60
model = pysd.read_vensim('large_model.mdl', 
61
                        split_views=True,
62
                        subview_sep=[',', '.'])
63

64
# Load with specific data file encoding
65
model = pysd.read_vensim('model.mdl',
66
                        data_files={'data.csv': 'population_data'},
67
                        data_files_encoding={'data.csv': 'utf-8'})
68
```
69

70
### Loading XMILE Models
71

72
Translates XMILE (.xml) format models into PySD Model objects, supporting the XMILE standard used by tools like Stella and other System Dynamics software.
73

74
```python { .api }
75
def read_xmile(xmile_file, data_files=None, data_files_encoding=None,
76
               initialize=True, missing_values="warning"):
77
    """
78
    Construct a model from XMILE file.
79

80
    Parameters:
81
    - xmile_file: str or pathlib.Path - Path to XMILE .xml file
82
    - data_files: dict or list or str or None - External data files for TabData
83
    - data_files_encoding: str or dict or None - Encoding for data files  
84
    - initialize: bool - Whether to initialize model on load (default True)
85
    - missing_values: str - How to handle missing values ("warning", "error", "ignore", "keep")
86

87
    Returns:
88
        Model: PySD Model object ready for simulation
89

90
    Raises:
91
        ImportError: If model was compiled with incompatible PySD version
92
        FileNotFoundError: If XMILE file doesn't exist
93
        XMLSyntaxError: If XMILE file is malformed
94
    """
95
```
96

97
#### Usage Examples
98

99
```python
100
# Load XMILE model
101
model = pysd.read_xmile('stella_model.xml')
102

103
# Load with external data
104
model = pysd.read_xmile('model.xml',
105
                       data_files=['time_series.csv'],
106
                       missing_values='ignore')
107
```
108

109
### Loading Pre-translated Python Models
110

111
Loads previously translated PySD Python model files, useful for models that have already been converted or for faster loading of frequently-used models.
112

113
```python { .api }
114
def load(py_model_file, data_files=None, data_files_encoding=None,
115
         initialize=True, missing_values="warning"):
116
    """
117
    Load a pre-translated Python model file.
118

119
    Parameters:
120
    - py_model_file: str - Path to translated Python model file
121
    - data_files: dict or list or str or None - External data files for TabData
122
    - data_files_encoding: str or dict or None - Encoding for data files
123
    - initialize: bool - Whether to initialize model on load (default True)  
124
    - missing_values: str - How to handle missing values ("warning", "error", "ignore", "keep")
125

126
    Returns:
127
        Model: PySD Model object ready for simulation
128

129
    Raises:
130
        ImportError: If Python model file cannot be imported
131
        FileNotFoundError: If Python model file doesn't exist
132
    """
133
```
134

135
#### Usage Examples
136

137
```python
138
# Load previously translated model
139
model = pysd.load('translated_population_model.py')
140

141
# Load with initialization disabled
142
model = pysd.load('model.py', initialize=False)
143
# Initialize later when ready
144
model.initialize()
145
```
146

147
### Data Files Integration
148

149
All loading functions support external data integration through the `data_files` parameter, enabling models to access time series data, lookup tables, and constants from external sources.
150

151
#### Data Files Format Options
152

153
**List of filenames** - Search all files for needed variables:
154
```python
155
data_files = ['data.xlsx', 'lookup.csv', 'constants.txt']
156
```
157

158
**Dictionary mapping** - Specify which files contain which variables:
159
```python
160
data_files = {
161
    'population_data.csv': ['births', 'deaths', 'migration'],
162
    'economic_data.xlsx': ['gdp', 'inflation_rate'],
163
    'constants.txt': ['country_area']
164
}
165
```
166

167
**Single filename** - Search single file for all variables:
168
```python
169
data_files = 'comprehensive_data.xlsx'
170
```
171

172
### Missing Values Handling
173

174
Control how missing or incomplete data is handled during model loading:
175

176
- **"warning"** (default): Show warning and interpolate missing values
177
- **"error"**: Raise exception when missing values encountered  
178
- **"ignore"**: Interpolate missing values silently
179
- **"keep"**: Preserve missing values (may cause simulation failure)
180

181
```python
182
# Strict error handling
183
model = pysd.read_vensim('model.mdl', missing_values='error')
184

185
# Silent interpolation
186
model = pysd.read_vensim('model.mdl', missing_values='ignore')
187
```
188

189
### Translation Process
190

191
The loading functions perform these key steps:
192

193
1. **Parse Source**: Read and parse Vensim .mdl or XMILE .xml file
194
2. **Abstract Model**: Convert to internal abstract model representation
195
3. **Code Generation**: Generate executable Python code using ModelBuilder
196
4. **Module Loading**: Import generated Python code as Model object  
197
5. **Initialization**: Set up initial conditions and external data (if enabled)
198

199
This process preserves model structure, equations, and behavior while enabling Python integration capabilities.