py2aspen

A Python wrapper for Aspen Plus built on comtypes ✨

English | 简体中文

A Python wrapper for Aspen Plus built on comtypes, packaging COM automation calls into an object-oriented Python API: connect to the application, open .bkp files, place/connect blocks and streams on the flowsheet, read/write properties, run simulations, and export reports. It supports local COM as well as remote connections over DCOM.

Installation

Install with uv (recommended) or pip:

uv add py2aspen
# or
pip install py2aspen

Minimal example

from py2aspen import UnitAspen, bind, MaterialStream, MaterialStreamInput

# ProgID for Aspen Plus
PROGID = "AspenPlus.Document"
BKP_PATH = r"C:\path\to\solid1.bkp" # Example file shipped with Aspen; pick a valid path on your machine

with UnitAspen(PROGID) as aspen:
    aspen.suppress_dialogs(True)
    aspen.open_bkp(BKP_PATH)
    aspen.set_visible(True)

    stream = MaterialStream(name="WET-COAL")
    aspen.exec(bind(stream))

    stream.set_input(MaterialStreamInput(temperature=100))
    aspen.engine_run()

The with block automatically calls lazy_bind() to enable late binding and closes Aspen Plus on exit. To keep the application window open after the script finishes (e.g. for debugging), skip with and call lazy_bind() manually instead.

Development workflow (uv + ty + ruff)

The project uses the src layout with uv_build as the build backend. Dependency management is handled by uv, type checking by ty, and code style by ruff.

Generate the comtypes type module

py2aspen depends on comtypes.gen.Happ (the Aspen Plus type library). The repo ships the .tlb at tlb/v14/happ.tlb; after installing, generate it once in the target Python environment (the output is written to <env>/Lib/site-packages/comtypes/gen/):

.venv\Scripts\python.exe -c "import comtypes.client as cc; cc.GetModule(r'tlb\v14\happ.tlb')"

Re-run this command after recreating the virtual environment or deleting the comtypes/gen/ directory.

Environment and dependencies

# Initialize the environment after cloning (installs runtime deps and the dev group from pyproject.toml)
uv sync

Type checking (ty)

uvx ty check            # Check the whole repo
uvx ty check src/       # Check a specific path

Code style (ruff)

uvx ruff check          # Static checks
uvx ruff check --fix    # Auto-fix
uvx ruff format         # Format

Tests

uv run pytest -v        # Or run the pytest task in VS Code

Project Status

Contributors

Thanks to everyone who contributes to py2aspen!

Contributions of any kind are welcome: open an Issue to report problems or suggest features, or submit a Pull Request to improve the code.