Skip to main content

antupy

antupy (from the mapuzugun word "antü" (sun)1) 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.

  1. mapuzugun is the language of the Mapuche people, the main indigenous group in Chile. antü (antv) means sun, but it also represents one of the main pijan (spirits) in the Mapuche mythology. Here the word is used in its first literal meaning. The name was chosen because the first version of this software was written in Temuco, at the historic Mapuche heartland. ↩

Metadata

Release files for antupy 0.6.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for antupy 0.6.4
File Size Uploaded Provenance Actions
antupy-0.6.4.tar.gz 56.2 kB Without provenance Details for antupy-0.6.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for antupy 0.6.4
File Interpreter ABI Platform Actions
antupy-0.6.4-py3-none-any.whl Python 3 none any Details for antupy-0.6.4-py3-none-any.whl

Total release size: 119.7 kB

Release files / antupy-0.6.4.tar.gz

Download URL antupy-0.6.4.tar.gz
Size 56.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1b722a5217a9c6ff166866d457a1ccb1021a4d4a968a7d2e5bdca83d9cff6b7e
BLAKE2b-256 checksum
How to use checksums
6880086621d10508f7ae7d414ebe3b5a82256db81963afcdb8a2c5948bdb27d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.4 CPython/3.12.10 Windows/11

Release files / antupy-0.6.4-py3-none-any.whl

Download URL antupy-0.6.4-py3-none-any.whl
Size 63.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8907c4d9670b155ddd3c5b733e63e2d7bf8484a67c61a4b54d5ebbb08060f12b
BLAKE2b-256 checksum
How to use checksums
28a6b198cc2b1e0a51d8ed8f82fd05fb4655e061a669a1089ecc126f61fdfdbc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.4 CPython/3.12.10 Windows/11

Security for antupy 0.6.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page