Species Calculations

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: User Guide ➔ Edit ➔ Project Configuration (cfg File) ➔ Calculation Configuration ➔ Species Calculations

Edit Configuration Step 2 of 2 - Calculation Tab
Calculation Configuration (Summary) User Property Calculations User Property Expressions Species Calculations Species Calculation Expressions

Species Calculations

The user may add any number of Species Calculations to the configuration file. These calculations will be displayed on the species flow (Sp) tab which is part of the Qi/Qo tabs of the Pipe, Qo tab of a DirectLink and QFeed/QProd tab of many unit operations' Access Window. They will also be shown on the Content composition tab page of dynamic units with surge. The calculations will be peformed on solve or run and will change as the user changes from mass to volume view etc.

Adding a New Calculation to the Configuration File

Button Small 1.png On the Calculations tab page, click on the Species Calculations section Add button.
Button Small 2.png A new calculation with a default name such as Calc01 appears. Click on this and type in the required calculation name.
  • For example: Fe2+, please note that calculation name must be unique, and follows some naming rules, please note that the calculation name must be unique, and follow some naming rules, see Model Tag naming rules. Please make sure you have not used any illegal characters in the variable name and there are matching pairs of any brackets used.
Button Small 3.png The actual expression for the calculation is entered in the 'Expression' panel. Click on this editing box to activate the panel buttons.
Button Small 4.png Click on the Terms button to open the "Select Term for Species Calculation" box, see Species Terms (next heading)
  • Insert any of the expressions shown in the list by double clicking on the required expression (or by selecting and pressing OK).
  • Alternatively, users may type the required expression, when typing in the expressions manually, please check examples for syntax.
Button Small 5.png Users can assign a conversion type to the calculation using the Cnv Type dropdown list (None, View or Frac), for example:
  • When using View: The conversion units will follow the Sp tab column display settings, for example, Mass Flow (t/h), Mass Frac (%) or Conc (g/L) and so on
  • For fractional type calculations, use the Frac conversion type.
  • For dimensionless calculations, use the None conversion type.
  • Note that some species calculation will only make sense for certain species views, for example, the calculation shown above will only be valid for mass views (mass flow, mass frac, mass concentration, etc.). Refer to Button Small 8.png below.
  • Calculations that are not suitable to use the View conversion type may be better defined as User Property Calculations.
Button Small 6.png The check box Concealed may be used to create a calculation hidden from the user in the access window. This is useful if it is an intermediate result to be referenced in other calculations.
Button Small 7.png Users can check for syntax errors by clicking on the Check All button. This will place a ! next to any calculations that have errors. Note: If the user does not check expressions, and then loads a project, SysCAD will check the expressions at load time and will NOT load the project if there are any errors in the calculations. The user will receive an error message in the Messages window.
Button Small 8.png Select the Species Views and basis that is valid for the calculation. The Fe2+ example given above should only be valid for Mass.
Button Small 9.png Select the Species Display for the calculation. The Fe2+ example given above can be display with Liquid or All.
  • Please note that the display order for the species calculations is set on the Species Tab.

Species Terms

Clicking on the Terms button will open a dialog box which contains a list of all available expressions, including all species in the configuration file and any previously defined Species Calculations.


The top line of the Terms dialog box are filters:

Species List Box Use this box to select the required species This is used by the Species Functions group
Element List Box Use this box to select the required element This is used by the Elemental Functions group
Phase List Box Use this box to select the required phase This is used by the Phase and Elemental Functions groups
With T and P Tick Box Select this tick box if the expression requires user defined Temperature and Pressure This is used by the Species Functions group

The functions are divided into groups, the group headings are highlighted in green in the above picture. The terms required for the definition of 'Fe2+' (=[FeSO4(aq)]*MW(Fe)/MW(FeSO4(aq))) have a red dot next to them and are highlighted in yellow.

Double clicking on any of these expressions will add it to the Expression window. Alternatively, the user may define a calculation by typing in the expressions.

  • Note there are less functions available here (compared with user property calculations), this is because the species calculation can be displayed in multiple views. For example, adding Fe2+ to the Mass Species Views will produce values for mass flow, mass fraction, mass concentration and so on.

The allowed expressions are shown in the Species Calculation Expressions table. Please refer to this table for an explanation of all the available expressions and some simple expression examples.

Operators Allowed in Calculations

The main operators used in calculations are addition (+), subtraction (-), multiplication (*), division (/) and power (^).

Opening '(' and closing ')' brackets can be used when defining calculations.

Comparison operators >, >=, ==, <>, <= and < can also be used. The result of a comparison operation will be 1 (for true) or 0 (for false).

Useful Functions Allowed in Calculations

The conditional If function is very useful to perform a function based on a criteria or simply return a zero. It can also be used to prevent divide by zero and meaningless results.

Functions such as Range, Min and Max can be used to keep the terms or results of functions valid, including avoiding silly results from a divide by zero.

Mathematical functions such as Sin, Cos, Ln, Abs, etc. are available.

User Defined Constants

SysCAD allows a limited number of user defined variables (12 maximum) to be used in the custom calculations. These variables are called Project User Values (PUV) and are defined in the Plant Model - Project Tab. These PUVs can be manipulated by the user during a project solve without having to go back to the calculation tab to adjust them. Useful for data/equation fitting. These are shown in the picture below.


Other predefined variables users can manipulate are the Environment Function constants. These are defined in the Plant Model - Environment Tab.

Editing and Removing Calculations

To edit a previously defined calculation, select it from the list. It can be renamed by clicking on the current name and the expression can be edited in the expression window.

To remove a calculation, select the calculation in the list and press the Remove button. If this is pressed by mistake, press the cancel button at the bottom of the window and this change will not be saved.

Species Conversions

Species Calculations will always be displayed on the Species Flow (Sp) tab. The user may have several columns of results on this page and may change the view of each column between Mass Flow, Volume Flow, Mass Fraction, Volume Fraction, Concentration, etc. Depending on the calculation and how it is configured, the calculation may not be valid and only shown with some views and may change value with change of view. Refer to next section for more detail on specifying which Views the calculation is valid for.

Species Views

Button Small 8.png CalculationsSpView.png

Some calculations are only valid in certain views, such as a mass view. To prevent users from seeing calculations displayed which do not make sense, the user may define which view the calculation is shown in using the View drop down box. The three groups of views to choose from are Mass, Volume and Molar. Users may choose only one of these groups or any combination of the three.

The different combinations of Views are explained further in the following table:

View Group
Example of when to use this Group
Mass This group includes MassFlow, MassFrac and MassConc. [FeSO4(aq)] * MW(Fe)/MW(FeSO4(aq)) This calculation is only valid when mass is used.
Volume This group includes VolFlow, VolFrac, NormVolFlow and NormVolFrac. [R(o)]/[H2O(l)] NOTE: This view option is currently not working.
Molar This group includes MoleFlow and MoleFrac. 2*[Fe2[SO4]3(aq)] NOTE: This view option is currently not working.
Mass, Volume This includes all those described above for Mass and Volume SumPhase(g)-[H2O(g)] This calculation is only valid when mass or volume is used.
Mass,Molar This includes all those described above for Mass and Molar SumElemPhase(S,l) This calculation is only valid when mass or moles is used.
Volume,Molar This includes all those described above for Volume and Molar [He(g)]/[Ar(g)] NOTE: This view option is currently not working.
Mass,Volume,Molar This includes all those described above for Mass, Volume and Molar [H2O(l)] This calculation is valid in mass, volume and molar views.

The Basis refers to the SpBasis on the Sp Tab, user can select to have the user species displayed when the SpBasis is set to All, Phase or Individual Phases (or combinations of these).


  • Calculations are not shown in the following views: Molality, PartialP, PartialPFrac, Specific Hf, Specific Hs, Specific Hz, Total Hf, Total Hs and Total Hz.
  • Calculations are not shown on the EC (Elements and Components) tab page.
  • Calculations that include aqueous species with density correction in use cannot be displayed in the volume view. SysCAD checks the calculation at project load time, if a species with density correction is used in a calculation, the project would not load and user is given an error message on the Species Database tab of the Message Window. For example: Invalid View(s): Volume for Expression [H2SO4(aq)].
  • Calculations that include elements cannot be displayed for the individual phases basis.
  • The Hide Zeros and Species Filter options may also affect the display of species calculations.

Species Display

The Species Calculations are ordered alphabetically in the Species Calculation tab. The order in which they will appear on the Species View tab page will depend on the Order chosen for the Species display.



  • If one of the default orders are chosen (Sol-Liq-Gas, Gas-Liq-Sol or Liq-Sol-Gas), user can select a display area from the "Display With" droplist (All, Solid, Liquid or Gas):
    • If All is selected, then calculations are displayed at the bottom of species list in alphabetical order.
    • If a phase is selected, then calculations are displayed at the bottom of phase in alphabetical order.
  • If one of the semi custom orders are chosen (Sol-Liq-Gas Custom, Gas-Liq-Sol Custom or Liq-Sol-Gas Custom), species are grouped by phase, user can order the species within the phase group.
  • If the Custom order is chosen
    • the species are NOT automatically sorted into the phase group, all species, including user species calculations have to be ordered manually using the Move Up and Move Down buttons.
    • User can also add a new page, and move all the user species calculation to display on this new separate page.

Example Species Display in Streams:



  1. This is shown with SpBasis set to: Individual phase.
  2. All calculations are marked with [c]
    • Calculations with highlights are created automatically. These are totals for stream, phase and and individual phases.
    • Calculations with highlights are added by the user. These can be found in the example table below.
    • Calculation with the highlights (A/O) is NOT valid for all species views. Only the ones marked in the above table are valid, so please use this with caution. Recommend that the user only adds this as a User Property Calculation to avoid confusion.
  3. User can also show the calculation formula in the access window by selecting ShowSpFormulas from Plant Model - Views Tab:

Examples of Species Calculations

Most of the calculations presented here have equivalent calculations in the Examples of User Property Calculations table. Please note that we have used different names due to the unique naming rule.

Caution: The User Property Calculations and Species Calculations functions may look similar, but they have subtle differences, they cannot be copied directly from one section to another.

Tag Expression Cnv Type View Basis Display With Description Notes
Fe2+ [FeSO4(aq)]*MW(Fe)/MW(FeSO4(aq)) View Mass All, Phase, IndPhase Liquid Ferrous ion. This is valid for mass flow, mass frac and mass concentration displays only.
Fe3+ [Fe2[SO4]3(aq)]*MW(Fe2)/MW(Fe2[SO4]3(aq)) View Mass All, Phase, IndPhase Liquid Ferric ion. This is valid for mass flow, mass frac and mass concentration displays only.
Sulphate (([Fe3+]*3/2+[Fe2+])/MW(Fe)+([H2SO4(aq)]/MW(H2SO4(aq))))*MW(S1O4) View Mass All, Phase, IndPhase Liquid
  • SO4 in ferrous, ferric sulfate and sulfuric acid only.
  • Both Fe2+ and Fe3+ must have been defined.
This is valid for mass flow, mass frac and mass concentration displays only.
SO4_equiv SumElemPhase(S,l)*MW(S1O4)/MW(S) View Mass All, Phase Liquid Assumes all Sulphur in liquid phase is present as SO4. This is valid for mass flow, mass frac and mass concentration displays only. This is not valid for individual phase view.
N_equiv SumElemIPhase(N,aq) View Mass, Volume, Molar All, Phase, IndPhase Liquid Sum of aqueous species containing nitrogen (ammonia) compounds displayed as the nitrogen equivalent.
U3O8_sol_equiv SumElemPhase(U,s,l)*MW(U3O8(s))/(MW(U)*3) View Mass All, Phase, IndPhase All Sum of solid and liquid species containing Uranium compounds displayed as the U3O8 equivalent. This is valid for mass flow, mass frac and mass concentration displays only.
DryGas SumPhase(g)-[H2O(g)] View Mass, Volume, Molar All, Phase, IndPhase Gas Dry Gas (excluding water vapours).
The following calculations are shown here for information only, they should be added to the User Property sections, see Examples of User Property Calculations for equivalent calculation formats. These are NOT recommended for Species calculations.
A/O if(SumIPhase(o)>0, SumIPhase(aq)/SumIPhase(o), 0) None Mass, Volume, Molar All, Phase, IndPhase Liquid
  • Ratio of aqueous to organic.
  • The if statement is used to avoid division by zero errors.
Only valid for Fraction Views, recommend adding this calculations to User property Calculation only.
Fe2+/Fe3+ if([Fe3+]>0.000000001, [Fe2+]/[Fe3+], 0) None Mass All, Phase Liquid
  • The ratio of ferrous ion to ferric ion.
  • Both Fe2+ and Fe3+ must have been defined.
  • The if statement is used to avoid division by zero errors.
This is only valid for Mass Fraction. Recommend adding this calculations to User property Calculation only.