PHREEQC Model Configuration
Jump to navigation
Jump to search
Navigation: Models -> TPS Models -> PHREEQC Models -> PHREEQC Model Configuration
| PHREEQC Overview | PHREEQC Model Configuration | PHREEQC Direct Calc Model | PHREEQC Side Calc Model | PHREEQC Reactor |
|---|
New for Build 138. Currently in BETA - contact SysCAD for demonstrations or further information.
Contents
General Description
PHREEQC is a computer program that is designed to perform a wide variety of aqueous geochemical calculations. It is developed and maintained by the United States Geological Survey. See wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc for further information.
This model allows the user to define the PHREEQC database file to be used in SysCAD and some configuration of its use. The two main functions are to select a PHREEQC Database File (*.dat) provided as part of PHREEQC installation; and then for the selected Database file 'map' PHREEQC species/ions to SysCAD species/ions used in the project. This allows the other PHREEQC models in SysCAD to convert the SysCAD species flow data to PHREEQC species data (and vice-versa) and use the PHREEQC functionality to calculate aqueous equilibrium data.
The model does not do any calculations and has no process links to any other models in SysCAD flowsheets. Its sole purpose is for management and configuration of a selected PHREEQC Database, other unit models performing PHREEQC calculations will reference this model. Therefore, this model is essential if the user wishes to use the PHREEQC functionality in SysCAD.
The user must have a PHREEQC Database file before initialising the SysCAD PHREEQC Model Configuration. See Referenced File for instructions on where to find this file.
NB The user MUST have installed a version of PHREEQC on their computer. Please see wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc for more information.
Referenced File
The file that will be referenced by the SysCAD PHREEQC Model Configuration is the PHREEQC Database file which is provided as part of the PHREEQC installation, e.g. phreeqc.dat.
Sample database files are stored in the database subfolder of the PHREEQC installation. Typical path is C:\Program Files\USGS\Phreeqc Interactive X.Y.Z-NNNNN\database.
Notes:
- This file is essential for the PHREEQC functionality to work in SysCAD.
- The file can be saved at any location - it does not have to be saved in the SysCAD project.
Diagram
The diagram shows the default drawing of a PHREEQC Model Configuration unit model.
Inputs and Outputs
There are no connections to this unit.
Model Theory
PHREEQC requires a defined input stream which defines almost all species in ionic form (no phase). At the given conditions (temperature, pressure), PHREEQC returns an output stream which includes aqueous ions in solution and any precipitates (solids) as species.
The PHREEQC Model Configuration defines the mapping of SysCAD species to PHREEQC ions/species to define the required input stream, and the convert the PHREEQC output stream back to SysCAD species.
The PHREEQC implementation allows for inclusion of adsorption calculations in addition to precipitation. The PHREEQC Model Configuration allows for specification of hydrous ferric oxide precipitates, which are used to calculate the total amount of HFO moles for adsorption calculations.
Notes:
- Some automatic mapping functions are available to match species based on molecular weights and elements.
- Users can also manually adjust the mappings by selecting matching ions/species from dropdown lists.
- Where more than one ionic breakdown reactions is available for a SysCAD species (defined in IonList.txt), the user can choose which one or combination to use.
- SysCAD species can be selected to bypass the PHREEQC calculations by excluding them from the defined PHREEQC input stream.
- PHREEQC solid and gaseous species can also be excluded from being formed as part of the PHREEQC output stream.
- Ion definitions are provided in IonList.txt. These are used to calculate SysCAD species breakdowns.
Workflow
The suggested workflow for configuring the model is:
- On the PHREEQCModelCfg tab page, browse for required .dat file.
- On the PHREEQCModelCfg tab page, press the Load button to load the .dat file.
- Map the PHREEQC ions and species to SysCAD ions and species on the PHREEQCConfig tab page. The simplest way to do this is to press the Try Map Species button next to MapByElements on the PHREEQCConfig tab page.
- Make any required adjustments to the SatIndex on the PHREEQCConfig tab page.
- If required, set the species conversion Algorithm on the AppSpRebuild tab page.
- If required, make any adjustments to the selection of Ion Breakdown reactions on the IonicBreakdown tab page.
Once these steps are performed and the mappings are checked, the project can be run. Any PHREEQC Direct Calc Models, PHREEQC Side Calc Models or PHREEQC Reactors referencing this PHREEQC Model Configuration unit model will use the mappings defined.
Data Sections
The tabs and variable names are described in detail in the following tables.
- PHREEQCModelCfg tab - This first tab requires the user select the PHREEQC database file and has various related options and parameters.
- PHREEQCConfig tab - This tab requires the user to map the PHREEQC ions/species to the equivalent species/ions in SysCAD, so that PHREEQC stream compositions can be converted to a SysCAD stream and vice-versa.
- ScdSpMap tab - This tab reports the SysCAD to PHREEQC species mapping as a result of choices made on the PHREEQCConfig tab page, so the SysCAD stream composition can be converted to a PHREEQC stream.
- ScdIonMap tab - This tab reports the SysCAD to PHREEQC ion mapping as a result of choices made on the PHREEQCConfig tab page, so the SysCAD stream composition can be converted to a PHREEQC stream.
- AppSpRebuild tab - This tab allows the user to select the species conversion algorithm used when converting PHREEQC species back to SysCAD species.
- IonicBreakdown tab - This tab lists the Ion Breakdown reactions for SysCAD species and allows the user to select which ones to use.
- Engines tab - This tab contains information about the PHREEQC Engines.
- Info tab - contains general settings for the unit and allows the user to include documentation about the unit and create Hyperlinks to external documents.
PHREEQC Model Configuration tab page
Unit Type: PHREEQCModelCfg - The first tab page in the access window will have this name.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| Tag | Display | This name tag may be modified with the change tag option. |
| Condition | Display | OK if no errors/warnings, otherwise lists errors/warnings. |
| ConditionCount | Display | The current number of errors/warnings. If condition is OK, returns 0. |
| GeneralDescription / GenDesc | Display | This is an automatically generated description for the unit. If the user has entered text in the 'EqpDesc' field on the Info tab (see below), this will be displayed here. If this field is blank, then:
|
| ======== BETA VERSION ======== This program contains PHREEQC Copyright U.S. Geological Survey (USGS) | ||
| Interface... | ||
| Acknowledgement | Display | This program contains PHREEQC Copyright U.S. Geological Survey (USGS) |
| Website | Web Link | //https://www.usgs.gov/software/phreeqc |
| Version | Display | This displays the version of PHREEQC installed on the user's computer |
| Model... | ||
| Select PHREEQC database file | ||
| FileName | Input | This is the name of the database file that was created by PHREEQC, e.g. phreeqc.dat |
| Folder | Display | The folder where the database file shown above is saved. |
| Browse |  |
Click on this button to browse to the required database file. |
| CheckSpListForDuplicates | Tickbox | If enabled this will check the PHREEQC species list for duplicates. |
| Load |   |
Click on this button to load the required database file. If the model has not been initialised, then the button will show "Init and Load" and when pressed the model will first be initialised and then the database file will be loaded. |
| DefnStatus | List | If the PHREEQC database file has been loaded and no errors have been detected then will show OK, otherwise will show error message. |
| SpDBCount | Display | The number of species loaded from the PHREEQC database file. |
| Sol.Count | Display | The number of solid species loaded from the PHREEQC database file. |
| Liq.Count | Display | The number of liquid species loaded from the PHREEQC database file. |
| Vap.Count | Display | The number of gaseous species loaded from the PHREEQC database file. |
| ElemCount | Display | The number of elements loaded from the PHREEQC database file. |
| ElemList | Display | The list of the elements used in the PHREEQC database file. |
| Mapping Tolerances | ||
| Discard.Tol.SigDigits | Input | This provides an easy way to change the Discard.Tol.Rel value. For example, 4 here will set 1.00e-4 to Discard.Tol.Rel. If user changes the Discard.Tol.Rel value, this value will also be updated. |
| Discard.Tol.Rel | Input | The relative tolerance for ignoring species produced from the PHREEQC calculations. If the mass fraction of a species is > DiscardTol and it is not mapped to a SysCAD species/ion then an error is generated. |
| Convergence Tolerances | ||
| ElemBal.Tol.SigDigits | Input | This provides an easy way to change the ElemBal.Tol.Rel value. For example, 4 here will set 1.00e-4 to ElemBal.Tol.Rel. If user changes the ElemBal.Tol.Rel value, this value will also be updated. |
| ElemBal.Tol.Rel | Input | The relative tolerance for Element Balance (Input - Output). If the relative error is > ElemBal.Tol.Rel then an error is generated. The ElemBal is used in PHREEQC Side Calc Model and PHREEQC Reactor. |
| EnthConv.Tol.SigDigits | Input | This provides an easy way to change the EnthConv.Tol.Rel value. For example, 4 here will set 1.00e-4 to EnthConv.Tol.Rel. If user changes the EnthConv.Tol.Rel value, this value will also be updated. |
| EnthConv.Tol.Rel | Input | Enthalpy convergence tolerance. This is used for iterative enthalpy convergence calculations in SysCAD. |
| Water adjustment tolerance | ||
| WaterAdjust.Tol.SigDigits | Input | This provides an easy way to change the WaterAdjust.Tol.Rel value. For example, 4 here will set 1.00e-4 to WaterAdjust.Tol.Rel. If user changes the WaterAdjust.Tol.Rel value, this value will also be updated. |
| WaterAdjust.Tol.Rel | Input | The relative tolerance for water adjustment. If the relative error is > WaterAdjust.Tol.Rel then an error is generated. |
| Adsorption | ||
| Adsorption.IncludeCalcs | Tickbox | If ticked additional fields will be shown on this tab and the PHREEQCConfig tab page. These are parameters for the diffuse layer model of Dzombak and Morel (1990), used for multicomponent adsorption. |
| Adsorption.MolesStrongPerMoleFe / Hfo_sPerFe | Input | Only visible if Adsorption.IncludeCalcs has been enabled. Default values are from Dzombak and Morel (1990). |
| Adsorption.MolesWeakPerMoleFe / Hfo_wPerFe | Input | Only visible if Adsorption.IncludeCalcs has been enabled. Default values are from Dzombak and Morel (1990). |
| Adsorption.SpecificSurfaceArea / SSA_Sorption | Input | Only visible if Adsorption.IncludeCalcs has been enabled. The specific surface area in metres squared per mole of Fe. Default values are from Dzombak and Morel (1990). |
| Select equilibrium model to use / Equilibrium model used was specified in database | ||
| (Depending on the PHREEQC database file chosen, the user may or may not have a choice of equilibrium models. eg. if using 'pitzer.dat', 'Pitzer' equilibrium model will be used.) | ||
| EquilibriumModel | Davies | Use the Davies equilibrium model to perform equilibrium calculations. |
| Pitzer | Use the Pitzer equilibrium model to perform equilibrium calculations. | |
| SIT | Use the SIT (Specific ion Interaction Theory) equilibrium model to perform equilibrium calculations. | |
PHREEQC Config tab page
This tab is used to map the PHREEQC species/ions to the SysCAD species/ions. There are usually more PHREEQC solid species than there are solid species in the SysCAD project.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| PHREEQCConfig... | ||
| SpeciesName |   |
The Species:Long or Short button is used to change the display of the Species names between the Short form, the Chemical compound, or the longer species names. |
| Map PHREEQC species/ions to SysCAD species/ions | ||
| MapByMW |  |
This will try to map the PHREEQC species/ions to the SysCAD species/ions based on their Molecular Weights. |
| CheckMapByMW |  |
This will check the mapping of the PHREEQC species/ions to the SysCAD species/ions based on their Molecular Weights. Any unexpected results in the current mappings will be displayed as warnings in the Messages Window. |
| MapByElements | |
This will try to map the PHREEQC species/ions to the SysCAD species/ions based on their Elemental compositions. This is the recommended option. |
| CheckMapByElements | |
This will check the mapping of the PHREEQC species/ions to the SysCAD species/ions based on their Elemental compositions. Any unexpected results in the current mappings will be displayed as warnings in the Messages Window. |
| MaximumMWDiff / MaxMWDiff | Input | This is the maximum allowed difference between molecular weights of mapped species without generating a warning. |
| MaximumChargeDiff / MaxChargeDiff | Input | This is the maximum allowed charge difference between mapped species without generating a warning. |
| SpDBCount | Display | The number of species/ions defined in the PHREEQC database. |
| SpUsedCount | Display | The number of species/ions in the PHREEQC database that are used in the project. These are shown on the PHREEQCConfig tab page. |
| SpMappedCount | Display | The number of species/ions in the PHREEQC database that have been mapped to equivalent SysCAD species/ions. |
| SpCFECount | Display | The number of species/ions in the PHREEQC database that can be used with CFE (constrained free energy). |
| DetailedGridView | Tickbox | Global selection. If enabled, more fields will be shown in grid views (tables) including the tables on this page. |
| Filter View | ||
| Filter |   |
This button will enable or disable the species filter options. |
| ShowUnmapped (Only visible if Filter is enabled) |
Tickbox | When enabled, all species will be displayed. When disabled, only species that are mapped to a SysCAD species will be shown. |
| Phases (Only visible if Filter is enabled) |
All | No filtering of species based on phase. |
| Solids | Only show solid phase species, hide other species. | |
| Liquids | Only show liquid phase species, hide other species. | |
| Vapours | Only show vapour (gaseous) phase species, hide other species. | |
| Solids & Liquids | Only show solid and liquid phase species, hide other species. | |
| Solids & Vapours | Only show solid and vapour (gaseous) phase species, hide other species. | |
| Liquids & Vapours | Only show liquid and vapour (gaseous) phase species, hide other species. | |
| Aqueous | Only show aqueous individual phase species, hide other species. | |
| Solid | Only show solid individual phase species, hide other species. | |
| Exchange | Only show exchange individual phase species, hide other species. | |
| Surface | Only show surface individual phase species, hide other species. | |
| Gas | Only show gas individual phase species, hide other species. | |
| Filters | Display | Always set to 'Content'. |
| Content (Only visible if Filter is enabled) |
All | No filtering of species based on element or name. |
| Contains Any Element | This will display all species that contain any of the elements entered in their elemental definition. | |
| Contains All Elements | This will display only species that contain ALL of the elements entered in their elemental definition. | |
| Starts with ... | This will display species that start with the text entered based on the short or long species tag depending on the current SpeciesTag selection. | |
| Contains any ... | This will display species that contain the text entered in the currently displayed short or long species tag. | |
| Contains All ... | This will display species that contain ALL the separate text entered in the currently displayed short or long species tag. | |
| Select | Input | Only visible if Filter is enabled and Content is NOT set to All. The user specified Elements or text to filter the species list. Refer to Species Filter for more information and examples. |
| (The following tables (one per phase) display the PHREEQC species/ions from the selected database and the mapped SysCAD species/ions. The user can choose, or change, the mapped SysCAD species/ions using the dropdown list.) (Each table has the following columns (one row per PHREEQC species/ion):) | ||
| SatIdx | Input | The user specified Saturation Index of the PHREEQC species. This is only available for solid and gas species. |
| MoleWt | Display | The Molecular Weight of the PHREEQC species/ion. |
| Charge | Display | Only shown if DetailedGridView has been enabled. The electrical charge of the PHREEQC species/ion. |
| IsCFE | Display | Only shown if DetailedGridView has been enabled. 1 = species can be used for CFE (constrained free energy), thus allows a portion of a species to be locked up and not allowed to react. |
| Index | Display | Only shown if DetailedGridView has been enabled. The index of the PHREEQC species/ion. |
| MappedIon | List | The user may select the most appropriate SysCAD ion from a dropdown list to map to the PHREEQC ion. The relationship between ions and species in SysCAD is defined on the IonicBreakdown tab page. It is expected that PHREEQC ions would be mapped to SysCAD ions. This column is not shown for solid and gas species. |
| MappedSpecies | List | The user may select the most appropriate SysCAD species from a dropdown list to map to the PHREEQC species. |
| MapSpByEl | Button | Only shown if DetailedGridView has been enabled. If pressed, SysCAD will try to find the most appropriate SysCAD species to map to this PHREEQC species by matching elemental compositions. |
| MapSpByMW | Button | Only shown if DetailedGridView has been enabled. If pressed, SysCAD will try to find the most appropriate SysCAD species to map to this PHREEQC species by matching molecular weights. |
ScdSpMap tab page
This tab is used to display the mapping of SysCAD species to PHREEQC species. This is often a 1 to 1 mapping.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| SysCAD to PHREEQC mapping | ||
| ScdSpMap... | ||
| (The following table displays all the SysCAD species in the project with its mapped PHREEQC species (if there is one).) (The table has the following columns (one row per SysCAD species):) | ||
| Mapping | Display | The name of the first mapped PHREEQC species (if there is one). |
| MapType | Direct | There is an exact match of species between "SysCAD species database/cfg file" and the loaded PHREEQC database, and the species is allowed by the license option and mapped directly on the PHREEQCConfig page. |
| Ions | The species is not mapped on the PHREEQCConfig page, but can be broken down to valid ions (ionlist.txt). | |
| Unmapped | Species exist in the loaded PHREEQC database, but not in the "SysCAD species database/cfg file". User may consider adding the species to the SysCAD database if it is required. | |
| Unlicensed | There is an exact match of species between "SysCAD species database/cfg file" and the loaded PHREEQC database, but the species is not allowed by the license option. | |
| MapCount | Display | The number of PHREEQC species that are mapped to the relevant SysCAD species. |
| MW_Diff | Display | The difference in Molecular Weights between the SysCAD species and the first mapped PHREEQC species (shown in the name column). |
ScdIonMap tab page
This tab is used to display the mapping of SysCAD ions to PHREEQC ions. This is usually a 1 to 1 mapping.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| SysCAD Ions to PHREEQC mapping | ||
| ScdIonMap... | ||
| (The following table displays all the SysCAD ions in the project with its mapped PHREEQC ion (if there is one).) (The table has the following columns (one row per SysCAD ion):) | ||
| Name | Display | The name of the mapped PHREEQC ion (if there is one). |
| MW_Diff | Display | The difference in Molecular Weights between the SysCAD ion and the the mapped PHREEQC ion (shown in the name column). |
| CalcFormableSp | Tickbox | If selected, SysCAD will show the SysCAD molecular species that can be formed from the selected ions. |
| (The following fields are only shown if the CalcFormableSp option has been enabled for at least one ion. | ||
| Selected Ions: | ||
| x formable species from y selected ions | ||
| Formable... | ||
| SpX | Display | The name of a SysCAD molecular species that can be formed from one or more of the selected ions. |
AppSpRebuild tab page
This set the species conversion Algorithm for reverse mapping, see Species Mapping for more information.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| Select Options for building SysCAD apparent species from ions | ||
| SelectAlgorithm | SimpleExtent | Species are built in order of reaction extent, with no regard for if they are acids, bases, or salts. |
| SaltsFirst | Salts are built preferentially. Remaining form acids and bases. Each group is built in order of reaction extent. Recommended in most cases. | |
IonicBreakdown tab page
This tab displays the Ion Breakdown reaction for the SysCAD species. These are defined in the IonList.txt file, normally located in C:\SysCAD138\BaseFiles folder. Where more than one reaction has been defined for a species, the user can choose how to split the species between the different reactions.
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| IBR... | ||
| Ion Breakdown Reactions for Species | ||
| The following table displays all the SysCAD species in the project with their Ion Breakdown reaction/s. The table has one row per breakdown reaction | ||
| CopyToClipboard | Species | Pressing the CopyToClipboard button and select Species will copy the ion breakdown for all species. (top table) |
| SpeciesAndIons | Pressing the CopyToClipboard button and select Species and Ions will copy the ion breakdown for species and Ions, including further breakdown of larger Ions. | |
| Ion Breakdown reactions | Display | The relevant SysCAD species that is assumed to breakdown as per the specified reaction. |
| Ion Breakdown Reactions for Larger Ions | ||
| (The following table displays all the complex ions in the project (if any) with their Ion Breakdown reaction/s to simpler ions.) | ||
| Ion Breakdown reactions | Display | The relevant SysCAD species that is assumed to breakdown as per the specified reaction. |
Engines tab page
| Tag (Long/Short) | Input / Calc | Description/Calculated Variables / Options |
| Status | OK | The model has been initialised correctly and the database file has been found and loaded correctly. |
| Init Required | The model needs to be initialised. | |
| Init Failed | The model initialisation has been attempted but failed. | |
| Not installed | ||
| Wrong Version | ||
| Reload |  |
|
| InitTime | Display | The time taken to initialise the model on the last attempt. |
| TotalCalcCount | Display | The number of calculations that have been performed mapping the PHREEQC species data to the SysCAD species data. The mappings are required for other units such as the PHREEQC Direct Calc Model, PHREEQC Side Calc Model or PHREEQC Reactor . This is cumulative and may include multiple iterations. It is reset to zero at the beginning of a run. |
| TotalCalcTime | Display | The cumulative amount of time used to map the PHREEQC species to the SysCAD species. This is cumulative and may include multiple runs. |
| AverageCalcTime | Display | The average amount of time required to map the PHREEQC species to the SysCAD species for this unit. AverageCalcTime = TotalCalcTime/TotalCalcCount. |
| TotalReloadCount | Display | |
| TotalReloadTime | Display | |
| AverageReloadTime | Display | |
| TotalWaitTime | Display | |
| (Times that Engine instances are locked. The following parameters are shown for 5 PHREEQC Engines:) | ||
| EngineX | Display | The Engine number (X) of the Engine starting at 1. |
| TimeLocked | Display | The time that the relevant Engine is locked. |
| Status | OK | The model has been initialised correctly and the database file has been found and loaded correctly. |
| Init Required | The model needs to be initialised. | |
| Init Failed | The model initialisation has been attempted but failed. | |
| Not installed | ||
| Wrong Version | ||
Adding this Model to a Project
Insert into Configuration file
Sort either by DLL or Group.
|
|
DLL: |
ScdPHREEQC.dll |
→ |
Units/Links |
→ |
PHREEQC: PHREEQC Chem Model Configuration |
|
or |
Group: |
General |
→ |
Units/Links |
→ |
PHREEQC: PHREEQC Chem Model Configuration |
See Project Configuration for more information on adding models to the configuration file.
Insert into Project
|
|
Insert Unit |
→ |
PHREEQC |
→ |
PHREEQC Chem Model Configuration |
See Insert Unit for general information on inserting units.
