antupy

antupy (from the mapuzugun word "antü" (sun)¹) is an open-source python toolkit to support simulations of energy engineering projects. It is structured in three layers:

• Core layer: antupy works with a unit management system (Unit) based on the SI-unit system that allows to handle physical quantities. Based on that, three classes are available: Var for scalars, Array for 1D vectors/timeseries, and Frame for polars(pandas) tabular data with per-column units.
• Utilities layer: A set of helper modules: props (thermophysical properties), htc (heat transfer correlations), solar (sun position and radiation calculations), and loc (geographical location management).
• Simulation layer: Framework for building and analyzing energy systems using Model, Plant, and Parametric classes, and a set of time-series generators to retrieve useful data (e.g. Weather, Market).

Brief Introduction

antupy works in its core with a unit management system represented by the class Unit, that represents physical quantities compatible with the SI unit system. From this, three type of variables are introduced:

1. The Var class to manage single variables, with the structure (value:float, unit:str).
2. The Array class for 1D data structures in the form of (array:np.ndarray, unit:str).
3. The Frame class for 2D data structures in the form of (frame:DataFrame, units:list[str]). Where the string unit (or units) has to follow a couple of simple rules to represent properly physical units. All three classes support arithmetic operations with automatic unit conversion and dimensional checking, ensuring dimensional consistency throughout calculations.

You can start using antupy with these three classes to support your calculations. The utility modules and simulation classes provide additional functionality. Check the examples below and the documentation for further information.

Documentation

The full documentation is available here.

Installation

The easiest way to install antupy is using pip:

py -m pip install antupy

As usual, it is recommended to use a virtual environment to avoid conflicts with other packages. antupy core system depends only on numpy and polars (which is just an alternative of pandas), while other modules have additional dependencies, such as CoolProp in ap.props and pvlib in ap.solar.

Conda is still not implemented as a distribution method, but it is planned for the future. If you need it, please contact the author or raise an issue.

This is an open-source initiative. You can download the source code and use it freely. Look at the toml file. If you want to contribute, please contact the author or raise an issue.

Quick Start - Core Classes

import antupy as ap
import numpy as np

# Scalar with units
mass = ap.Var(5.0, "kg")
power = ap.Var(100, "kW")
time = ap.Var(1, "day")
eta =  ap.Var(0.8, "-")

# Arrays and Frames with units
temps = ap.Array([20, 25, 30], "degC")

# Frames with per-column units
data = {"power": [10., 20., 40.], "area": [20., 35., 50.]}
df = ap.Frame(data=data, units={"power": "MW", "area": "m2"})

All the core classes have two main methods to interact with them: .gv(str) (or .get_value(str), where str is any valid unit string) and .su(str) (or .set_unit(str)). .gv(str) allows you to retrieve the data (as float, np.ndarray, or pl.DataFrame) from your antupy variables, while .su(str) allows you to change the units in which the data is stored. This is useful to check wheter a variable has the units you expect. You can also use the compatible() method, if you are not sure the unit of a variable. You can also retrieve a variable label string using the .u (or .unit) attribute and the stored data with the .v ( or .value) attribute. The difference between .gv() and .v is the last one does not check the units, so use it carefully and under your own responsability.

import antupy as ap

# Scalar with units
mass = ap.Var(5.0, "kg")
power = ap.Var(100, "kW")
time = ap.Var(1, "day")
temps = ap.Array([20, 25, 30], "degC")

mass_in_ton = mass.gv("ton")
power_wrong = power.gv("J")         # Throws and error. "J" not compatible with "kW".


mass2 = mass.su("mg")
energy = (power * time).su("J")     # The expected unit of power and time is energy

power.compatible()      # ['W', 'Wp']

mass.u    # 'kg'
mass.v = # 5.0

You can do most of basic arithmetic operations (+,-,*,/) and relational operations (==, <, >, etc.) between variables. Only compatible units can be added or substracted (as far as I'm aware, mass + power wouldn't mean anything, right?). Multiplication and division follows conventional unit conversions. floats are assumed as non-dimensional values.

import antupy as ap
time = Var(1, "day")
nom_power = Var(100, "kW")
energy = nom_power * time
energy_2 = (8*energy/2 - energy*2) # 200 ["kW-day"]

if energy >=  energy_2:
    print("energy is greater than energy_2")

Thermophysical Properties

Here's an example of the helper module props to retrieve thermophysical properties of water.

import antupy as ap

# Calculate energy stored in a water tank
temp_max = ap.Var(60, "degC")
temp_mains = ap.Var(20, "degC")
vol_tank = ap.Var(300, "L")

# Get temperature-dependent properties
fluid = ap.props.Water()
temp_avg = (temp_max + temp_mains) / 2
cp = fluid.cp(temp_avg)   # Specific heat [J/kg-K]
rho = fluid.rho(temp_avg)  # Density [kg/m3]

# Calculate stored energy
q_stg = vol_tank * rho * cp * (temp_max - temp_mains)
print(f"Energy stored: {q_stg.su('kWh'):.1f}")  # Output in kWh

Now, you can also use a CoolProp wrapper called FluidState to retrieve properties of any fluid. You need to provide two independent properties to specify the state. If only one property is given, it is flagged as "ISO-CURVE". You can update a state using the .update() method. If more than two properties are provided, the state is flagged as "OVERDETERMINED" and a warning is raised. The lazy argument allows to delay the calculation of the state until a property is requested. All the fluids have the following available properties: temp, p, rho, h, s, cp, cv, mu, and k. The units are automatically handled by the Var class.

import antupy as ap

fs = ap.FluidState(fluid="water", temp=ap.Var(60, "degC"), p=ap.Var(2, "MPa"))
print(f"Density: {fs.rho.su('kg/m3'):.2f}")

This is the basic usage. For deeper usage and the use of the simulation classes such as Plant and Parametric, see the documentation.

Applications

So far, some research projects that have used antupy:

• bdr_csp: A repository for csp simulations.
• tm_solarshift: A repository for domestic electric water heating systems (specifically for the Australian market).

Data

Some basic data for Chile and Australia are included in this package.