Documentation

Quick start guide and technical reference

Quick Start

1. Prerequisites

Before installing Smart Cool Tech, ensure you have:

  • Python 3.9+ with conda or venv
  • InfluxDB 3.0 for time-series data storage
  • Docker (optional, for containerized deployment)
  • Building Data: Historical chiller operational data (minimum 2 weeks)

2. Installation

# Clone the repository
git clone https://github.com/your-org/smartcooling.git
cd smartcooling

# Create conda environment
conda create -n brick-csc python=3.9
conda activate brick-csc

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "import rdflib, brickschema; print('OK')"

3. Configuration

Create a configuration profile for your building:

# config/profiles/your_building.yaml

building:
  name: "Your Building Name"
  location: "City, Country"

influxdb:
  url: "http://localhost:8086"
  token: "${INFLUX_TOKEN}" # Use environment variable
  org: "your_org"
  bucket: "hvac"

chillers:
  - id: "CH-01"
    capacity: 3500 # kW
    type: "centrifugal"
    cooling_water: "freshwater"
  - id: "CH-02"
    capacity: 3500
    type: "centrifugal"
    cooling_water: "freshwater"

4. Create Brick Model

Generate a Brick Schema model for your building:

# Generate Brick model from configuration
python -m brick.model_generator --profile your_building

# Validate the model
python -m brick.validator --model models/your_building.ttl

# Output:
# ✓ Brick model validated successfully
# ✓ Found 9 chillers
# ✓ Found 18 temperature sensors
# ✓ All relationships valid
What is Brick Schema?
Brick is a standardized semantic metadata framework that describes building systems and their relationships. It enables Smart Cool Tech to work across different buildings without code changes.

5. Train Models

# Train load forecasting model
python -m models.load_forecasting_trainer \
  --profile your_building \
  --data-range "2024-01-01/2024-12-31"

# Train chiller COP models
python -m models.chiller_model_trainer \
  --profile your_building \
  --model-type bnn # Bayesian Neural Network

# Output:
# Load Model CVRMSE: 8.3%
# CH-01 COP Model RMSE: 0.042
# CH-02 COP Model RMSE: 0.039
# Models saved to: models/saved_models/

6. Run Optimization

# Single optimization run
python -m cli.main optimize \
  --mode single \
  --profile your_building

# Batch optimization (hourly for past 7 days)
python -m cli.main batch-optimization \
  --profile your_building \
  --hours 168

# Schedule automatic optimization (every hour)
python -m cli.main schedule \
  --profile your_building \
  --interval 3600

7. Launch Dashboard

# Start the dashboard
streamlit run dashboard/app.py --server.port 8501

# Access at:
# http://localhost:8501

# Default credentials:
# Username: operator
# Password: demo123
Security Note: Change default credentials before deploying to production. Use environment variables or a secure credential store for passwords and API tokens.

Key Concepts

Two-Stage Optimization

Smart Cool Tech uses a two-step approach:

  • Stage 1 - Load Forecasting: Predict cooling load demand for the next hour using historical patterns, weather data, and time features.
  • Stage 2 - Chiller Sequencing: Given the predicted load, determine the optimal combination and loading of chillers that minimizes total plant power while respecting all constraints.

COP (Coefficient of Performance)

COP measures chiller efficiency: COP = Cooling Load / Power Consumption. Higher COP means better efficiency. Smart Cool Tech's BNN models predict COP for any chiller at any load condition with uncertainty quantification.

PLR (Part Load Ratio)

PLR indicates how heavily a chiller is loaded: PLR = Current Load / Rated Capacity. Most chillers are most efficient at PLR between 0.5 and 0.8. Smart Cool Tech balances loads to keep chillers in their efficient operating range.

Sigma (σ) - Prediction Uncertainty

Bayesian Neural Networks provide not just predictions but also confidence levels (sigma). When sigma exceeds a threshold, Smart Cool Tech automatically switches to the physics-based fallback model for that chiller.

Common Operations

Update Models with New Data

# Retrain with recent data
python -m models.chiller_model_trainer \
  --profile your_building \
  --incremental \
  --data-range "2025-01-01/2025-01-31"

Export Optimization Results

# Export to CSV
python -m cli.main export \
  --profile your_building \
  --output results.csv \
  --date-range "2025-01-01/2025-01-31"

Validate Brick Model

# Run SHACL validation
python -m brick.validator \
  --model models/your_building.ttl \
  --shapes brick/shapes/chiller_shapes.ttl

Query Building Metadata

# Execute SPARQL query
python -m brick.query \
  --model models/your_building.ttl \
  --query "SELECT ?chiller ?capacity WHERE { \
    ?chiller a brick:Chiller . \
    ?chiller brick:hasCapacity ?capacity \
  }"

Troubleshooting

High Prediction Error

  • Check if input data quality is good (no missing values, no sensor errors)
  • Verify that training data covers the full range of operating conditions
  • Consider retraining models with more recent data
  • Review bias correction statistics in the monitoring dashboard

Optimization Not Running

  • Verify InfluxDB connection: python -m database.test_connection
  • Check that Brick model is valid and loaded correctly
  • Ensure trained models exist in models/saved_models/
  • Review logs: tail -f logs/optimization.log

Dashboard Shows No Data

  • Confirm optimization has run at least once
  • Check database connection and query results
  • Verify profile name matches between config and dashboard
  • Clear browser cache and refresh the page

API Reference

Python API

Smart Cool Tech provides a Python API for programmatic access:

from optimization.real_time_optimizer import RealTimeOptimizer

# Initialize optimizer
optimizer = RealTimeOptimizer(profile="your_building")

# Run optimization
result = optimizer.optimize()

# Access results
print(f"Recommended chillers: {result['recommended']}")
print(f"Expected savings: {result['energy_saving_pct']:.1f}%")

Additional Resources

Need Help?

Contact our support team or join the community discussion.

Access Dashboard