# Species Database Class

Navigation: PGMs -> Classes -> Predefined Classes

Species Database Class Particle Size Definition Class Array Class StrArray Class Matrix Class Tag Select Class Plant Model Class Noise Class TimeClass

## Description

The Species Data Base (SDB) class is very useful as it provides member functions that allow users to access the details 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.

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

SpSymbol(SpIndex)

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

string

SpIndex is type integer

SpeciesSymbol = SDB.SpSymbol(3)

SpeciesSymbol = "H2O(l)"

SpTag(SpIndex)

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

string

SpIndex is type integer

SpeciesTag = SDB.SpTag(3)

SpeciesTag = "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.

Note: Only available in SysCAD 9.3.

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 available in SysCAD 9.3 and only valid for vapour species.

real

SpIndex is type integer

H2OIndex = SpI("H2O(g)") = 7

V_Critital_T = SDB.SpTc(H2OIndex)

V_Critital_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 = -285830.72 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 = -15866.02 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 = 1888.47 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.83 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 = 1888.47 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.83 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

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 Available in SysCAD 9.3 and 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 Available in SysCAD 9.3 and 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

ElemAtmWeight(EleName)

This returns the molecular weight of the specified element.

real

EleName is string of required element

Weight = SDB.ElemAtmWeight("Ni")

Weight = 58.69

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() only work if the species name is defined directly 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)")


### 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_14, to a user specified value, 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.SpSymbol(i)        ; Find the tag of the species with index i
SplitUnitTag  = StrCat2("RO_Plant.GM.IOs.[P_14].Splt.", ReqdSpecies, " (%)")
SetDynTag(SplitUnitTag, RequiredValue)
endif
i = i + 1
endwhile


### Find Species Molecular Weights

The following example (in SysCAD 9.3 format) retrieves molecular weights at initialisation for use in functions:

Real    MW_H2O, MW_NaCl

Sub InitialiseSolution()
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_ThemalCond@("HCond", "kW/m.K"), Steam_ThemalCond@("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_ThemalCond  = SDB.SpThermalCond(WaterIndex, StreamT_K, WaterVP)
Steam_ThemalCond  = SDB.SpThermalCond(SteamIndex, StreamT_K, WaterVP)

\$ ; --- end of file ---