Editing User Species Database

From SysCAD Documentation
Jump to navigation Jump to search

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

Latest SysCAD Version: 25 February 2021 - SysCAD 9.3 Build 138.28098

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, User Data;
  • Hardwired data stored within SysCAD; or
  • Ignore all data.

Opening the User Species Database Dialog Window

You can edit the Species Table in the following ways:

  1. Start SysCAD, and before opening a project, click on the icon Icon - Edit Configuration.png, or go to Edit - Project Configuration. The dialog box shown below will open:
    Edit Configuration dialog window - displays all recently opened or used Configuration files.Edit Species dB via Configuration Rev 1.png
    About this image
  2. Before the project is open, click on the icon Icon - Edit Species dB.png, 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. User should choose the option "Edit Species Database with reference to selected cfg file". (using this option will allow user to choose different hardwired data where applicable)
    EditDBwithReftoCfg.png
  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.

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.

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, EditButton.png 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 DoneButton.png 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:

1. Displays all of the species within the Species Database in Alphabetical order2. All Species that are Ticked will be included in the project.3. The list of Species may be filtered to show all species in a selected phase, or containing a selected Element, etc.4. The Species Definition.  You must click on the 'Edit Definition' button to change any of these fields.5. Click on the small button next to a field to edit the data in the field.6. Import a Species from either another SysCAD species database, or from an HSC database.7. Add a completely new Species, or add a Species from the hardwired species list.8. You may Copy or Delete the highlighted Species.9. You must either click on Update or Undo when you have made any changes to a Species.10. Click on the Done button to close the Species editor.This string describes the species and is often the common or English name for the species, e.g. Water, Lime, Nitric_Acid, etc.This is normally the chemical formula of the Species, e.g. H2O, HNO3, etc.This is usually the same as the short nameThe Elemental makeup and, if required, the Charge of the Species, e.g. H2O1, H1N1O3, H1+ etc.The required phase of the Species - Solid, Liquid or Gas.The Individual phase of the Species, e.g. s, l, g, aq, o, ml, etc.Heat of formation at 25C.  You may also enter data for Heat of DilutionEntropy at 25C.The specific heat may be a constant value, a single function, or a number of functions.The Density may be a constant value, a function of Temperature, a function of Mass Fraction, or a function of Mass Fraction AND Temperature.Phase change data includes Solubility, Phase change at Temperature or Phase change at mass fraction.The Boiling Point Elevation constant - SysCAD uses the van't Hoff formula for BPE.The acid or base dissociation constants for acidic or basic species.  If there is a value entered in this field, then the species will be used for pH calculations.The viscosity of a species.The Thermal conductivity of a species.The user may type a warning message here.  The message will be displayed on the Species tab of the Messages window when a project is opened.The user may enter the reference information for the data. This is optional, but highly recommended.The user may enter their name or initials to show that the data has been checked.When a species has been modified, SysCAD will record the name of the computer and the date and time in this field.Species dB Editor 9.3.png
About this image

Descriptions

Button Small 1.png 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.
Button Small 2.png 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.
Button Small 3.png 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.
Button Small 4.png The top section displays the fields that are used to define a species. To edit any of these fields, you must click on the Edit Definition.png button.
Button Small 5.png 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 Hardwired Data.png icon next to a field, then there is Hardwired data available for that field.
If there is a User Data.png icon next to a field, then there is user data available for that field.
Button Small 6.png The user may import a species into the database from an external database using either of these 2 buttons, Species Import.png:
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.

Button Small 7.png Click on the Add Button.png button to add a totally new species, or to add a species from the Hardwired list.
Button Small 8.png The Copy and Delete Button.png 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.
Button Small 9.png The Update and Undo Button.png 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.
Button Small 10.png Click on the DoneButton.png button to close the Species Database Editor.

Data Field Indicators and Buttons

Button or Indicator Description
EditButton.png When the user clicks on this button they will see a list of the data that exist for the adjacent field.
  1. 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.
  2. 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 button on the left of the property field will allow the user to view and change the between user and hardwired data.View Field Data.png
    About this image

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.
Hardwired Data.png 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.)
User Data.png If this indicator is visible next to a field it means that there is user data available for this field.
HardwiredUser.png 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 Edit Definition.png 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 (eg. 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, Hardwired Data.png 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, User Data.png 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 species property edit dialog window allows the user to change data.The user may select a function from the drop down list.Species Density Editor.png
About this image

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):

SPline Data.png

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.

Select HW.png

Adding a New Species

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

  1. Click on the Add Button.png 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:
Add a new Species.png

Example

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

  1. Click on the Add Button.png button;
  2. In the 'Select Defined Species' dialog window, click on the Define New Species.png button;
  3. You will then see the 'Species Definition' dialog window, as shown below:
    Table - New Species Definition.png
  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 Na2SO4.);
  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 Copy Button.png button.
  2. You must first edit the Species definition data fields to create a unique new Species:
    Copy Species Definition.png
    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:
    Change Species Definition.png
    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.mdb 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

Species Import.png
  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 Outotec, using the HSC Button in the Import section.
    • For more information on the Licensed Software HSC Chemistry from Outotec, contact your local distributor or Outotec Research directly (www.outotec.com/HSC).

NOTE:

  • In Build 138 or earlier, the import HSC database function is only available for older format HSC databases (*.hsc files), it does not support new newer HSC databases (.hsc8 files). For the newer version of HSC, the data needs to be entered manually in SysCAD.
  • In Build 139 and later, new import functionality has been added for HSC8 and newer. To use the new 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 HSC directly.

For more information, please see Importing Species into User Species Database

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:

SaveAndReload 9.3.PNG

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"