exergy-imperative

Screening-grade exergy, emissions, health, and economic analysis from the industrial energy data you actually have. Give it as little as an equipment name and a country; every default it fills in stays visible, sourced, and replaceable with your own measurements.

📖 This project began as The Exergy Imperative — a complete, free guide to exergy analysis and its role in the energy transition. Read it to understand why energy quality matters; use this library to put it to work.

Why this library

Most exergy tools (TESPy, ExerPy, Aspen Plus) start from a fully specified plant simulation. Real industrial decisions usually start earlier, with a utility bill, a telemetry export, or a one-line description of a steam system. exergy-imperative works at that end of the funnel:

• Sparse input, transparent output. Progressive-fidelity assessments (F0 upward) from a bare technology name to measured site data. Every number carries provenance, a range, and warnings — screening defaults are never passed off as measurements.
• The whole business case, not just thermodynamics. Exergetic efficiency and destruction, AR6 20/100-year climate impact, air-pollutant health screening, and project economics (NPV, IRR, payback, levelized cost, marginal abatement cost) in one result.
• Industrial data plumbing built in. Auditable ingestion from CSV, Excel, Parquet, JSON, and SQL with unit conversion and mapping inference; native Excel input templates and workbook reports; weather normalization from NASA POWER; connectors for World Bank, ERA5-Land, EDGAR, eGRID, and DOE IAC data.
• Agent-native. Versioned JSON recipes with validate-only / dry-run / execute modes, stable error codes, capability discovery, and an optional MCP server so AI assistants can drive full assessments safely.
• Zero required dependencies. The core is pure Python (3.11–3.14); pandas, CoolProp, PDF, and MCP support are opt-in extras.

Install

python -m pip install exergy-imperative

Optional extras, only if you need them:

python -m pip install "exergy-imperative[data]"     # Excel / Parquet readers
python -m pip install "exergy-imperative[reports]"  # PDF reports
python -m pip install "exergy-imperative[mcp]"      # MCP server for agents
python -m pip install "exergy-imperative[all]"      # everything

Sixty seconds to a result

import exergy_imperative as xi

case = xi.assess_process("compressed air", energy=2_500, country="DEU")
print(case.summary())

Compressed-air system
Fidelity: F1
Exergetic efficiency: 0.15 dimensionless (screening range 0.08-0.25)
Climate impact: 8.24e+05 kg CO2e (100-year)
Screening energy opportunity: 500 MWh (screening range 125-875)
Warnings and limitations:
  - The improvement opportunity uses a broad template screening prior; ...

Add whatever you know — efficiency, temperatures, energy prices, capital cost, refrigerant leakage — and the fidelity, ranges, and economics tighten accordingly. Then export deliverables:

case.export_html("compressed-air.html")
case.export_pdf("compressed-air.pdf")              # [reports] extra
case.export_excel_compatible("compressed-air-data")

The same works from the command line, from JSON recipes, and from Excel templates:

exergy report examples/process_report_recipe.json --html output/report.html
exergy capabilities --json     # discovery for scripts and agents
exergy validate                # run the bundled reference checks

See the quickstart for the full tour.

What's inside

• Twelve industry process templates: steam, furnaces, compressed air, refrigeration, drying, desalination, hydrogen electrolysis, data centers, cement, steel reheat, food processing, district energy.
• Engineering screens for steam systems, heat pumps, furnaces, refrigeration, compressed air, and waste-heat matching.
• Explicit GHG boundaries (combustion, process, fugitive, purchased energy), methane vent/flare/recovery project analysis, and grid intensities for 213 countries (Ember / Our World in Data, 2020–2025).
• Monte Carlo uncertainty propagation, sensitivity ranking, and value of perfect information.
• Dependency-free SVG/HTML reports, optional PDF, and auditable Excel-compatible bundles with complete source payloads.
• Optional real-fluid physical exergy via CoolProp ([properties] extra).

When to use it — and when not to

This library is deliberately a screening tool: its thermodynamics are closed-form (Carnot factors, Gouy–Stodola, Petela, ideal-mixture separation) plus optional CoolProp real-fluid properties. Results based on bundled profiles are screening estimates with declared ranges — a triage and business-case layer that tells you where a detailed simulation or site audit is worth the money, not a substitute for one.

Data, provenance, and validation

Bundled reference data ships with sources, versions, licenses, and confidence labels: Ember/OWID electricity intensities, IPCC AR6 warming potentials, IPCC 2006 fuel factors, EPA and EMEP/EEA pollutant screening profiles. No restricted publisher data (IEA, Energy Institute) is redistributed — local adapters map your licensed copies with SHA-256 fingerprinting. Run exergy validate to execute the bundled reference calculations and see every expected value, tolerance, and citation.

Documentation

Status

0.3.0 alpha. The public Python API, CLI commands, recipe contract 1.0, packaged JSON Schemas, and MCP tools are stable surfaces within a minor version (see AGENTS.md). Contributions are welcome — especially reviewed profiles, validation cases against published literature, and dataset adapters; see CONTRIBUTING.md.

License and citation

Code is Apache-2.0. The guide, explanatory documentation, and bundled profile data are CC BY 4.0; third-party data attributions are listed in NOTICE. Cite via CITATION.cff.

Published by Exergy Lab — a platform for accelerating scientific discovery and technological innovation, purpose-built for energy and deep-tech industries. Free for anyone to use.