System Classes

Antupy provides Plant and Parametric classes to build and analyze thermal systems. The Plant class is the main simulation container where you define components and their interactions in the run_simulation() method. The Parametric class allows running multiple simulations while varying one or more parameters to perform parametric studies.

Using the Plant class

The Plant class lets you build system simulations by defining components as class attributes and implementing the run_simulation() method. Here’s a simple solar water heating system:

from dataclasses import dataclass
from antupy import SimulationOutput, Var, Plant
from antupy.tsg.weather import TMY
from antupy.utils.props import Water

@dataclass
class SolarCollector():
    area = Var(2, "m2")
    Fr_ta = Var(0.7, "-")
    Fr_Ul = Var(0.5, "W/m2-K")

    def run_model(self, temp_amb: Var, temp_in: Var, solar_rad: Var):
        x = (temp_in - temp_amb) / solar_rad if solar_rad.gv("W/m2") > 0 else Var(0,"W/m2")
        eta_out = self.Fr_ta - self.Fr_Ul * x
        rho, cp = Water().rho(temp_in), Water().cp(temp_in)
        temp_out = temp_in + eta_out * solar_rad / (self.area * cp * rho)
        return {"temp_out": temp_out, "eta_out": eta_out}

@dataclass
class HotWaterTank():
    volume = Var(200, "L")
    U = Var(0.4, "W/m2-K")

    def run_model(self):
        return {}

class SolarWaterHeating(Plant):
    heater = SolarCollector()
    tank = HotWaterTank()
    weather = TMY(location="Antofagasta")

    def run_simulation(self, verbose: bool = False) -> SimulationOutput:
        df_sim = self.weather.load_data()
        for _, row in df_sim.iterrows():
            out_collector = self.heater.run_model(
                row["temp_amb"], row["temp_in"], row["GHI"]
            )
            out_tank = self.tank.run_model()
        return super().run_simulation(verbose)

# Run the simulation
plant = SolarWaterHeating()
results = plant.run_simulation()

Using the Parametric class

The Parametric class runs multiple simulations varying one or more parameters. You provide a base case plant and a dictionary of parameter ranges as Array objects:

import numpy as np
from antupy import Array, Var, Parametric

# Define base case
base_case = SolarWaterHeating()

# Define parameter ranges
params_in = {
    "heater.area": Array(np.arange(1.5, 3.1, 0.5), "m2"),
    "heater.Fr_ta": Array(np.linspace(0.6, 0.8, 3), "-"),
}

# Create and run parametric study
study = Parametric(
    base_case=base_case,
    params_in=params_in,
    save_results_detailed=True,
    dir_output="./parametric_results",
    path_results="./parametric_results/results.csv",
)

df_results = study.run_analysis()
print(df_results.head())

The parametric study runs all combinations of the input parameters and saves results to CSV files. The save_results_detailed=True option stores individual simulation outputs for further analysis.