AQSol Database Utility

From SysCAD Documentation
Jump to navigation Jump to search

NOTE: This feature is currently in BETA with limited release. Please contact us ([email protected]) if you are interested in using this model. This page is currently under development and details may change. Use with caution - we do not guarantee compatibility between different BETA versions.

Navigation: Models ➔ TCE Models ➔ AQSol ➔ AQSol Database Utility

AQSol
Overview 		AQSol
Database Utility 		AQSol
Model Configuration 		AQSol
Direct Calc 		AQSol
Side Calc 		AQSol
Reactor 		AQSol
Evaporator 		AQSol
Flash Tank 		AQSol
Reverse Osmosis 		AQSol
Feeder

Latest SysCAD Version: 25 October 2024 - SysCAD 9.3 Build 139.36522

Applicability

This utility is for adding a list of species into a new SysCAD.93.db3 file for use with AQSol TCE.

  • It will use data from existing databases (in SysCAD database format), examples of such are Default.93.db3, SysCAD.93.db3 from user projects (these can be renamed for better identification).
  • It will NOT extract data from AQSol databases.
  • It will add species to the new database based on the DLL files selected. It will include species that "may" form given the list of ions present.
  • If a species is not found in the existing database, it will add the species with minimum data (Long Name, Short Name, compound, definition, phase, occurrence), but will leave all the other properties blank. User will need to check and fill in data from other sources after the database is created.

General Information

Utility file name: SysCADAQSolUtils.exe

  • This utility can be used to create a species database using data from the AQSol DLL file(s). Users must install AQSol using the standard c:\Program Files (x86)\AQSolXXX\ location for install.
  • The utility can be placed in any folder, but the folder must meet the following requirements:
    AQSol Utility Folder Structure
    1. There must be an existing SysCAD.93.db3 file inside the folder to serve as a template (for species table layout).
      • CAUTION: depending on user selections, this file may be stripped down to contain only water and steam, then new data will be added based on the AQSol model species list. Stripping of the file is optional.
      • Please use a “copy” of the actual SysCAD.93.db3 file to avoid destroying user data.
    2. There must be a subfolder, “DB3Files”, containing the following files:
      • May contain the Default.93.DB3 file (copy from SysCADxxx\BaseFiles folder).
      • May contain user’s own database files, formatted in SysCAD DB file format.
      • Any database files stored in the DB3Files subfolder will be used to populate the SysCAD.93.DB3 file.
      • when more than one database is present, there may be multiple entries for the same species, if a species has multiple sets of data, user must choose which set of data to add to the SysCAD.93.DB3 file.
      • as an alternative to the above, user can specify a preferred database. In this case, the preferred database will be used whenever possible, with alternate databases used elsewhere and placeholder species created where no data is available. Selecting a preferred database will avoid choosing data for each case where multiple options are available.
      • The databases in this folder will be used to build a list of options presented to the user by the utility.
    3. There must be at least one version of AQSol installed:
      • Users must install AQSol using the standard c:\Program Files (x86)\AQSolXXX\ location for install.
      • There is an option to select one or all of the installed versions of AQSol in the generation of the database.
    4. An ErrorLog.txt file is generated in all cases. It contains any errors encountered while running the utility and should be reviewed after generation of the SysCAD database.
    5. A MessageLog.txt file is generated in all cases. It contains general messages generated while running the utility and should be reviewed after generation of the SysCAD database.
    6. IonList.txt, the ion list can be created by the utility, see item "Config.txt" below.
      TPS IonList AqSol.png
    7. Optional: User can place a Replacements.txt file in the same folder as the executable. This is a tab-delimited file that contains replacement strings. If not found, it is simply not used.
      Replacements.txt
      TPS Replacements File.png
      • If the above file were used, any AQSol species containing the string Ice would be replaced with H2O in the creation of SysCAD species.
    8. Optional: User can place a Config.txt file in the same folder as the executable. This is a formatted file that contains configuration settings. If not found, it is simply not used.
      Config.txt
      TPS Config File.png
      • INCLUDE_ELEMENTS: specify in the line below this keyword the elements you want to include, comma separated list.
      • EXCLUDE_ELEMENTS: specify in the line below this keyword the elements you want to exclude, comma separated list.
      • INCLUDE_OCCURRENCES: specify in the line below this keyword the occurrences you want to include, comma separated list. Can be s, l, or g.
      • INCLUDE_PHASES: specify in the line below this keyword the phases you want to include, comma separated list. These are substrings, thus, in the example above, any phase which contains slag (case insensitive) would be included.
      • EXCLUDE_SUBSTRINGS: specify in the line below this keyword any substrings within species that you want to exclude, comma separated list. For example, entering C2, C3, C4 (case sensitive) would exclude ethyl, propyl, and butyl species.
      • ALLOW_DUPLICATE_SHORT_NAME: specify in the line below this keyword either 0 (false) or 1 (true). If you allow duplicate short names, the short names will be appended with _1, then _2, etc. For example, if you have multiple types of silica, you would get SiO2, SiO2_1, SiO2_2, etc.
      • CREATE_DEFAULT_SPECIES_IF_NO_MATCHES_FOUND: specify in the line below this keyword either 0 (false) or 1 (true). If you allow default species to be created, you will get default species (with no thermodynamic or properties data) as placeholders when a matching species is not found. If false, only matched species will be added to the database (with thermodynamic and properties data taken from the db3 file). Default value is true.
      • MIN_TEMP_CP: specify in the line below this keyword the desired lower bound temperature of the heat capacity correlation for selection, in K. The utility will use this if, in the selection of the database, you choose -1. It will then find the matching database entry with the greatest Cp range within the desired range.
      • MAX_TEMP_CP: specify in the line below this keyword the desired upper bound temperature of the heat capacity correlation for selection, in K. The utility will use this if, in the selection of the database, you choose -1. It will then find the matching database entry with the greatest Cp range within the desired range.
      Example for Cp Range: Consider where MIN_TEMP_CP is 273 K and MAX_TEMP_CP is 423 K. There are two possible species matching, one with a range of Range(K,273,450), and another with a Range (K,500,1500). Even though the second has a greater Cp Range than the first, its range is fully outside of the desired range, and thus, it will be rejected in favour of the first, which has a smaller range, but its range fully encompasses the desired range defined by MIN_TEMP_CP and MAX_TEMP_CP. Selections by this method are logged in the ErrorLog.txt file.
      • USE_HARDWIRED_DATA: specify in the line below a value of 1 (true) or 0 (false). If true, it will use "hardwired" data from SysCAD and some additional data from NBS Tables when no data is available for a specific property and species.
      • CREATE_ION_LIST: specify in the line below this keyword 1 (true) or 0 (false). If true, an IonList.dat file will be created which contains all ionic species (for ion mapping). All combinations of cations/anions will be used to add whole salt, acid, and base aqueous species to the species database. If false, ions will be added directly to the SysCAD database, usually using default thermochemical data for the liquid species (unless you have data for these ionic species and specify an appropriate source database.
      • The IonList.txt is created by executing the utility (if Create_Ion_List = 1 in Config.txt).
      • If no Config.txt file exists, all species are loaded unfiltered.
      • AQSOL_INSTALL_PARENT_FOLDER: specify in the line below the installation path where all of the AQSol DLLs are installed. The default location when AQSol is installed is c:\Program Files (x86)

How to use the Utility

The utility has two functions:

  1. assisting with the creation of IonList.txt.
  2. creating the SysCAD.93.db3 file.

Creating the Database

  1. Run SysCADAQSolUtils.exe
  2. The utility will ask for selection of a preferred database. Select the corresponding preferred database, or -1 if none is preferred. If -1 is selected, the user will manually select the data for each species where more than one option exists (see later step).
  3. Select the DLL file for which you wish to create a database. Select -1 to create files which incorporate all of the DLL files in the AQSol installation folder.
  4. Where a suitable species does not exist in the available SysCAD database source files, a placeholder species will be created with NO thermodynamic data.
  5. Upon completion, the utility will show a summary, confirming the database was created successfully. Press any key to close the utility.
    AQSol Utility - Create SysCAD.93.db3
NOTES:
  • If the species data does not exist in the reference SysCAD databases, then a place holder species with no thermodynamic or physical properties data will be used. When this happens, any project using this database will log appropriate warnings on load, look out for these species when Checking the Created SysCAD.93.db3
    In the above screenshot, we have 11 species using default (placeholder) data. In other words, 11 solid species have no thermodynamic data or physical properties data, and will use SysCAD default values when used in a project.
  • While running the utility, if you have NOT selected a preferred database (i.e. used -1 as selection) and multiple data is found for a species, you will be prompted to select one of the options:
    Select Species PHREEQC-AQSol.png
    In the above example, the utility has found 2 sets of data for “NaCl” in the available databases, we have selected data set 2 by typing in the "2".
    If a Cp range was specified using MIN_TEMP_CP and MAX_TEMP_CP, the utility may be able to select from multiple databases based upon maximum Cp range coverage. In this case, the prompt above would not be shown.
  • User can use <Ctrl+Z> to quit the utility at any time.

Checking the Created SysCAD.93.db3

Check the SysCAD.93.db3 file before copying it to your actual project's cfgfile folder. You can use any SQLite DB reader, such as DB Browser for SQLite. View the SpeciesData table to see the data. Species for which no data was found in the reference databases will appear as having each of the definition columns filled, but all of the property columns blank.

PlaceholderSpecies DBBrowser.png

In the above example, NaCl*2H2O is using placeholder data.

Copy the files to the CfgFiles folder

Generally speaking, user only need to use this Utility to generate the SysCAD.93.db3 file at the start of a new AQSol project group. Once the database has been created, the SysCAD.93.db3 file, as well as the associated AQSol Configuration file used to generate them, should be copied to the AQSol SysCAD project group\CfgFiles sub-folder. Note that SysCAD interface does not currently support more than one AQSol configuration file.

Updating the SysCAD Configuration

  1. Edit the SysCAD configuration
    1. Open SysCAD without a project open. Go to Edit->Project Configuration
    2. Edit the new configuration. Press "Next" on the Step 1 of 2 dialog.
    3. In the Step 2 of 2 dialog, go to the species tab, then add the required species to the project.
    4. Go to the TCEs tab
    5. Update the configuration for AQSol. See TCE Configuration Help Page for more information.

NOTES: To select ALL species for the project:

  • Select the first species in the middle column, hold shift, and select the last species in that column. This will select ALL species in the database.
  • Add all species to the project by pressing the "Add Species>>" button.

Creating a Test Project

You should now have a working SysCAD configuration file. The next step is to create a project and review the species properties.

  1. Create a new SysCAD project and select the newly created configuration. See Introductory Tutorial - Creating a SysCAD Project for more details.
  2. Once the project is open, review the species properties
    1. Go to Species->View Properties
    2. This brings up a window showing all data used for all species. More information on this window is here: Species Properties ($SDB). It is recommended to carefully review this to ensure it is correct.

Troubleshooting

Error Description Possible cause / suggested solution.
Utility Startup Errors Missing SysCAD Template species database (SysCAD.93.db3) The SysCAD.93.db3 file is missing from the Utility folder. This file is required as a starting point. User may copy any valid SysCAD.93.db3 file from the SysCADxxx folder here.
No SysCAD reference species database found in folder DB3Files The "DB3Files" folder is missing or empty. Please check the folder name and or make sure it contains at least one SysCAD database, such as the Default.93.db3
No DLLs found in specified folder where AQSol DLLs are installed Ensure that the appropriate version of AQSol is installed and ensure that AQSOL_INSTALL_PARENT_FOLDER is specified correctly in the Config.txt file.
Parent folder not specified for finding AQSol DLLs Ensure that AQSOL_INSTALL_PARENT_FOLDER is specified in the Config.txt file.

Recommended Procedure

The following steps are recommended in the creation of a new configuration to match a TCE database. These steps are applicable for all of the TCE packages (PHREEQC, AQSol, OLI, and ChemApp). Note that ChemApp requires an additional file, IPhaseMap.txt.

  1. Create a SysCAD database
    1. Extract the utility files to a folder of your choice
    2. Copy the TCE database file into the DatabaseFiles (CSTFiles for ChemApp) folder of that utility folder structure, e.g. for PHREEQC, this will be a DAT file, for OLI, this will be a DBS file, etc. This step is not applicable to AQSol.
    3. Update the settings in the Config.txt file.
    4. Run the utility to generate a database file.
  2. Create a SysCAD configuration
    1. Open SysCAD without a project open. Go to Edit->Project Configuration
    2. In the resulting dialog, create a new configuration. Give it a name of your choice. Press OK when done.
    3. Edit the newly created configuration. In the Step 1 of 2 dialog, enable the TCE interface that you are using, i.e. enable the ScdOLI2, ScdPHREEQC, ScdAQSol, or ScdChemApp dll. Press Next. Then press OK.
    4. Right click on the project configuration that you just created, select "Open Containing Folder" to open that folder in windows explorer.
    5. Copy the TCE database file into the new configuration, i.e. into the CfgFiles folder. This can be done using windows explorer. This could be a dat, dbs, or CST file. Note that there is no file associated with AQSol.
    6. Copy over the SysCAD93.db3 file generated (the SysCAD database), the IonList.txt file, and the IPhaseMap.txt file (if using ChemApp).
  3. Edit the SysCAD configuration
    1. Open SysCAD without a project open. Go to Edit->Project Configuration
    2. Edit the new configuration. Press "Next" on the Step 1 of 2 dialog.
    3. In the Step 2 of 2 dialog, go to the species tab, select the first species in the middle column, hold shift, and select the last species in that column
    4. Add all species to the project by pressing the "Add Species>>" button
    5. Go to the TCEs tab
    6. Update the configuration for the TCE you are using, see TCE Configuration Help Page for more information.

You should now have a working SysCAD configuration file. The next step is to create a project and review the species properties.

  1. Create a new SysCAD project and select the newly created configuration. See Introductory Tutorial - Creating a SysCAD Project for more details.
  2. Once the project is open, review the species properties
    1. Go to Species->View Properties
    2. This brings up a window showing all data used for all species. More information on this window is here: Species Properties ($SDB). It is recommended to carefully review this to ensure it is correct.
Retrieved from "https://help.syscad.net/index.php?title=AQSol_Database_Utility&oldid=80690"