User Guide Overview¶

Welcome to the Steel Model User Guide. This section contains comprehensive documentation for users and developers working with the Steel Model simulation system.

Contents¶

Installation Guide ¶

Step-by-step installation instructions for developers. Covers:

Basic installation: Clone repository, set up virtual environment with uv, install dependencies
Running tests: pytest, coverage reports, wind/PV tests
Static type checking: mypy configuration and usage
Managing dependencies: Adding, updating, and upgrading packages with uv
Building the package: Creating distribution packages
Jupyter notebooks: Running interactive analysis notebooks
Standalone application: Building Electron apps via GitHub Actions
System requirements: CBC solver installation for different platforms

Running Simulations Locally ¶

Complete guide to running steel model simulations on your local machine. Covers:

Three execution methods: Programmatic (Python/Notebook), Command-Line Interface (CLI), and Django Web Interface
Data pipeline architecture: From S3 storage through local caching to simulation execution
Caching system: Content-based caching for faster repeated simulations
Configuration examples: Technology constraints, custom paths, and simulation parameters
Troubleshooting: Common issues and debugging tips
Output files: Understanding simulation results and visualizations

CLI Commands ¶

Reference documentation for all command-line interface tools:

run_simulation: Main command to run simulations with automatic data preparation and caching
list-binaries: View available Steel Model standalone binaries on S3
download-binaries: Download specific builds of the Electron app
download-latest: Get the latest version of the Electron app for your platform

Each command includes usage examples, options, and practical tips.

Command-Line Entrypoints ¶

Detailed reference for programmatic access to CLI functionality. Covers:

Python functions behind CLI commands
Integration patterns for custom workflows
Examples of programmatic usage
Advanced configuration options

Configuration ¶

Comprehensive guide to configuring the Steel Model simulation:

SimulationConfig: Central configuration object for all simulation parameters
Path configuration: Custom data sources and output directories
Technology settings: Controlling which technologies are available and when
Economic parameters: Carbon pricing, capital costs, discount rates
Geographic constraints: Land use, infrastructure, and renewable energy
Environment variables: System-wide configuration options

Logging Guide ¶

Understanding and controlling simulation logging:

Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
Configuring loggers: Module-specific logging control
Output destinations: Console, file, and structured logging
Debugging workflows: Using logs to troubleshoot issues
Performance logging: Tracking simulation performance metrics

Quick Start¶

For Developers (from source)¶

See the Installation Guide for complete setup instructions:

Clone and set up:

git clone git@github.com:systemiqofficial/steel-iq.git
cd steel-iq
uv venv -p python3.13
source .venv/bin/activate
uv sync

Run tests:
```
pytest
```
Run a simulation:
```
run_simulation
```

For Package Users¶

Install the package:
```
uv add steel-model
```
Prepare data (automatic):
```
run_simulation
```
The run_simulation command automatically downloads and prepares all required data.

Run a simulation:

run_simulation --start-year 2025 --end-year 2030

Common Workflows¶

Running a Quick Test¶

# Short simulation for testing
run_simulation --start-year 2025 --end-year 2027 --log-level INFO

Using Custom Data¶

# Prepare data with your own master Excel
steelo-data-prepare --master-excel path/to/your/master_input.xlsx

# Run simulation
run_simulation

Web Interface¶

# Set up Django (first time only)
cd src/django
python manage.py migrate
python manage.py prepare_default_data

# Start services
python manage.py runserver          # Terminal 1
python manage.py db_worker          # Terminal 2

Then open http://localhost:8000 in your browser.

Key Concepts¶

Data Pipeline¶

The Steel Model uses a structured data flow:

S3 Storage: Raw data packages (core-data, geo-data, master Excel)
Local Cache: Downloaded packages cached in ~/.steelo/data_cache/
Data Preparation: Transform raw data into JSON repositories
Preparation Cache: Processed data cached in ~/.steelo/preparation_cache/
Simulation: Uses prepared fixtures for fast execution

Caching System¶

Content-based: Cache keys derived from master Excel file hash
Automatic reuse: Same inputs = instant cache hit
Version tracking: Automatic invalidation when code changes
Cache commands: steelo-cache stats, steelo-cache clear, etc.

Configuration Hierarchy¶

Environment variables: System-wide defaults (e.g., STEELO_HOME)
SimulationConfig: Explicit configuration object
Command-line flags: Override defaults for specific runs

Getting Help¶

Documentation¶

Quick reference: See CLI Commands for command syntax
Detailed guides: See Running Simulations Locally
Configuration: See Configuration

Troubleshooting¶

Common issues and solutions are documented in:

Running Simulations Locally > Troubleshooting
CLI Commands examples

Support¶

Issue Tracker: Report bugs and request features
Documentation: Comprehensive guides and API references
Community: Share experiences and get help