API Documentation

The ExerPy package offers a flexible, Python-based solution for conducting exergy, economic and exergoeconomic analysis of energy-conversion systems. The current release supports integration with three simulation tools (Ebsilon Professional, Aspen Plus, and TESPy) and allows users to extract detailed simulation data on components and connections. The framework follows a structured workflow that includes data parsing, physical and chemical exergy calculations, and the generation of comprehensive exergy analysis results, and continues with the sizes and the costs of the components up to the cost of every stream.

This section provides detailed information about the Application Programming Interface (API) of ExerPy. It follows the steps of the workflow:

  1. Parsing and Data Preparation

  2. Exergy Analysis

  3. Component Sizing

  4. Economic Analysis

  5. Exergoeconomic Analysis

The results of the exergy analysis can also be shown as Sankey and waterfall diagrams, see the visualization example.

1. Model Parsing and Data Preparation

ExerPy supports parsing models from different simulation tools to extract and prepare data for exergy calculations:

Supported Simulation Tools

Tool

Description

License type

Supported version

Operating system

Ebsilon Professional

A comprehensive tool for simulating and analyzing energy systems, particularly in the field of power plant engineering.

Commercial

17.0

Windows

Aspen Plus

A powerful process simulation software used for designing and optimizing chemical processes.

Commercial

14.5

Windows

TESPy

A versatile Python package for simulating thermal energy systems.

Open Source

0.11.3 or later

Windows, macOS, Linux

Note

Note that Ebsilon Professional and Aspen Plus require a valid commercial license for use. Additionally, while these tools are designed only for Windows, they can also be operated on macOS or Linux through the use of a virtual machine. For Ebsilon Professional, a valid license including EBSOpen is required to enable the API connection.

Supported components

ExerPy supports a wide range of components from the simulation tools. For Ebsilon Professional, the following components are supported:

exerpy.parser.from_ebsilon.ebsilon_config.grouped_components

This is the mapping of component groups to their respective component IDs:

  • “Turbine”: [6, 23, 56, 57, 58, 68, 122],

  • “HeatExchanger”: [7, 10, 25, 26, 27, 43, 47, 51, 55, 61, 62, 70, 71, 78, 124, 126],

  • “CombustionChamber”: [22, 90],

  • “Valve”: [2, 13, 14, 39, 42, 59, 68, 133],

  • “Pump”: [8, 44, 83, 159],

  • “Compressor”: [24, 94],

  • “Deaerator”: [9, 63],

  • “Drum”: [20],

  • “SimpleHeatExchanger”: [15, 16, 35, 91],

  • “SteamGenerator”: [5],

  • “Mixer”: [3, 28, 37, 38, 49, 60, 102, 141, 161],

  • “FlashTank” : [34],

  • “Storage”: [118],

  • “Splitter”: [4, 17, 18, 19, 52, 109, 140, 157],

  • “CycleCloser”: [80],

  • “PowerBus”: [31]

Components 88 (flue gas zone) and 89 (main heating surface) are not listed here: each 88/89 pair models the two sides of a single heat exchanger and is merged by the parser into one “HeatExchanger” whose name is <name of 89>_<name of 88>.

For Aspen Plus, the supported components include:

exerpy.parser.from_aspen.aspen_config.grouped_components

This is the mapping of component groups to their respective component IDs:

  • “Turbine”: [‘Compr’],

  • “HeatExchanger”: [‘HeatX’],

  • “CombustionChamber”: [‘RStoic’],

  • “Valve”: [‘Valve’],

  • “Pump”: [‘Pump’],

  • “Compressor”: [‘Compr’],

  • “SimpleHeatExchanger”: [‘Heater’],

  • “Mixer”: [‘Mixer’],

  • “Splitter”: [‘FSplit’],

  • “Generator”: [‘Gen’],

  • “Motor”: [‘Motor’]

For TESPy, the supported components include:

exerpy.parser.from_tespy.tespy_config.EXERPY_TESPY_MAPPINGS

This is the mapping of component groups to their name in TESPy:

  • “SteamTurbine”: “Turbine”,

  • “HeatExchanger”: “HeatExchanger”,

  • “MovingBoundaryHeatExchanger”: “HeatExchanger”,

  • “Desuperheater”: “HeatExchanger”,

  • “MovingBoundaryHeatExchanger”: “HeatExchanger”,

  • “Condenser”: “HeatExchanger”,

  • “SimpleHeatExchanger”: “SimpleHeatExchanger”,

  • “ParabolicTrough”: “ParabolicTrough”,

  • “Pipe”: “SimpleHeatExchanger”,

  • “SolarCollector”: “SimpleHeatExchanger”,

  • “CombustionChamber”: “CombustionChamber”,

  • “DiabaticCombustionChamber”: “CombustionChamber”,

  • “Valve”: “Valve”,

  • “Compressor”: “Compressor”,

  • “Pump”: “Pump”,

  • “Turbine”: “Turbine”,

  • “Merge”: “Mixer”,

  • “Generator”: “Generator”,

  • “Motor”: “Motor”,

  • “Drum”: “Drum”,

  • “CycleCloser”: “CycleCloser”,

  • “Splitter”: “Splitter”,

  • “DropletSeparator”: “FlashTank”,

  • “PowerBus”: “PowerBus”,

We are continuously working to expand the list of supported components, so please refer to the latest documentation for updates. If you need to parse a component that is not yet supported, please contact us or open an issue on the GitHub repository.

Inputs

This module requires the user to provide the following inputs:

  • Simulation model: The model file from the supported simulation tools (e.g., Ebsilon Professional .ebs, Aspen Plus .bkp, or TESPy scripts).

  • Parsing method: The appropriate method (from_aspen, from_ebsilon or from_tespy) based on the simulation tool used.

  • Ambient Conditions (optional): Ambient temperature (Tamb) and pressure (pamb). By default, the reference state of the simulation model is used. Values passed here replace it, and all exergies are computed at them.

  • Chemical Exergy Library (optional): The library used for calculating chemical exergy. Currently only the Ahrendts model is supported.

Example:

from exerpy import ExergyAnalysis
model_path = 'my_model.ebs'
ean = ExergyAnalysis.from_ebsilon(model_path, chemExLib='Ahrendts')

Note

Profiles (Ebsilon only). An Ebsilon model can hold several profiles, i.e. operating points of the same plant such as part-load or seasonal cases. They form a tree: the root profile holds the design case and its children hold the deviations. ExerPy simulates and analyses one profile at a time, by default the one the model was saved with.

Use get_ebsilon_profiles to see which profiles a model contains. It opens the model without simulating it and returns the name, id, parent and active flag of each profile:

from exerpy.parser.from_ebsilon.ebsilon_parser import get_ebsilon_profiles

for profile in get_ebsilon_profiles('my_model.ebs'):
    print(profile)
# {'name': 'Design', 'id': 0, 'parent': None, 'active': True}
# {'name': 'Part load 50%', 'id': 1, 'parent': 'Design', 'active': False}

Pass one of them as profile (name or id) to analyse that operating point. The profile is activated before the simulation runs, so all results refer to it. An unknown name raises a ValueError listing the available profiles:

ean = ExergyAnalysis.from_ebsilon(
    'my_model.ebs', chemExLib='Ahrendts', profile='Part load 50%'
)

A part-load study is then a loop over the profiles, for instance:

for profile in get_ebsilon_profiles('my_model.ebs'):
    ean = ExergyAnalysis.from_ebsilon(
        'my_model.ebs', chemExLib='Ahrendts', profile=profile['name']
    )
    ean.analyse(E_F=fuel, E_P=product, E_L=loss)
    ean.export_to_json(f"results/{profile['name']}.json")

The same argument is available in run_ebsilon, which returns the parsed data of a single profile without performing the analysis.

The parsing process involves the following key steps:

1. Initialization and Simulation: ExerPy initializes the model by connecting to the chosen simulation tool. If required, it runs the simulation to ensure all the latest data are available.

2. Data Extraction: Extracts detailed information about components and connections, including properties like temperature, pressure, mass flow, enthalpy, and entropy. All data are converted to SI units for consistency.

3. Ambient Conditions: Retrieves or sets ambient conditions (Tamb and pamb), which are essential for exergy calculations. These can be sourced from the model or specified by the user.

4. Physical Exergy Calculation: Imports or calculates mechanical and thermal exergy values using the extracted properties. This ensures consistency in fluid property models between the simulation and the exergy calculations.

5. Chemical Exergy Calculation: Calculates chemical exergy based on material composition, utilizing the Ahrendts reference environment.

6. Data Storage: Saves the parsed data and exergy calculations into a JSON file for subsequent analysis.

It is possible to provide a JSON file containing the connection and component data in the format described in JSON format. This file must include information on the physical exergy values (mechanical and thermal), as ExerPy does not calculate them itself. In this case, the method from_json should be used to load the data. The chemical exergy calculation is then performed based on the provided data and the Ahrendts reference environment.

Outputs

The output of this first module is a JSON file containing all the extracted data and calculated exergy values. This JSON file serves as the primary input for the exergy analysis module.

2. Exergy Analysis

The exergy analysis module provides tools for evaluating system performance at both the component and system levels. Key capabilities include:

  1. Exergy Analysis of Components: Evaluates the exergy destruction and efficiency of individual components within the system.

  2. Exergy Analysis of the Entire System: Assesses the overall exergy balance, including the exergy of fuel, product, and losses, to determine system-wide efficiency and irreversibilities.

The method used to perform the exergy analysis is analyse. This method takes the parsed data as input and conducts the component-level exergy analysis based on the specified parameters.

Inputs

The exergy analysis in ExerPy requires three structured inputs, each defined by a dictionary of connection IDs. These inputs represent the exergy flows associated with the fuel, product, and losses in the system. All connections entering or leaving the system must be specified, as they are essential for calculating the exergy balance.

  • Exergy of the fuel (E_F):

    • inputs: flows entering the system that supply the exergy used to obtain the product (e.g., fuel flow to a combustion chamber or an inlet flow of a hot stream)

    • outputs: streams leaving the system that reduce the fuel exergy (e.g., outlet flow of a cold stream)

  • Exergy of the product (E_P):

    • inputs: flows leaving the system counted as useful output (e.g., the power flow from a generator)

    • outputs: flows entering the system that reduce the net product (e.g., the power flow to a motor)

  • Exergy loss (E_L):

    • inputs: flows leaving the system and released to the environment (e.g., exhaust gases, cold outlet flow of a condenser in a steam cycle)

    • outputs: flows entering the system that will later exit as losses (e.g., cold inlet flow of a condenser in a steam cycle)

Note

Solar thermal components (Ebsilon only). The heliostat field, parabolic trough and solar tower are currently produced only by the Ebsilon parser (from_ebsilon); the Aspen and TESPy parsers do not provide solar components. These components receive their exergy from incoming solar radiation, which the parser represents as a synthetic <name>_Q heat connection (there is no ordinary inlet stream carrying it). To declare this solar input as fuel, put the name of the component — not a connection name — in E_F["inputs"], e.g. {"inputs": ["SF"], "outputs": []} for a heliostat field named SF. ExerPy resolves the component name to its <name>_Q connection automatically. The same applies if such a flow ever needs to appear in E_P or E_L.

from exerpy import ExergyAnalysis
model_path = 'my_model.ebs'
ean = ExergyAnalysis.from_ebsilon(model_path)

fuel = {"inputs": ['1'], "outputs": ['3']}
product = {"inputs": ['E1'], "outputs": ['E2']}
loss = {"inputs": ['13'], "outputs": ['11']}

ean.analyse(E_F=fuel, E_P=product, E_L=loss)

Outputs

The results of the exergy analysis can be printed to the console:

ean.exergy_results()

Alternatively, they can be stored in separate pandas.DataFrames for further analysis:

df_comps, df_material_conns, df_non_material_conns = ean.exergy_results()

The results include the following key parameters:

  • Fuel exergy (E_F) in kW

  • Product exergy (E_P) in kW

  • Exergy destruction (E_D) in kW

  • Exergy loss (E_L) in kW

  • Exergy efficiency (epsilon) in %

  • Exergy destruction ratio (y and y_star) in %

These values are provided both for each component and for the entire system.

ean.export_to_json("results.json") saves the model and these results, every value with its unit. See JSON format for the format and for exporting in other units.

3. Component Sizing

The module exerpy.costing reads the sizes of the components from the analysed plant, for the cost functions of the economic analysis: the power, the mass flow, the inlet volume flow and the pressure ratio of turbomachines, the power of motors and generators, the heat flow of heat exchangers, and the area of a heat exchanger from its sections, with the heat transfer coefficients of the user or the defaults of comparable cells. It also gives access to the cost correlations of OpenPyTEA [8], with pip install exerpy[costs].

Inputs

  • The analysed plant: the components of an ExergyAnalysis.

  • For the area of a heat exchanger, optionally the exchanger type (exchanger_type), the coefficients (U) and the method (method), see What to give.

  • For a cost estimate with OpenPyTEA, the key of the correlation.

Outputs

sizes() returns every size the model determines, in SI units, and estimate() the purchased equipment cost of a correlation with its reference year, the size it used and how that size fits the range of the correlation:

from exerpy import costing

costing.sizes(ean.components["COMP"])            # {"power": ..., "mass_flow": ..., ...}
costing.size(ean.components["EVA"], "area", exchanger_type="finned_tube")

See Component Sizing for the method.

4. Economic Analysis

EconomicAnalysis turns the purchased equipment costs of the components into their cost rates \(\dot{Z}\) with the total revenue requirement method [2], carries costs from different years to the base year with a plant cost index, and levelizes the cost of the streams entering the plant.

Inputs

  • Purchased equipment costs: known costs, costs scaled from a reference component, user-defined cost equations or the correlations of OpenPyTEA, see Where the purchased equipment costs come from.

  • Economic parameters: the effective rate of return, the lifetime, the operating hours, the installation factor and the maintenance share; optionally the reference years, the base year, the plant cost index, the costs of the entering streams, the escalation rate and the currency.

The same inputs can be given in a JSON file, read with from_json().

Outputs

economic_results() returns the cost rates of the components and the levelized costs of the plant, and compute_costs() the cost dictionary of the exergoeconomic analysis:

from exerpy import EconomicAnalysis

economic = EconomicAnalysis.from_json("costs.json")
economic.economic_results(ean)
costs = economic.compute_costs(ean)              # input of the exergoeconomic analysis

See Economic Analysis for the method.

5. Exergoeconomic Analysis

The exergoeconomic analysis module extends exergy analysis by allocating monetary costs to all exergy streams in the system. It solves a linear equation system based on the SPECO method (Specific Exergy Costing) to determine cost rates and specific costs for every connection and component.

Note

With split_physical_exergy=True a material stream carries a cost rate for its thermal (C^T) and one for its mechanical exergy (C^M). With False it carries a single cost rate for its physical exergy (C^PH) instead. The split resolves the fuel and the product of a component more finely, so the two settings do not give the same specific costs. Below the ambient temperature the split is needed to charge the cold exergy of a stream to the product of the component producing it; without it such a component either keeps the cold exergy in its outlet stream or turns dissipative, and a warning says so. The two settings are compared on the CGAM process in Split Physical Exergy in Exergoeconomics.

Inputs

The exergoeconomic analysis requires the following inputs:

  • Completed ExergyAnalysis: An ExergyAnalysis instance on which analyse() has already been called.

  • Cost dictionary: A dictionary containing:

    • Component investment costs: "<component_name>_Z" in currency/h (mandatory for all components except CycleCloser, PowerBus and Splitter)

    • Input stream costs: "<connection_name>_c" in currency/GJ (mandatory for all streams entering the system boundary). A material stream can also have a cost per exergy form, "<connection_name>_c_T", "_c_M", "_c_PH" or "_c_CH", see Cost input format.

    Another unit in the same currency can be given next to a value, e.g. "10_c_unit": "EUR / MWh".

    Both can be typed in, as below, or obtained from the economic analysis with compute_costs().

from exerpy import ExergoeconomicAnalysis

eco = ExergoeconomicAnalysis(ean)

costs = {
    "COMP_Z": 80.0,   # Component investment cost [EUR/h]
    "CC_Z": 30.0,
    "1_c": 0.0,        # Input stream cost [EUR/GJ]
    "10_c": 10.0,
}

eco.run(costs)

Outputs

The results are retrieved using the exergoeconomic_results method, which returns four pandas.DataFrames:

df_comp, df_mat_props, df_mat_costs, df_non_mat = eco.exergoeconomic_results()

The results include:

  • Component results: Cost of fuel (C_F), cost of product (C_P), cost of exergy destruction (C_D), investment cost rate (Z), share of the cost of the dissipative components charged to the component (Z_diss), total cost (C_D+Z), exergoeconomic factor (f), and relative cost difference (r)

  • Material connection costs: Thermal (C_T), mechanical (C_M), chemical (C_CH), and total (C_TOT) cost rates with their specific costs

  • Non-material connection costs: Total cost rate (C_TOT) and specific cost (c_TOT) for power and heat streams

eco.export_to_json("costs.json") saves the model with the costs of every stream and component, each with its unit.

Additionally, the evaluate_results method identifies the components with the highest cost improvement potential:

eco.evaluate_results(sort_by="C_D+Z", top_n=5)

API References