Getting Started

A short guide to install the package and run your first optimization.

Installation

Install from source:

git clone https://github.com/example/chiller-model.git
cd chiller-model
pip install -e .

Basic Concepts

COP (Coefficient of Performance)

Cooling output divided by electrical input. A COP of 4.0 means 4 kW of cooling per 1 kW of electricity.

Thermal interference

Exhaust from one chiller heats a neighbour’s intake, forcing it to work harder for the same cooling output.

Max cooling capacity

Each chiller has a nameplate limit (kW of cooling). Aging reduces this capacity over time.

Startup ramp

A freshly started chiller comes online at reduced capacity and ramps to full output over a short period (default 15 minutes).

Package Structure

  • chiller_sim.layout: Grid geometry and wind conditions

  • chiller_sim.physics: COP, degradation, ramp, and plume models

  • chiller_sim.simulation: Builder, simulator, and result types

Minimal Working Example

import numpy as np
from chiller_sim import Simulator

sim = (
    Simulator()
    .with_grid(rows=2, cols=2, spacing_m=10.0, base_cop=4.0, max_cooling_kw=500.0)
    .with_wind(speed_m_per_s=5.0, angle_deg=0.0)
    .with_ambient_temp(temp_k=298.15)
    .with_load_fn(lambda t: 800.0)
    .build()
)

result = sim.optimize(time_hours=0.0)

print(f"Active mask:    {result.active_mask}")
print(f"COP per chiller: {np.round(result.cop_array, 2)}")
print(f"Total work:     {result.total_work_kw:.2f} kW")

Understanding Results

optimize() returns an OptimizeResult with these fields:

  • time_hours – Simulation time of this step

  • load_kw – Facility cooling load (kW)

  • active_mask – Boolean array: which chillers are running

  • cop_array – Effective COP for each chiller

  • temp_rise_array – Inlet temperature rise per chiller (K)

  • total_work_kw – Total electrical power consumed (kW)

  • baseline_work_kw – Power if all chillers were running

  • savings_fraction – Fraction of energy saved vs. baseline

Next Steps

  • See User Guide for the full API narrative and architecture overview

  • See Examples for worked examples with generated images

  • See API Reference for the complete API reference