Professional Documents
Culture Documents
Modeler 2004.1
Library Reference Guide
Who Should Read this Guide
1 CONTROL MODELS..................................................................................... 11
Time Units in Control Models ................................................................................... 11
Comparator........................................................................................................... 12
Comparator Equation......................................................................................... 12
Configuring Comparator ..................................................................................... 12
Dead_time ............................................................................................................ 12
Dead_time Equation .......................................................................................... 12
Configuring Dead_time ...................................................................................... 13
Discretize.............................................................................................................. 13
Discretize Equations .......................................................................................... 13
Configuring Discretize ........................................................................................ 13
FeedForward ......................................................................................................... 14
FeedForward Equations ...................................................................................... 14
Configuring FeedForward.................................................................................... 15
HiLoSelect............................................................................................................. 15
HiLoSelect Equations ......................................................................................... 15
Configuring HiLoSelect ....................................................................................... 16
IAE ...................................................................................................................... 16
IAE Equation .................................................................................................... 16
Configuring IAE................................................................................................. 17
ISE ...................................................................................................................... 17
ISE Equation .................................................................................................... 17
Configuring ISE................................................................................................. 18
Lag_1................................................................................................................... 18
Lag_1 Equations ............................................................................................... 18
Configuring Lag_1 ............................................................................................. 19
Lead_lag............................................................................................................... 19
Lead_lag Equations ........................................................................................... 19
Configuring Lead_lag ......................................................................................... 20
Multiply ................................................................................................................ 21
Multiply Equations ............................................................................................. 21
Configuring Multiply........................................................................................... 21
Contents 3
Noise ................................................................................................................... 21
Noise Equations ................................................................................................ 22
Configuring Noise.............................................................................................. 22
PID ...................................................................................................................... 23
PID Algorithms ................................................................................................. 31
PID Controller Faceplates ................................................................................... 32
Closed-Loop Controller Tuning using the Ziegler-Nichols Technique .......................... 32
Using the ISE and IAE Models with a PID Controller ............................................... 33
PIDIncr................................................................................................................. 34
PID Algorithms ................................................................................................. 41
Anti Reset Windup............................................................................................. 42
PIDIncr Controller Faceplates.............................................................................. 43
Automatic Controller Tuning Context.................................................................... 44
Using Automatic Controller Tuning ....................................................................... 44
Using the ISE and IAE Models with the PIDIncr Controller ....................................... 47
PRBS.................................................................................................................... 47
PRBS Equations ................................................................................................ 48
Configuring PRBS .............................................................................................. 49
Ratio .................................................................................................................... 50
Ratio Equations................................................................................................. 50
Configuring Ratio .............................................................................................. 50
Scale.................................................................................................................... 50
Scale Equations ................................................................................................ 51
Configuring Scale .............................................................................................. 51
SplitRange ............................................................................................................ 52
SplitRange Equations ......................................................................................... 52
Configuring SplitRange....................................................................................... 52
SteamPtoT ............................................................................................................ 54
Sum..................................................................................................................... 54
Sum Equations ................................................................................................. 54
Configuring Sum ............................................................................................... 54
Transform ............................................................................................................. 55
Transform Equations.......................................................................................... 55
Configuring Transform ....................................................................................... 55
Valve_dyn............................................................................................................. 56
Valve_dyn Equations ......................................................................................... 56
Configuring Valve_dyn ....................................................................................... 57
Contents 4
Design of ART Reaction Model Component ................................................................. 60
Using ART Reaction Model Component in Reactor Model............................................... 62
Interface to Reaction Global Structures ................................................................ 62
Interface to Non-Distributed Portion of a Reaction Model......................................... 63
Interface to Distributed portion of a Reaction Model ............................................... 63
Use Multiple Sets of Reaction Models in a Reactor Model ......................................... 64
Examples ......................................................................................................... 65
Configuration of ART Reaction Model Component ........................................................ 68
Adding ART Configure Form to Reaction Global Structure ........................................ 68
ART Configure Form .......................................................................................... 70
Built-in Reaction Classes ......................................................................................... 78
Power Law ....................................................................................................... 78
LHHW.............................................................................................................. 80
GLHHW............................................................................................................ 82
Equilibrium....................................................................................................... 82
Custom Reaction Model...................................................................................... 83
Building Custom Reaction Model Component .............................................................. 83
Custom Reaction Model Wizard ........................................................................... 83
Writing a Custom Reaction Model ........................................................................ 84
Compiling a Custom Reaction Model..................................................................... 86
Removing a Custom Reactions Model ................................................................... 87
Exporting a Custom Reaction Model .......................................................................... 87
Appendix .............................................................................................................. 88
Example of Assigning Variables and Equations to Hierarchy Levels ........................... 88
Defining Stoichiometry for a Reaction................................................................... 89
Calculation of Concentration Exponents for Reverse Rate ........................................ 90
Contents 5
Procedure pEnth_Mol_Liq ..................................................................................103
Procedure pEnth_Mol_Vap .................................................................................103
Procedure pEntr_Mol_Liq...................................................................................104
Procedure pEntr_Mol_Vap .................................................................................104
Procedure pFuga_Liq ........................................................................................105
Procedure pFuga_Vap .......................................................................................105
Procedure pGibbs_Mol_Liq.................................................................................106
Procedure pGibbs_Mol_Vap ...............................................................................106
Procedure pKllValues ........................................................................................107
Procedure pKValues..........................................................................................108
Procedure pSurf_Tens.......................................................................................108
Procedure pVisc_Liq .........................................................................................109
Procedure pVisc_Vap ........................................................................................109
Property Procedures without Analytic Derivatives.......................................................110
Procedure pAct_Coeff_Liq..................................................................................110
Procedure pBubt ..............................................................................................110
Procedure pDens_Mass_Sol ...............................................................................111
Procedure pDens_Mol_Sol .................................................................................111
Procedure pDewt..............................................................................................112
Procedure pEnth_Mol ........................................................................................113
Procedure pEnth_Mol_Sol ..................................................................................113
Procedure pEntr_Mol ........................................................................................114
Procedure pEntr_Mol_Sol ..................................................................................114
Procedure pFlash .............................................................................................115
Procedure pFlash3............................................................................................115
Procedure pFlash3PH ........................................................................................116
Procedure pFlash3PV ........................................................................................117
Procedure pFlash3TH ........................................................................................118
Procedure pFlash3TV ........................................................................................119
Procedure pFlashPH..........................................................................................119
Procedure pFlashPV ..........................................................................................120
Procedure pFlashTH..........................................................................................121
Procedure pFlashTV ..........................................................................................121
Procedure pFuga_Sol ........................................................................................122
Procedure pGibbs_Mol_IDLGAS ..........................................................................123
Procedure pGibbs_Mol_Sol ................................................................................123
Procedure pMolWeight ......................................................................................124
Procedure pMolWeights .....................................................................................124
Procedure ppH .................................................................................................125
Procedure pPropZ.............................................................................................125
Procedure pPropZPct ........................................................................................126
Procedure pPropZPPct.......................................................................................126
Contents 6
Procedure pSurf_Tensy .....................................................................................127
Procedure pTrueCmp2 ......................................................................................128
Procedure pTrueCmpVLS ...................................................................................129
Procedure pTrueComp ......................................................................................129
Procedure pTrueCmp2 ......................................................................................131
Procedure pVap_Pressures ................................................................................132
Procedure pVap_Pressure ..................................................................................132
Contents 7
Calling Routine ACM_RQST from Fortran..............................................................157
ACM_GetComponents Routine.................................................................................161
Calling Routine ACM_GETCOMPONENTS from Fortran ............................................161
Calling Routine ACM_GetComponents from C/C++................................................162
Routines Provided for Compatibility with SPEEDUP 5.5................................................163
Procedure pSpRMod .........................................................................................163
Procedure pLMTD .............................................................................................164
Procedure pLimit ..............................................................................................164
7 VARIABLE TYPES......................................................................................167
A Variable Types ..............................................................................................167
C Variable Types ..............................................................................................167
D Variable Types..............................................................................................168
E Variable Types ..............................................................................................168
F Variable Types ..............................................................................................169
G Variable Types..............................................................................................170
H Variable Types ..............................................................................................170
K Variable Types ..............................................................................................171
L Variable Types ..............................................................................................171
M Variable Types..............................................................................................171
N Variable Types ..............................................................................................171
P Variable Types ..............................................................................................172
R Variable Types ..............................................................................................172
S Variable Types ..............................................................................................172
T Variable Types ..............................................................................................173
V Variable Types ..............................................................................................173
GENERAL INFORMATION..............................................................................174
Copyright.............................................................................................................174
Related Documentation..........................................................................................176
TECHNICAL SUPPORT...................................................................................177
Online Technical Support Center .............................................................................177
Phone and E-mail..................................................................................................178
INDEX ..........................................................................................................179
Contents 8
Contents 9
Introducing Aspen Custom
Modeler
1 Control Models 11
1 After instancing one or more control models, in Explorer go to Simulation
and open the Globals table.
2 Change the value of GlabalTimeScalar to the number of seconds per time
unit used in your models.
The default value of 3600 is for models written in hours. If your models
are written in minutes, change the value to 60, and if they are written in
seconds, change the value to 1
Comparator
Input1
Output_
Input2
Comparator calculates its output as the difference of the two input signals.
Comparator Equation
The equation used in the Comparator model is:
Output_ = Input1 – Input2
Configuring Comparator
Comparator has no configuration parameters.
Dead_time
Input_ Output_
Dead_time Equation
The equation used in the dead-time model is:
Output_ = Delay Input_ by DeadTime
1 Control Models 12
Configuring Dead_time
Dead_time has the following configuration parameter:
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
Discretize
Input_ Output_
Discretize Equations
The following illustration shows the relationship between the input and output
signals:
Configuring Discretize
Discretize has the following configuration parameter:
1 Control Models 13
Parameter Description Units Valid Default
Values Value
Interval Sample min 0 -> 1E6 0
interval
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
FeedForward
FeedForward Equations
The main equations for the FeedForward controller are:
For Lead-Lag:
Alpha*$aux = Gain*(PVs - SPs) - aux
Output_LL = Beta*$aux + aux
For Dead Time:
Output_DT = Delay Output_LL by DeadTime
Where:
1 Control Models 14
Alpha = Lag time constant.
Beta = Lead time constant.
Gain = Process gain.
PVs = Scaled process variable.
SPs = Scaled setpoint.
aux = Auxiliary variable connecting the lead
and the lag.
Output_LL = Output of the lead-lag.
DeadTime = Dead time.
Output_DT = Output of the dead-time.
Configuring FeedForward
The FeedForward Configure form has the following parameters:
HiLoSelect
Input1
Output_
Input2
HiLoSelect models a high or low selector. The output is either the larger or
smaller of the two inputs, depending on the select option you specify.
HiLoSelect Equations
When configured as a high selector:
1 Control Models 15
If Input1>Input2 then
Output_ = Input1
Else
Output_ = Input2
Endif
When configured as a low selector:
If Input1<Input2 then
Output_ = Input1
Else
Output_ = Input2
Endif
Configuring HiLoSelect
HiLoSelect has the following configuration parameter:
IAE
Input
IAE
SP
IAE calculates the integral of the absolute value of the error between its input
and a set point value.
The model provides a time-integral performance criterion. You can use IAE to
measure how successful a control system has been in keeping a process
variable at its set point (SP) over the entire dynamic response of a controlled
process. SP can be specified within the block or be an input from another
block.
IAE Equation
The equation used in the model is the standard integral of the absolute value
of the error form:
1 Control Models 16
T
IAE = ∫
0
| e(t )|. dt
Where:
e = Deviation of the variable from the desired set point.
t = Time.
IAE = Integral absolute error value.
T = Current time.
Configuring IAE
IAE has the following configuration parameter:
SP for IAE
SP specifies the required value of the input variable. The IAE element
calculates its performance criterion as the integral of the absolute difference
between this required value and the input value. SP may be specified within
the IAE block, or supplied through an input signal to the block. If SP is
supplied through an input signal, make sure you change its Spec from Fixed
to Free on the block Configure table.
ISE
Input_
ISE
SP
ISE calculates the integral of the squared error between its input and a set
point value.
The model provides a time-integral performance criterion. You can use ISE to
measure how successful a control system has been in keeping a process
variable at its set point (SP) over the entire dynamic response of a controlled
process. SP can be specified within the block or be an input from another
block.
ISE Equation
The equation used in the model is the standard integral of the absolute value
of the error form:
T
ISE = ∫
0
e(t ) 2 . dt
1 Control Models 17
Where:
e = Deviation of the variable from the desired set point.
t = Time.
ISE = Integral absolute error value.
T = Current time.
Configuring ISE
ISE has the following configuration parameter:
SP for ISE
SP specifies the required value of the input variable. The ISE element
calculates its performance criterion as the integral of the squared difference
between this required value and the input value. SP may be specified within
the ISE block, or supplied through an input signal to the block. If SP is
supplied through an input signal, make sure you change its Spec from Fixed
to Free on the block Configure table.
Lag_1
Input_ Output_
Lag_1 models a first order lag between the input and output signals.
Lag_1 Equations
The Laplace domain transfer function for the first order lag is:
Gain
g (s ) =
Tau.s + 1
Where:
1 Control Models 18
d (Output _)
Gain.Input _ = Tau. + Output _
dt
Configuring Lag_1
Lag_1 has the following configuration parameters:
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
Lead_lag
Input_ Output_
Lead_lag models a lead-lag element. The output is the input signal passed
through a lead-lag function.
A lead-lag consists of a first-order lead of unit gain and a first-order lag of
unit gain in series. The numerator component introduces phase lead and the
denominator component introduces phase lag. The response of the output can
span from approximate first-order lag behavior to approximate first-order
lead behavior.
Lead_lag Equations
The Laplace domain transfer function for the lead-lag element is:
1 Control Models 19
Beta.s + 1
g (s ) = Gain.
Alpha.s + 1
Where:
Beta = Lead time constant in minutes
Alpha = Lag time constant in minutes
Gain = Steady state gain
The model uses the following equations to implement this in the time domain:
d (aux )
Alpha + aux = Gain.Input _ (lag component)
dt
d (aux )
Output _ = Beta + aux (lead component)
dt
Where:
aux = Signal after the lag but before the lead.
Configuring Lead_lag
Lead_lag has the following configuration parameters:
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
1 Control Models 20
Alpha for Lead_lag
Alpha specifies the amount of lag that is imposed upon the input variable. A
pure lead with no lag is physically impractical, and may cause problems when
solving the simulation. Therefore Alpha has a lower limit of 0.01.
The units of Alpha are minutes.
Multiply
Input1
Output_
Input2
Multiply evaluates its output as the product of the two input signals.
Multiply Equations
The equation used in the Multiply model is:
Output _ = Input 1.Input 2
Configuring Multiply
Multiply has no configuration parameters.
Noise
Input_ Output_
Noise generates a Gaussian noise signal. You can use the Noise model in two
ways:
• To add noise to the input signal.
• To generate a noisy signal.
Noise can be used for testing how well your control system rejects noise.
1 Control Models 21
Noise Equations
The Noise model generates a random value with amplitude which follows a
Gaussian probability distribution. The mean of the noise is zero, and the
magnitude of the noise is determined by the specified standard deviation. The
output of this model is the sum of the input to the model plus the noise.
The model approximates Gaussian white noise, which is often a good
representation of noise found in process measurement and control systems.
The following graph shows the shape of the Gaussian distribution.
Probability
−3σ −2σ −σ 0 σ 2σ 3σ
Amplitude
σ = Standard deviation
Configuring Noise
To add noise to an input signal, connect to both the Input_ and Output_
connections. To generate a noisy signal, connect Output_ only, and Fix Input_
to the required mean value of the noisy signal.
Noise has the following configuration parameters:
1 Control Models 22
PID
SPRemote
PV OP
1 Control Models 23
Configuring PID
Use the Configure form to enter parameters for PID.
The form is divided into four tabs for configuring different aspects of the
controller. Each of these is explained below. You will need to change values
on the Tuning and Ranges tab, but the default values on the Filtering and
Other tab are suitable for most applications.
To help you configure the controller, ensure that you have connected the
Process Variable (PV) and output (OP) connections, and then use the Initialize
Values button on the Configure form.
When you click the button, the current values of the measured variable and
manipulated variable are used to initialize controller parameters as follows:
Name Initialized to
Operator set point Measured Variable
Bias Manipulated Variable
PV range minimum If Measured Variable > 0 0
If Measured Variable < 0 2 x Measured Variable
PV range maximum If Measured Variable > 0 2 x Measured variable
If Measured Variable < 0 0
Output range If Manipulated Variable > 0 0
maximum If Manipulated Variable < 0 2 x Manipulated
Variable
Output range If Manipulated Variable > 0 2 x Manipulated Variable
minimum If Manipulated Variable < 0 0
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
1 Control Models 24
PID Tuning Tab
The PID tuning tab has these configuration parameters:
1 Control Models 25
PID Ranges Tab
The PID Ranges tab has these configuration parameters:
1 Control Models 26
PID Filtering Tab
The PID Filtering tab has these configuration parameters:
1 Control Models 27
point changes is limited.
0 The proportional action acts only on process variable
movement. This enables smooth integrated response to set
point changes and fast response to disturbances.
1 Control Models 28
Anti-reset windup ARWindup – Yes Yes
No
Range below set DBlo % 0 -> 100 0
point
Range above set DBhi % 0 -> 100 0
point
1 Control Models 29
Integral error without
anti-reset windup
Manipulated variable
Proportional error
1 Control Models 30
specify the lower and upper limits of this dead band as a percentage of the
process variable range (PVmax–PVmin).
PID Algorithms
The equations used in the PID model to describe controller output depend on
the algorithm you choose:
• Ideal algorithm
• Series algorithm
• Parallel algorithm
Ideal Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain ∗ E P +
IntegralTime ∫ E I .dt + DerivTime
dt
Where:
EP = Proportional mode error
All of these errors are derived from the standard error (E), which is defined
as:
E = set point – process variable
Series Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain.E P +
IntegralTime ∫ E I .dt .1 + DerivTime
dt
Parallel Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain.E P +
IntegralTime ∫ E I .dt + DerivTime
dt
Note: All values of the variables used in these equations are the
scaled values based on the process variable range minimum and
1 Control Models 31
maximum or the output range minimum and maximum.
The first three buttons at the top level enable you to switch between auto,
manual, and cascade modes respectively. When you are in auto mode (as in
the example), the value for SP has a white background, which means you can
type a new value. When you are in manual mode, the value for OP has a
white background, which means you can change the value.
Pressing the fourth button from the left opens the Configure table so that you
can easily change configuration parameters.
The fifth button opens the plot for the controller which shows values of SP, PV
and OP either in process units, or as a percentage of the range versus time.
The sixth button plots the same variables but shows them as percentages of
range, instead of in process units.
The compact faceplate shows a subset of the information found on the full
faceplate.
1 Control Models 32
The Ziegler-Nichols closed-loop method is suitable for many single-loop
controllers. For processes that contain interacting loops, open-loop tuning
methods are preferred. For more information on open-loop tuning, please
consult a text book on controller tuning.
The gain that gives these continuous oscillations is called the ultimate gain,
KU . The period of the oscillations is called the ultimate period, TU .
PI 0.45 K u Tu / 1.2 0
PID 0.6 K u Tu / 2 Tu / 8
1 Control Models 33
PIDIncr
SPRemote
PV OP
1 Control Models 34
simulations which previously used PID, you can drag and drop PIDIncr from
Simulation Explorer on to an existing controller and select yes to use PIDIncr
in place of PID. The controller settings will be automatically mapped across.
Configuring PIDIncr
Use the Configure form to enter parameters for PID.
The form is divided into four tabs for configuring different aspects of the
controller. Each of these is explained below. You will need to change values
on the Tuning and Ranges tab, but the default values on the Filtering and
Other tab are suitable for most applications.
To help you configure the controller, ensure that you have connected the
process variable (PV) and output (OP) connections, and then use the Initialize
Values button on the Configure form.
When you click the button, the current values of the measured variable and
manipulated variable are used to initialize controller parameters as follows:
Parameter Initialized to
Set point Measured Variable
Initial Output Manipulated Variable
PV range minimum If Measured Variable > 0 0
If Measured Variable < 0 2 x Measured Variable
PV range maximum If Measured Variable > 0 2 x Measured variable
If Measured Variable < 0 0
Output range If Manipulated Variable > 0 0
maximum If Manipulated Variable < 0 2 x Manipulated
Variable
Output range If Manipulated Variable > 0 2 x Manipulated Variable
minimum If Manipulated Variable < 0 0
1 Control Models 35
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
1 Control Models 36
Action for PIDIncr
Controller action determines whether the controller is direct or reverse acting.
The following table shows the effects of direct or reverse action:
1 Control Models 37
If Clip PV to Range is selected, the value of PV used in the controller
equations is clipped between PVmin and PVmax, which means PVs is always
between 0 and 100%.
If Clip SP to range is selected, the value of SP used in the controller equations
is clipped between PVmin and PVmax.
1 Control Models 38
Derivative term filter constant for PIDIncr
This is the derivative term filter constant (Alpha). To avoid excessive
response to rapid changes in error, the error term is passed through a first-
order filter before it is used to calculate the derivative term. The time
constant for this filter is the product of Alpha and the derivative time.
In the Laplace domain the filter equation is:
1
g (s ) =
(Alpha.DerivTime).s + 1
Alpha can be set to any value between 0.03 and 1.0. Normal settings are
between 0.1 to 0.125. Increasing Alpha reduces the effect of the derivative
term.
1 Control Models 39
excessive due to abrupt changes in the set point.
1 Control Models 40
If DBlow and DBhi The result is
are
0.0 No dead band is active (default)
>0.0 Dead band is active within the ranges specified
PID Algorithms
The equations used in the PIDIncr model to describe controller output depend
on the algorithm you choose:
• Ideal algorithm
• Series algorithm
• Parallel algorithm
Ideal Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain ∗ E P +
IntegralTime ∫ E I .dt + DerivTime
dt
Where:
EP = Proportional mode error
All of these errors are derived from the standard error (E), which is defined
as:
E = set point – process variable
Series Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain.E P +
IntegralTime ∫ E I .dt .1 + DerivTime
dt
Parallel Algorithm
The equation used to determine the controller output (OP) is:
1 d (E D )
OP = Bias + Gain.E P +
IntegralTime ∫ E I .dt + DerivTime
dt
Note: All values of the variables used in these equations are the
scaled values based on the process variable range minimum and
maximum or the output range minimum and maximum.
1 Control Models 41
Anti Reset Windup
In common with modern industrial controllers, PIDIncr implements anti reset
windup. This section explains what anti reset windup is.
The integral term of a controller causes its output to continue changing as
long as there is a non-zero error. If the error cannot be eliminated quickly,
then eventually the integral term saturates the control action (the valve is
completely open or shut). Then, even if the error returns to zero, the control
action may remain saturated. This phenomenon is called reset windup or
integral windup.
The integral mode of the controller does not reverse the direction of the
controller output until the measurement crosses the set point.
Proportional action, on the other hand, reverses the direction of the controller
output when the controller input reverses:
Proportional error = SP − PV
Manipulated variable
Proportional error
1 Control Models 42
the proportional error term decreases, while the integral term continues to
increase. The controller has to pull back the extra amount that the integral
term has wound up while the manipulated variable has saturated at its
minimum.
The first three buttons at the top level enable you to switch between auto,
manual, and cascade modes respectively. When you are in auto mode (as in
the example), the value for SP has a white background, which means you can
type a new value. When you are in manual mode, the value for OP has a
white background, which means you can change the value.
The fourth button enables you to switch between viewing values in process
units or percentages of range. To see the process units you can hold the
mouse pointer over the label SP, PV or OP.
1 Control Models 43
Pressing the fifth button opens the Configure form so that you can easily
change configuration parameters.
The sixth button opens the plot for the controller which shows values of SP,
PV and OP either in process units, or as a percentage of the range, versus
time.
The seventh button opens the Tune form which you can use to automatically
determine tuning parameters for the controller.
To save space the compact faceplate only includes the three buttons required
to change controller mode, and does not include bars to represent values.
Otherwise the behavior is the same as for the main faceplate.
1 Control Models 44
For step tests, in some cases the automatic tuner may find it difficult to
estimate the Time constant and Dead time from the test results. This can be
true if you are using the Discretize model to simulate the effect of an analyzer
in the control loop. For this reason we recommend you visually check that the
values shown look reasonable. The diagram below shows how the values can
be determined from the step response curve.
55 65
54
62.
5
53
52 60
Controller Output
Process Variable
Set Point
51 57.
5
50
55
49
48 52.
5 Dead time Time constant
47
50
46
45
0 0.5 1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6 6.5 7
Time Hours
If you would like to change the values used for the calculation of the tuning
parameters type in the values you want to use in place of those determined
by the automatic tuner.
If for any reason you wish to stop a test without calculating the results press
the Cancel test button to abort the test.
To calculate tuning parameters select the Tuning parameters tab. Select the
tuning parameter options and press the Calculate button to calculate the
results. If you wish to update the controller with the calculated values click
the Update controller button.
Tips:
1 Control Models 45
to their previous values. To prevent this click the Update
controller button after you have rewound or restarted the
simulation.
Tip: You can try different steps directions and sizes to see how
these affect the results. The more non-linear the process the
greater the differences will be.
For a closed loop ATV test the control operates as a relay controller to create
a limit cycle in the PV. For a Direct acting controller, when the PV is greater
than the set point, the controller moves the output to the initial output plus
the relay amplitude that you specify. When the PV is less than the set point
the controller moves the output to the initial value less the amplitude. If the
controller action is reverse this works the other way round. It is important
that you select the correct controller action before running this test.
The size and period of the limit cycle in the PV is used to determine the
ultimate gain and ultimate period of the process.
Tip: The Closed Loop ATV test method is only effective if you
have some dead time in the control loop. If you have not
modeled loop dead time you should use the Open Loop test
method.
1 Control Models 46
IMC – Uses tuning rules developed by Rivera and Morari. Aims to provide
robust control with no oscillation or overshoot. Provides a more damped
response than Ziegler-Nichols and Cohen-Coon
If you select the IMC tuning rule you must enter a value for lambda. This is a
filter parameter. It must be greater than 0.2 times the calculated process
time constant. For a PI controller is must be greater than 1.7 times the dead
time, and for a PID controller it must be greater than 0.25 times the dead
time. A smaller value gives a faster response.
IAE – Aims to minimize the integrated absolute error in the response to a
disturbance
ISE – Aims to minimize the integrated squared error in the response to a
disturbance
ITAE – Aims to minimize the integrated time waited absolute error in the
response to a disturbance
PRBS
Output_
PRBS generates a pseudo-random binary signal. You can use the output from
the model in two ways:
1 Control Models 47
• As a noise source added to a signal using the Sum model.
• As the signal itself.
PRBS can be used for testing how well your control system rejects noise.
The output signal can have either a fixed or varying amplitude.
PRBS Equations
PRBS can be used to generate a noise signal with one of the following:
• Fixed amplitude
• Variable amplitude
When fixed amplitude signal is selected, the output is always the datum plus
or minus the amplitude. If a variable amplitude is selected, the output is the
datum plus or minus a random value in the range (-amplitude) to
(+amplitude). In both cases, the output signal is re-calculated at an interval
defined by the specified period of the noise.
The following graphs show the two types of pseudo-random signals that can
be generated:
Fixed Amplitude
Upper
bound
Amplitude
Datum
Amplitude
Lower
bound
Time
1 Control Models 48
Varying Amplitude
Upper
bound
Amplitude
Datum
Amplitude
Lower
bound
Time
Configuring PRBS
PRBS has the following configuration parameters:
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
If The result is
AmplitudeType is
Fixed Deviation around Datum is fixed at -Amplitude or
+Amplitude.
Variable Deviation around Datum can vary between -Amplitude
and +Amplitude.
1 Control Models 49
Datum for PRBS
Datum specifies the fixed value around which the random deviation occurs.
For steady-state and other non-dynamic run modes, the output from PRBS is
fixed at Datum.
Ratio
Input1
Output_
Input2
Ratio Equations
The model equation calculates the ratio of the first input signal to the second
input signal:
Input 1
Output _ =
Input 2
Configuring Ratio
Ratio has no configuration parameters.
Scale
Input_ Output_
1 Control Models 50
Scale maps an input signal onto a scale, where a given minimum is 0% and a
given maximum is 100%. The output signal can also be clipped to remain
within the range 0 to 100%.
Scale Equations
Scale uses the following scaling equation:
100.(Input _ − ScaleMin )
Output _ =
ScaleMax − ScaleMin
If clipping is enabled, Output_ will never be less than 0 or greater than 100,
even if this equation calculates a value outside of this range.
Configuring Scale
Scale has the following configuration parameters:
1 Control Models 51
SplitRange
Output1
Input_
Output2
SplitRange Equations
The following illustration shows the relationship between the input and output
signals:
Configuring SplitRange
SplitRange has the following configuration parameter:
1 Control Models 52
Output1InMin Value of input above which – -1E9 -> 1E9 0
Output 1 starts to change
Output1InMax Value of input above which – -1E9 -> 1E9 50
Output 1 stops changing
Output2Action Action for Output 2 – Direct Direct
Reverse
Output2Min Minimum value of Output 2 – -1E9 -> 1E9 0
Output2Max Maximum value of Output 2 – -1E9 -> 1E9 100
Output2InMin Value of input above which – -1E9 -> 1E9 50
Output 2 starts to change
Output2InMax Value of input above which – -1E9 -> 1E9 100
Output 2 stops changing
1 Control Models 53
Output2Max for SplitRange
Output2Max specifies the maximum value of output 2.
SteamPtoT
P PT T
Sum
Input1
Output_
Input2
Sum evaluates its output as the sum of the two input signals.
Sum Equations
The equation used in the Sum model is:
Output _ = Input 1 + Input 2
Configuring Sum
Sum has no configuration parameters.
1 Control Models 54
Transform
Input_ Output_
Transform Equations
The equation used depends on the transform operation selected as follows:
Transform Equation
Loge Output _ = ln( Input _)
None Output _ = Input _
Power
Output _ = Input _ Power
Square
Output _ = Input _ 2
Square root
Output _ = Input _
Configuring Transform
Transform has the following configuration parameters:
1 Control Models 55
Output _ = Input _ Power
Valve_dyn
Input_
Output_
Valve_dyn models the dynamics of a valve actuator. It relates the input signal
to a control valve to the valve stem position. It includes the following options:
• Direct or reverse action.
• First-order, second-order, or negligible dynamic effects.
• Velocity limiting (when using first- or second-order dynamics).
• Modeling of hysteresis effects caused by valve dead band.
Connect Valve_dyn between a controller output signal and the input signal to
a Valve block. Make sure the input signal is in the range 0 to 100%. The
output signal represents the valve percentage open.
Valve_dyn Equations
When the first-order dynamics option is used, the valve stem response is
modeled using the following first-order differential equation:
d (Output )
Input = Output + Tau1.
dt
Where:
Tau1 = First-order time constant
For second-order dynamics, the following second-order differential equation is
used:
d 2 (Output ) d (Output )
Input = Tau 2 . 2
+ 2.Gamma.Tau. + Output
dt dt
StemMass
Tau =
Hookes
Where:
1 Control Models 56
When velocity limiting is used, the rate of change of stem position is clipped
so that it does not exceed the maximum velocity defined by the stroke time.
Configuring Valve_dyn
The properties for Valve_dyn are:
If your process models are written to work in time units other than hours, you
will need to change the control model time units. See Time Units in Control
Models, earlier in this chapter.
1 Control Models 57
StemMass for Valve_dyn
StemMass is the mass of the stem assembly. A greater mass results in a
slower response to input signal changes.
StemMass has no effect when Dynamics=None.
Valve Closing
position
Opening
0 100
Input
signal
DBand
1 Control Models 58
2 Aspen Reactions Toolkit
Configuration
T
ART Reactions
P Species Reaction Rate
Model
zi
Kinetic
Module
Based on this design, each ART Reaction Model has three portions:
• Reaction Global Structures
• This portion of Reaction Model consists of a set of global structures
associated with the reaction configuration in Module, Classes, and
Reactions hierarchies. It encapsulates the declarations of all configuration
parameters and variables (such as intrinsic pre-exponential constants and
activation energies). The parameters and variables contained in this
portion of the ART Reactions Model component can be shared by many
instances of reactor models of different types (PFR or CSTR).
• Non-distributed portion of the Reaction Model
• This portion of the Reaction Model consists of a set of non-distributed
submodels in Module, Class, and Reaction hierarchies. It encapsulates the
declarations of variables and the equations which do not need to be
discretized for a Distributed system. This non-distributed portion of the
ART Reactions Model component is common for both the Lumped and
Distributed systems, and is called the same way for both systems. The
Examples
To use the built-in Reactions Model component to write a model called
CSTRMassBal for the mass balance calculation of a CSTR (Lumped system):
Model CSTRMassBal
T as Temperature;
P as Pressure;
z(ComponentList) as molefraction;
Rho as dens_mol;
call (Mws) = pmolweights ();
…
// Reference to the Reaction Global Structure
IRxnCfg as external ARTRxnCfg;
Vol*sigma(IRxnModel(node).CompRate("Vapor",componentlist))+
Vol*$Rho(Node)= 0;
Endfor
End
3 Select Custom OCX from the Available Form Definitions list, and click
OK.
Configuration sheet
Use this sheet to add, edit, and delete reactions from a reaction set. You can
specify a Name for each reaction; names must be unique and a maximum of
8 characters long). You can switch to a different Reaction Class. You can
also set the Status of each reaction to on or off. Set a reaction's status to off
to set its rate to be zero without deleting the reaction from the sheet.
In the Edit Stoichiometry dialog box, you can change the reaction class of a
reaction, specify if the reaction is reversible and specify reactants and
products, and their stoichiometric coefficients.
Kinetic sheet
Use this sheet to specify the reacting phase, concentration basis, rate basis,
and kinetic parameters for rate-controlled reactions of the power-law, LHHW,
GLHHW classes. For GLHHW reactions, you also need to specify the shared
adsorption parameters on the GLHHW Ads. sheet.
Click the Driving Force button to bring up the Driving Force dialog box to
enter parameters for the driving force expression for the selected reaction.
Important Note: You must click Apply for the changes to take
effect.
Activity sheet
Use this sheet to define reaction activity classes and associate them with
reactions. Reaction activity classes are scalar multipliers to the reaction rate.
The net reaction rate for a reaction is calculated as the product of the
reaction's intrinsic rate and all reaction activities associated with the reaction.
The relationship between the intrinsic rate, ri ,intrinsic , and net reaction rate,
ri ,net , is:
where the a j are all the reaction activities associated with the reaction i.
The activity classes defined here create activity variables in a reactor block
that uses the Reaction Model component. The activity values entered here are
only the default values to initialize the activity variables in the block.,
Individual reactor blocks that uses the Reaction Model component can
override them.
Where:
K eq = Equilibrium constant
T =Temperature in Kelvin
and
A, B, C, D are user-specified constants
Power Law
The general rate expression for a reaction can be written
as γ = γ forward − γ reverse
Where:
γ forward = Rate of forward reaction
n = Temperature exponent
Ea = Activation energy
(
γ reverse = K r ∏ C iv ri
)
Where:
Kr = Reverse kinetic factor
K eq
=
Kf
and
υr = Concentration exponent for the reverse reaction
The concentration exponents for the reverse rate (υr ) can be computed from
the stoichiometry and the concentration exponents for the forward rate(υf).
Details can be found in the appendix section Calculation of concentration
exponents for the reverse rate.
The concentration terms Ci depend on the concentration basis you select:
LHHW
The general rate expression for a reaction can be written as:
γ = γ forward − γ reverse
Where:
γ forward = Rate of forward reaction
γ forward =
( v
K f ∏ Ci f i )
Adsorption Expression
where:
C = Component concentration
υf = Concentration exponent for forward reaction
i = Component index
Adsorption expression= ΣK i ∏ C j j { ( v
)}
m
n = Temperature exponent
Ea = Activation energy
γ reverse =
( v
K r ∏ Ci r i )
Adsorption Expression
Where:
Kr = Reverse kinetic factor
K eq
=
Kf
υr = Concentration exponent for reverse reaction
The concentration exponents for the reverse rate (υr ) can be computed from
the stoichiometry and the concentration exponents for the forward rate(υf).
Details can be found in the appendix section Calculation of concentration
exponents for the reverse rate.
The concentration terms Ci and Cj depend on the concentration basis you
select:
The adsorption equilibrium constants, Ki, are calculated from the following
correlation:
ln Ki = Ai + Bi/T + Ci * ln(T) + Di * T
Where:
T = Temperature in Kelvin
Ai, Bi, Ci, Di = User-supplied coefficients
Equilibrium
For an equilibrium reaction, the rate expression is replaced by an equation
relating the equilibrium constant to the concentrations at equilibrium:
K eq = ∏ aivsi
where:
Keq = Equilibrium constant
ai = Activity of component i
υsi = Stoichiometric coefficient of component i
Keq can be computed from rigorous thermodynamics or using an empirical
correlation of the form:
B
K eq = A + + C × ln(T ) + D × T
T
Where:
T = Temperature in Kelvin
and
A, B, C, D are user-specified constants
The thermodynamic activity ai is defined as:
fi
ai =
f i0
where:
fi = Fugacity of component i
fi0 = Fugacity of component i in its standard state
The standard state used depends on the species involved
For non-electrolyte systems, the standard state is assumed to be pure
component ideal gas at the reference pressure (Pref=1atm). The activity is
therefore given by :
fi
ai =
Pref
Note: You must refresh the ACM Explorer in order to see the
generated templates.
Module Equations
For each Reaction Model component, there are two templates (submodels) for
writing the module equations. They are ModuleIDModNDModel for writing the
module non-distributed equations, and ModuleIDModDistModel for writing the
module distributed equations, where ModuleID is the ID of the Reaction Model
component.
You are not required to write any module equations. However, if you do, you
may need to change the specification of the variables so that the problem
remains square.
Class Equations
For each reaction class that you declare in the wizard, there are two model
templates (submodels) for writing the class equations. They are
ClassNameClsNDModel for writing the class non-distributed equations, and
ClassNameClsDistModel for writing the class distributed equations, where
ClassName is the name of the reaction class.
You are not required to write any class equations. However, if you do, you
may need to change the specification of the variables so that the problem
remains square.
Reaction Equations
For each reaction class that you declare in the wizard, there are two model
templates (submodels) for writing the reaction equations. They are
ClassNameRxnNDModel for writing the reaction non-distributed equations and
ClassNameRxnRateModel for writing the reaction rate expression and other
reaction distributed equations, where ClassName is the name of the reaction
class.
It is in ClassNameRxnRateModel that the variables for rate constant (K) and
reaction rate (Rate) are declared and the equations for the calculation of rate
constant and rate expression are defined.
Reaction Submodels
NewModNDModel
NewModDistModel
Cls1ClsNDModel
Cls2ClsNDModel
…
NewClsNDModelUnion
Cls1ClsDistModel
Cls2ClsDistModel
…
NewClsDistModelUnion
Cls1RxnNDModel
Cls2RxnNDModel
…
NewRxnNDModelUnion
Cls1RxnRateModel
Cls2RxnRateModel
…
NewRxnDistModelUnion
NewRxnCfgModel
NewRxnModel
Reaction Submodels
NewRxnModel
NewRxnCfgModel
NewRxnDistModelUnion
Cls1RxnRateModel
Cls2RxnRateModel
…
NewRxnNDModelUnion
Cls1RxnNDModel
Cls2RxnNDModel
…
NewClsDistModelUnion
Cls1ClsDistModel
Cls2ClsDistModel
…
NewClsNDModelUnion
Cls1ClsNDModel
Cls2ClsNDModel
…
NewModDistModel
NewModNDModel
Once the installation is complete, the exported model component is ready for
use inside Aspen Plus.
To use the exported Custom Reaction Model component, do the following in
Aspen Plus:
1 Create a new reaction object in Aspen Plus by clicking New on the
Reactions object manager.
2 Select USERACM as the type of the new reaction object.
3 On the Setup sheet of the newly created reaction object, the User model
dropdown box will display a list of all installed custom reaction models.
Select the appropriate model.
More details about USERACM input can be found in the Aspen Plus help.
Appendix
Example of Assigning Variables and
Equations to Hierarchy Levels
To demonstrate how to best structure the kinetic module in terms of module,
class, and reaction hierarchies, consider the following example:
− ∆E1
r1 = φ A0,1e R ⋅T n
Rxn1: A → B ; PA 1
− ∆E2
r2 = φ A0, 2 e R ⋅T n2
Rxn2: A → C ; PA
− ∆E3
φ A0,3e R ⋅T
PB
n3
Rxn3: B → C ; r3 =
1 + ∑ K ads ,i Pi
i
− ∆E4
φ A0, 4 e R ⋅T
PB
n4
Rxn4: B → D ; r4 =
1 + ∑ K ads ,i Pi
i
r5 = φ A0,5e R⋅T n5
Rxn5: C → D ; PC
causes catalyst to deactivate, K ads ,i is defined by K ads ,i = K ads 0,i e R⋅T , and the
index i varies over the four species A, B, C, and D.
Define α, β, Coke, and φ as module variables, since they are used in all rate
laws. Define α and β as module non-distributed variables because they are
constant across the distributed domain. The amount of coke on the catalyst
can vary within the reactor, and therefore Coke should be a module
distributed variable. Since Coke is a distributed variable, φ must also be a
module distributed variable. It is defined by the following equation:
φ = α e − β ⋅Coke
As this equation involves only module variables and applies to all reactions, it
is a module equation. Because it depends on distributed variables, it is a
distributed equation.
Reactions which follow the same functional form should belong to the same
class, so we have two reaction classes, PowerLaw and LHHW. Rxn1, Rxn2,
and Rxn5 belong to PowerLaw, while Rxn3 and Rxn4 belong to LHHW.
The variables such as A0,1 , ∆E1 , n1 are declared in the Reaction Global
Structure at Reaction hierarchy, since they are intrinsic kinetic parameters
and are unique for each reaction. Since the variables in the PowerLaw
reactions are all reaction-specific (no variable is shared among reactions in
the class), there are no class variables. In the LHHW reaction class, define the
K ads 0,i and ∆H i variables as Reaction Global Structure at class hierarchy. The
K ads ,i is defined as class distributed variables, since they are all shared by all
reactions in LHHW. The K ads ,i are distributed variables since they depend on
temperature which can vary with reactor length.
Species Symbols Reactant and product species identified by component IDs defined
in the ACM component list.
Coefficients Integer or real numbers preceding species symbols to indicate the
number of moles of each species present as either reactants or
products. Coefficients are always followed by the * delimiter. A
coefficient of 1 can be omitted.
Currently ART does not check the atom balance. Care must be
taken to ensure the reaction is balanced.
Delimiters + Separates species on either side of a reaction.
* Separates a stoichiometric coefficient from its species.
Calculation of Concentration
Exponents for Reverse Rate
Consider a reversible reaction:
a*A + b*B <=> c*C + d*D
Suppose νfa, νfb , νfc and νfd are the concentration exponents for the forward
rate and νra, νrb , νrc and νrd are the concentration exponents for the reverse
rate.
The forward rate is given by:
γ forward = K f [C A ]ν [C B ]ν [C C ]ν
fA fB fC
[C D ]ν fD
= K r [C A ] [C B ]ν [C C ]ν [C D ]ν
ν rA
γ reverse
rB rC rD
Where:
Kf = Forward rate constant
Kr = Reverse rate constant
C = Concentration
At equilibrium:
γ forward = γ reverse
i.e.
K f [C A ] [C B ]ν [CC ]ν [C D ]ν = K r [C A ] rA [C B ] rB [C C ] rC [C D ] rD
ν fA fB fC fD ν ν ν ν
Since by definition:
Kf
K eq =
Kr
and
[C A ]a [C B ]b
the following relation must be satisfied at equilibrium:
[C A ]ν [C B ]ν [CC ]ν [C D ]ν
rA rB rC rD
=
[CC ]c [C D ]d
[C A ]ν [C B ]ν [CC ]ν [C D ]ν
fA fB fC fD
[C A ]a [C B ]b
This implies that for consistency with equilibrium conditions, the
concentration exponents for the forward and reverse reactions must be
related as follows:
ν rA − ν fA = a
ν rB − ν fB = b
ν rC − ν fC = c
ν rD − ν fD = d
In other words, the concentration exponents for the reverse reaction can be
computed from the concentration exponents of the forward reaction rate and
the reaction stoichiometry.
The following are the non-distributed portion of sub-models for the built-in
reaction model:
ARTRxnCfgModel This is the topmost sub-model for non-distributed portion of the built-in
reaction model.. This sub-model inherits from ARTRxnBaseCfgModel.
ARTRxnBaseCfgModel This sub-model declares variables that are common to built-in and
custom reaction non-distributed sub-models
ARTModND This is the non-distributed portion of module sub-model in the built-in
reaction model. This is a dummy sub-model, since there is no non-
distributed module variable in the built-in reaction model.
ARTClsNDUnion This is a container for all the non-distributed portion of class sub-
models in the built-in reaction model (i.e. GLHHWClsND, LHHWClsND,
PowerLawClsND).
ARTRxnNDUnion This is a container for all the non-distributed portion of reaction sub-
models in the built-in reaction model (i.e. GLHHWRxnND, LHHWRxnND,
PowerLawRxnND).
GLHHWClsND This is the non-distributed portion of class sub-model for GLHHW. This
is a dummy sub-model, since there is no non-distributed class variable
for GLHHW class.
GLHHWRxnND This is the non-distributed portion of reaction sub-model for GLHHW.
This is a dummy sub-model, since there is no non-distributed reaction
variable for GLHHW class.
LHHWClsND This is the non-distributed portion of class sub-model for LHHW. This is
a dummy sub-model, since there is no non-distributed class variable
for LHHW class.
LHHWRxnND This is the non-distributed portion of reaction sub-model for LHHW.
This is a dummy sub-model, since there is no non-distributed reaction
variable for LHHW class.
PowerLawClsND This is the non-distributed portion of class sub-model for PowerLaw.
This is a dummy sub-model, since there is no non-distributed class
variable for PowerLawclass.
PowerLawRxnND This is the non-distributed portion of reaction sub-model for PowerLaw.
This is a dummy sub-model, since there is no non-distributed reaction
variable for PowerLawclass.
The following are the non-distributed portion of sub-models for the built-in
reaction model
ARTRxnModel This is the topmost sub-model for distributed portion of the built-in
reaction model. This sub-model inherits from ARTRxnBaseModel
ARTRxnBaseModel This sub-model declares variables that are common to the distributed
portion of the built-in and custom reaction models.
ARTModDist This is the distributed portion of module sub-model in the built-in
reaction model. This is a dummy sub-model, since there is no
distributed module variable in the built-in reaction model.
ARTClsDistUnion This is a container for all the distributed portion of class sub-models in
the built-in reaction model (i.e. GLHHWClsDist, LHHWClsDist,
PowerLawClsDist).
ARTRxnDistUnion This is a container for all the distributed portion of reaction sub-models
in the built-in reaction model (i.e. GLHHWRxnDist, LHHWRxnDist,
The following are the non-distributed portion of sub-models for the custom
reaction model of the ID, ModuleID:
ModuleIDRxnCfgModel This is the topmost sub-model for non-distributed portion of a
custom reaction model.
ModuleIDModND This is the non-distributed portion of module sub-model in a
custom reaction model. This sub-model inherits ARTModND.
ModuleIDClsNDUnion This is a container for all the non-distributed portion of class sub-
models in a custom reaction model. This sub-model inherits
ARTClsND.
ModuleIDRxnND This is a container for all the non-distributed portion of reaction
sub-models in a custom reaction. This sub-model inherits
ARTRxnND.
ClassIDClsND This is the non-distributed portion of class sub-model for reaction
class, ClsID.
ClassIDRxnND This is the non-distributed portion of reaction sub-model for
reaction class, ClsID.
The following are the distributed portion of sub-models for the custom
reaction model of the ID, ModuleID:
ModuleIDRxnModel This is the topmost sub-model for distributed portion of a custom
reaction model.
ModuleIDModDist This is the distributed portion of module sub-model in a custom
reaction model. This sub-model inherits ARTModDist.
ModuleIDClsDistUnion This is a container for all the distributed portion of class sub-
models in a custom reaction. This sub-model inherits ARTClsDist.
ModuleIDRxnDistUnion This is a container for all the distributed portion of reaction sub-
This chapter describes the physical property procedures included in the Aspen
Custom Modeler library.
There are two main categories of physical property procedures. They are
procedures with analytic property derivatives and procedures without analytic
property derivatives.
Important Note:
3 Property Procedures 96
Description Variable Type Base Units
Liquid thermal Cond_liq W/m/K
conductivity
pCond_Liq Example
The following is an example of the pCond_Liq procedure:
call (T_cond) = pCond_Liq (T1, P1, x);
Procedure pCond_Vap
pCond_Vap is a physical property procedure that calculates the thermal
conductivity of a vapor.
pCond_Vap Example
The following is an example of the pCond_vap procedure:
call (T_cond) = pCond_Vap (Tv, Pv, y);
Procedure pCp_Mol_Liq
pCp_Mol_Liq is a physical property procedure that calculates the molar heat
capacity of a liquid at constant pressure.
3 Property Procedures 97
pCp_Mol_Liq Output Variable Types
The output variable types for pCp_Mol_Liq are:
pCp_Mol_Liq Example
The following is an example of the pCp_Mol_Liq procedure:
call (Cpl_in) = pCp_Mol_Liq (Tin, Pin, x_in);
Procedure pCp_Mol_Vap
pCp_Mol_Vap is a physical property procedure that calculates molar heat
capacity of a vapor at constant pressure.
pCp_Mol_Vap Example
The following is an example of the pCp_Mol_Vap procedure:
call (Cp_in) = pCp_Mol_Vap (Tin, Pin, Out_P.Z);
Procedure pCv_Mol_Liq
pCv_Mol_Liq is a physical property procedure that calculates the molar heat
capacity of a liquid at constant volume.
3 Property Procedures 98
Pressure Pressure bar
Composition Molefraction(*) kmol/kmol
pCv_Mol_Liq Example
The following is an example of the pCv_Mol_Liq procedure:
call (Cv1) = pCv_Mol_Liq (T1, P1, x);
Procedure pCv_Mol_Vap
pCv_Mol_Vap is a physical property procedure that calculates the molar heat
capacity of a vapor at constant volume.
pCv_Mol_Vap Example
The following is an example of the pCv_Mol_Vap procedure:
call (CVv) = pCv_Mol_Vap (Tv, Pv, y);
Procedure pDens_Mass_Liq
pDens_Mass_Liq is a physical property procedure that calculates the mass
density of a liquid.
3 Property Procedures 99
Description Variable Type Base Units
Temperature Temperature C
Pressure Pressure bar
Composition Molefraction(*) kmol/kmol
pDens_Mass_Liq Example
The following is an example of the pDens_Mass_Liq procedure:
call (RHOml) = pDens_Mass_Liq (T1, P1, x);
Procedure pDens_Mass_Vap
pDens_Mass_Vap is a physical property procedure that calculates the mass
density of a vapor.
pDens_Mass_Vap Example
The following is an example of the pDens_Mass_Vap procedure:
call (RHOmv) = pDens_Mass_Vap (Tv, Pv, y);
Procedure pDens_Mol_Liq
pDens_Mol_Liq is a physical property procedure that calculates the molar
density of a liquid.
pDens_Mol_Liq Example
The following is an example of the pDens_Mol_Liq procedure:
call (rho) = pDens_Mol_Liq (T, P, x);
Procedure pDens_Mol_Vap
pDens_Mol_Vap is a physical property procedure that calculates the molar
density of a vapor.
pDens_Mol_Vap Example
The following is an example of the pDens_Mol_Vap procedure:
call (Rhov) = pDens_Mol_Vap (T, P, y);
pDiffus_Liq Example
The following is an example of the pDiffus_Liq procedure:
call (D_liq) = pDiffus_Liq (T1, P1, X);
Procedure pDiffus_Vap
pDiffus_Vap is a physical property procedure that calculates the vapor
diffusion coefficients of components in a mixture.
Procedure pEnth_Mol_Liq
pEnth_Mol_Liq is a physical property procedure that calculates liquid molar
enthalpy.
pEnth_Mol_Liq Example
The following is an example of the pEnth_Mol_Liq procedure:
Rig_enth_mol_liq: call (h) = pEnth_Mol_Liq (T, P, x);
Procedure pEnth_Mol_Vap
pEnth_Mol_Vap is a physical property procedure that calculates vapor molar
enthalpy.
pEnth_Mol_Vap Example
The following is an example of the pEnth_Mol_Vap procedure:
call (hv) = pEnth_Mol_Vap (T, P, y);
Procedure pEntr_Mol_Liq
pEntr_Mol_Liq is a physical property procedure that calculates liquid molar
entropy.
pEntr_Mol_Liq Example
The following is an example of the pEntr_Mol_Liq procedure:
call (s) = pEntr_Mol_Liq (T, P, x);
Procedure pEntr_Mol_Vap
pEntr_Mol_Vap is a physical property procedure that calculates vapor molar
entropy.
pEntr_Mol_Vap Example
The following is an example of the pEntr_Mol_Vap procedure:
call (sv) = pEntr_Mol_Vap (Tv_out, Pv_out, y_out);
Procedure pFuga_Liq
pFuga_Liq is a physical property procedure that calculates component liquid
fugacity coefficients.
pFuga_Liq Example
The following is an example of the pFuga_Liq procedure:
call (fuga_coeff) = pFuga_Liq (T1, P1, x);
Procedure pFuga_Vap
pFuga_Vap is a physical property procedure that calculates component vapor
fugacity coefficients.
pFuga_Vap Example
The following is an example of the pFuga_Vap procedure:
call (fuga_coeff) = pFuga_Vap (Tv, Pv, Y);
Procedure pGibbs_Mol_Liq
pGibbs_Mol_Liq is a physical property procedure that calculates liquid molar
Gibbs Free Energy.
pGibbs_Mol_Liq Example
The following is an example of the pGibbs_Mol_Liq procedure:
call (Gl) = pGibbs_Mol_Liq (Tx_in, Px_in, x_in);
Procedure pGibbs_Mol_Vap
pGibbs_Mol_ Vap is a physical property procedure that calculates vapor molar
Gibbs Free Energy.
pGibbs_Mol_Vap Example
The following is an example of the pGibbs_Mol_Vap procedure:
call (Gv) = pGibbs_Mol_Vap (Ty_in, Py_in, y_in);
Procedure pKllValues
pKllValues is a physical property procedure that calculates component liquid-
liquid equilibrium K values.
pKllValues Example
The following is an example of the pKllValues procedure:
Procedure pKValues
pKValues is a physical property procedure that calculates component vapor-
liquid equilibrium K values.
pKValues Example
The following is an example of the pKValues procedure:
call (Kfc) = pKValues (T_feed, P_feed, xfc, yfc);
Procedure pSurf_Tens
pSurf_Tens is a physical property procedure that calculates liquid surface
tension.
Procedure pVisc_Liq
pVisc_Liq is a physical property procedure that calculates the viscosity of a
liquid.
pVisc_Liq Example
The following is an example of the pVisc_Liq procedure:
call (viscL) = pVisc_Liq (T, P, x);
Procedure pVisc_Vap
pVisc_Vap is a physical property procedure that calculates the viscosity of a
vapor.
pVisc_Vap Example
The following is an example of the pVisc_Vap procedure:
call (visg ) = pVisc_Vap (Out_P.T, Out_P.P, y_out);
pAct_Coeff_Liq Example
The following is an example of the pAct_Coeff_Liq procedure:
call (Activ) = pAct_Coeff_Liq (T1, P1, x);
Procedure pBubt
pBubt is a physical property procedure that calculates bubble point
temperature at a fixed pressure.
pBubt Example
The following is an example of the pBubt procedure:
call (T_bubble) = pBubt (P, x_out);
Procedure pDens_Mass_Sol
pDens_Mass_Sol is a physical property procedure that calculates the mass
density of a solid.
pDens_Mass_Sol Example
The following is an example of the pDens_Mass_Sol procedure:
call (RHOms) = pDens_Mass_Sol (Ts, Ps, s);
Procedure pDens_Mol_Sol
pDens_Mol_Sol is a physical property procedure that calculates the molar
density of a solid.
pDens_Mol_Sol Example
The following is an example of the pDens_Mol_Sol procedure:
call (RHOs) = pDens_Mol_Sol (Ts_out, Ps_out, s);
Procedure pDewt
pDewt is a physical property procedure that calculates the dew point
temperature at fixed pressure.
pDewt Example
The following is an example of the pDewt procedure:
call (T_dew) = pDewt (P_out, x_out);
pEnth_Mol Example
The following is an example of the pEnth_Mol procedure:
call (hin) = pEnth_Mol (Tin, Pin, zin);
Procedure pEnth_Mol_Sol
pEnth_Mol_Sol is a physical property procedure that calculates solid molar
enthalpy.
pEnth_Mol_Sol Example
The following is an example of the pEnth_Mol_Sol procedure:
Procedure pEntr_Mol
pEntr_Mol is a physical property procedure that calculates mixed phase molar
entropy.
pEntr_Mol Example
The following is an example of the pEntr_Mol procedure:
call (sv) = pEntr_Mol (Tv_in, Pv_in, y_in);
Procedure pEntr_Mol_Sol
pEntr_Mol_Sol is a physical property procedure that calculates solid molar
entropy.
Procedure pFlash
pFlash is a physical property procedure that performs a two-phase flash at
the given temperature and pressure.
pFlash Example
The following is an example of the pFlash procedure:
call (y_out, x_out, vf, hv_out, hl_out) = pFlash (T, P, z);
Procedure pFlash3
pFlash3 is a physical property procedure that performs a three-phase flash at
the given temperature and pressure.
pFlash3 Example
The following is an example of the pFlash3 procedure:
call (y_out, x_out1, x_out2, vf, lf, hv_out, hl_out1,
hl_out2,) = pFlash3 (T, P, z, rigor);
Procedure pFlash3PH
pFlash3PH is a physical property procedure that performs a three-phase flash
at the given pressure and molar enthalpy.
pFlash3PH Example
The following is an example of the pFlash3PH procedure:
call (T, VF, Y, X1, X2, LF, HV, HL1, HL2) = pFlash3PH (P,
H, Z, rigor);
Procedure pFlash3PV
pFlash3PV is a physical property procedure that performs a three-phase flash
at the given pressure and vapor fraction.
pFlash3PV Example
The following is an example of the pFlash3PV procedure:
call (T, Y, X1, X2, LF, HV, HL1, HL2) = pFlash3PV (P, VF,
Z, rigor);
Procedure pFlash3TH
pFlash3TH is a physical property procedure that performs a three-phase flash
at the given temperature and molar enthalpy.
pFlash3TH Example
The following is an example of the pFlash3TH procedure:
Procedure pFlash3TV
pFlash3TV is a physical property procedure that performs a three-phase flash
at the given temperature and vapor fraction.
pFlash3TV Example
The following is an example of the pFlash3TV procedure:
call (P, Y, X1, X2, HV, HL1, HL2) = pFlashTV (T, VF, Z,
rigor);
Procedure pFlashPH
pFlashPH is a physical property procedure that performs a two-phase flash at
the given pressure and molar enthalpy.
pFlashPH Example
The following is an example of the pFlashPH procedure:
call (T, VF, Y, X, HV, HL) = pFlashPH (P, H, Z);
Procedure pFlashPV
pFlashPV is a physical property procedure that performs a two-phase flash at
the given pressure and vapor fraction.
pFlashPV Example
The following is an example of the pFlashPV procedure:
call (T, Y, X, HV, HL) = pFlashPV (P, VF, Z);
Procedure pFlashTH
pFlashTH is a physical property procedure that performs a two-phase flash at
the given temperature and molar enthalpy.
pFlashTH Example
The following is an example of the pFlashTH procedure:
call (P, VF, Y, X, HV, HL) = pFlashTH (T, H, Z);
Procedure pFlashTV
pFlashTV is a physical property procedure that performs a two-phase flash at
the given temperature and vapor fraction.
pFlashTV Example
The following is an example of the pFlashTV procedure:
call (P, Y, X, HV, HL) = pFlashTV (T, VF, Z);
Procedure pFuga_Sol
pFuga_Sol is a physical property procedure that calculates component solid
fugacity coefficients.
pFuga_Sol Example
The following is an example of the pFuga_Sol procedure:
call (fuga_coeff) = pFuga_Sol (Ts, Ps, w);
pGibbs_Mol_IDLGAS Example
The following is an example of the pGibbs_Mol_IDLGAS procedure:
call (GIdeal) = pGibbs_Mol_IDLGAS (Tv_in, Y_in);
Procedure pGibbs_Mol_Sol
pGibbs_Mol_Sol is a physical property procedure that calculates solid molar
Gibbs Free Energy.
Procedure pMolWeight
pMolWeight is a physical property procedure that calculates the average
molar weight.
pMolWeight Example
The following is an example of the pMolWeight procedure:
call (MWout ) = pMolWeight (zin );
Procedure pMolWeights
pMolWeights is a physical property procedure that calculates the component
molar weights.
pMolWeights Example
The following is an example of the pMolWeights procedure:
call (Mws) = pMolWeights();
ppH Example
The following is an example of the ppH procedure:
call (pH) = ppH (T, P, x);
Procedure pPropZ
pPropZ is a physical property procedure that calculates petroleum properties
which are a function of composition only. The following four property
calculations are available:
pPropZ Example
The following is an example of the pPropZ procedure:
call (SpecificGravity) = pPropZ ("SG", x);
Procedure pPropZPct
pPropZPct is a physical property procedure that calculates petroleum
properties which are a function of composition and liquid volume % distilled.
The following property calculation is available:
pPropZ Example
The following is an example of the pPropZ procedure:
call (D86Temperature) = pPropZPct ("D86T", x, xpct);
Procedure pPropZPPct
pPropZPPct is a physical property procedure that calculates petroleum
properties which are a function of composition, property pressure, and liquid
volume % distilled. The following property calculation is available:
pPropZ Example
The following is an example of the pPropZ procedure:
Call (D!1160Temperature) = pPropZPPct(“D1160T”, x, P,
xpct);
Procedure pSurf_Tensy
pSurf_TensY is a physical property procedure that calculates surface tension
using vapor and liquid molefractions.
pSurf_TensY Example
The following is an example of the pSurf_TensY procedure:
call (surfL) = pSurf_TensY (T, P, x, y);
Procedure pTrueCmp2
pTrueCmp2 is a physical properties procedure that calculates the equilibrium
true composition in the slurry phase. Note that the true phase is named the
“slurry” phase since it may contain precipitated solids as well as liquid. The
properties returned are the overall true composition, the liquid true
composition, the solid true composition, the true solid mole fraction and the
true to apparent mole ratio.
Note that pTrueCmp2 is similar to pTrueComp, but is more straightforward to
understand and use. pTrueComp has been retained for backward
compatibility.
Procedure pTrueCmpVLS
pTrueCmpVLS is a physical properties procedure that calculates the 3-phase
equilibrium true composition of the slurry phase. The properties returned are
the vapor phase true composition, the liquid true composition, the solid true
composition, the true vapor mole fraction, the true solid mole fraction and the
true to apparent mole ratio.
pTrueCmpVLS is an extension of pTrueCmp which considers liquid and solid
phase only.
pTrueCmpVLS Example
The following is an example usage of the pTrueCmpVLS procedure:
call (y_out, x_out, s_out, vfrac, sfrac, rat) = pTrueCmpVLS
(T, P, z_in);
lfrac = ( 1.0 – sfrac – vfrac );
Procedure pTrueComp
pTrueComp is a physical properties procedure that calculates the equilibrium
true composition in the slurry phase, along with the solid to true liquid mole
pTrueComp Example
The following is an example usage of the pTrueComp procedure:
Procedure pTrueCmp2
pTrueCmp2 is a physical properties procedure that calculates the equilibrium
true composition in the slurry phase. Note that the true phase is named the
"slurry" phase since it may contain precipitated solids as well as liquid. The
properties returned are the overall true composition, the liquid true
composition, the solid true composition, the true solid mole fraction and the
true to apparent mole ratio.
Note that pTrueCmp2 is similar to pTrueComp, but is more straightforward to
understand and use.
pTrueComp has been retained for backward compatibility.
Procedure pVap_Pressures
pVap_Pressures is a physical property procedure that calculates pure
component vapor pressures.
pVap_Pressures Example
The following is an example of the pVap_Pressures procedure:
call (comp_P_vap) = pVap_Pressures (T_in);
Procedure pVap_Pressure
pVap_Pressure is a physical property procedure that calculates total vapor
pressure.
pVap_Pressure Example
The following is an example of the pVap_Pressure procedure:
call (P_vp) = pVap_Pressure (In_F_T, In_F_z);
Key Features
Properties Calculated
Given the temperature, pressure and composition of a fluid the property
submodels can be used to calculate the following properties:
• Phase molar fractions
• Phase compositions
• Phase and overall molar enthalpy
• Phase molar weights
• Phase molar densities
For each property submodel there is a second model which calculates all of
these properties and also calculates overall and phase entropies. Entropy is
not needed as often as the other properties, so versions of the submodels
have been provided with and without this. You can then choose which is
appropriate and avoid unnecessary calculations which slow down your
simulation.
Where:
hl = Liquid molar enthalpy
xi = Mole fraction of component i
Ai, Bi = Local property parameters for component i
T = Temperature
nc = Number of components
These parameters in these functions are fitted using rigorous physical
property values obtained from calls to the AspenTech physical property
system.
To ensure good accuracy, parameter values are updated during a dynamic
simulation. Also, separate sets of parameters are fitted and used at each
location in the flowsheet.
Flash Efficiencies
All of the flash methods support the use of efficiencies. There are two types of
efficiency, Vaporization and Murphree. Both adjust the flash results to allow
for non-equilibrium conditions, and are most commonly used in distillation
stage models.
When Vaporization efficiency is selected the equation
Yi = EFFi.Ki..Xi
is used, where:
EFFi = Efficiency for component i
Ki = Equilibrium K value for component i
Xi = Liquid component mole fraction of component i
Yi = Vapor component mole fraction of component i
Units of Measurement
All of the property submodels work in the ACM Metric units of measurement
set. To use these submodels it is strongly recommended that you write your
model in these same units of measurement. The documentation for each
submodel shows the units of measurement for each variable.
Summary of Features
The following table summarizes the features are available for each submodel:
In the variable list, the first name is that in the submodel, and the second
name is that in the model. These may be the same or different , for example
the variable Rho in the submodel is related to Rhoout in the model.
In this example, if T, P and x are Fixed in the model, the submodel will
calculate hout and Rhoout. It would also be valid to fix P, x and hout and then
submodel would then calculate T and Rhoout.
If you do not need to calculate the density in your model you can use the
following:
Rho is still calculated by the submodel, but it is not related to any variable in
the model.
You can also relate variables in your model to those in the submodel using
the following syntax:
pliq as Props_liquid;
pliq.T = T;
pliq.P = P
pliq.h = hout;
However declaring the submodel and the variable relationships in a single
statement is usually more convenient.
Conditional Instancing
You can instance arrays of property submodels. This is useful when you want
to conditionally instance a submodel dependant upon some parameter. For
Changing Options
You can specify non-default values for the flash method (FlashBasis) and
properties mode (PropMode) in the call to the submodel, for example:
Props_liquid
Props_liquid calculates liquid phase properties at known composition,
pressure, and either temperature or molar enthalpy. It can be used to
calculate polymer properties.
Example usage:
Props_liq_entr
Props_liq_entr calculates liquid phase properties, including molar entropy, at
known composition, pressure, and either temperature, molar enthalpy or
molar entropy.
Example usage:
Props_vapor
Props_vapor calculates vapor phase properties at known composition,
pressure, and either temperature or molar enthalpy.
Example usage:
Props_vap_entr
Props_vap_entr calculates vapor phase properties, including entropy, at
known composition, pressure, and either temperature, molar enthalpy or
molar entropy.
Example usage:
Props_flash2
Given the temperature, pressure and composition of a fluid, Props_flash2
performs a vapor-liquid flash and calculates:
• Vapor molar fraction
• Phase compositions
• Phase and overall molar enthalpy
• Phase molar weights
• Phase molar densities
If the overall molar enthalpy or vapor molar fraction is known, these can be
specified and temperature or pressure is calculated.
Example usage:
Props_flash2_entr
Given the temperature, pressure and composition of a fluid, Props_flash2
performs a vapor-liquid flash and calculates:
• Vapor molar fraction
• Phase compositions
• Phase and overall molar enthalpy
• Phase and overall molar entropy
• Phase molar weights
• Phase molar densities
If the overall molar enthalpy, molar entropy or vapor molar fraction is known,
these can be specified and temperature or pressure is calculated.
Example usage:
Props_flash3
Given the temperature, pressure and composition of a fluid, Props_flash3
performs a vapor-liquid-liquid flash and calculates:
• Vapor and liquid molar fractions
• Phase compositions
• Phase and overall molar enthalpy
• Phase molar weights
• Phase molar densities
If the overall molar enthalpy or vapor molar fraction is known, these can be
specified and temperature or pressure is calculated.
Example usage:
Props_flash3_entr
Given the temperature, pressure and composition of a fluid,
Props_flash3_entr performs a vapor-liquid-liquid flash and calculates:
• Vapor and liquid molar fractions
• Phase compositions
• Phase and overall molar enthalpy
• Phase and overall molar entropy
• Phase molar weights
• Phase molar densities
If the overall molar enthalpy or vapor molar fraction is known, these can be
specified and temperature or pressure is calculated.
Example usage:
Example usage:
Props_lle
Given the temperature, pressure and composition of a fluid, Props_lle
performs a liquid-liquid equilibrium calculation, and calculates:
• Molar fractions of each liquid phase
• Phase compositions
• Phase and overall molar enthalpy
• Phase molar weights
• Phase molar and mass densities
Props_lle includes the option to calculate liquid-liquid equilibrium k values
using the following correlation:
Klli = exp(kll_a i + kll_b i /Tabs + kll_c i.ln(Tabs) + kll_d i.Tabs)
Where:
Klli = Liquid-liquid k value for component I
Tabs = Absolute temperature (K)
To use this option set KLLSpec to ”KLL correlation”, and enter values for the
coefficients kll_a, kll_b, kll_c and kll_d for each component. If KLLSpec is set
to “Property method” then the Kll values are calculated using either Local or
Rigorous properties as specified by PropMode.
Example usage:
Props_lwe
Given the temperature, pressure and composition of a fluid, Props_lwe
performs a liquid-water equilibrium calculation, and calculates:
• Molar fractions of each phase
• Liquid composition
• Phase and overall molar enthalpy
• Phase molar weights
• Phase molar and mass densities
Example usage:
This chapter describes utility routines that you can use from within code
which you interface to Aspen Custom Modeler.
The utility routines are:
• ACM_Print - enables you to display messages within the Aspen Custom
Modeler GUI.
• ACM_Rqst - enables you to access the values of simulation options.
ACM_Print Routine
This section describes using the ACM_Print routine to display diagnostic
messages:
• Calling the ACM_PRINT routine from Fortran code.
• Calling the ACM_Print routine from C code.
Character Explanation
% Percent character. Lead character for format specification.
- Optional minus sign. A minus sign left justifies the number.
Without the minus sign, the number is right justified.
d Decimal notation
f Decimal notation of the form [-]mmm.ddd, where the number
of d's is specified by the precision. The default precision is 6;
a precision of 0 suppresses the decimal point.
e, E Decimal notation of the form [-]m.dddddde+xx or [-
]m.ddddddE+xx, where the number of ds is specified by the
precision. The default precision is 6; a precision of 0
suppresses the decimal point.
g,G %e or %E is used if the exponent is less than -4 or greater
than or equal to the precision; otherwise %f is used. Trailing
zeros and a trailing decimal point are not printed.
S Characters from the string are printed until a '\0' is reached
or until the number of characters indicated by the precision
have been printed.
Example Formats
For Fortran, you would typically use the following escape sequences in your
message:
Sequence Explanation
\n new line
\\ backslash
\? question mark
\' single quote
\" double quote
CHARACTER*45 TEXT
INTEGER N
:
TEXT = 'The value %d is outside the valid range.\n'
CALL ACM_PRINT (-1,TEXT,N,0,0,0,0)
IFAIL = 4
Variable Explanation
% Percent character. Lead character for format specification.
- Optional minus sign. A minus sign left justifies the number.
Without the minus sign, the number is right justified.
D Decimal notation
f Decimal notation of the form [-]mmm.ddd, where the number
of d's is specified by the precision. The default precision is 6; a
precision of 0 suppresses the decimal point.
e, E Decimal notation of the form [-]m.dddddde+xx or [-
]m.ddddddE+xx, where the number of ds is specified by the
precision. The default precision is 6; a precision of 0 suppresses
the decimal point.
g,G %e or %E is used if the exponent is less than -4 or greater than
or equal to the precision; otherwise %f is used. Trailing zeros
and a trailing decimal point are not printed.
s Characters from the string are printed until a '\0' is reached or
until the number of characters indicated by the precision have
been printed.
Example Formats
You can also include the following escape sequences in your message:
Variable Explanation
\a alert (bell) character
\b backspace
\f form feed
\n new line
\r carriage return
\t horizontal tab
\v vertical tab
ACM_Rqst Routine
ACM_Rqst is a supplied Fortran or C utility routine that enables your routines
to access the values of parameters that are defined in the Options definition.
ACM_Rqst can be called from both Fortran and C. It is supplied in the library
atdll.lib in the Procedures folder of the Aspen Custom Modeler installation.
REQSTR For valid values, see Values for REQSTR in Fortran and
ACM_Option Tokens in C on page 5-159.
IINFO Integer*4
XINFO Double precision real
SINFO String
JFLAG An integer flag set by ACM_RQST to inform the calling routine
of the type of information requested. On exit from the
routine, JFLAG will have one of the following values:
xinfo double
sinfo char*
For Example:
option = ACM_TIME_UOM;
jflag = ACM_Rqst(&option, &iinfo, &xinfo,
&sinfo);
if (jflag == ACM_RQST_STRING_AND_INT)
{
/* xinfo contains the scale factor to
convert Time -> hours, sinfo contains the
Time UOM */
ACM_Print(0, "Time is measured in %s, scale
factor=%g",sinfo,&xinfo);
delete [] sinfo; /* In C: free(sinfo). Do
this or you'll have a memory leak */
}
†
The value returned by ACM_TEAR (30) only depends on the tearing
option specified on the Solver Options, Tearing tab. This value may be
ignored by some integrators: use ACM_TEAR_STATE (40) to determine
if tearing is active.
††
Only valid for VSIE(11.1), Implicit Euler and Gear integrators
†††
The value returned by ACM_TEAR_STATE (40) indicates whether
tearing is active in the current combination of options. The GEAR
integrator does not support tearing and will return 0. The other
integrators will return 1 unless tearing is OFF in the Solver Options,
. Tearing tab.
††††
ACM_TIME_UOM (41) returns 2 things: a character string which is the
currently selected units of measurement for modelling time in the Run
Options. It also returns a double which is the factor required to convert
the units of time back to the default modelling time units (Hours),
according to:
Default Units = Actual Units / factor.
††††
Only valid for Implicit Euler and Gear integrators
ACM_GetComponents Routine
ACM_ GetComponents is a supplied Fortran or C utility routine that enables
your routines to access the names of the components of the relevant stream
type. It is intended to be used from procedures that specify PROPERTIES as
one of the options in the procedure definition. ACM_ GetComponents can be
called from both Fortran and C/C++. It is supplied in the library atdll.lib in the
Procedures folder of the Aspen Custom Modeler installation.
Calling Routine
ACM_GETCOMPONENTS from Fortran
You can call the routine ACM_GETCOMPONENTS from your Fortran as follows:
Syntax for ACM_GETCOMPONENTS Fortran Interface
Call ACM_GETCOMPONENTS(ITYPE, NCOMP, COMPNAMES, STATUS)
Prototype:
EXT_C_AS_C(ULONG) ACM_GetComponents(const int iType,
const int nComps,
char**ppCompList);
#include “atdll.h”
int iType, nComp;// You need to set these to values passed into your
procedure
char ** ppCompNames = new char*[nComp];
for (int i=0;i<nComp;i++)
ppCompNames[I] = new char[41];
Note: The caller must eventually free the memory allocated for
the strings:
for (int i=0;i<nComp;i++)
delete [] ppCompNames[i];
delete [] ppCompNames;
Procedure pSpRMod
The pSpRMod procedure type returns the current run mode of the simulation
as an integer:
Integer Meaning
1 Steady state
2 Optimization
3 Estimation or data reconciliation
4 Dynamic
5 Initialization
Procedure pLMTD
The pLMTD procedure type calculates the temperature difference.
pLMTD Input Variable Types
The input variable types for pLMTD are:
pLMTD Example
The following is an example of the pLMTD procedure type:
call (LMTD ) = pLmtd (T, Tmed_in, Out_P.T, Tmed_out,
LMTDFlowDir);
Procedure pLimit
The pLimit procedure limits variable values between upper and lower bounds.
pLimit Input Variable Types
The input variable types for pLimit are:
pLimit Example
The following is an example of the pLimit procedure type:
call (Pdropc ) = pLimit(P_drop, dpmin, dpmax);
This chapter describes the port type used to create your own ports:
• MainPort
MainPort Example
The following is an example of the MainPort port type:
PORT MainPort
F AS flow_mol
Z (componentlist) AS molefraction
T AS temperature
P AS pressure
h AS enth_mol
END
The following tables are a complete list of all the variable types arranged
alphabetically.
A Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
act_coeff_liq 1 0 30 – –
angle 0 -7 7 Angle rad
angle_rad USES – – – – –
angle
area 1 0 1E6 Area m2
C Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
coefficient 1 -50 50 – –
conc_mole 0.5 0 100 MolarDensity kmol/m3
conc_mass 10.0 0 2000 MassDensity kg/m3
control_signal 1 -1E9 1E9 – –
conductivity 1.0 0.001 500 ThermalConductiv W/m/K
ity
cond_liq 0.20 0.01 10 ThermalConductiv W/m/K
ity
cond_vap 0.10 0.001 1 ThermalConductiv W/m/K
ity
constant 1.0 0.0 1E12 – –
cp_mass 1.0 0.1 10.0 MassHeatCapacity kJ/kg/K
cp_mass_liq 1.0 0.1 10.0 – –
USES
cp_mass
cp_mass_vap 1.0 0.1 10.0 – –
USES
cp_mass
cp_mol 100 1 1E3 MolarHeatCapacit kJ/kmol/K
y
cp_mol_liq 100 1 1E3 – –
D Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
delta_p 100 1 1E5 PressureDiffS N/m2
mall
dens_mass 1000 1E-30 25E3 MassDensity kg/m3
dens_mass_sol 2000 250 25E3 – –
USES
dens_mass
dens_mass_liq 1000 1E-30 10E3 – –
USES
dens_mass
dens_mass_vap 1 1E-30 1000 – –
USES
dens_mass
dens_mol 20 1E-30 5E3 MolarDensity kmol/m3
dens_mol_sol 20 0.1 5E3 – –
USES
dens_mol
dens_mol_liq 20 0.001 5E3 – –
USES
dens_mol
dens_mol_vap 0.01 1E-30 250 – –
USES
dens_mol
diffus_liq 1.5E -5 0 8E-5 Diffusivity cm2/s
diffus_vap 0.1 0 1 Diffusivity cm2/s
E Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
energy_act 1 -1E9 1E9 MolarEnthalp GJ/kmol
y
enthflow 1 -1E5 1E5 HeatFlow GJ/hr
enth_mass 0.5 -10 10 MassEnthalpy MJ/kg
enth_mass_liq 0.5 -10 10 – –
USES enth_mass
F Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
flow_mass 1000 0 1E10 MassFlow kg/hr
flow_mass_liq 1000 0 1E10 – –
USES
flow_mass
flow_mass_vap 1000 0 1E10 – –
USES
flow_mass
flow_mass_ – -1e10 – – –
USES
flow_mass
flow_mass_spec 1 -1E4 1E4 MassSpecificFlo kg/hr/
ific w m2
flow_mol 10 0 1E8 MoleFlow kmol/h
r
flow_mol_vap 10 0 1E8 – –
USES
flow_mol
flow_mol_liq 10 0 1E8 – –
USES
flow_mol
flow_mol_ USES – -1E8 – – –
flow_mol
flow_vol 1 0 1E12 VolumetricFlow m3/hr
flow_vol_vap 1 0 1E12 – –
USES
flow_vol
G Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
gibb_mol_sol 0 -1E3 1E3 MolarGibbs kJ/kmol
gte_one 1 1 1E30 – –
H Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
head 50 -1E6 1E6 Head kJ/kg
heat_react 1 -100 100 HeatOfReaction GJ/m3/h
r
heat_flux 1 -1E5 1E5 HeatFlux kW/m2
heat_flux_liin 1 -1E8 1E8 HeatFluxLinear W/m
heat_trans_coeff 1 0 1E3 HeatTransferCoe kW/m2/
ff K
holdup_heat 1 -1E5 1E5 Energy GJ
holdup_heat_liq -1 -1E5 1E5 – –
USES holdup_heat
holdup_heat_vap 1 -1E5 1E5 – –
USES holdup_heat
holdup_mass 2.5 0 1E6 Mass kg
holdup_mass_liq 2.5 0 1E6 – –
USES holdup_mass
holdup_mass_vap 2.5 0 1E6 – –
USES holdup_mass
holdup_mol 2.5 0 1E6 Moles kmol
holdup_mol_liq 2.5 0 1E6 – –
USES holdup_mol
holdup_mol_vap 2.5 0 1E6 – –
K Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
k_value 1 1E-14 1E30 – –
L Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
length 1 0 5E6 Length m
length_delta 10 0 1000 LengthShort mm
length_short 10 0 100 LengthShort mm
liqfraction 0.5 0 1 MoleFraction kmol/kmo
l
liqmassfraction 0.5 0 1 MassFraction kg/kg
M Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
mass 10 0 1E7 Mass kg
massfraction 0.5 0 1 MassFraction kg/kg
molefraction 0.5 0 1 MoleFraction kmol/km
ol
molweight 75 1 1E8 MolarWeight kg/kmol
moment_inertia 100 1E-3 1E4 MomentOfInertia kg m2
momentum 1 -5E3 5E3 Momentum tonne
m/s
N Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
negative -1 -1E9 -1E-9 – –
neg_small -1 -500 0 – –
neg_large -1 -1E30 0 – –
R Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
ratio_ 1 0 1E3 – –
reaction 10 -1E6 1E6 MolarReaction kmol/hr/m
Rate 3
reaction_mass 1000 -1E6 1E6 MassReactionR kg/hr/m3
ate
rotation 500 0 2000 AngularVelocit rad/s
y
S Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
surf_tens 0.05 0 1 SurfaceTensio N/m
T Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
temperature 25 -246 5000 Temperature C
temperature_ab 300 27 5273 AbsoluteTemperatur K
s e
temp_diff 10 -1000 1000 TemperatureDifferen C
ce
temp_drop 10 0 100 TemperatureDifferen C
ce
temp_rise 10 0 100 TemperatureDifferen C
ce
time_ 1E-4 0.0 1E4 Time hr
timeMin 1 0.0 1E6 TimeMin min
timeSec 1 0.0 1E8 TimeSec s
V Variable Types
Variable Value Lower Upper Physical Base
Bound Bound Quantity Units
vapfraction 0.5 0 1 MoleFraction kmol/kmol
vapmassfraction 0.5 0 1 MassFraction kg/kg
velocity 1 0 5E3 Velocity m/s
vel_angular 5000 0 20000 AngularVelocit rpm
y
visc_liq 1 1E-30 1E5 Viscosity cP
visc_vap 0.01 1E-30 1E5 Viscosity cP
vol_mass 0.1 2.0E-8 1E30 MassSpecificV m3/kg
olume
vol_mol 0.05 2.0E-4 1E30 MolarVolume m3/kmol
vol_mol_liq 0.05 2.0E-4 1000 – –
USES
vol_mol
vol_mol_vap 100 4.0E-3 1E30 – –
USES
vol_mol
volume 10 0 1E5 Volume m3
Copyright
Version Number: 2004.1
April 2005
Copyright © 1982-2005 Aspen Technology, Inc, and its applicable
subsidiaries, affiliates, and suppliers. All rights reserved. This Software is a
proprietary product of Aspen Technology, Inc., its applicable subsidiaries,
affiliates and suppliers and may be used only under agreement with
AspenTech.
Aspen ACOL™, Aspen Adsim®, Aspen Advisor™, Aspen Aerotran®, Aspen
Alarm & Event™, Aspen APLE™, Aspen Apollo Desktop™, Aspen Apollo
Online™, Aspen AssetBuilder™, Aspen ATOMS™, Aspen Automated Stock
Replenishment™, Aspen Batch Plus®, Aspen Batch.21™, Aspen BatchCAD™,
Aspen BatchSep™, Aspen Calc™, Aspen Capable-to-Promise®, Aspen
CatRef®, Aspen Chromatography®, Aspen Cim-IO for ACS™, Aspen Cim-IO
for Csi VXL™, Aspen Cim-IO for Dow MIF™, Aspen Cim-IO for G2™, Aspen
Cim-IO for GSE D/3™, Aspen Cim-IO for Hewlett-Packard RTAP™, Aspen Cim-
IO for Hitachi PLC (H04E)™, Aspen Cim-IO for Intellution Fix™, Aspen Cim-IO
for Melsec™, Aspen Cim-IO for WonderWare InTouch™, Aspen Cim-IO for
Yokogawa Centum CS™, Aspen Cim-IO for Yokogawa Centum XL™, Aspen
Cim-IO for Yokogawa EW3™, Aspen Cim-IO Interfaces™, Aspen Cim-IO
Monitor™, Aspen Cim-IO™, Aspen Collaborative Demand Management™,
Aspen Collaborative Forecasting™, Aspen Compliance.21™, Aspen
COMThermo TRC Database™, Aspen COMThermo®, Aspen Cost Factor
Manual™, Aspen Crude Manager™, Aspen Crude Margin Evaluation™, Aspen
Custom Modeler®, Aspen Data Source Architecture™, Aspen Decision
Analyzer™, Aspen Demand Manager™, Aspen DISTIL™, Aspen Distribution
Scheduler™, Aspen DMCplus® Composite, Aspen DMCplus® Desktop, Aspen
DMCplus® Online, Aspen DPO™, Aspen Dynamics®, Aspen eBRS™, Aspen
Enterprise Model™, Aspen ERP Connect™, Aspen FCC®, Aspen FIHR™, Aspen
FLARENET™, Aspen Fleet Operations Management™, Aspen Framework™,
Aspen FRAN™, Aspen Fuel Gas Optimizer Desktop™, Aspen Fuel Gas
Optimizer Online™, Aspen General Construction Standards™, Aspen Hetran®,
Aspen HX-Net®, Aspen Hydrocracker®, Aspen Hydrotreater™, Aspen HYSYS
Amines™, Aspen HYSYS Crude™, Aspen HYSYS Dynamics™, Aspen HYSYS
OLGAS 3-Phase™, Aspen HYSYS OLGAS™, Aspen HYSYS OLI Interface™,
Aspen HYSYS Tacite™, Aspen HYSYS Upstream Dynamics™, Aspen HYSYS
Upstream™, Aspen HYSYS®, Aspen Icarus Process Evaluator®, Aspen Icarus
Corporate
Aspen Technology, Inc. Phone: (1) (617) 949-1000
Ten Canal Park Toll Free: (1) (888) 996-7001
Cambridge, MA 02141-2201 Fax: (1) (617) 949-1030
USA URL: http://www.aspentech.com
Aspen Custom Modeler 2004.1 User Guide Contains a general overview of ACM
functionality and more complex and
extensive examples of using Aspen
Custom Modeler.
Scale 50
A SplitRange 52
ACM_Print routine 152 SteamPtoT 54
ACM_Rqst routine 156 Sum 54
Algorithms 31, 41 time units 11
ART Reactions Model Wizard 83 Transform 55
available 177 Valve_dyn 56
creating a new Reactions Model 83
B
D
Bounds, pLimit for limiting 163
Bubble Point and Dew Point Calculations 139 Dead_time control model 12
Diagnostic information
C ACM_Print routine 152
Control models
E
Comparator 12
Dead_time 12 Error messages
Discretize 13 ACM_Print routine 152
Feedforward 14
F
HiLoSelect 15
IAE 16 Faceplates for PID model 32, 43
ISE 17 Feedforward model 14
Lag_1 18
Lead_lag 19
H
Index 179
I pDens_Mol_Vap procedure 101, 112
pDewt procedure 102, 112
IAE control model 16
pDiffus_Liq procedure 102, 113
ISE control model 17
pDiffus_Vap procedure 102
Index 180
Props_vapor 141 Simulation Messages window
PID control model 23, 34 ACM_Print routine 152
faceplates 32, 43 SplitRange control model 52
tuning 32 SteamPtoT control model 54
PID model stoichiometry
faceplates 32, 43 defining 89
pKllValues procedure 107, 124 syntax 89
pKValues procedure 108 Sum control model 54
pLimit procedure 163 syntax of stoichiometry 89
pLMTD procedure 163
pMolWeight procedure 108, 124
T
Index 181