Quickstart¶

Installation¶

The package can be installed via the package manager of your choice:

pip install aspen-pysys

uv pip install aspen-pysys

Opening files¶

Dispatch the HYSYS app¶

This depends on how fast your computer opens the app but if already open, dispatching is then processed immediately:

from aspen_pysys.app import HysysApp

hysys_app = HysysApp.dispatch()

HysysApp is the main entry point for interfacing with the HYSYS app. It is essential to call the .dispatch method, even if the app is already open on your device, to ensure that the app has already dispatched.

If required, passing True to the should_log_version argument (default: False) allows for the visual indication of successfully dispatching the HYSYS app by printing the version of the app available on your device.

Open your simulation case¶

To open a Aspen HYSYS simulation file (.hsc), use the hysys_app.open(sim_filepath) method call, where sim_filepath is the filepath to your simulation file as seen below:

from pathlib import Path
from aspen_pysys.app import HysysApp

hysys_app = HysysApp.dispatch()
sim_filepath = Path("parent_folder/filename.hsc") # (1)!
simcase = hysys_app.open(sim_filepath)

1. The path to your simulation case goes here.

Data types¶

Objects retrieved via this package can be broadly sorted into one of two supertypes: HysysObject and HysysPrimitive.

Succinctly, HysysObject objects are akin to objects with properties and methods and HysysPrimitive objects represent primitive types on the HYSYS app such as constants, functions and collections like arrays and dictionaries.

For the most part, you'll be interacting with HysysObject objects, such as instances of HysysUnitOperation or HysysCase, to either retrieve other HysysObject objects or values in the form of HysysPrimitive objects, such as HysysArray or HysysFunction.

HysysObject objects¶

Since not all objects have a known structure to them, you can explore a HysysObject object's attributes by calling the .attrs() method to view all possible properties that can be accessed. For example:

separator = flowsheet.get_unit_operation("Separator")
separator.attrs()

{'AddRef',
 'Application',
 'AttachedFeeds',
 'AttachedLogicalOps',
 'AttachedProducts',
 'AvailableUA',
 'AvailableUAValue',
 'BottomOfHeater',
 'BottomOfHeaterValue',
 ...
 'VesselPressureDrop',
 'VesselPressureDropValue',
 'VesselPressureValue',
 'VesselTemperature',
 'VesselTemperatureValue',
 'VesselTotalMoles',
 'VesselTotalMolesValue',
 'VesselVolume',
 'VesselVolumeValue',
 'VisibleTypeName',
 'name'}

Accessing the flowsheet¶

Your simulation case's flowsheet contains all functionality pertaining the streams and models present on it. To access them, you must first get a reference to the flowsheet through your case object's get_flowsheet method:

from pathlib import Path
from aspen_pysys.app import HysysApp

hysys_app = HysysApp.dispatch()
sim_filepath = Path("parent_folder/filename.hsc")
simcase = hysys_app.open(sim_filepath)

flowsheet = simcase.get_flowsheet()

Process streams¶

Accessing streams by name¶

material_stream = flowsheet.get_material_stream("Material stream name")  # (1)!

energy_stream = flowsheet.get_energy_stream("Energy stream name")  # (1)!

Getting stream properties¶

A few properties are listed below but you may refer to the API reference for all supported properties:

vapour_fraction = material_stream.get_vapour_fraction()  # Vapour fraction
temperature = material_stream.temperature()              # Temperature
mass_flow = material_stream.mass_flow()                  # Mass flow

heat_flow = energy_stream.get_heat_flow()  # Heat flow

Unit operations¶

Accessing unit operations by name¶

unit_op = flowsheet.get_unit_operation("Unit operation name")  # (1)!

1. The name of your unit operation goes here.

Getting unit operation properties¶

However, unit_op, an object of type HysysUnitOperation, does not have specific functionality for the type of unit operation it is. For example, 'HX-101' might refer to a heat exchanger and you would like to retrieve its log mean temperature difference (LMTD).

You could then either:

1. (Recommended) Instantiate a HysysHeatExchanger object from unit_op and use supported methods to access commonly required properties and functionality:

   unit_op = simcase.get_unit_operation("HX-101")
   hx = HysysExchanger.from_obj(unit_op)
   lmtd = hx.get_lmtd()
   

2. Call the .get_float method after identifying the corresponding attribute on the COM object ('LMTD' in this case):

   unit_op = simcase.get_unit_operation("HX-101")
   lmtd = unit_op.get_float("LMTD")
   

However, since not all unit operation types are supported by this package, the second option can be used in the absence of support for your unit operation.