ICapeThermoEquilibriumRoutineCalcEquilibrium Method

[DispIdAttribute(1)]
void CalcEquilibrium(
	Object specification1,
	Object specification2,
	string solutionType
)

<DispIdAttribute(1)>
Sub CalcEquilibrium ( 
	specification1 As Object,
	specification2 As Object,
	solutionType As String
)

Parameters

specification1  Object

First specification for the Equilibrium Calculation. The specification information is used to retrieve the value of the specification from the Material Object. See below for details.

specification2  Object

Second specification for the Equilibrium Calculation in the same format as specification1.

solutionType  String

The identifier for the required solution type. The standard identifiers are given in the following list:

Unspecified

Normal

Retrograde

The meaning of these terms is defined below in the notes. Other identifiers may be supported but their interpretation is not part of the CO standard.

The specification1 and specification2 arguments provide the information necessary to retrieve the values of two specifications, for example the pressure and temperature, for the Equilibrium Calculation. The CheckEquilibriumSpec method can be used to check for supported specifications. Each specification variable contains a sequence of strings in the order defined in the following table (hence, the specification arguments may have 3 or 4 items):

property identifier The property identifier can be any of the identifiers listed in section 7.5.5 but only certain property specifications will normally be supported by any Equilibrium Routine.

phase label The phase label denotes the Phase to which the specification applies. It must either be one of the labels returned by GetPresentPhases, or the special value “Overall”.

Some examples of typical phase equilibrium specifications are given in the table below.

The values corresponding to the specifications in the argument list and the overall composition of the mixture must be set in the associated Material Object before a call to CalcEquilibrium.

Components such as a Property Package or an Equilibrium Calculator must implement the ICapeThermoMaterialContext interface, so that an ICapeThermoMaterial interface can be passed via the SetMaterial method. It is the responsibility of the implementation of CalcEquilibrium to validate the Material Object before attempting a calculation.

The Phases that will be considered in the Equilibrium Calculation are those that exist in the Material Object, i.e. the list of phases specified in a SetPresentPhases call. This provides a way for a client to specify whether, for example, a vapour-liquid, liquid-liquid, or vapourliquid-liquid calculation is required. CalcEquilibrium must use the GetPresentPhases method to retrieve the list of Phases and the associated Phase status flags. The Phase status flags may be used by the client to provide information about the Phases, for example whether estimates of the equilibrium state are provided. See the description of the GetPresentPhases and SetPresentPhases methods of the ICapeThermoMaterial interface for details. When the Equilibrium Calculation has been completed successfully, the SetPresentPhases method must be used to specify which Phases are present at equilibrium and the Phase status flags for the phases should be set to Cape_AtEquilibrium. This must include any Phases that are present in zero amount such as the liquid Phase in a dew point calculation.

Some types of Phase equilibrium specifications may result in more than one solution. A common example of this is the case of a dew point calculation. However, CalcEquilibrium can provide only one solution through the Material Object. The solutionType argument allows the “Normal” or “Retrograde” solution to be explicitly requested. When none of the specifications includes a phase fraction, the solutionType argument should be set to “Unspecified”.

The definition of “Normal” is

where V F is the vapour phase fraction and the derivatives are at equilibrium states. For “Retrograde” behaviour,

CalcEquilibrium must set the amounts, compositions, temperature and pressure for all Phases present at equilibrium, as well as the temperature and pressure for the overall mixture if not set as part of the calculation specifications. CalcEquilibrium must not set any other Physical Properties.

As an example, the following sequence of operations might be performed by CalcEquilibrium in the case of an Equilibrium Calculation at fixed pressure and temperature:

- With the ICapeThermoMaterial interface of the supplied Material Object:

- Use the GetPresentPhases method to find the list of Phases that the Equilibrium Calculation should consider.

- With the ICapeThermoCompounds interface of the Material Object use the GetCompoundIds method to find which Compounds are present.

- Use the GetOverallProp method to get the temperature, pressure and composition for the overall mixture.

- Perform the Equilibrium Calculation.

- Use SetPresentPhases to specify the Phases present at equilibrium and set the Phase status flags to Cape_AtEquilibrium.

- Use SetSinglePhaseProp to set pressure, temperature, Phase amount (or Phase fraction) and composition for all Phases present.

Reference