© 2021 Jasper van Baten, AmsterCHEM

Help on Python Unit Operation

Editor

The Python Unit Operation edit dialog uses the Scintilla as editor. Some of the default Scintilla key bindings are highligted below, in addition to the key bindings added by the Python Unit Operation edit dialog.

F5Test run the current script
Ctrl+F, Ctrl+H7   Toggle find bar
F3Find next
Shift+F3Find previous
Ctrl+GJump to line
Ctrl+KComment selected lines
Ctrl+Shift+KUn-comment selected lines
Alt+MouseBlock selection
Ctrl+LCut line
Ctrl+Shift+LDelete line
Ctrl+(Num+)Zoom in
Ctrl+(Num-)Zoom out
TabIndent selected lines
Shift+TabUn-indent selected lines
Ctrl+[Paragraph up, extend selection
Ctrl+]Paragraph down, extend selection
Ctrl+UConvert selection to lower case
Ctrl+Shift+UConvert selection to upper case

The unit operation is configured through the Configure function that you provide, and the resulting parameters, ports and reports can be inspected at various tabs in the editor window. For input parameters, values can be changed by clicking on the value on the Parameter tab; any valid Python expression can be entered as the new value.

See the examples for more information.

Python Unit Operation class reference

class Compound
A compound. A Compound represents a single compound in material stream type. It provides name, chemical formula, compound constant properties and temperature dependent properties.
Data members
cas_registry_number Chemical Abstracts registry number.
constant_properties Names of supported constants.
formula Chemical formula.
index Index in compound list.
molecular_weight Relative molecular mass.
name Compound name.
temperature_dependent_properties Names of supported temperature dependent properties.
Methods
get_constant Get compound constant by name. Required arguments: name -- compound constant name. Constant names are listed by constant_properties.
get_temperature_dependent_property Get one or more temperature dependent properties. Required arguments: properties -- a temperature dependent property name or list of temperature dependent property names. t -- temperature [K]. Temperature dependent property names are listed by temperature_dependent_properties.
class EnergyObject
Object representing energy stream. Energy ports can be added using add_port during Configure. All energy streams support work. Thermal energy streams in addition have a temperature_range. Axle energy streams have an axis_frequency.
Data members
axis_frequency Axis frequency [Hz], NaN if not available
stream_name Information stream name.
temperature_range Temperature range, as tuple with lower and upper temperature [K], NaN if not available
work Work [W]
class ExternalParameter
External parameter on information stream. Information ports can be added using add_port during Configure. Information streams connect to information objects, which contain the parameters that carry the information. This is typically one scalar real value, which is available as ExternalParameter from unit.ports[] during Calculate.
Data members
name External parameter name.
stream_name Information stream name.
value Value
class Material
Material stream. Material ports can be added using add_port during Configure. A Material stream represents a complete thermodynamic configuration that includes compound definitions, phase definitions, property calculation routines and a phase equilibrium calculator. To calculate mixture properties, create a Phase object (directly or from a PhaseType). To calculate phase equilibrium properties, create a PhaseEquilibrium object. The compound member lists the compound in the package. For a feed stream, flow_rate represent the feed total molar flow rate and all the properties that are available from a PhaseEquilibrium are also available for a feed stream. For a product stream, x and flow_rate must be set, plus two equilibrium conditions. Equilibrium conditions can be set using set_property, or alternatively set set t, p or vapor_fraction members directly. Multiple properties can be set simultaneously for a product stream using set.
Data members
compounds Compounds.
constant_compound_properties Names of supported compound constant properties.
flow_rate Molar total flow rate [mol/s].
name Name
p Pressure [Pa].
phase_equilibrium_properties Names of properties supported by the package that may be used for phase equilibrium conditions.
phase_pair_properties Names of two phase properties supported by the package.
phase_properties Names of single phase properties supported by the package.
phase_types Descriptions of defined phases.
phases Phases present at phase equilibrium for material object connected to feed port.
solution_type Solution type for product port flash. Defaults to unspecified. Options are 'normal' or 'retrograde'.
t Temperature [K].
temperature_dependent_compound_properties Names of supported compound temperature dependent properties.
vapor_fraction Fraction [mol/mol] of vapor phase, or 0 if vapor is not present.
x Overall composition [mol/mol].
Methods
copy_from Specify from PhaseEquilibrium or material feed stream. Required argument: source -- PhaseEquilibrium or material feed stream The copy_from method provides an alternative way to specify a product stream. It cannot be called for a feed stream. The copy_from method attempts to recreate the phase equilibrium on the specified PhaseEquilibrium or material feed stream. If the phase equilibrium is on a vapor phase boundary, detected by a value of exactly zero of the vapor phase fraction or exactly zero of the sum of non vapor phase fractions when at least 2 phases are present, it is attempted to keep the product at the phase boundary by performing a pressure-vapor fraction flash with unspecified solution type. If the enthalpy of the resulting phase equilibrium is close enough to the source phase equilibrium, the calculation is accepted. Next, a temperature-pressure flash is attempted, which is accepted if the enthalpy of the resulting phase equilibrium is close enough to the source phase equilibrium. If the temperature-pressure flash is not accepted, a pressure-enthalpy flash is performed. If the source is a feed material stream, flow_rate is copied a well. If the source equilibrium is a PhaseEquilibrium, flow_rate must be specified separately. The source should be of the same thermodynamic definition as the product stream. If not, a source with a different number of compounds will cause an error to be raised, or otherwise an incorrect phase equilibrium results on the product port.
create_liquid_phase Create a liquid phase. Keyword arguments: t -- temperature [K]. p -- pressure [Pa]. x -- composition [mol/mol].
create_phase_equilibrium Calculate phase equilibrium. Legacy calling method: Required arguments: x -- overall composition [mol/mol]. condition1 -- first condition name. value1 -- value of first condition. condition2 -- second condition name. value2 -- value of second condition. Keyword arguments: solution_type -- solution type. New calling method: Keyword arguments: flow_rate -- total molar flow rate [mol/s]. x -- composition [mol/mol] t -- temperature [K] p -- pressure [Pa] vapor_fraction -- molar vapor fraction [mol/mol] solution_type -- solution type for product flash In addition to the above keywords, any property returned by phase_equilibrium_properties may be specified as keyword argument. Valid conditions are listed in phase_equilibrium_properties. Valid values for solution_type include "unspecified", "normal" and "retrograde". A solution_type should not be specified unless vaporFraction is one of the flash conditions.
create_phase_pair Create a phase pair. Required arguments: phase1 -- first Phase. phase2 -- second Phase.
create_solid_phase Create a solid phase. Keyword arguments: t -- temperature [K]. p -- pressure [Pa]. x -- composition [mol/mol].
create_vapor_phase Create a vapor phase. Keyword arguments: t -- temperature [K]. p -- pressure [Pa]. x -- composition [mol/mol].
get_property Calculate and one or more feed properties by name. Material objects connected to feed ports are in phase equilibrium, and this method can be used to obtain overall properties. It is equivalent to PhaseEquilibrium.get_property. This method is not available for material objects connected to product properties; to obtain a phase equilibrium from material objects connected to product properties, use create_phase_equilibrium. Required arguments: properties -- specify one or more property names as string or list of strings. Valid property names are listed in the phase_equilibrium_properties member.
set Specify multiple product properties. Keyword arguments: flow_rate -- total molar flow rate [mol/s]. x -- composition [mol/mol] t -- temperature [K] p -- pressure [Pa] vapor_fraction -- molar vapor fraction [mol/mol] solution_type -- solution type for product flash In addition to the above keywords, any property returned by phase_equilibrium_properties may be specified as keyword argument. Valid conditions are listed in phase_equilibrium_properties. Valid values for solution_type include "unspecified", "normal" and "retrograde". A solution_type should not be specified unless vaporFraction is one of the flash conditions.
class Parameter
A Parameter. Configure parameters using unit.add_parameter during Configure. Parameters are available from unit.parameters during Calculate.
Data members
description Description.
is_input True for input parameters, False for output parameters.
name Name.
type Type, as string.
type_id Type ID, as passed to add_parameter.
value Value.
class Phase
A Phase. A Phase represents a mixture in a certain state of aggregation. It is defined by temperature, pressure and composition (mole fractions). Once defined, it can be used for mixture property calculations. To calculate two-phase properties, first create a PhasePair.
Data members
excluded_compound Name of excluded compound, or empty.
index Index in phase type list.
key_compound Name of key compound, or empty.
name Phase name.
p Pressure [Pa].
phase_fraction Phase fraction [mol/mol].
properties Names of supported properties.
state_of_aggregation State of aggregation.
t Temperature [K].
x Mole fraction [mol/mol].
Methods
get_property Calculate and one or more properties by name. Required arguments: properties -- specify one or more property names as string or list of strings. Valid property names are listed in the properties member.
set Set conditions. Keyword arguments: t -- temperature [K]. p -- pressure [Pa]. x -- composition [mol/mol].
class PhaseEquilibrium
A Phase Equilibrium. A PhaseEquilibrium represents a set of phases at thermodynamic phase equilibrium. Each of the phases is a Phase, populated with temperature, pressure, phase fraction and composition (mole fraction). The PhaseEquilibrium itself provides overall properties.
Data members
p Pressure [Pa].
phases Phases coexisting at thermodynamic phase equilibrium.
properties Names of supported properties.
t Temperature [K].
vapor_fraction Fraction [mol/mol] of vapor phase, or 0 if vapor is not present.
x Overall composition [mol/mol].
Methods
get_property Calculate and one or more properties by name. Required arguments: properties -- specify one or more property names as string or list of strings. Valid property names are listed in the properties member.
class PhasePair
A pair of two distinct phases. A PhasePair is a combination of two phases for calculation of two-phase properties.
Data members
phase1 First phase.
phase2 Second phase.
properties Names of supported properties.
Methods
get_property Calculate and one or more properties by name. Required arguments: properties -- specify one or more property names as string or list of strings. Valid property names are listed in the properties member.
class PhaseType
A phase type. A PhaseType describes the properties of a phase, prior to actually creating a Phase instance.
Data members
excluded_compound Excluded compound, or empty.
index Index in phase type list.
key_compound Key compound, or empty.
name Phase type name.
properties Names of supported properties.
state_of_aggregation State of aggregation, vapor, liquid or solid (empty if unknown).
Methods
create_phase Create a phase of this type. Keyword arguments: t -- temperature [K]. p -- pressure [Pa]. x -- composition [mol/mol].
class PythonUnitOperation
Unit operation. A unit operation is the object representing the CAPE-OPEN unit operation and its functionality. It is passed as argument to functions such as Configure and Calculate in the Python script.
Data members
allow_inconsistent_compounds If False (default), the unit will validate only if all Material Ports have the same compound slate. Can be set to True during Configure.
parameters Parameter objects.
ports Objects connected to ports.
private_data Private data. The Unit Operation may store any data in this dictionary. Data in private_data is persisted between sessions. Only data that can be pickled should be stored. Data that can not be pickled or unpickled will lead to a persistence problem. Persistence problems in private_data are reported as warning to the simulation environment, provided that the simulation environment supports CAPE-OPEN diagnostics. In this case you may find that private_data is empty upon loading. Be careful that there is no automatic way in which private_data gets removed. One can inspect and manipulate private data from Configure or Calculate using temporary code while using the Test execution. Example: #maintenance: print(list(unit.private_data)) del unit.private_data['initial guess'] #no longer used in this version Direct on indirect references to external objects, such as streams, compounds, stream parameters, etc, may not be stored.
reports Output file objects for printing reports.
validation_data Data stored during Validate. The validation_data dictionary is cleared prior to a call to Validate. At Validate, results of constant data analysis, such as compound resolution or phase resolution, mat be stored here. The data is available during Calculate. Unlike private_data, validation_data is not persisted. Direct on indirect references to external objects, such as streams, compounds, stream parameters, etc, may not be stored.
volatile_data Volatile data. The Unit Operation may store any data in this dictionary. In contrast to private_data , data in volatile_data is not persisted between sessions. Direct on indirect references to external objects, such as streams, compounds, stream parameters, etc, may not be stored.
Methods
add_image Add image during configure. Required arguments: name -- image report name. function -- name of the function that creates the image. The image creation function must accept the following arguments, and create a png image: path -- location in which the image file is to be saved, in png format. width -- requested image width, in pixels. height -- requested image height, in pixels. The image is to produced on request, not during Calculate.
add_parameter Add parameter during Configure. Required arguments: name -- parameter name. type -- parameter type, of type unit.ParameterType. mode -- parameter mode, of type unit.ParameterMode. Keyword arguments: description -- parameter description. min -- minimum value, applies to real and integer values. max -- maximum value, applies to real and integer values. default -- default value. initial - initial value, defaults to default value. options -- list of options for STRING parameter. If specified, value must be one of the options. dimension -- dimension for REAL parameters, a Dimension object. difference -- specify True for temperature and pressure differences. length -- specify the length for array parameters. If not specified, values of any length are accepted. optional -- specify True if a missing value is allowed. Missing values for real parameters are represented by NaN. Missing values for integer parameters are not supported; an integer defaults to 0 if unspecified. Missing values for boolean are not supported; a boolean defaults to False if unspecified. Missing values for string parameters are represented by an empty string. Missing values for array parameters are empty arrays. Each element can be missing as well. Array default, min and max values apply to element values, whereas initial value should be an array. Default value is an empty array in case length is not specified, or an array of specified length with default value for each element. Parameters are available from unit.parameters during Calculate.
add_port Add port during Configure. Required arguments: name -- port name. type -- port type, of type unit.PortType. direction -- port direction, of type unit.PortDirection. Keyword arguments: optional -- set to True if a port connection is not required. Default False. data_name -- preferred name for external parameter on information stream. Defaults to name. dimension -- dimension for external parameter on information stream. difference -- specify True for external parameter on information stream that are temperature and pressure differences. thermal -- specify True for energy port that is thermal. Adds temperature_range. axle -- specify True for energy port that is an axle. Adds axis_frequency. Objects connected to ports are available from unit.ports during Calculate.
add_report Add report during configure. Required arguments: name -- report name. Reports can be written as file, e.g. using the file keyword argument of print. The file object is available from unit.reports during Calculate.
define_from Define unit operation from external module. Required arguments: module -- external module. The user defined script defines only the unit to which it belongs. If multiple unit operations need to be defined from the same script, it may be advantageous to keep this script in a separate, external module. Such a module can be identified as the module that defines the unit operation, by passing the module to define_from in the Configure method. If define_from is used, the user defined script should not make any other configuration during Configure, such as add ports, parameters, reports or images. Any other content of the user defined module is subsequently ignored. It is expected that the module passed to define_from provides at least a Configure and Calculate method, and any other members that would normally be defined in the user provided script.
class Dimension
Dimension Pass a Dimension as dimensionality argument when creating real typed parameters. Basic dimensions are METER, KILOGRAM, SECOND, AMPERE, KELVIN, MOLE, CANDELA, RADIAN. Dimension objects can be combined to create new Dimensions. Examples: JOULE=unit.Dimension.KILOGRAM*unit.Dimension.METER**2/unit.Dimension.SECOND**2 WATT=JOULE/unit.Dimension.SECOND HERTZ=1/unit.Dimension.SECOND Real typed parameters take an optional additional argument difference=True that should be specified for temperature differences and pressure differences, e.g. pressure drop.
Static members
AMPERE, CANDELA, KELVIN, KILOGRAM, METER, MOLE, RADIAN, SECOND
class ParameterMode
ParameterMode Pass a ParameterMode as mode argument when creating a Parameter. Defined ParameterModes are INPUT and OUTPUT.
Static members
INPUT, OUTPUT
class ParameterType
ParameterType Pass a ParameterType as type argument when creating a Parameter. Defined ParameterTypes are REAL, INTEGER, BOOLEAN, STRING and ARRAY_REAL.
Static members
ARRAY_REAL, BOOLEAN, INTEGER, REAL, STRING
class PortDirection
PortDirection Pass a PortDirection as direction argument when creating a port. Defined PortDirections are FEED and PRODUCT.
Static members
FEED, PRODUCT
class PortType
PortType Pass a PortType as type argument when creating a port. Defined PortTypes are MATERIAL, ENERGY and INFORMATION.
Static members
ENERGY, INFORMATION, MATERIAL