exerpy.analyses¶

class exerpy.analyses.EconomicAnalysis(pars)[source]¶

Bases: object

Perform economic analysis of a power plant using the total revenue requirement method.

Parameters:

pars (dict) – Dictionary containing the following keys: - tau: Full load hours of the plant (hours/year) - i_eff: Effective rate of return (yearly based) - n: Lifetime of the plant (years) - r_n: Nominal escalation rate (yearly based)

Variables:

tau (float) – Full load hours of the plant (hours/year).
i_eff (float) – Effective rate of return (yearly based).
n (int) – Lifetime of the plant (years).
r_n (float) – Nominal escalation rate (yearly based).

compute_celf()[source]¶

Compute the Cost Escalation Levelization Factor (CELF) for repeating expenditures.

Returns:: float – The cost escalation levelization factor.

Notes

k = (1 + r_n) / (1 + i_eff) CELF = ((1 - k**n) / (1 - k)) * CRF

compute_component_costs(PEC_list, OMC_relative)[source]¶

Compute the cost rates for each component.

Parameters:

PEC_list (list of float) – The purchasing equipment cost (PEC) of each component (in currency).
OMC_relative (list of float) – For each component, the first-year OM cost as a fraction of its PEC.

Returns:

tuple – (Z_CC, Z_OM, Z_total) where: - Z_CC: List of investment cost rates per component (currency/hour) - Z_OM: List of operating and maintenance cost rates per component (currency/hour) - Z_total: List of total cost rates per component (currency/hour)

compute_crf()[source]¶

Compute the Capital Recovery Factor (CRF) using the effective rate of return.

Returns:: float – The capital recovery factor.

Notes

CRF = i_eff * (1 + i_eff)**n / ((1 + i_eff)**n - 1)

compute_levelized_investment_cost(total_PEC)[source]¶

Compute the levelized investment cost (annualized investment cost).

Parameters:: total_PEC (float) – Total purchasing equipment cost (PEC) across all components.
Returns:: float – Levelized investment cost (currency/year).

class exerpy.analyses.ExergoeconomicAnalysis(exergy_analysis_instance, currency='EUR')[source]¶

Bases: object

” This class performs exergoeconomic analysis on a previously completed exergy analysis. It takes the results from an ExergyAnalysis instance and builds upon them to conduct a complete exergoeconomic analysis. It constructs and solves a system of linear equations to determine the costs (both total and specific) associated with each exergy stream in the system, and calculates various exergoeconomic indicators for each component.

Variables:

exergy_analysis (ExergyAnalysis) – The exergy analysis instance used as the basis for calculations.
connections (dict) – Dictionary of all energy/material connections in the system.
components (dict) – Dictionary of all components in the system.
chemical_exergy_enabled (bool) – Flag indicating if chemical exergy is considered in calculations.
E_F_dict (dict) – Dictionary mapping fuel streams to components.
E_P_dict (dict) – Dictionary mapping product streams to components.
E_L_dict (dict) – Dictionary mapping loss streams to components.
num_variables (int) – Number of cost variables in the exergoeconomic equations.
variables (dict) – Dictionary mapping variable indices to variable names.
equations (dict) – Dictionary mapping equation indices to equation types.
currency (str) – Currency symbol used in cost reporting.
system_costs (dict) – Dictionary of system-level costs after analysis.

initialize_cost_variables()[source]¶: Defines and indexes all cost variables in the system.

assign_user_costs(Exe_Eco_Costs)[source]¶: Assigns user-defined costs to components and input streams.

construct_matrix(Tamb)[source]¶: Constructs the linear equation system for exergoeconomic analysis.

solve_exergoeconomic_analysis(Tamb)[source]¶: Solves the cost equations and assigns results to connections and components.

run(Exe_Eco_Costs, Tamb)[source]¶: Executes the complete exergoeconomic analysis workflow.

exergoeconomic_results(print_results=True)[source]¶: Displays and returns tables of exergoeconomic analysis results.

assign_user_costs(Exe_Eco_Costs)[source]¶

Assign component and connection costs from user input dictionary.

Parameters:: Exe_Eco_Costs (dict) – Dictionary containing cost assignments for components and connections. Format for components: “<component_name>_Z”: cost_value [currency/h] Format for connections: “<connection_name>_c”: cost_value [currency/GJ]
Raises:: ValueError – If a component cost is missing or if a required input connection cost is not provided.

Notes

Component costs are converted from [currency/h] to [currency/s]. Connection costs are converted from [currency/GJ] to [currency/J]. Material connections receive c_T, c_M, c_CH cost breakdowns. Heat and power connections receive only c_TOT values.

check_cost_balance(tol=1e-06)[source]¶

Check the exergoeconomic cost balance for each component.

For each component, verify that sum of inlet C_TOT minus sum of outlet C_TOT plus component Z_costs equals zero within the given tolerance.

Parameters:: tol (float, optional) – Numerical tolerance for balance check (default is 1e-6).
Returns:: dict – Mapping from component name to tuple (balance, is_balanced), where balance is the residual and is_balanced is True if abs(balance) <= tol.

construct_matrix()[source]¶

Construct the exergoeconomic cost matrix and vector.

Returns:: tuple – A tuple containing: - A: numpy.ndarray - The coefficient matrix for the linear equation system - b: numpy.ndarray - The right-hand side vector for the linear equation system

Notes

This method constructs a system of linear equations that includes: 1. Cost balance equations for each productive component 2. Equations for inlet streams to fix their costs based on provided values 3. Auxiliary equations for power flows 4. Custom auxiliary equations from each component 5. Special equations for dissipative components

detect_linear_dependencies(tol_strict: float = 1e-12, tol_near: float = 1e-08)[source]¶

Scan A for zero-rows, zero-cols, pairwise colinear equation pairs, and use SVD null-space analysis to identify multi-equation dependencies.

The SVD analysis finds the actual null space of A^T, revealing which equations participate in linear dependencies even when no two equations are pairwise colinear.

distribute_all_Z_diff(C_solution)[source]¶

Distribute every dissipative cost-difference (the C_diff variables) among all components according to their serving_weight.

Parameters:: C_solution (array_like) – Solution vector of cost variables from the solved linear system.

evaluate_results(top_n=5, sort_by='C_D+Z')[source]¶

Analyze and print the most important components from the exergoeconomic analysis.

This method ranks components by the selected criterion and prints a summary table highlighting where the highest cost increases occur and whether they are driven by investment (Z) or by inefficiency (C_D).

Parameters:

top_n (int, optional) – Number of top components to display (default is 5).
sort_by (str, optional) – Column to sort by. Valid options:
- "C_D+Z" : total cost rate of exergy destruction plus investment (default)
- "C_D" : cost rate of exergy destruction (inefficiency-driven cost)
- "Z" : investment cost rate
- "r" : relative cost difference [%]
- "f" : exergoeconomic factor [%]

Returns:

pandas.DataFrame – The sorted component DataFrame (excluding the TOT row).

Notes

The exergoeconomic factor f indicates whether the cost increase in a component is dominated by investment (f close to 100 %) or by exergy destruction (f close to 0 %). A low f suggests that improving component efficiency would be more effective, while a high f suggests that reducing investment cost is the priority.

exergoeconomic_results(print_results=True)[source]¶

Displays tables of exergoeconomic analysis results with columns for costs and economic parameters for each component, and additional cost information for material and non-material connections.

Parameters:: print_results (bool, optional) – If True, prints the results as tables in the console (default is True).
Returns:: tuple of pandas.DataFrame – (df_component_results, df_material_connection_results_part1, df_material_connection_results_part2, df_non_material_connection_results) with the exergoeconomic analysis results.

initialize_cost_variables()[source]¶

Initialize cost variables for the exergoeconomic analysis.

This method assigns unique indices to each cost variable in the matrix system and populates a dictionary mapping these indices to variable names.

For material streams, separate indices are assigned for thermal, mechanical, and chemical exergy components when chemical exergy is enabled (otherwise only thermal and mechanical). For non-material streams (heat, power), a single index is assigned for the total exergy cost.

Notes

The assigned indices are used for constructing the cost balance equations in the matrix system that will be solved to find all cost variables.

print_dependency_report(tol_strict: float = 1e-12, tol_near: float = 1e-08)[source]¶: Nicely print which equations or variables are under- or over-determined, distinguishing exact vs. near colinearities, and showing SVD null-space analysis.

print_equations()[source]¶

Get mapping of equation indices to equation descriptions.

Returns:: dict – Keys are equation indices (int), values are equation descriptions (str).

print_variables()[source]¶

Get mapping of variable indices to variable names.

Returns:: dict – Keys are variable indices (int), values are variable names (str).

run(Exe_Eco_Costs, allow_singular=False)[source]¶

Execute the full exergoeconomic analysis.

Parameters:

Exe_Eco_Costs (dict) – Dictionary containing cost assignments for components and connections. Format for components: “<component_name>_Z”: cost_value [currency/h] Format for connections: “<connection_name>_c”: cost_value [currency/GJ]
allow_singular (bool, optional) – If True, use least-squares solver as fallback when the matrix is singular. The solution may not be physically consistent. Default is False.

Notes

This method performs the complete exergoeconomic analysis by: 1. Initializing cost variables for all components and streams 2. Assigning user-defined costs to components and boundary streams 3. Solving the system of exergoeconomic equations

solve_exergoeconomic_analysis(allow_singular=False)[source]¶

Solve the exergoeconomic cost balance equations and assign the results to connections and components.

Parameters:: allow_singular (bool, optional) – If True, use least-squares solver as fallback when the matrix is singular. The solution may not be physically consistent. Default is False.
Returns:: tuple – (exergy_cost_matrix, exergy_cost_vector) - The coefficient matrix and right-hand side vector used in the linear equation system.
Raises:: ValueError – If the exergoeconomic system is singular (and allow_singular is False) or if the cost balance is not satisfied.

Notes

This method performs the following steps: 1. Constructs the exergoeconomic cost matrix 2. Solves the system of linear equations 3. Assigns cost solutions to connections 4. Calculates component exergoeconomic indicators 5. Distributes loss stream costs to product streams 6. Computes system-level cost variables

class exerpy.analyses.ExergyAnalysis(component_data, connection_data, Tamb, pamb, chemExLib=None, split_physical_exergy=True)[source]¶

Bases: object

This class performs exergy analysis on energy system models from various simulation tools. It parses input data, constructs component objects, calculates exergy flows, and provides a comprehensive exergy balance for the overall system and individual components. The class supports importing data from TESPy, Aspen, Ebsilon, or directly from JSON files.

Variables:

Tamb (float) – Ambient temperature in K for reference environment.
pamb (float) – Ambient pressure in Pa for reference environment.
_component_data (dict) – Raw component data from the input model.
_connection_data (dict) – Raw connection data from the input model.
chemExLib (object, optional) – Chemical exergy library for chemical exergy calculations.
chemical_exergy_enabled (bool) – Flag indicating if chemical exergy calculations are enabled.
split_physical_exergy (bool) – Flag indicating if physical exergy is split into thermal and mechanical components.
components (dict) – Dictionary of component objects constructed from input data.
connections (dict) – Dictionary of connection data with exergy values.
E_F (float) – Total fuel exergy for the overall system in W.
E_P (float) – Total product exergy for the overall system in W.
E_L (float) – Total loss exergy for the overall system in W.
E_D (float) – Total exergy destruction for the overall system in W.
E_F_dict (dict) – Dictionary specifying fuel connections.
E_P_dict (dict) – Dictionary specifying product connections.
E_L_dict (dict) – Dictionary specifying loss connections.
epsilon (float) – Overall exergy efficiency of the system.

analyse(E_F, E_P, E_L={})[source]¶: Performs exergy analysis based on specified fuel, product, and loss definitions.

from_tespy(model, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶: Creates an instance from a TESPy network model.

from_aspen(path, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶: Creates an instance from an Aspen model file.

from_ebsilon(path, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶: Creates an instance from an Ebsilon model file.

from_json(json_path, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶: Creates an instance from a JSON file containing system data.

exergy_results(print_results=True)[source]¶: Displays and returns tables of exergy analysis results.

plot_exergy_waterfall(title=None, figsize=(12, 10), exclude_components=None, show_plot=True)[source]¶: Creates an exergy destruction waterfall diagram visualizing exergy flow through the system.

print_exergy_summary()[source]¶: Prints a concise text summary of the exergy analysis results.

export_to_json(output_path)[source]¶: Exports the model and analysis results to a JSON file.

_serialize()[source]¶

analyse(E_F, E_P, E_L=None) → None[source]¶

Run the exergy analysis for the entire system and calculate overall exergy efficiency.

Parameters:

E_F (dict) – Dictionary containing input connections for fuel exergy (e.g., {“inputs”: [“1”, “2”]}).
E_P (dict) – Dictionary containing input and output connections for product exergy (e.g., {“inputs”: [“E1”], “outputs”: [“T1”, “T2”]}).
E_L (dict, optional) – Dictionary containing input and output connections for loss exergy (default is {}).

exergy_results(print_results=True)[source]¶

Displays a table of exergy analysis results with columns for E_F, E_P, E_D, and epsilon for each component, and additional information for material and non-material connections.

CycleCloser components are excluded from the component results.

Parameters:: print_results (bool, optional) – If True, prints the results as tables in the console (default is True).
Returns:: tuple of pandas.DataFrame – (df_component_results, df_material_connection_results, df_non_material_connection_results) with the exergy analysis results.

export_to_json(output_path)[source]¶

Export the model to a JSON file.

Parameters:: output_path (str) – Path where the JSON file will be saved.
Returns:: None – The model is saved to the specified path.

Notes

This method serializes the model using the internal _serialize method and writes the resulting data to a JSON file with indentation. NaN values are converted to null for valid JSON output.

classmethod from_aspen(path, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶

Create an instance of the ExergyAnalysis class from an Aspen model file.

Parameters:

path (str) – Path to the Aspen file (.bkp format).
Tamb (float, optional) – Ambient temperature for analysis, default is None.
pamb (float, optional) – Ambient pressure for analysis, default is None.
chemExLib (str, optional) – Name of the chemical exergy library (if any).
split_physical_exergy (bool, optional) – If True, separates physical exergy into thermal and mechanical components.

Returns:

ExergyAnalysis – An instance of the ExergyAnalysis class with parsed Aspen data.

classmethod from_ebsilon(path, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶

Create an instance of the ExergyAnalysis class from an Ebsilon model file.

Parameters:

path (str) – Path to the Ebsilon file (.ebs format).
Tamb (float, optional) – Ambient temperature for analysis, default is None.
pamb (float, optional) – Ambient pressure for analysis, default is None.
chemExLib (str, optional) – Name of the chemical exergy library (if any).
split_physical_exergy (bool, optional) – If True, separates physical exergy into thermal and mechanical components.

Returns:

ExergyAnalysis – An instance of the ExergyAnalysis class with parsed Ebsilon data.

classmethod from_json(json_path: str, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=None)[source]¶

Create an ExergyAnalysis instance from a JSON file.

Parameters:

json_path (str) – Path to JSON file containing component and connection data.
Tamb (float, optional) – Ambient temperature in K. If None, extracted from JSON.
pamb (float, optional) – Ambient pressure in Pa. If None, extracted from JSON.
chemExLib (str, optional) – Name of chemical exergy library to use. Default is None.

Returns:

ExergyAnalysis – Configured instance with data from JSON file.

Raises:

FileNotFoundError – If JSON file does not exist.
ValueError – If JSON structure is invalid or missing required data.
JSONDecodeError – If JSON file is malformed.

classmethod from_tespy(model: str, Tamb=None, pamb=None, chemExLib=None, split_physical_exergy=True)[source]¶

Create an instance of the ExergyAnalysis class from a tespy network or a tespy network export structure.

Parameters:

model (str | tespy.networks.network.Network) – Path to the tespy Network export or the actual Network instance.
Tamb (float, optional) – Ambient temperature for analysis, default is None.
pamb (float, optional) – Ambient pressure for analysis, default is None.
chemExLib (str, optional) – Name of the library for chemical exergy tables.

Returns:

ExergyAnalysis – Instance of the ExergyAnalysis class.

plot_exergy_waterfall(title=None, figsize=(12, 10), exclude_components=None, show_plot=True)[source]¶

Create an exergy destruction waterfall diagram.

This method visualizes the exergy flow through the system as a waterfall chart, showing how exergy is destroyed in each component from the exergetic fuel (100%) down to the exergetic product and losses.

Parameters:

title (str, optional) – Title for the plot. If None, no title is displayed.
figsize (tuple, optional) – Figure size as (width, height) in inches. Default is (12, 10).
exclude_components (list, optional) – List of component names to exclude from the diagram. By default, all components with NaN E_F (Exergetic Fuel) are excluded, as well as CycleCloser and PowerBus components.
show_plot (bool, optional) – Whether to display the plot immediately. Default is True.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the waterfall diagram.
ax (matplotlib.axes.Axes) – The axes object of the waterfall diagram.

Raises:

RuntimeError – If the exergy analysis has not been performed yet (analyse() not called).

Notes

The waterfall diagram displays exergy values as percentages of the total fuel exergy.
Components are sorted by their exergy destruction rate (y [%]) in descending order.
Each bar represents the remaining exergy after destruction in that component.
Red bars indicate exergy destruction in components.
Blue bar represents the initial exergetic fuel (100%).
Green bar represents the final exergetic product.

Examples

>>> analysis = ExergyAnalysis.from_tespy(network, Tamb=288.15, pamb=101325)
>>> analysis.analyse(E_F={'inputs': ['fuel']}, E_P={'outputs': ['power']})
>>> fig, ax = analysis.plot_exergy_waterfall(title='Power Plant Exergy Waterfall')
>>> fig.savefig('exergy_waterfall.pdf')