Editing User Species Database

Navigation: User Guide ➔ Species Database ➔ Editing User Species Database

Main	Editing User Species Database		Species Database Data Table - Theory and Equations								Viewing Properties
Species Database	Editing User Species Database	Importing data into Species Database	Species Table	Heat of Formation and Entropy	Density	Specific Heat (Cp)	Phase Change (solubility)	BPE & Acid/Base Ka/b	Vapour Properties	Transport Properties	Viewing Species Properties	Species Properties Reports

Related Links: Species Configuration, Species Tags

---

Introduction

All of the physical and thermodynamic data for any species used within a SysCAD project is stored in the User database. The user may edit this database at any stage to add, change or delete species.

Species may be configured to use:

• Data entered by the user
• Hardwired data stored within SysCAD
• Ignore all data

Video Link

This YouTube video shows you how to import a species from the default SysCAD database and how to add data for a new species.

Opening the User Species Database Dialog Window

You can edit the Species Table in the following ways:

1. Before opening a project - Via Edit Configuration - then edit database
2. Before opening a project - Via Edit Species - then select the corresponding configuration file
3. After the project is opened - Via Edit Species - then reload the project.

These are explained below:

Method (1)	Start SysCAD, and before opening a project, click on the icon , or go to Edit - Project Configuration. The dialog box shown below will open: - Select the required project configuration file - Click on the "Species DB" button to edit the Species Database, without changing the configuration file, OR - Click on the "Edit" button to Edit the configuration file, then click on the "Edit User Database" button on the Species Configuration Tab to edit the database.
Method (2)	Start SysCAD, and before opening a project, click on the icon , or go to Species - Edit User Database, browse for the SysCAD.93.db3 file in the correct location, usually within the same project group, inside the cfgfiles folder. A popup will be shown, listing the available configuration files within the folder. - Select the required project configuration file - Recommend choosing the option "Edit Species Database with reference to selected cfg file". using this option will allow user to choose different hardwired data where applicable
Method (3)	If the project is already open, use menu command Species - Edit User Database to open the database. See notes below. You may also edit the Default Species database. NOTES: You must exit and reload your project (or exit and restart SysCAD) in order to use any changes or additions. See Loading the modified data into SysCAD When a new chemical species is added to the species database, it may be added to the configuration file by: a) Ticking the box next to the species in the species list; or b) Adding in the Configuration File editor - see Adding a Species to the Configuration File.

Species Table Layout

In the Species database editor Solids, Liquids and Gases will have different fields visible. So, for example:

• Boiling Point Elevation (BPE) and Disassociation Constants (Ka/b) will only be visible for Liquid species;
• Vapour Pressure (Vp) and Gas Constants will only be visible for Gas species.

The Species Database editor has the layout of a data entry form:

• The user may edit any field for a species, no matter if it has a white or grey background:

  A white background indicates that User data is used for the field;

  A grey background indicates that Hardwired data is used for the field.

• The 'Edit' button, at the right of the field has the following functionality:

  If the user clicks on the button it will display the data that is available for the field;

  If the user double clicks on the button they will see the User data editor and they can edit the user data.

• Clicking on the will close the Species Database Editor.
• See Species Table for the definition of the various fields.

The image below shows the species database editor for a Liquid species. If you move your mouse over the image you will see a description of each field or area. If you click in the fields, you will jump to that topic:

Descriptions

	All of the species that exist within the species database may be displayed in alphabetical order in this Display Window. When you click on a species in the display window the parameters for that species become visible for viewing or editing. In the above window, CuSO4(aq) is selected and its parameters are displayed. You may use the Filter at the bottom of the list to change the species that are displayed.
	Species that are ticked are selected in the project configuration. The user may click in the box to toggle the tick and hence select or un-select the species. Note: If the user clicks in the box to add a species to the project, then SysCAD will add that species to the display list. It is recommended that the user checks the position of the species in the display list in the configuration editor.
	The user may use the filters to change the display of the species. The second filter, where the user may enter required species or elements, is only active with the 'Starts' and 'Contains' filters - all other filter options, 'All Species', 'Solids in Project', etc. will ignore the text entered in the second box.
	The top section displays the fields that are used to define a species. To edit any of these fields, you must click on the button.
	If the user clicks on the small button next to a field, a window will display all available data for that field. If the users double clicks on the button, the Edit User Data dialog will be pop up and the user may edit the data. If there is a icon next to a field, then there is Hardwired data available for that field. If there is a icon next to a field, then there is user data available for that field.
	The user may import a species into the database from an external database using either of these 2 buttons, : click on the SysCAD button to import a species from another SysCAD database, including the default database that is supplied with SysCAD. If you own the HSC software, then you may click on the HSC button to import a species from the HSC database into SysCAD. NOTE: Currently we only support importing of data from HSC database up to HSC 7. (Database *.hsc files). Import is not working with .HSC8 database format.
	Click on the button to add a totally new species, or to add a species from the Hardwired list.
	The buttons will work on the species that is currently selected. Note that if the user copies a species, then you MUST change the definition to ensure that it is a unique species.
	The buttons are used when you have made changes to a species. You cannot move to another species, or click on the Done button, until you have clicked on either Update or Undo.
	Click on the button to close the Species Database Editor.

Data Field Indicators and Buttons

Button or Indicator	Description
	When the user clicks on this button they will see a list of the data that exist for the adjacent field. The data that is used in the project will have a tick displayed next to it, and this will be the data that is visible in the data field. The user may click on any value in the list and this will be selected to be used in the project. This data will also be displayed in the field. The Data that may be listed is as follows: Hardwired Data: Only visible if hard-wired data is available for this field. The Hardwired data will be displayed with the name of the reference. In the above example only 1 set of Hardwired data is available, and the reference for this data is Felder; User Data: Only visible if user data is available for this field. The data will be called 'User' with the value displayed; Ignore Data: Always visible. If the user clicks on this line, then the project will ignore all data, including User data and Hard-wired data; and Edit User Data: Always visible. If the user clicks on the 'Edit User Data', the Data Editor dialog box will be visible and the user may enter data for the field. This data will then be used in the project and will be displayed in the field.
	If this indicator is visible next to a field it means that there is hard-wired data available for this field. (If the hard-wired data is being used in the project, then the field will have a grey background.)
	If this indicator is visible next to a field it means that there is user data available for this field.
	If both the Hard-wired and User indicators are visible and the background colour is also visible, this means that the Hard-wired data = User data. The user may then remove the user data and just use the hard-wired data, if required.

Data Fields

The Data Fields are described briefly below. (For further information on how the data is used within SysCAD, please see Species Table)

Data Field Name	Data Type	Required / Optional	Description	Example
Species Definition To edit any of these fields, you must click on the button.
Long Name	Alphanumeric string	Required	The name of the species	SodiumChloride
Short Name	Alphanumeric string	Required	The species tag, normally a chemical formula	NaCl
Component	Alphanumeric string	Required	The compound, normally a chemical formula, usually the same as the Short Name	NaCl
Definition	Alphanumeric string	Required	The elemental makeup and charge of the species (case sensitive). Charge is specified by adding any number of '+' or '-' to the end of the elemental definition (e.g. Fe1++).	Na1Cl1
Phase Occurrence	Selection Buttons	Required	The phase in which the species occurs. This may only be Solid, Liquid or Gas.	Liquid
Individual Phase Label	Drop down list, or user defined	Required	The individual phase. This may be the same as the Phase or a subset of the phase, e.g aq is a subset of liquid. The user may also type in their own name, i.e. "o" for an organic species.	aq
Thermodynamic Data
H25	Single value or Heat of Dilution (for Liquids only)	Optional	The enthalpy of formation in J/mol at 250C. Normally 0 for elements in their Standard State, negative for most other species. Users may enter Heat of dilution data for liquid species.	-407312.394
S25	Single value	Optional	The entropy in J/mol.K at 250C	117.152
Cp	Single value or Function	Optional	The specific Heat in J/mol.K. This may be a constant, or any of the equations shown in the User selection list. * A species may have more than one Cp equation. In the example above, NaCl(aq) has 2 equations covering a temperature range from 273K to 473K.	CRC_Cp(40.016, 25.468, 3.648, 0): Range(C,25,150)
Common Physical Data These fields are visible for Solids, Liquids and Gases.
Density	Single value or Function	Optional	The density of the species. This may be a constant or a polynomial where density is a function of Temperature or Mass Fraction, in the case of a dissolved liquid species.	2300
Phase Change	Single value or Function	Optional	Methods of changing between species phases. This includes: * Solubility; * Temperature; and * Mass Fraction.	SolubleT -g/100g
Liquid Only Data Visible only if the species is a Liquid.
BPE	Single value of Function	Optional	The user enters the van't Hoff constant for the species. (This functionality currently expects the solvent to be water.)	vantHoffConst(1.68)
Ka/b	Values	Optional	The dissociation constant(s) of the species. Values for common acids and bases are present in SysCAD. See also Acidity Calculations	Ka(1,0)
Liquid and Gas Data Visible if the species is a Liquid OR a Gas.
Viscosity	Function or Single Value	Optional	The user may enter an equation to calculate the viscosity of the species - normally as a function of temperature	Prausnitz(0.34,0.00057,0,0)
Thermal Conductivity	Function or Single Value	Optional	The user may enter an equation or single value for the thermal conductivity of the species	1.536
Vapour Properties Visible only if the species is a Gas.
Vp	Function	Optional	Vapour pressure equation, used in VLE. Any of the standard vapour pressure equations, including the various forms of the Antoine equation. See Vapour Pressure in the Species Table.	VpAnt(3.81634, 319.013, -6.45) : Range(K, 64.29, 97.2)
Gas Constants	Constant Values	Optional	The user may enter the critical constants for Temperature, Pressure and Volume as well as the Acentric Factor.	Gc(154.6, 5.045985, 0.0734, 0.021)
CpCv	Single Value	Optional	The user may enter the CpCv value for a gas.	1.34
Administration
Warning	Alphanumeric	Optional	Field to allow user to enter a warning message that will appear once when the project is loaded.	Thermodynamic data for Jarosite is suspect!
Reference	Alphanumeric	Optional	Field to allow user to give references for user data. Ideally this will contain references for all the user data for the species.	Cp from HSC Database & Gas Constants from Prausnitz 1977
Checked / Reviewed	Alphanumeric	Optional	Field to allow user to confirm that data has been checked. Ideally this will contain the users name or initials and date.	John Doe 23/6/2007

Enter or Change Species data

You may enter or change data for most species in the Species database. However, the following species are handled differently in the SysCAD database:

• Water and Steam, H2O(l) and H2O(g), always exist in the SysCAD database and you CANNOT change the data for these two species. The properties for water and steam are calculated using internal functions and data. Please see Water and Steam Properties.
• Sulfuric acid, H2SO4(l) and H2SO4(aq), always exist in the SysCAD database. However, you can edit the data for these species. Please see Editing the Properties of Sulfuric Acid.

You may add, delete and edit all other species. You may click on a species in the Display List and the fields that can be edited are displayed on the right hand side:

1. All fields may be edited, no matter if they have a white or grey background;
2. Fields with a grey background are using hardwired data that is stored in SysCAD. The user may still enter and use their own data for this field;
3. Fields that contain Hardwired data have an indicator, on the right hand side of the field. If the configuration is set up to use the Hardwired data, then the data will be displayed in the field with a grey background. You may edit these fields by clicking on the Edit button at the right of the field. If you wish to return to the Hardwired data at any time, you simply click on the Edit button and select the Hardwired data from the list;
4. Fields that contain User data have an indicator, on the right hand side of the field. If the configuration is set up to use the User data, then this data will be displayed in the field on a white backgroung. You may edit these fields by clicking on the Edit button at the right of the field;
5. Fields that contain Hardwired data that is exactly equal to the User data, will have both the Hardwired and User indicators shown on a coloured background. This is not a problem, but the user may want to remove the User data, and just use the Hardwired data.

Properties Editor Dialog Boxes

To edit the user properties, either:

1. Click on the 'Edit User Data' line in the list of available data; OR
2. Double click on the button.

The properties Editor dialog box will be visible. The dialog box for editing Density is shown below:

The Function Type drop down contains a list of functions that you may use for that particular property. The image above shows the functions available for the Density field:

Entering Spline Data

Currently you may enter TSpline data for a number of properties in the Species Database.

TSpline data has the following requirements:

• The user must enter a table of data with X and Y values;

  Note: The best way to enter this data is to copy it from an Excel spreadsheet with the X and Y data in adjacent columns, but the user may manually enter the data;

• Low Range - the lowest X value in the table;
• High Range - the highest X value in the table;
• Tension - this factor determines the shape of the curve between data points. If this factor is small, the curve approaches a cubic spline. As the tension increases the curve between points becomes more linear. The default value of 1 will normally be acceptable;
• Once you are happy with the data. click on the Check button so that SysCAD can check for incorrect syntax or missing values;
• If there are no errors with the data, click on the OK button;
• SysCAD will then use a Spline method to interpolate from the data in the table.

Notes:

1. A spline is a special function defined piecewise by polynomials and is used in interpolating problems.
2. A fitted equation will be processed more quickly within SysCAD and hence is preferred to entering TSpline data.

The steps for entering this data are shown in the image below (the example shown is for Solubility, but the principle is the same for all other properties):

Use Hardwired Data for User Data

When editing the Gas Constants field (only applicable to gaseous species), the Edit User Data dialog contains a button called Select H/W. If pressed, this button will display the available hard wired data sets for this gas. The user can choose one of them and the user data will be populated with this data.

Adding a New Species

To add a new chemical species using the Edit Species Tab page:

1. Click on the button.
2. You may then either add a new species, or 'import' a species from the Hardwired species in SysCAD, as shown in the image below:

Example

To add a 'pseudo' species, such as InertSolids or Gangue, do the following:

1. Click on the button;
2. In the 'Select Defined Species' dialog window, click on the button;
3. You will then see the 'Species Definition' dialog window, as shown below:

   

4. Enter the required fields, in this case we have used a pseudo species called Gangue;
5. When entering the definition of a 'pseudo' species, you can use a false element and composition, in this case Gn1(100), where Gn is NOT a real element. Here we are saying that Gangue consists of 1 atom of Gn which has a molecular weight of 100. (Normally this is the elemental composition of the species, such as Na2S1O4 for Na₂SO₄, as shown in the above picture on the right);
6. Choose the Phase Occurrence as Solid and the required Individual Phase Label, usually s; please see General notes for more information.
7. Click on the 'OK' button;
8. You can then enter data for all of the other fields. These are all optional, but it is recommended that you enter a reasonable value for the density, as this will affect stream densities and volumetric flows.
9. It is also recommended that you enter some information in the Checked and Reference fields, so that there is an audit trail for this information.

Copy an Existing Species

1. To add a new Species that resembles an existing Species in the species database, click on the similar Species in the species display window and press the button.
2. You must first edit the Species definition data fields to create a unique new Species:

   

   You can change the long name, short name (and component) and definition of the species - in the example above we could change the species,H3O.Al3[SO4]2[OH]6(s), to:

   

   Alternatively, you could have changed the phase to Liquid with an individual phase = aq and this would create a unique species, H3O.Al3[SO4]2[OH]6(aq).

3. Once you have changed the Species Definition fields, click on the 'OK' button;
4. You may change any of the other field values, or leave them to have the same values as the copied species;
5. When you have finished making changes, click on the Update button to add the new species to the database. (or Undo to cancel the edit.)

Delete Species from database

Click on the unwanted Species in the species display window and press Delete. The Species will be deleted from the SysCAD.93.db3 file that you are editing.

Note: The following species CANNOT be deleted from the SysCAD database:

• H2O(l),
• H2O(g),
• H2SO4(l), and
• H2SO4(aq)

Importing Species from SysCAD or HSC Database

1. Data may be imported from other SysCAD Species Tables using the SysCAD Button in the Import section.
2. Data may be imported directly from the Species Database provided with HSC Chemistry by Metso Outotec, using the HSC Button in the Import section.
   • For more information on the Licensed Software HSC Chemistry from Metso, contact your local distributor or Metso Outotec directly www.metso.com/portfolio/hsc-chemistry.

NOTES:

• In Build 138 or earlier, the import HSC database function is only available for older format HSC databases (*.hsc files), it does not support newer HSC databases (.hsc8 files). For the newer versions of HSC, the data needs to be entered manually in SysCAD Build 138.
• In Build 139 and later, import functionality has been added for HSC8 and HSC9. To use this import functionality, the HSC COM interface is required. This requires user to have a licensed working copy of HSC installed. If not, the connect to HSC COM Interface fails, and user cannot import from HSC8 or HSC9 directly.
• For HSC10 and newer a direct import is not available, the data needs to be viewed in HSC and entered manually in SysCAD. HSC10 or newer does not have an available API to support direct import of thermodynamic data for individual species.

For more information, please see

• Importing Species from other SysCAD database
• Importing Species from HSC

Loading the modified data into SysCAD

• You must exit and reload your project (or exit and restart SysCAD) in order to use any changes or additions.
• For newly added chemical species to appear in your SysCAD project, the configuration file must be edited as well. See Adding a Species to the Configuration File.

An option has been added to allow automated save and reload of data if the project was open when existing data is modified. (This does not show new additions, new additions must first be added to the configuration file).

The follow dialog box will appear when SysCAD sees a change in the species database:

The user may choose to continue and the changes will only apply after a project reload. Alternatively the user can close and reload the project to use the most up to date information, with three sub-options relating to the saving of the project: don't save; save; or, save as new version.

General Notes

When defining a new species, please check the following:

1. Species name does not contain illegal characters or characters using foreign language (for example, letters or punctuations from Chinese input keyboard).
2. Phase name clash with existing phases. For example, user can use "s" (lower case s, which is an existing phase) for solids phase, but user cannot use "S" (upper case) to define a new phase name. This is because it is using the exact same name as an existing phase, only in a different case.
   • If user did use "S" as a phase name, it will not return errors at the time of species definition, this is because "S" is not an illegal character, however, during project load species check, this will be reported as an error.
   • Furthermore, if user opens the reaction editor without rectifying the above issue, the "Reaction Editor" will not open correctly, the following error message will be given: "An item with the same key has already been added".
   • User can use upper case letters for new phase names, but only if the phase name is different to the existing phases, such as "S1"