×

Mission

CAPE-OPEN

COCO

Excel Thermo Import

Excel Unit Operation

Matlab Unit Operation

Matlab Thermo Import

OO Calc Thermo Import

REFPROP PPM

SciLab Unit Operation

SciLab Thermo Import

Python Unit Operation

Examples

Help

Python Thermo Import

FlowExchange

ThermoSystemAdapter

COBIA Class Wizard

ScanIt

Downloads

Services

Links

About us

Publications

Contact us

Examples:

Table of contents

• The basics
• Calculating thermo-physical properties
• Units of measure
• Validation
• Parameters
• Information streams
• Energy streams
• Text reports
• Putting it all together
• Building a library

Examples

• Example 1: a simple heater.
• Example 2: thermo-physical property calculations.
• Example 3: Dimension and units of measure.
• Example 4: Water separator.
• Example 5: Heat exchanger configuration.
• Example 6: Counter-current heat exchanger with maximum heat exchange.
• Example 7: Added options to the heat exchanger of Example 6.
• Example 8: Expose temperature deviation from dew point via information port.
• Example 9: Heater, with thermal energy feed port.
• Example 10: Heater, with thermal energy feed port.
• Example 11: Writing a report.
• Example 12: Multi-stream shell and tube heat exchanger.
• Example 13: importing an external unit operation definition.
• Example 14: importing an external unit operation definition in the path.

The basics

Let's start with the basics. Each Unit Operation requires a Configure function and a Calculate function. Each of these functions takes a unit argument. During Configure, one can add parameters, ports and reports, using add_parameter, add_port and add_report.

During Calculate, the ports can be obtained from unit.ports[<name>], that is, the objects connected to the ports are obtained like that. If a ports is not connected, it will not appear in the unit.ports dictionary. Ports can only be left unconnected, if optional=True was specified as argument to add_port. Values can be obtained from FEED ports, while PRODUCT ports must be fully specified.

Similarly, parameters are available during Calculate from unit.parameters[<name>]. The value of an INPUT parameter is known at the start of Calculate, whereas the value of an OUTPUT parameter must be set during Calculate.

Reports are available from unit.reports[<name>]; reports can subsequently be written using e.g. print with the file argument set to the report.

During configure, two MATERIAL ports are added; a FEED called "Feed", and a PRODUCT called "Product".

Calculating thermo-physical properties

The example uses fd.flow_rate, fd.x and fd.t to access total flow rate, mol/s, overall composition, mol/mol, and temperature, K. Material streams, or rather phase equilibria in general, are defined by composition, temperature, pressure, phase presence, and for each phase, composition, temperature, pressure and phase fraction. These properties can be used directly.

Other properties can be calculated using get_property; for a FEED MATERIAL and PhaseEquilibrium, get_property delivers equilibrium properties; for a Phase, get_property delivers single phase properties, for a PhasePair, get_property delivers two-phase properties. The lists of equilibrium properties, single phase properties and two phase properties can be obtained from a MATERIAL stream using phase_equilibrium_properties, phase_properties and phase_pair_properties. Alternatively, a Phase returns single the list of available single phase properties as properties, and a phase pair returns the list of two phase properties as properties.

Pure compound constant properties can be obtained from a Compound; the list of compounds is exposed by a MATERIAL stream's compounds member. Constant properties can be obtained from a Compound using get_constant, and temperature dependent properties can be obtained using get_temperature_dependent_property; the lists of these properties are available from constant_properties and temperature_dependent_properties for a Compound, or, equivalently, constant_compound_properties and temperature_dependent_compound_properties from a MATERIAL stream. One can directly obtain name, molecular_weight, formula and cas_registry_number from a compound.

Units of measure

In example 1, an INPUT, REAL parameter "Heat duty" is added that has the dimension WATT.

WATT is constructed from the base dimensions as kg*m²/s³. All real numbers in CAPE-OPEN are exchanged in pure SI units. For real parameters and information ports you get to decide on the dimensionality of the number; for properties on MATERIAL ports, the dimension is predefined. In many cases CAPE-OPEN allows a choice between specific and molar units; the Python Unit Operation always selects molar units. So flow rates are in mol/s, compositions are in mol/mol, density is in mol/m³, enthalpy in J/mol, etc.

For temperature differences and pressure differences, conversions from guage pressure and Celcius or Fahrenheit should not take into account the offset. For such quantities, pass difference=True in addition to the dimension argument.

Example 3 shows some ways to setup units of measure. A Calculate method is not provided in example 3.

Validation

CAPE-OPEN unit operations are validated prior to calculation, and the PME is required to validate a Unit Operation after any change in configuration (not including changes to values on feed or product streams, provided the configuration of the streams does not change).

Unit operations do not need to be validated in case Calculate is called multiple times and the configuration is not changing, for example if the Unit Operation is in a recycle or during a parametric study.

Python Unit Operations may optionally implement a Validate function. A Validate function can raise an exception in case the configuration of the Unit Operation is not valid, or in case the streams connected to the Unit Operation have a configuration that is not suitable for the Unit Operation. In addition, the Unit Operation can store data during validation, that pertains to the configuration of the streams. After all, the PME must revalidate the Unit Operation in case this configuration changes. Such data typically includes information on phase or compound mapping.

During Validate, data can be stored in the validation_data dictionary, and then the data will be available during Calculate. The Unit Operation must not store any reference to external objects, such as streams, compounds, etc, directly or indirectly. Such objects cannot be referenced between calculations or validations. If the Unit Operation stores external references, behaviour is unpredictable.

The following example shows a water separator. This unit copies the feed stream to the product stream after taking out any water. The water is placed on a separate product stream called "Water". The example features a Validate function that locates water, first by CAS registry number, then by chemical formula, and if all fails, by name. Exception handling is used in case compounds are present that have no CAS registry number or chemical formula. If water is not found, validation fails. Otherwise the index of water in the compound slate is stored in validation_data and used during Calculate. For vector math, numpy is used. Note that no special care is taken in this example for zero flow rate of the Product stream, which will lead to a division by zero.

Your custom implementation of Validate is called after all built-in validation has already passed. Built in validation checks that all ports that are not marked as optional=True are connected, and that all input parameters not marked with optional=True are specified, and that the values are valid (e.g. not violating imposed minimum and maximum values). Then it will check that the compounds found on each of the connected material streams are consistent. For some PMEs this is always the case. Other PMEs allow you to define streams with different thermodynamic subsystems, and therefore different compounds, and will allow you to connect such streams to a unit operation. By default, the Python Unit Operation will not validate in such a case.

Sometimes it can be useful to allow for this. Consider a heat exchanger with a hot and a cold stream, or more generally, a stream 1 and stream 2. There is no particular reason that stream 1 and stream 2 should have the same compound slates. One side of your heat exchanger may be a process stream, while the other side may be steam for example. Consider the following configuration:

Now, connecting Feed 1 consistently with Product 1, and Feed 2 consistently with Product 2, but Feed 1 and Feed 2 inconsistently, will fail to validate with the following message:

material objects connected to ports 'Feed 2' and 'Feed 1' do not have same compounds

This behaviour can be changed by setting unit.allow_inconsistent_compounds=True in Configure. At this point you should take care of validation of consistent compound slates where required yourself.

Parameters

The above heat exchanger example is starting to look like an actual unit operation. But it is not very flexible. Let's add some INPUT parameters to allow further configuration of the unit operation.

Start with adding two pressure drop parameters, one for stream 1 and one for stream 2. These are created as INPUT, REAL parameters, with dimension=PASCAL, with Pa = N/m² = (kg*m/s)/m². Also, as these are pressure drops, in case of a unit of measure of e.g. barg, the offset in the unit of measure should be ignored. This is indicated with difference=True.

Next, an option is added that allows to switch between counter- and co-current operation. For counter-current operation, the maximum heat transfer is as in Example 6. For co-current heat transer, the maximum heat transfer is that for which the temperature of Product 1 equals the temperature of Product 2. This requires a root finder, and the toms748 routine from scipy is used. The limits are given by 0, and the maximum heat transfer for the counter-current case.

Finally, instead of applying the maximum possible heat transfer, an Efficiency parameter allows specifying a fraction of the maximum possible heat tranfer to be applied. For dimensionless parameters, by CAPE-OPEN convention, difference=True indicates a fraction.

Parameters cannot be used only to allow the user to configure the Unit Operation; they can also be used to report solution values. These types of parameters are OUTPUT parameters, and the Unit Operation reports out the maximum and actual heat transfer, both of which have the dimension of WATT, with W = kg*m²/s³.

For INPUT parameters, we can use the value; for OUTPUT parameters, we must set the value.

In the above example, a STRING parameter was used with a predefined set of options. The control to select such an option is typically rendered as a drop down list by the PME. If no option list is specified, a STRING parameter can take any value, and is typically configured using a text box.

In the Python Unit Operation edit window, one can edit an INPUT parameter value by clicking on it. Any Python expression can be entered here:

In addition to REAL and STRING parameters, the Python Unit Operation supports INTEGER, BOOLEAN and REAL_ARRAY parameters.

Information streams

As an alternative to parameters, one can use information streams. Most PMEs will allow Unit Operation parameters to be used in a computational manner in any case, but sometimes it makes sense to explicitly state that a specific piece of information must flow from one Unit Operation to another, and should therefore appear on an information stream. An information stream typically contains a single scalar real parameter, and that is exactly what is supported by the Python Unit Operation.

This example demonstrates a Unit Operation that measures the temperature difference between the actual stream temperature and the dew point temperature, for the purpose of exposing this information via an information stream to a controller.

Keep in mind that not all PMEs support information streams.

Energy streams

Our simple heater in Example 1 used an INPUT parameter to specify the heat duty. Alternatively, an ENERGY port can be used.

Generic ENERGY energy streams transfer work, J/s.

An ENERGY FEED stream is an input specification. This does not mean that energy must be consumed; work with a negative sign means the input specification is on how much energy is produced. For a ENERGY PRODUCT stream, a positive sign means energy produced, a negative sign means energy consumed.

A thermal=True ENERGY port transfers heat. It does so within temperature_range which is available from a FEED and must be specified for a PRODUCT.

An axle=True ENERGY port transfers work via a rotating axle. It does so with axis_frequency which is available from a FEED and must be specified for a PRODUCT.

Here is a revision of Example 1, using an ENERGY port:

Note that in addition to the heating or cooling of the product stream, the unit checks whether the temperature range on the ENERGY FEED stream is suitable for performing the heating or cooling. If the temperature range is not feasible, the unit produces a warning. Note that warnings issues via warnings.warn are automatically forwarded to the simulation environment:

An alternative arrangement is that the Product stream is heated to a specified temperature, and the required heat is reported as ENERGY PRODUCT stream.

Text reports

Reports are added using add_report during Configure.

The most convenient way to write to a report is to use built-in print function, specifying the report in the file argument:

Putting it all together

The last example is a bit more complicated, and uses material streams, parameters, private storage, custom validation, reporting and the abilty of displaying graphics. Here is the full listing of a multi-stream heat exchanger.

The example depends on numpy and scipy for the numerics.

In the Configure function, a configuration parameter is defined: number_of_tubes. Such a parameter cannot be exposed as input parameter, as this changes the collection of ports and parameters; CAPE-OPEN allows such collections to change only while editing the unit operation.

Subsequently, this value is stored in private_date so that it is available during Validate and Calculate. The value is also used during configuration; two ports, feed and product, and two parameters, UA and flow direction, are added for each tube.

The unit is allowed to connect to streams with inconsistent compound slates, allow_inconsistent_compounds=True, and the validation of compounds on the connected streams is analogous to Example 5 and Example 6.

To speed up the calculations, enthalpy interpolation tables are created. For the simplicity of the example, zero pressure drop is assumed, so that enthalpy is a function only of temperature, at constant composition and pressure. Enthalpy is interpolated using spline interpolation from scipy.interpolate for enthalpy calculated at phase equilibrium, at user specified maximum temperature intervals of Interpolation temperature interval. Enthalpy at phase equilibrium vs. temperature is only 0th order continuous at phase boundaries, so as to prevent improper interpolation over the phase boundaries, the dew and bubble points are found using a pressure-vapor fraction flash. If within the specified temperature region, separate interpolation tables are produced on either side of the phase boundary.

Enthalpy tables can be re-used between successive calculations, provided the overall composition did not change, the pressure did not change, and the new temperange range is within bounds of the current table. The needs_update method checks this. In addition, the tables should not be used if the thermodynamic configuration of any of the materials has changed. If this happens, the PME must call Validate.

The enthalpy tables are stored in volatile_data. As opposed to private_data, volatile_data is not persisted between sessions. There would be no point to save the data in persistent storage, as after restoring, Validate will be called as thermdynamic configuration may have changed. At Validate, the tables are removed from volatile_data using del.

The calculation simulates heat transer between the shell and each of the tubes, under the assumption that the heat transfer coefficients are constant. The total U*A for each tube is specified as input parameter. In addition, each tube can be co- or counter-current to the shell, which is also specified as input parameter. Discretizing the heat balances over dimensionless length leads to the following equations for cell j:

Here, Q and each equation applies to a grid cell, where T applies to each grid node; the number of nodes is the number of cells plus 1. However feed temperatures are not calculated, as they are constant, and are excluded from the variables, so that the number of variables and equations match. All temperatures are organized in the direction of shell feed to shell product, so shell and co-current tubes have forward indexing with the feed temperature at the start, and counter-current tubes have reverse indexing, with feed temperature at the end. Temperature indexing is pre-calculated and stored as t_indices in temporary storage stream_info. The temperatures can then quickly be extracted in the order required for the equations, using t_indices on an array of [x]+[t_feed] where x is all temperatures solved for, and t_feed contains the constant feed temperatures.

The functions are implemented in fun; the Jacobian is rather sparse, but to not make the example overly complex, a dense Jacobian is implemented in jac. The equations are solved using scipy.optimize.root with a tolerance that the user provides as input parameter. Note that this tolerance, applies only to solving the equations. Some additional systemic error rises from the use of interpolation tables. This error can be reduced by choosing a smaller value for Interpolation temperature interval.

Any profiles stored from an initial guess can of course be used as an initial guess. The solution therefore proceeds in two attempts, due to the for loop over use_initial_guess. In the first attempt, if profiles are available, and if the shape of the profiles (number of tubes, number of grid cells) match the current problem, the initial guess is backed out from the stored profiles.

If this fails, or if appropriate profiles are not available, an initial guess is calculated. In the special case that all tubes are co-current with the shell, the initial guess exit temperatures are solved as one common temperature for which the heat balance closes. This temperature is bracketed between the min. and max. value of all inlet temperatures; these equations are implemented in f_heat_balance and solved using scipy.optimize.toms748.

If at least one tube if counter-current, a rough initial guess is calculated by solving

The equations are implemented in f_init along with the full Jacobian, and solved using scipy.optimize.root.

After estimating the outlet temperatures, the initial guess is constructed from linear interpolation between inlet and outlet temperatures.

The WriteProfileReport demonstrates how to use the print statement with the file argument set to a report; WriteProfileReport is called with unit.reports['Temperature profiles'] as argument. The reports are not only exposed to the PME, but also shown in the Reports tab:

Finally, matplotlib is used to create a graph showing the temperature profiles as a function of dimensionless distance. Images can be added just like reports, using add_image in Configure. The script must supply a function that creates a PNG file for the image at requested width and height, see CreateTemperatureGraph. Note that, in contrast to creation of reports, images are not created as part of Calculate, but on request, with specified size. The unit should save relevant data to create the image. The image is displayed on the Report tab of the edit window:

Building a library

So far, the module that defines the Unit Operation, its configuration and its calculation, has been typed directly in the editor. This script will be saved as part of the Unit Operation.

Sometimes you want the same Unit Operation definition to be used in multiple places. One way to do this is to copy and paste the script. Which works fine. But it is not very maintenance friendly. If you discover a bug in the script, or want to modify the calculation, all Unit Operations that are defined by the same script must be edited separately to correct for the same issues.

As an alternative, the Unit Operation can be defined from an external module. To demonstrate how this works, the following steps are followed.

• This example assumes that the library of Unit Operation definitions exists in a folder Python Unit Operation Models, and that this folder is a sub-folder of the My Documents folder. Create this folder,
• Copy the Multi-stream shell and tube heat exchanger code from Example 12, and place it in a file multistreamhtx.py, in the Python Unit Operation Models folder,
• Define the Unit Operation from Example 13.

Of course if the folder that contains the Unit Operation models is already in the Python path, the script becomes a lot simpler: