exerpy.parser

Parsers that read the models of simulation tools into ExerPy’s input format.

exerpy.parser.STATE_CHECK_STEP = 0.05

Temperature step in K below and above a stream’s temperature for state_between().

exerpy.parser.state_between(h, s, below, above, rtol=1e-07)

Whether the enthalpy h and entropy s of a stream lie between their values below and above.

below and above are (h, s) at the stream’s pressure and its temperature minus and plus STATE_CHECK_STEP, from the property calculation that splits the physical exergy. The stream’s own values lie between them, also when it is saturated or two-phase, unless the split uses other property data than the simulator used for the stream.

>>> state_between(100.0, 1.0, (99.9, 0.99), (100.1, 1.01)), state_between(100.0, 1.0, (100.1, 1.0), (100.2, 1.0))
(True, False)

exerpy.parser.from_ebsilon

Ebsilon Model Parser

This module defines the EbsilonModelParser class, which is used to parse Ebsilon models, simulate them, extract data about components and connections, and write the data to a JSON file.

class exerpy.parser.from_ebsilon.ebsilon_parser.EbsilonModelParser(model_path: str, split_physical_exergy: bool = True, Tamb: float | None = None, pamb: float | None = None, profile: str | int | None = None)

Bases: object

A class to parse Ebsilon models, simulate them, extract data, and write to JSON.

Reference state

The model has to define it with two measuring points (component 46): one with FTYP = 26 for the ambient temperature and one with FTYP = 13 for the ambient pressure, each holding its value in MEASM. Measuring points of these types without a value are ignored, several of the same type are accepted as long as they agree, and conflicting ones raise an error. Values passed as Tamb and pamb take precedence over the model and are used for all exergies. If they differ from the measuring points, or the model has none, the physical exergy of a stream is computed at them from its fluid data instead of taken from the exergy E of the pipe, which Ebsilon computes at the measuring points.

Steam generator heating surfaces

A flue gas zone (component 88) and its main heating surface (component 89) model the two sides of one heat exchanger and are merged into a single component; see _merge_steam_generator_surfaces().

activate_profile(profile: str | int)

Activate a profile of the model, so that it is the one being simulated and parsed.

Parameters:

profile (str or int) – Name or id of the profile.

Raises:

ValueError – If the model has no profile with that name or id.

active_profile() → str

Return the name of the profile the model is currently set to.

get_sorted_data() → dict[str, Any]

Sorts the component and connection data alphabetically by name.

Returns:

dict – A dictionary containing sorted ‘components’, ‘connections’, and ambient conditions data.

initialize_model()

Initializes the Ebsilon application and opens the specified model.

Raises:

• FileNotFoundError – If the model file cannot be opened.

• RuntimeError – If the COM server cannot be started or ObjectCaster cannot be obtained.

list_profiles() → list[dict[str, Any]]

List the profiles (operating points) of the opened model.

Ebsilon stores the profiles as a tree: the root profile holds the design case and its children hold the deviations, e.g. part load or seasonal cases. The list is returned in depth-first order.

Returns:

list – One dictionary per profile with its name, id, parent (name of the parent profile, None for the root) and whether it is currently active.

parse_component(obj: Any)

Parses data from a component, including its type and various properties.

Parameters:

obj – The Ebsilon component object to parse.

parse_connection(obj: Any)

Parses the connections (pipes) associated with a component.

Parameters:

obj – The Ebsilon component object whose connections are to be parsed.

parse_model()

Parses all objects in the Ebsilon model to extract component and connection data.

Raises:

• ValueError – If ambient conditions are not set.

• Exception – If model parsing fails.

simulate_model()

Simulates the Ebsilon model and logs the messages of the solver.

A failed calculation leaves the results of an earlier one in the model, so it is not parsed: errors, comments and warnings are logged, and a failed status raises an error.

Raises:

RuntimeError – If the calculation does not end successfully, i.e. with a status other than successful, successful with comments or successful with warnings.

write_to_json(output_path: str)

Writes the parsed and sorted data to a JSON file.

Parameters:

output_path (str) – Path where the JSON file will be saved.

Raises:

Exception – If writing to JSON fails.

exerpy.parser.from_ebsilon.ebsilon_parser.get_ebsilon_profiles(model_path: str) → list[dict[str, Any]]

List the profiles (operating points) stored in an Ebsilon model.

A model can hold several profiles, e.g. a design case and part load or seasonal cases. This opens the model without simulating it and reports which ones are available, so that one of them can be passed as the profile of run_ebsilon().

Parameters:

model_path (str) – Path to the Ebsilon model file.

Returns:

list – One dictionary per profile with its name, id, parent and active flag.

Raises:

• FileNotFoundError – If the model file is not found at the specified path.

• RuntimeError – If Ebsilon is not available.

exerpy.parser.from_ebsilon.ebsilon_parser.run_ebsilon(model_path: str, output_dir: str | None = None, split_physical_exergy: bool = True, Tamb: float | None = None, pamb: float | None = None, profile: str | int | None = None) → dict[str, Any]

Main function to process the Ebsilon model and return parsed data. Optionally writes the parsed data to a JSON file.

Parameters:

• model_path (str) – Path to the Ebsilon model file.

• output_dir (str) – Optional path where the parsed data should be saved as a JSON file.

• split_physical_exergy (bool) – Flag to split physical exergy into thermal and mechanical components.

• Tamb (float) – Ambient temperature in K. Defaults to the measuring point of the model. A value passed here overrides the model and is used for all exergies; if it differs from the model, the physical exergies are computed from the fluid data of the streams.

• pamb (float) – Ambient pressure in Pa, like Tamb.

• profile (str or int) – Name or id of the profile to simulate. Defaults to the profile the model was saved with.

Returns:

dict – Parsed data in dictionary format. Its ambient_conditions hold the ambient state the exergies were computed at.

Raises:

• FileNotFoundError – If the model file is not found at the specified path.

• RuntimeError – For any error during model initialization, simulation, parsing, or writing.

exerpy.parser.from_aspen

class exerpy.parser.from_aspen.aspen_parser.AspenModelParser(model_path, split_physical_exergy=True, Tamb=None, pamb=None)

Bases: object

A class to parse Aspen Plus models, simulate them, extract data, and write to JSON.

add_ambient_temperature_analyses(streams)

Adds a prop-set with h and s and, for each stream, a Generic analysis at the stream’s pressure and at T0 and the stream’s temperature minus and plus exerpy.parser.STATE_CHECK_STEP.

Returns:

dict – Name of the analysis and its number of temperatures for each stream.

analysis_states(analysis, stream, rows)

Reads the temperature and h and s per kg of the first rows rows of the analysis of a stream.

Returns:

list – (T in K, h in J/kg, s in J/kgK) of each row; a value without a result in Aspen is None.

assign_combustion_chamber_connectors(block_name, aspen, connections_data)

Assign connectors for a combustion chamber (RStoic), one per stream.

Inlets: oxidant streams (O2 mole fraction above 0.15) first, then fuel streams (CH4 above 0.15), then the other material streams, each group in port order. Outlets: the combustion gas at 0, taken as the material outlet with the largest mass flow since it carries the air, then the further material outlets such as ash or a water decant. Heat and work streams come last on their side, so they never replace a material stream and the combustion chamber rejects them. A heat duty (QCALC) without a heat stream gives a warning, since the exergy of that heat ends up in the exergy destruction of the combustion chamber.

assign_connectors(component_data, block_name)

Assigns connectors to streams for each component based on its type.

assign_generic_connectors(block_name, component_type, aspen, connections_data, connector_mappings)

Generic function for components with predefined connector mappings.

assign_mixer_connectors(block_name, aspen, connections_data)

Assign connectors for a Mixer by examining connected streams and their source/target components.

assign_splitter_connectors(block_name, aspen, connections_data)

Assign connectors for a Splitter (FSplit) by examining connected streams and their source/target components. The inlet stream is assigned ‘target_connector’ = 0. The outlet streams are assigned ‘source_connector’ numbers starting from 0.

assign_turbine_connectors(block_name, aspen, connections_data)

Assign connectors for a Turbine (Compr with MODEL_TYPE=TURBINE).

In Aspen, a gas turbine has up to one input and one output power connection:

• F(IN): inlet gas flow → inlet connector 0

• P(OUT): outlet gas flow → outlet connector 0

• WS(OUT): power output → outlet connector 1

• WS(IN): direction depends on the sign of the Aspen power value:

  • positive → power leaves the turbine → outlet connector 2 (source/target swapped)

  • negative → power enters the turbine → inlet connector 1 (kept as-is)

The _aspen_power_sign field (set during parse_streams) carries the sign of the raw Aspen POWER_OUT value. energy_flow is always stored as a positive value because ExerPy does not work with negative values.

static free_names(folder, stem, count)

Returns count IDs stem1, stem2, … that no element of folder uses yet.

get_sorted_data()

Sorts the component and connection data alphabetically by name.

Returns:

dict – A dictionary containing sorted ‘components’, ‘connections’, and ambient conditions data.

group_component(component_data, component_name)

Group the component based on its type into the correct group within components_data.

Parameters: - component_data: The dictionary of component attributes. - component_name: The name of the component.

initialize_model()

Initializes the Aspen Plus application and opens the specified model.

mult_block_type(block_name, factor)

Decides whether a multiplier block on work streams is a generator or a motor.

The work stream entering the block comes from its machine. Aspen reports its power as negative if the machine produces it, as a turbine does for a generator, and as positive if the machine consumes it, as a compressor or a pump does for a motor. Without this sign, a factor below 1 means a generator and a factor above 1 a motor.

Returns:

str – “Generator” or “Motor”.

orient_consumer_power()

Lets the power of a compressor or pump flow into it.

Aspen draws the work stream of a compressor from its WS(OUT) port, so the parsed stream leaves the machine, and the stream of a motor block that drives it leaves the motor towards the grid. A machine that consumes power receives it, so such streams are reversed: a stream leaving a compressor or pump now enters it on connector 1, and the stream at the other end of a motor driving it enters the motor on connector 0.

parse_ambient_conditions()

Parses the ambient conditions from the Aspen model and stores them as class attributes. Raises an error if Tamb or pamb are not found or are set to None.

parse_blocks()

Parses the blocks (components) in the Aspen model and ensures that all components, including motors created from pumps, are properly grouped.

parse_model()

Parses the components and connections from the Aspen model.

parse_streams()

Parses the streams (connections) in the Aspen model.

per_kg(path, key, molar_mass)

Reads a value per kg or per mol and returns it in the SI unit of key, per kg.

Parameters:

molar_mass (float) – Molar mass in kg/mol, to convert a value per mol.

port_power(block_name, port)

Returns the power of the first work stream at a port of a block, or None if there is none.

set_ambient_conditions()

Writes the ambient state passed to the parser to REF_TEMP and REF_PRES and runs the model again, so that Aspen computes the exergies of the streams at it. Nothing happens if no value is passed or the model holds the passed values already. The change exists in memory only; the model file stays unchanged.

Raises:

ValueError – If the model has no REF_TEMP or REF_PRES node for a passed value.

set_rows(path, values)

Inserts rows with values into the list at path.

split_physical_exergy_of_streams()

Splits the physical exergy of the material streams into a thermal part e_T and a mechanical part e_M.

A Generic property analysis per stream flashes the stream’s composition with the stream’s property method at the ambient temperature T0 and the stream’s pressure p. Then e_T = h - h(T0, p) - T0 * (s - s(T0, p)) and e_M = e_PH - e_T. The analysis also evaluates the stream just below and above its own temperature, to check that these properties reproduce the stream’s h and s. The analyses exist in memory only and take one run of the Aspen engine; the model file stays unchanged.

write_to_json(output_path)

Writes the parsed and sorted data to a JSON file.

Parameters:

output_path (str) – Path where the JSON file will be saved.

exerpy.parser.from_aspen.aspen_parser.run_aspen(model_path, output_dir=None, split_physical_exergy=True, Tamb=None, pamb=None)

Main function to process the Aspen model and return parsed data. Optionally writes the parsed data to a JSON file.

Parameters:

• model_path (str) – Path to the Aspen model file.

• output_dir (str) – Optional path where the parsed data should be saved as a JSON file.

• split_physical_exergy (bool) – Flag to split physical exergy into thermal and mechanical components.

• Tamb (float) – Ambient temperature in K. Defaults to REF_TEMP of the model. A value passed here replaces REF_TEMP and the model is run again, so all exergies are computed at it. The model file stays unchanged.

• pamb (float) – Ambient pressure in Pa, like Tamb for REF_PRES.

Returns:

dict – Parsed data in dictionary format. Its ambient_conditions hold the ambient state the exergies were computed at.