Simulation

class chiller_sim.simulation.builder.SimulatorBuilder[source]

Bases: object

Fluent builder that assembles a Simulator from its constituent plugins.

__init__()[source]

Initialise builder with all fields unset and sensible numeric defaults.

Return type:

None

with_grid(rows, cols, spacing_m, base_cop, max_cooling_kw, alpha=0.7, ages_years=None, seed=None)[source]

Set the chiller grid layout.

Parameters:
Return type:

SimulatorBuilder

with_layout(positions_m, ages_years, base_cop, max_cooling_kw, alpha=0.7)[source]

Set the chiller layout from explicit (x, y) positions.

Parameters:
Return type:

SimulatorBuilder

with_wind(speed_m_per_s, angle_deg)[source]

Set static wind conditions (speed and direction).

Parameters:
Return type:

SimulatorBuilder

with_wind_fn(fn)[source]

Set a time-varying wind plugin; overrides any static wind.

Parameters:

fn (WindFn)

Return type:

SimulatorBuilder

with_ambient_temp(temp_k)[source]

Set a constant ambient temperature in Kelvin.

Parameters:

temp_k (float)

Return type:

SimulatorBuilder

with_ambient_temp_fn(fn)[source]

Set a time-varying ambient temperature plugin.

Parameters:

fn (AmbientTempFn)

Return type:

SimulatorBuilder

with_dispersion(coeff, heat_rejection_scale=None)[source]

Override the Gaussian plume dispersion coefficient and heat rejection scale.

Parameters:

  • coeff (float)

  • heat_rejection_scale (float | None)

Return type:

SimulatorBuilder

with_heat_rejection_scale(scale)[source]

Override the heat rejection scale that converts plume influence to Kelvin.

Parameters:

scale (float)

Return type:

SimulatorBuilder

with_load_fn(fn)[source]

Set the facility load profile plugin.

Parameters:

fn (LoadFn)

Return type:

SimulatorBuilder

with_cop_fn(fn)[source]

Override the default COP computation plugin.

Parameters:

fn (CopFn)

Return type:

SimulatorBuilder

with_degradation_fn(fn)[source]

Override the default age-based capacity degradation plugin.

Parameters:

fn (DegradationFn)

Return type:

SimulatorBuilder

with_ramp_fn(fn)[source]

Override the default startup ramp plugin.

Parameters:

fn (RampFn)

Return type:

SimulatorBuilder

with_switching_threshold(min_savings_kw)[source]

Set the minimum savings (kW) required to switch chiller on/off.

Parameters:

min_savings_kw (float)

Return type:

SimulatorBuilder

build()[source]

Validate configuration and construct the Simulator.

Return type:

Simulator

class chiller_sim.simulation.simulator.Simulator(builder, layout, initial_wind, model, load_fn, cop_fn, degradation_fn, ramp_fn, wind_fn, ambient_temp_k, ambient_temp_fn, min_savings_kw)[source]

Bases: object

Chiller array simulator that optimises active-chiller selection each time step.

Parameters:
__init__(builder, layout, initial_wind, model, load_fn, cop_fn, degradation_fn, ramp_fn, wind_fn, ambient_temp_k, ambient_temp_fn, min_savings_kw)[source]

Initialise the simulator and precompute the interaction matrix.

Parameters:
Return type:

None

with_wind(speed_m_per_s, angle_deg)[source]

Delegate to builder for re-configuration with new static wind.

Parameters:
Return type:

SimulatorBuilder

with_wind_fn(fn)[source]

Delegate to builder for re-configuration with a time-varying wind plugin.

Parameters:

fn (WindFn)

Return type:

SimulatorBuilder

with_ambient_temp(temp_k)[source]

Delegate to builder for re-configuration with a new constant ambient temperature.

Parameters:

temp_k (float)

Return type:

SimulatorBuilder

with_ambient_temp_fn(fn)[source]

Delegate to builder for re-configuration with a time-varying ambient temperature.

Parameters:

fn (AmbientTempFn)

Return type:

SimulatorBuilder

optimize(time_hours, load_kw=None)[source]

Run one greedy optimization step and return detailed results.

Parameters:
Return type:

OptimizeResult

stream(duration_hours, time_step_hours=1.0, initial_time_hours=0.0, initial_state=None)[source]

Yield one OptimizeResult per time step over the requested duration.

Parameters:
Return type:

Generator[OptimizeResult, None, None]

simulate(duration_hours, time_step_hours=1.0, initial_time_hours=0.0, initial_state=None)[source]

Run the full simulation and return all steps collected into a SimulationResult.

Parameters:
Return type:

SimulationResult

class chiller_sim.simulation.results.OptimizeResult(time_hours, load_kw, active_mask, total_work_kw, baseline_work_kw, savings_fraction, cop_array, temp_rise_array)[source]

Bases: object

Output of a single optimization step.

Parameters:
time_hours: float
load_kw: float
active_mask: ndarray[tuple[Any, ...], dtype[bool]]
total_work_kw: float
baseline_work_kw: float
savings_fraction: float
cop_array: ndarray[tuple[Any, ...], dtype[float64]]
temp_rise_array: ndarray[tuple[Any, ...], dtype[float64]]
__init__(time_hours, load_kw, active_mask, total_work_kw, baseline_work_kw, savings_fraction, cop_array, temp_rise_array)
Parameters:
Return type:

None

class chiller_sim.simulation.results.SimulationResult(steps)[source]

Bases: object

Aggregated results across all steps of a dynamic simulation.

Parameters:

steps (list[OptimizeResult])

steps: list[OptimizeResult]
property schedule: ndarray[tuple[Any, ...], dtype[bool]]

Return 2-D boolean array of active masks, shape (n_steps, n_chillers).

property total_work_kw: ndarray[tuple[Any, ...], dtype[float64]]

Return total work per step in kW, shape (n_steps,).

property loads_kw: ndarray[tuple[Any, ...], dtype[float64]]

Return facility load per step in kW, shape (n_steps,).

property savings_fraction: ndarray[tuple[Any, ...], dtype[float64]]

Return savings fraction per step, shape (n_steps,).

property cop_arrays: ndarray[tuple[Any, ...], dtype[float64]]

Return per-chiller COP array per step, shape (n_steps, n_chillers).

__init__(steps)
Parameters:

steps (list[OptimizeResult])

Return type:

None

class chiller_sim.simulation.results.InitialState(active_mask, time_since_start_hours)[source]

Bases: object

Optional warm-start state for stream()/simulate() calls.

Parameters:
active_mask: ndarray[tuple[Any, ...], dtype[bool]]
time_since_start_hours: ndarray[tuple[Any, ...], dtype[float64]]
__init__(active_mask, time_since_start_hours)
Parameters:
Return type:

None