Species Database Class

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: PGMs ➔ Classes ➔ Species Database Class

Global Pre-Defined Class Instances SysCAD Pre-Defined Classes
Sp Database
SDB Class 		Particle Size Defn
PSD Class 		Plant Model
PM Class 		Array
Class 		StrArray
Class 		Matrix
Class 		TagSelect
Class 		Time
Class 		Noise
Class

Latest SysCAD Version: 19 March 2024 - SysCAD 9.3 Build 139.35102

Related Links: Defining a Class, Example PGM Files

Description

The name of the single global instance of the Species Database class is SDB and can be referenced directly.

The Species Data Base (SDB) class is very useful as it provides member functions that allow users to access the details and properties of the species within a project.

  • The information for species that users may obtain using the SDB class includes Molecular Weight, Density, Saturated Temperature and Pressure, etc.
  • The user may also obtain the total number of species in a project, number of solid, liquid or gaseous species, etc.
  • The user does not have to declare the SDB class before using it.

Data Members

None

Member Functions

The examples in the following table are all based upon a project containing the following species:

H2O(g), O2(g), N2(g)
H2O(l), H2SO4(aq), NaCl(aq), NiSO4(aq)
Fe2O3(s), Fe[OH]2(s), NiO(s)
RH2(org), RNi(org)
Call Functionality Return Type Parameters Example

Species Index

FindSpecies(Symbol/Tag)

This returns the index of the required species, or -1 if it is not found.

integer

The user may specify either the species symbol or tag

SpeciesIndex = SDB.FindSpecies("H2O(l)") or
SpeciesIndex = SDB.FindSpecies("Water(l)")
SpeciesIndex = 3
Similar Function - SpI(), see comparison here

Species Information

SpShortName(SpIndex)

This returns the short name (symbol) of the species with the specified species index. Previous function name (Build 135) was SpSymbol.

string

SpIndex is type integer

SpeciesName = SDB.SpShortName(3)
SpeciesName = "H2O(l)"

SpLongName(SpIndex)

This returns the long name of the species with the specified species index. Previous function name (Build 135) was SpTag.

string

SpIndex is type integer

SpeciesName = SDB.SpLongName(3)
SpeciesName = "Water(l)"

SpMolecularWt(SpIndex)

This returns the Molecular Weight of the species with the specified species index.

real

SpIndex is type integer

O2Index = SpI("O2(g)") = 1
O2MW = SDB.SpMolecularWt(O2Index)
O2MW = 31.999
Similar Function - MW(), see comparison here

SpCharge(SpIndex)

This returns the Charge of the species with the specified species index.

real

SpIndex is type integer

H2OIndex = SpI("H2O(g)") = 7
Charge = SDB.SpCharge(H2OIndex)
Charge = 0

SpDensity(SpIndex, temperature, pressure)

This returns the Density, in kg/m^3, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
H2ORho = SDB.SpDensity(H2OIndex, 298.15, 101.325)
H2ORho = 997.05 kg/m^3

SpVapourP(SpIndex, temperature)

This returns the Saturated Vapour Pressure, in kPa, of the required vapour species at the specified temperature, in K.
Notes:

  1. The species MUST be a vapour species.
  2. If the species has no data for calculating the saturated vapour pressure, this will return 0.

real

SpIndex is type integer
temperature in degrees Kelvin

H2OIndex = SpI("H2O(g)") = 7
VP = SDB.SpVapourP(H2OIndex, 350)
VP = 41.68 kPa

SpVapourT(SpIndex, Pressure)

This returns the Saturated Vapour Temperature, in degrees Kelvin, of the required vapour species at the specified pressure, in kPa.
Note: If the species has no data for calculating the saturated vapour temperature, this will return 0.

real

SpIndex is type integer
pressure in kPa (absolute)

H2OIndex = SpI("H2O(g)") = 7
VT = SDB.SpVapourT(H2OIndex, 101.13)
VT = 373.07 K

SpTc(SpIndex)

This returns the Critical Temperature, in degrees Kelvin, of the required vapour species.
Note: Only valid for vapour species.

real

SpIndex is type integer

H2OIndex = SpI("H2O(g)") = 7
V_Critical_T = SDB.SpTc(H2OIndex)
V_Critical_T = 647.14 K

SpmlHf(SpIndex, temperature, pressure)

This returns the Molecular Heat of Formation, in J/mol, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlHf = SDB.SpmlHf(H2OIndex, 298.15, 101.325)
WatermlHf = -285829.97 J/mol

SpmsHf(SpIndex, temperature, pressure)

This returns the Mass Heat of Formation, in kJ/kg, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsHf = SDB.SpmsHf(H2OIndex, 298.15, 101.325)
WatermsHf = -15865.97 kJ/kg

SpmlHz(SpIndex, temperature, pressure)

This returns the Molecular Enthalpy (including phase change), in J/mol, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlHz = SDB.SpmlHz(H2OIndex, 298.15, 101.325)
WatermlHz = 1889.23 J/mol

SpmsHz(SpIndex, temperature, pressure)

This returns the Mass Enthalpy (including phase change), in kJ/kg, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsHz = SDB.SpmsHz(H2OIndex, 298.15, 101.325)
WatermsHz = 104.87 kJ/kg

SpmlHs(SpIndex, temperature, pressure)

This returns the Molecular Enthalpy (excluding phase change), in J/mol, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlHs = SDB.SpmlHs(H2OIndex, 298.15, 101.325)
WatermlHs = 1889.23 J/mol

SpmsHs(SpIndex, temperature, pressure)

This returns the Mass Enthalpy (excluding phase change), in kJ/kg, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsHs = SDB.SpmsHs(H2OIndex, 298.15, 101.325)
WatermsHs = 104.87 kJ/kg

SpmlCp(SpIndex, temperature, pressure)

This returns the Molecular Specific Heat, in kJ/kmol.C, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlCp = SDB.SpmlCp(H2OIndex, 298.15, 101.325)
WatermlCp = 75.338 kJ/kmol.C

SpmsCp(SpIndex, temperature, pressure)

This returns the Mass Specific Heat, in kJ/kg.C, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsCp = SDB.SpmsCp(H2OIndex, 298.15, 101.325)
WatermsCp = 4.182 kJ/kg.C

SpmlSf(SpIndex, temperature, pressure)

This returns the Molecular Entropy, in kJ/kmol.C, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlSf = SDB.SpmlSf(H2OIndex, 298.15, 101.325)
WatermlSf = 70.057 kJ/kmol.C

SpmsSf(SpIndex, temperature, pressure)

This returns the Mass Entropy, in kJ/kg.C, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsSf = SDB.SpmsSf(H2OIndex, 298.15, 101.325)
WatermsSf = 3.889 kJ/kg.C

SpmlGf(SpIndex, temperature, pressure)

Implemented in Build 138. This returns the Molecular Gibbs Free Energy, in kJ/kmol, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermlGf = SDB.SpmlGf(H2OIndex, 298.15, 101.325)
WatermlGf = -306717.40 kJ/kmol

SpmsGf(SpIndex, temperature, pressure)

Implemented in Build 138. This returns the Mass Gibbs Free Energy, in kJ/kg, of the species with the specified species index at the specified temperature and pressure.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WatermsGf = SDB.SpmsGf(H2OIndex, 298.15, 101.325)
WatermsGf = -17025.40 kJ/kg

SpViscosity(SpIndex, temperature, pressure)

This returns the Viscosity, in Pas, of the species with the specified species index at the specified temperature and pressure.
Only valid for Liquid or Gas.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WaterViscosity = SDB.SpViscosity(H2OIndex, 298.15, 101.325)
WaterViscosity = 0.00089 Pas

SpThermalCond(SpIndex, temperature, pressure)

This returns the Thermal Conductivity, in kW/m.K, of the species with the specified species index at the specified temperature and pressure.
Only valid for Liquid or Gas.

real

SpIndex is type integer
temperature in degrees Kelvin
pressure in kPa

H2OIndex = SpI("H2O(l)") = 3
WaterThermalCond = SDB.SpThermalCond(H2OIndex, 298.15, 101.325)
WaterThermalCond = 0.0006072 kW/m.K

Elemental Information

ElemCount()

This returns the total number of elements defined in the project configuration.

integer

None

NumElements = SDB.ElemCount()
NumElements = 7

FindElem(Symbol/Tag)

Available from Build 139.29999. This returns the index of the required element, or -1 if it is not found.

integer

The user needs to specify the element name.

ElementIndex = SDB.FindElem("Na")
ElementIndex = 3
Similar Function - ElemI(), see comparison here

ElemName(ElemIndex)

Available from Build 139.29999. This returns the name of the element with the specified element index.

string

ElemIndex is type integer

ElName = SDB.ElemName(3)
ElName = "Na"

ElemAtmWeight(EleName)

This returns the atomic weight of the specified element.

real

EleName is string of required element

Weight = SDB.ElemAtmWeight("Ni")
Weight = 58.69

ElemAW(ElemIndex)

Available from Build 139.29999. This returns the atomic weight of the element with the specified element index.

real

ElemIndex is type integer

NaIndex = ElemI("Na") = 3
NaAW = SDB.ElemAW(NaIndex)
NaAW = 22.99
Similar Function - MW(), see comparison here

SpElemMoles(SpIndex, EleName)

This returns the number of moles of the specified element in the specified species. Returns 0 if element is not found.

real

SpIndex is type long, EleName is type string

H2OIndex = SpI("H2O(l)") = 3
Moles = SDB.SpElemMoles(H2OIndex,"H") or
Moles = SDB.SpElemMoles(3,"H")
Moles = 2

Information about the Phase or Individual Phase of Species

SpPhaseNo(SpIndex)

This returns the index of the phase with the specified species index.

integer

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
SpPhIndex = SDB.SpPhaseNo(RNiIndex) or
SpPhIndex = SDB.SpPhaseNo(11)
SpPhIndex = 1

SpIPhaseNo(SpIndex)

This returns the index of the individual phase with the specified species index.

integer

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
IndPhIndex = SDB.SpIPhaseNo(RNiIndex) or
IndPhIndex = SDB.SpIPhaseNo(11)
IndPhIndex = 5

SpPhaseTag(SpIndex)

This returns the tag of the phase with the specified species index.

string

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
PhaseName = SDB.SpPhaseTag(RNiIndex) or
PhaseName = SDB.SpPhaseTag(11)
PhaseName = "liquid"

SpIPhaseTag(SpIndex)

This returns the tag of the individual phase with the specified species index.

string

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
IndPhName = SDB.SpIPhaseTag(RNiIndex) or
IndPhName = SDB.SpIPhaseTag(11)
IndPhName = "org"

SpPhaseSymbol(SpIndex)

This returns the symbol of the phase with the specified species index.

string

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
PhaseSymbol = SDB.SpPhaseSymbol(RNiIndex) or
PhaseSymbol = SDB.SpPhaseSymbol(11)
PhaseSymbol = "l"

SpIPhaseSymbol(SpIndex)

This returns the symbol of the individual phase with the specified species index.

string

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
IndPhSymbol = SDB.SpIPhaseSymbol(RNiIndex) or
IndPhSymbol = SDB.SpIPhaseSymbol(11)
IndPhSymbol = "org"

SpIsSolid(SpIndex)

This checks if a species with the specified species index is a solid and returns True if it is a solid, False otherwise.

bit

SpIndex is type integer

FeOH2Index = SpI("Fe[OH]2(s)") = 8
SolidSpecies = SDB.SpIsSolid(FeOH2Index) or
SolidSpecies = SDB.SpIsSolid(8)
SolidSpecies = True

SpIsLiquid(SpIndex)

This checks if a species with the specified species index is a liquid and returns True if it is a liquid, False otherwise.

bit

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
LiquidSpecies = SDB.SpIsLiquid(RNiIndex) or
LiquidSpecies = SDB.SpIsLiquid(11)
LiquidSpecies = True

SpIsGas(SpIndex)

This checks if a species with the specified species index is a gas and returns True if it is a gas, False otherwise.

bit

SpIndex is type integer

RNiIndex = SpI("RNi(org)") = 11
GasSpecies = SDB.SpIsGas(RNiIndex) or
GasSpecies = SDB.SpIsGas(11)
GasSpecies = False

Total Number of Species or Phases

SpeciesCount( )

This returns the total number of species defined in the project configuration.

integer

None

Numspecies = SDB.SpeciesCount( )
Numspecies = 12

PhaseCount( )

This returns the total number of phases defined in the project configuration, normally 3 – solid, liquid and gas.

integer

None

NumPhases = SDB.PhaseCount( )
NumPhases = 3

IPhaseCount( )

This returns the total number of Individual phases defined in the project configuration. This may be the same as above, i.e solids, liquids and gases, but often there are more such as aqueous, organic, slag, etc.

integer

None

NumIPhases = SDB.IPhaseCount( )
NumIPhases = 5

Phase indexes

SolidPhase( )

This returns the index of the solid phase for the project.

integer

None

SolidIndex = SDB.SolidPhase( )
SolidIndex = 0

LiquidPhase( )

This returns the index of the liquid phase for the project.

integer

None

LiquidIndex = SDB.LiquidPhase( )
LiquidIndex = 1

GasPhase( )

This returns the index of the gas phase for the project. This is normally 2.

integer

None

GasIndex = SDB.GasPhase( )
GasIndex = 2

FindPhase(PhaseName)

This returns the index of the required phase, or -1 if it is not found.

integer

PhaseName is type string

PhaseIndex = SDB.FindPhase("s")
PhaseIndex = 0

FindIPhase(IPhaseName)

This returns the index of the required individual phase, or -1 if it is not found.

integer

IPhaseName is type string

IndPhIndex = SDB.FindIPhase("aq")
IndPhIndex = 4

Phase Tag or Symbol

PhaseTag(PhIndex)

This returns the tag of the required phase index.

string

PhIndex is type integer

RequiredPhase = SDB.PhaseTag(1)
RequiredPhase = "liquid"

IPhaseTag(IPhIndex)

This returns the tag of the required individual phase index.

string

IPhIndex is type integer

ReqdIndPhase = SDB.IPhaseTag(4)
ReqdIndPhase = "aq"

PhaseSymbol(PhIndex)

This returns the symbol of the required phase index.

string

PhIndex is type integer

RequiredPhase = SDB.PhaseSymbol(1)
RequiredPhase = "l"

IPhaseSymbol(IPhIndex)

This returns the symbol of the required phase index.

string

IPhIndex is type integer

ReqdIndPhase = SDB.IPhaseSymbol(4)
ReqdIndPhase = "aq"

Examples

Species Names defined as String Variable

If the species name / index is to be defined as a variable, then functions SDB.FindSpecies() and SDB.SpMolecularWt() must be used to find the species index and molecular weights.
Predefined functions SpI() and MW() are more efficient but only work if the species name is defined directly (literal strings) into the functions, they will not work with variables.

For example: 
String   ReqdSpecies*
Long     SpeciesIndex@
Real     MW_ReqdSpecies@
 
ReqdSpecies    = "H2O(l)"
SpeciesIndex   = SDB.FindSpecies(ReqdSpecies)
MW_ReqdSpecies = SDB.SpMolecularWt(SpeciesIndex)
Compared With: 
Long     SpeciesIndex_Water@
Real     MW_Water@
 
SpeciesIndex_Water   = SpI("H2O(l)")
MW_Water             = MW("H2O(l)")

Element Names defined as String Variable

If the element name / index is to be defined as a variable, then functions SDB.FindElem() and SDB.ElemAW() must be used to find the element index and atomic weights.
Predefined functions ElemI() and MW() are more efficient but only work if the element name is defined directly (literal strings) into the functions, they will not work with variables.

For example: 
String   ReqdElement*
Long     ElementIndex@
Real     AW_ReqdElement@
 
ReqdElement    = "Na"
ElementIndex   = SDB.FindElem(ReqdElement)
AW_ReqdElement = SDB.ElemAW(ElementIndex)
Compared With: 
Long     ElementIndex_Sodium@
Real     AW_Sodium@
 
ElementIndex_Sodium  = ElemI("Na")
AW_Sodium            = MW("Na")

Find and Manipulate Species in a Given Phase

The following example uses the same species as in the above section. It finds all of the aqueous species and sets the split in a unit, RO_Plant, to stream P_014, to a user specified value, RequiredValue. 

Real     RequiredValue*  
String   ReqdSpecies, SplitUnitTag  
Long     NumSpecies, NumAqSpecies, AqPhaseIndex, SpeciesPhase, i

NumSpecies = SDB.SpeciesCount()          ; Find the number of species in the project, in this case 12
AqPhaseIndex = sdb.FindIPhase("aq")      ; Find the index of the aqueous phase

i = 0
while (i < NumSpecies)
  SpeciesPhase = sdb.SpIPhaseNo(i)       ; Find the individual phase index of species with index i
  if (SpeciesPhase == AqPhaseIndex)
    ReqdSpecies = sdb.SpShortTag(i)      ; Find the tag of the species with index i
    SplitUnitTag  = Concatenate("RO_Plant.GM.IOs.[P_014].Splt.", ReqdSpecies, " (%)")
    [SplitUnitTag] = RequiredValue
  endif
  i = i + 1
endwhile

Find Species Molecular Weights

The following example retrieves molecular weights at initialisation for use in functions: 

Real    MW_H2O, MW_NaCl

Sub InitialiseSolution()
 ;------Retrieve Molecular Weights from SysCAD---------
    MW_H2O  = MW("H2O")
    MW_NaCl = MW("NaCl")
EndSub

Find Water and Steam Properties

The following example returns some Water and Steam properties at a user specified Temperature: 

Real    StreamT_K*("T", "K")
Real    WaterVP@("P", "kPa")
Real    Water_MW@
Long    WaterIndex, SteamIndex
Real    Water_Enthalpy("H(Ms)", "kJ/kg")@, Steam_Enthalpy@("H(Ms)", "kJ/kg"),  LatentHeat@("H(Ms)", "kJ/kg")
Real    Water_Density@("Rho", "kg/m^3"), Steam_Density@("Rho", "kg/m^3")
Real    Steam_Critical_T@("T", "K")
Real    Water_Viscosity@("Visc", "Pas"), Steam_Viscosity@("Visc", "Pas")
Real    Water_ThermalCond@("HCond", "kW/m.K"), Steam_ThermalCond@("HCond", "kW/m.K") 

WaterIndex 	  = SpI("H2O(l)") 
SteamIndex 	  = SpI("H2O(g)") 
Water_MW 	  = MW("H2O") 
WaterVP 	  = SDB.SpVapourP(SteamIndex,StreamT_K) 
Water_Density 	  = SDB.SpDensity(WaterIndex,StreamT_K,WaterVP)
Steam_Density 	  = SDB.SpDensity(SteamIndex,StreamT_K,WaterVP)
Water_Enthalpy	  = SDB.SpmsHz(WaterIndex,StreamT_K,WaterVP)
Steam_Enthalpy	  = SDB.SpmsHz(SteamIndex,StreamT_K,WaterVP)
LatentHeat        = Steam_Enthalpy - Water_Enthalpy
Steam_Critical_T  = SDB.SpTc(SteamIndex)
Water_Viscosity   = SDB.SpViscosity(WaterIndex, StreamT_K, WaterVP)
Steam_Viscosity   = SDB.SpViscosity(SteamIndex, StreamT_K, WaterVP)
Water_ThermalCond  = SDB.SpThermalCond(WaterIndex, StreamT_K, WaterVP)
Steam_ThermalCond  = SDB.SpThermalCond(SteamIndex, StreamT_K, WaterVP)

$ ; --- end of file ---

Other Examples

See also Example Functions to split by species, Example PGM - Species Check

Retrieved from "https://help.syscad.net/index.php?title=Species_Database_Class&oldid=75134"