USTChEX Documentation - Thermodynamics

USTCHEX_EOS: Pure component properties solver
Applicable to: Almajose-Dalida EOS USTCHEX_AD(); Patel-Teja-Valderrama EOS USTCHEX_PTV(); Peng-Robinson EOS USTCHEX_PR(); Soave-Redlich-Kwong EOS USTCHEX_SRK()

Description

• Computes thermodynamic properties of a pure substance using a cubic equation of state. The function solves the EOS for all real compressibility factor roots and evaluates phase-dependent properties including fugacity coefficient, molar volume, enthalpy departure, and entropy departure. The solver supports both database-driven and manual input modes. Temperature-dependent attraction parameters are evaluated using a selectable alpha function, with full support for default correlations, database coefficients, or manually supplied tau constants. Multiple output modes allow either compact numerical results or full exposure of EOS internals for teaching, validation, and diagnostics.

Syntax
Database Mode: =USTCHEX_[EOS](T, Pbar, "CASN/NAME", [mode], [alphaOpt], [tauRange])
Manual Mode: =USTCHEX_[EOS](T, Pbar, Tc, Pc, Zc, omega, [mode], [alphaOpt], [tauRange])

Arguments

• T / Pbar
  Temperature [K] / Pressure [bar]

• "CASN/NAME"
  Compound identifier (CAS number or compound name, provided the compound is available in the USTCHEX ThermoDB)

• Tc (for manual mode only)
  Critical temperature [K]

• Pc (for manual mode only)
  Critical pressure [bar]

• Zc (for manual mode only)
  Critical compressibility factor

• omega (for manual mode only)
  Acentric factor

• mode (Optional)
  Printout mode for the output. Possible values: "L", "V", "STABLE", "FULL", "EDUC".
  Default (blank) value is "FULL"
  • "L": Only the liquid root is evaluated and returned
  • "V": Only the vapor root is evaluated and returned
  • "STABLE": Only the thermodynamically stable root is returned (minimum Gibbs energy)
  • "FULL": All physically relevant roots are evaluated and returned, including liquid and vapor roots and the third (nonphysical) root where applicable
  • "EDUC": Returns the full EOS calculation breakdown for teaching and diagnostics

• alphaOpt (Optional)
  Alpha function selector. Allows the code to switch between multiple alpha models.
  Default (blank) value is 0
  • 0: Uses the default alpha model of the EOS
  • 1: Soave alpha using τ₁
  • 2: Mathias-Copeman alpha using τ₁, τ₂, τ₃
  • 3: Heyen alpha using τ₁, τ₂
  • 4: Twu-2P alpha using τ₁, τ₂
  • 5: Twu-3P alpha using τ₁, τ₂, τ₃

• tauRange (Optional)
  Range of cells containing the τᵢ constants. This range is handled according to priority and mode. The size of tauRange must match the number of required tau constants:
  • alphaOpt = 1 → expects 1 value (τ₁)
  • alphaOpt = 2 → expects 3 values (τ₁, τ₂, τ₃)
  • alphaOpt = 3 → expects 2 values (τ₁, τ₂)
  • alphaOpt = 4 → expects 2 values (τ₁, τ₂)
  • alphaOpt = 5 → expects 3 values (τ₁, τ₂, τ₃)
  If the number of supplied coefficients does not match the selected alpha model, the function returns an error.

FOR DATABASE MODE
• Manual tau inputs from tauRange
• Database alpha coefficients
• Default alpha model (only when alphaOpt = 0)
That is:
• If tauRange is not empty → manual coefficients are always used
• If tauRange is empty → the code attempts to retrieve coefficients from the database
• If coefficients are not available in the database:
If alphaOpt = 0 → the code falls back to the default alpha model
If alphaOpt ≠ 0 → the function returns an error indicating that the requested coefficients are not available

FOR MANUAL MODE
• Priority 1: Manual tau inputs from tauRange
• Priority 2: Default alpha model (only when alphaOpt = 0)
That is:
• If alphaOpt ≠ 0 → tau coefficients must be supplied via tauRange
• If tauRange is empty and alphaOpt ≠ 0 → the function returns an error
• If alphaOpt = 0 → no tau input is required and the default alpha model is used

Returns

• "L", "V", "STABLE" modes: Returns a compact set of phase properties:
  • compressibility factor, Z
  • departure enthalpy, Hᴿ
  • departure entropy, Sᴿ
  • fugacity coefficient, φ
  These values correspond to the selected phase root.

• "FULL" mode: Returns a structured table containing:
  • liquid and vapor compressibility factors (ZL, ZV)
  • liquid and vapor departure enthalpies (HᴿL, HᴿV)
  • liquid and vapor departure entropies (SᴿL, SᴿV)
  • fugacity coefficients for each root
  • the third (nonphysical) root where applicable
  If only one real root exists, the liquid and vapor results are identical.

• "EDUC" mode: Returns the complete EOS calculation breakdown:
  • EOS used
  • alpha model used
  • EOS parameters (a, b, c where applicable)
  • temperature-dependent attraction parameter a(T)
  • derivative da(T)/dT
  • reduced parameters (A, B, C)
  • all real compressibility factor roots
  • phase classification (stable vs metastable)
  • molar volume
  • departure enthalpy and entropy
  • fugacity coefficients
  This mode is intended for thermodynamics teaching, validation, and detailed inspection of EOS behavior.

Notes
• Stable phase corresponds to the minimum Gibbs energy root
• In the single-root region, liquid and vapor properties are identical
• The solver is fully deterministic and does not require iteration
• The cubic equation is solved analytically for all real roots
• Incorrect tau dimensions or missing required coefficients result in a hard error
• Database mode requires that the compound exists in the USTCHEX ThermoDB
• Designed for both engineering calculations and detailed thermodynamic analysis

USTCHEX_EOS_MIX: Multicomponent mixture properties and VLE solver
Applicable to: Almajose-Dalida EOS USTCHEX_AD_MIX(); Soave-Redlich-Kwong EOS USTCHEX_SRK_MIX()

Description
Performs vapor-liquid equilibrium calculations for multicomponent mixtures using a cubic equation of state under a φ-φ framework. Pure-component parameters are evaluated using a selectable alpha function, with support for default alpha models, database coefficients, or manually supplied tau coefficients. Mixture parameters are evaluated using a selected mixing rule and, when applicable, binary interaction parameter matrices. The solver supports both database-driven and manual input modes. Multiple output modes allow either compact numerical results or full exposure of EOS internals for teaching, validation, and diagnostics.

Syntax
Database Mode: =USTCHEX_[EOS]_MIX(T, Pbar, compRange, xRange, [yTrialRange], [mode], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [psiMode])
Manual Mode: =USTCHEX_[EOS]_MIX(T, Pbar, TcRange, PcRange, ZcRange, omegaRange, xRange, [yTrialRange], [mode], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [nameRange], [psiMode])

Arguments

• T/Pbar
  Temperature [K] / Pressure [bar]

• compRange
  Vertical range of component identifiers (CAS number or compound name, provided the chemical compounds are available in the USTCHEX ThermoDB)

• xRange
  Vertical range of liquid-phase mole fractions of the mixture components. The entries must be nonnegative and must sum to unity.

• yTrialRange (Optional)
  Vertical range containing the initial vapor-phase composition guess.
  If blank, the code uses the liquid composition vector xRange as the initial vapor guess and normalizes it internally.

• mode (Optional)
  Printout mode for the output. Possible values: "SIMPLE", "FULL", "EDUC".
  Default (blank) value is "FULL".
  • "FULL": Returns the liquid-phase and vapor-phase mixture properties, followed by a component table containing liquid composition, vapor composition, liquid fugacity coefficient, vapor fugacity coefficient, and K-value.
  • "SIMPLE": Returns a compact numerical output intended for fast engineering calculations.
  • "EDUC": Returns the full mixture calculation breakdown. This is useful for thermodynamics teaching, debugging, and validation of mixing-rule calculations.

• alphaOpt (Optional)
  Alpha function selector. Allows the code to switch between five alpha function models.
  Default (blank) value is 0.
  • 0: Uses the default published alpha model of the EOS.
  • 1: Uses the Soave function with the value of τ₁ provided by the user or extracted from the database
  • 2: Uses the three-parameter Mathias-Copeman alpha function, with the value of τᵢ provided by the user or extracted from the database
  • 3: Uses the two-parameter Heyen alpha function, with the value of τᵢ provided by the user or extracted from the database
  • 4: Uses the two-parameter Twu alpha function, with the value of τᵢ provided by the user or extracted from the database
  • 5: Uses the three-parameter Twu alpha function, with the value of τᵢ provided by the user or extracted from the database

• mixRule (Optional)
  Mixing rule selector. Allows the code to switch between five mixture attraction-parameter models.
  Default (blank) value is 0.
  • 0: vdW1F-SYM: Uses the one-fluid van der Waals mixing rule with a symmetric K matrix.
  • 1: vdW1F-ASYM: Uses the one-fluid van der Waals mixing rule with a full asymmetric K matrix.
  • 2: Panagiotopoulos-Reid: Uses the Panagiotopoulos-Reid asymmetric correction to the attraction parameter.
  • 3: MKP-2P: Uses the Mathias-Klotz-Prausnitz two-parameter mixing rule. Requires K and L matrices.
  • 4: MKP-3P: Uses the Mathias-Klotz-Prausnitz three-parameter mixing rule. Requires K, L, and Q matrices.

• alphaCoeffRange (Optional)
  Range of cells containing the alpha-function τᵢ constants for each component. This range is handled according to priority. The size of alphaCoeffRange must match the number of components and the number of required tau constants.
  • For alphaOpt = 1: expected size is N × 1
  • For alphaOpt = 2: expected size is N × 3
  • For alphaOpt = 3: expected size is N × 2
  • For alphaOpt = 4: expected size is N × 2
  • For alphaOpt = 5: expected size is N × 3
  where N is the number of components in the mixture.
  If the dimensions do not match the selected alpha model, the output is: alpha coefficient range has wrong size.

FOR DATABASE MODE:
• Priority 1: Manual alpha inputs from alphaCoeffRange
• Priority 2: Database alpha coefficients
• Priority 3: Default alpha model when alphaOpt = 0
That is, if alphaCoeffRange is not empty, the code uses the cell values supplied by the user, even if the database contains coefficients. If alphaCoeffRange is empty, the code attempts to extract the required alpha coefficients from the database. If the required coefficients are unavailable and alphaOpt ≠ 0, the output is an error indicating that the requested coefficients are not available and that the user should either set alphaOpt = 0 or provide manual alpha coefficients.

FOR MANUAL MODE:
• Priority 1: Manual alpha inputs from alphaCoeffRange
• Priority 2: Default alpha model when alphaOpt = 0
That is, for manual mode, if alphaOpt ≠ 0, the required tau coefficients must be supplied through alphaCoeffRange. If alphaCoeffRange is empty, the output is an error indicating that the requested alpha coefficients were not provided. If alphaOpt = 0, the code falls back to the default alpha model of the EOS and no tau inputs are needed.

• BIPRange (Optional)
  Range of cells containing the binary interaction parameters. This range is handled according to priority and according to the selected mixing rule.

BIP PRIORITY:
• Priority 1: Manual BIP inputs from BIPRange
• Priority 2: Database pair interaction parameters
• Priority 3: Rule-dependent fallback behavior
That is, if BIPRange is not empty, the user-supplied matrix or block is used directly. If BIPRange is empty, the code attempts to retrieve the interaction parameters from the pair database. If the database cannot provide the required parameters, the fallback depends on the selected mixing rule.

BIP MECHANICS:
For mixRule = 0 (vdW1F-SYM): Expected BIPRange shape: N × N containing the [K] matrix only.
• Intended for symmetric one-fluid mixing
• If BIPRange is blank, the code defaults to a zero K matrix
• In manual mode, the matrix is used exactly as entered
• No automatic symmetrization is applied in manual mode
• In database mode, symmetric data are read from the pair database if available; otherwise the zero matrix fallback is used

For mixRule = 1 (vdW1F-ASYM): Expected BIPRange shape: N × N containing the [K] matrix only.
• Intended for asymmetric one-fluid mixing
• In manual mode, the matrix is used exactly as entered
• No automatic asymmetrization is applied in manual mode
• In database mode, the code attempts to assemble the asymmetric K matrix from the pair database
• If the pair database is unavailable or missing the required entries, the code falls back to a zero matrix

For mixRule = 2 (Panagiotopoulos-Reid): Expected BIPRange shape: N × N containing the [K] matrix only.
• The full matrix is used as entered
• No automatic structure correction is applied in manual mode
• If BIPRange is blank, the code must obtain the coefficients from the pair database
• If the pair database is missing or the Panagiotopoulos-Reid coefficients cannot be found, the function returns an error
Typical error messages include:
• Pair database not loaded or has been cleared...
• No Panagiotopoulos-Reid coefficients were found in the pair database...

For mixRule = 3 (MKP-2P): Expected BIPRange shape: N × 2N containing [K | L]
That is, the left block is the K matrix and the right block is the L matrix.
• Any other width is rejected
• In manual mode, K and L are used exactly as entered
• No automatic sign correction is applied in manual mode
• If BIPRange is blank, the code attempts to retrieve the coefficients from the pair database
• In database mode, the code reconstructs the lower-triangle sign behavior for L internally
• If the pair database is missing or MKP-2P coefficients cannot be found, the function returns an error
Typical error messages include:
• BIP range has wrong size for the selected mixing rule
• No MKP-2P coefficients were found in the pair database...

For mixRule = 4 (MKP-3P): Expected BIPRange shape: N × 3N containing [K | L | Q]
That is, the left block is the K matrix, the middle block is the L matrix, and the right block is the Q matrix.
• Any other width is rejected
• In manual mode, K, L, and Q are used exactly as entered
• No automatic sign correction is applied in manual mode
• If BIPRange is blank, the code attempts to retrieve the coefficients from the pair database
• In database mode, the code reconstructs the lower-triangle sign behavior internally for both L and Q
• If the pair database is missing or MKP-3P coefficients cannot be found, the function returns an error
Typical error messages include:
• BIP range has wrong size for the selected mixing rule
• No MKP-3P coefficients were found in the pair database...

Important note on BIP behavior: In manual mode, matrices are used exactly as entered by the user. The code does not automatically enforce symmetry, antisymmetry, or lower-triangle sign conventions. Therefore, it is the responsibility of the user to supply a physically meaningful matrix structure when using manual BIP inputs. In database mode, however, the addin automatically reconstructs the internal sign behavior for MKP-type parameters when assembling the matrices from the database.

• psiMode (Optional)
  Derivative evaluation mode for the composition derivative of the mixture attraction parameter, ∂a_mix/∂nᵢ.
  Default (blank) value is 0.
  • 0: Uses the analytical derivative expression.
  • 1: Uses a numerical derivative approximation. The analytical mode is the default and is generally faster. The numerical mode is primarily useful for validation, comparison, and debugging.

• TcRange (for manual mode only)
  Vertical range of critical temperatures [K]

• PcRange (for manual mode only)
  Vertical range of critical pressures [bar]

• ZcRange (for manual mode only)
  Vertical range of critical compressibility factors

• omegaRange (for manual mode only)
  Vertical range of acentric factors

• nameRange (Optional, for manual mode only)
  Vertical range of component names used only for labeling the output. If left blank, the components are labeled internally as component 1, component 2, and so on.

Returns

• "SIMPLE" mode: Returns a compact numerical table containing:
  • ZLmix, HRLmix, SRLmix, ZVmix, HRVmix, SRVmix, and the vapor-phase summation check
  • Followed by component-level vapor compositions and K-values
  This mode is intended for compact engineering calculations and quick worksheet use.

• "FULL" mode: Returns a structured equilibrium table containing:
  • liquid-phase compressibility factor, ZLmix
  • vapor-phase compressibility factor, ZVmix
  • liquid-phase departure enthalpy, HRLmix
  • vapor-phase departure enthalpy, HRVmix
  • liquid-phase departure entropy, SRLmix
  • vapor-phase departure entropy, SRVmix
  • component liquid composition, xᵢ
  • component vapor composition, yᵢ
  • component liquid fugacity coefficient, φᵢL
  • component vapor fugacity coefficient, φᵢV
  • component equilibrium ratio, Kᵢ
  • final vapor composition closure check
  This is the standard mode for mixture VLE calculations.

• "EDUC" mode: Returns the full mixture calculation breakdown, including:
  • EOS used
  • alpha model used
  • mixing rule used
  • derivative evaluation mode used
  • mixture parameters for the liquid and vapor phases
  • temperature derivatives of the mixture attraction parameter
  • reduced parameters for the liquid and vapor phases
  • liquid-phase and vapor-phase compressibility factors
  • liquid-phase and vapor-phase molar volumes
  • liquid-phase and vapor-phase departure enthalpies
  • liquid-phase and vapor-phase departure entropies
  • per-component pure parameters
  • per-component alpha values
  • per-component aᵢ and daᵢ/dT
  • per-component ∂a_mix/∂nᵢ in the liquid and vapor phases
  • per-component fugacity coefficients in the liquid and vapor phases
  • per-component equilibrium ratios
  This mode is intended for thermodynamics teaching, diagnostics, and validation of mixture-property and mixing-rule calculations.

Notes:
• The vapor composition is updated iteratively using Kᵢ = φᵢL / φᵢV until convergence
• The liquid composition vector must be valid, nonnegative, and sum to unity
• The initial vapor guess, if supplied, must also be nonnegative and of the same length as the component list
• Analytical derivative mode is the default and is recommended for normal use
• Numerical derivative mode is mainly intended for checking or debugging the implementation
• Manual BIP matrices are never automatically corrected by the code
• Incorrect matrix dimensions cause a hard error
• Missing required alpha coefficients or missing required pair parameters also cause a hard error
• The solver is iterative and may fail if the thermodynamic state is difficult, the interaction parameters are inconsistent, or the supplied initial guess is poor

USTCHEX_EOS_VLE: Binary vapor-liquid equilibrium generator
Applicable to: Almajose-Dalida EOS USTCHEX_AD_TXY(); Almajose-Dalida EOS USTCHEX_AD_PXY()

Description
Generates binary vapor-liquid equilibrium (VLE) data using a cubic equation of state under a φ-φ framework. The function evaluates equilibrium states across composition and constructs either a temperature-composition (T-x-y) diagram at fixed pressure or a pressure-composition (P-x-y) diagram at fixed temperature. At each composition point, the function internally performs a binary mixture phase-equilibrium calculation. Therefore, the handling of alpha functions, mixing rules, binary interaction parameters, derivative mode, and database/manual property logic is the same as in USTCHEX_[EOS]_MIX.

Syntax

Database Mode:
=USTCHEX_[EOS]_PXY(T, compRange, [yTrialRange], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [psiMode], [dxInit], [dxMin], [dxMax], [maxPoints])
=USTCHEX_[EOS]_TXY(Pbar, compRange, [yTrialRange], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [psiMode], [dxInit], [dxMin], [dxMax], [maxPoints])

Manual Mode:
=USTCHEX_[EOS]_PXY(T, TcRange, PcRange, ZcRange, omegaRange, [yTrialRange], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [nameRange], [psiMode], [dxInit], [dxMin], [dxMax], [maxPoints])
=USTCHEX_[EOS]_TXY(Pbar, TcRange, PcRange, ZcRange, omegaRange, [yTrialRange], [alphaOpt], [mixRule], [alphaCoeffRange], [BIPRange], [nameRange], [psiMode], [dxInit], [dxMin], [dxMax], [maxPoints])

Arguments

• T / Pbar
  Temperature [K] / Pressure [bar], depending on whether PXY or TXY is being generated.

• compRange
  Vertical range containing exactly two component identifiers (CAS number or compound name, provided the compounds are available in the USTCHEX ThermoDB). Used in database mode.

• TcRange / PcRange / ZcRange / omegaRange
  Vertical ranges of critical temperature [K], critical pressure [bar], critical compressibility factor, and acentric factor. Used in manual mode.

• yTrialRange (Optional)
  Initial vapor-phase composition guess used by the internal binary equilibrium calculation.

• alphaOpt (Optional)
  Alpha function selector. Same handling as in USTCHEX_[EOS]_MIX.

• mixRule (Optional)
  Mixing-rule selector. Same handling as in USTCHEX_[EOS]_MIX.

• alphaCoeffRange (Optional)
  Manual alpha coefficients. Same priority rules and size requirements as in USTCHEX_[EOS]_MIX.

• BIPRange (Optional)
  Binary interaction parameter block. Same mechanics, priority rules, and dimensional requirements as in USTCHEX_[EOS]_MIX.

• nameRange (Optional)
  Vertical range of component names used for labeling in manual mode.

• psiMode (Optional)
  Derivative evaluation mode. Same handling as in USTCHEX_[EOS]_MIX.

• dxInit (Optional)
  Initial composition step size used for tracing the binary VLE curve.

• dxMin (Optional)
  Minimum allowed composition step size.

• dxMax (Optional)
  Maximum allowed composition step size.

• maxPoints (Optional)
  Maximum number of points to be generated in the VLE table.

• Returns
  • For USTCHEX_[EOS]_PXY(), the output columns are: P [bar] | x | y | ZL | ZV | HRL | HRV | SRL | SRV
  • For USTCHEX_[EOS]_TXY(), the output columns are: T [K] | x | y | ZL | ZV | HRL | HRV | SRL | SRV

• Notes:
  • Both functions are designed strictly for binary systems.
  • The handling of alpha functions, mixing rules, binary interaction parameters, and derivative mode is identical to USTCHEX_[EOS]_MIX.
  • The curve-generation controls dxInit, dxMin, dxMax, and maxPoints regulate how the equilibrium points are plotted.
  • Because the solver is EOS-based and iterative at every point, curve generation may fail, terminate early, or become discontinuous in difficult regions such as near-critical states or when no valid two-phase solution exists.

• Use of the Twu (1991) three-parameter alpha function is recommended whenever database coefficients are available (alphaOpt = 5), as it provides highly accurate vapor pressure predictions over a wide temperature range, and consequently improves boiling point estimation.

• For binary systems, the Mathias–Klotz–Prausnitz three-parameter mixing rule is recommended when database parameters are available (mixRule = 4). For systems with similar components, the vdW1F-symmetric (mixRule = 1) or Panagiotopoulos–Reid (mixRule = 2) mixing rules are generally sufficient. However, the Panagiotopoulos–Reid mixing rule should not be applied to ternary systems due to the Michelsen–Kistenmacher syndrome.