View source for PHREEQC Model Configuration

[[Category: PHREEQC]] [[Category:Models]]
{{Navigation | [[Models]] |[[Models#Thermodynamic Calculation Engines|TCE Models]]| [[PHREEQC Overview|PHREEQC]]}}
{{PHREEQC Header Tabs | currentpage = 3}}

'''Related Links:''' [[PHREEQC_Overview#PHREEQC_SysCAD_Project_Workflow|PHREEQC SysCAD Project Workflow]]
----
{{TPS General Notes|PHREEQC }} 
{{TOC}}
== 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 [https://www.usgs.gov/software/phreeqc-version-3 https://www.usgs.gov/software/phreeqc-version-3] 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|Referenced File]] for instructions on where to find this file.

'''NB''' The user may install a version of PHREEQC on their computer if they wish, but it is not required to use the PHREEQC functionality in SysCAD.  Please see [https://www.usgs.gov/software/phreeqc-version-3 https://www.usgs.gov/software/phreeqc-version-3] for more information.

=== Demonstration Version ===

SysCAD includes a demonstration version of PHREEQC.  Using demo mode, demonstration projects for can be run and modified by the user.  However, this usage is restricted to the Ca-S-O-H system.  To turn off demonstration mode (for users with full PHREEQC add-on licenses), uncheck the ''Use Demo Version'' option in [[TCE Configuration]].

=== 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 ===

[[Image:TPS Model Cfg.png|50 px]]

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 precipitates which form specific surface types for adsorption, which are then used to calculate the total moles of surface sites and total surface area for adsorption calculations.

A diagram is provided below to explain the mapping process.  Red lines represent the mapping criteria.

[[Image:PHREEQCMappingDigram.PNG]]

'''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. If ions for a particular database file are missing, they can be added by pressing the [[Image:AddtoIonListButton.png]] on the [[#PHREEQC_Config_tab_page|PHREEQCConfig]] tab page The project must be reloaded before the added ions can be mapped.

=== Adsorption === 
* Adsorption is an advanced topic and requires specialized knowledge to implement correctly.  The assumptions and limitations of the selected PHREEQC database for adsorption calculations must be understood by the user.
* The user is advised to review the implementation of adsorption in PHREEQC by referring to the PHREEQC manual, available for download along with the software and databases here: [https://www.usgs.gov/software/phreeqc-version-3 https://www.usgs.gov/software/phreeqc-version-3]
* Specific databases, such as the minteq database, have additional documentation specific to the adsorption model.  For example, the minteq database adsorption model documentation can be found here: [https://www.epa.gov/sites/default/files/documents/USERMANU.PDF https://www.epa.gov/sites/default/files/documents/USERMANU.PDF]
* In specification of surface reactions in the PHREEQC database, please ensure that the surface type is specified with an underscore in its name, i.e. HFO_wOH, Alumina_sOH, etc., etc.
* Adsorption species in SysCAD are treated as "fictitious species".  They are created based upon the total mass/moles of identified species that generate surface adsorption sites. 
* SysCAD supports the implementation of both strong and weak adsorption sites, in line with PHREEQC modelling capabilities
* Adsorption includes multiple surface types.  (Note that in Build138 beta, only hydrous ferric oxide adsorption was implemented.)

== Workflow ==

{{TPS ModelCfg Workflow|TPS=PHREEQC|speciestypes=ions and species|databasefile=.dat|SatIndex=Yes|Suppression=No|IonsPresent=Yes}}

== Data Sections ==

The tabs and variable names are described in detail in the following tables.

# '''[[#PHREEQC Model Configuration tab page|PHREEQCModelCfg]]''' tab - This first tab requires the user select the PHREEQC database file and has various related options and parameters.
# '''[[#PHREEQC Config tab page|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 page|ScdSpMap]]''' tab - This tab reports the SysCAD to PHREEQC species mapping as a result of choices made on the '''[[#PHREEQC Config tab page|PHREEQCConfig]]''' tab page, so the SysCAD stream composition can be converted to a PHREEQC stream.
# '''[[#ScdIonMap tab page|ScdIonMap]]''' tab - This tab reports the SysCAD to PHREEQC ion mapping as a result of choices made on the '''[[#PHREEQC Config tab page|PHREEQCConfig]]''' tab page, so the SysCAD stream composition can be converted to a PHREEQC stream.
# '''[[#IonicBreakdown tab page|IonicBreakdown]]''' tab - This tab lists the Ion Breakdown reactions for SysCAD species and allows the user to select which ones to use.
# '''[[#LogKAdjust tab page|LogKAdjust]]''' tab - Optional tab, only visible if the ''ShowLogKTuning'' option is enabled on the [[#PHREEQC Model Configuration tab page|PHREEQCModelCfg]] tab. Enables entry of LogK values directly in SysCAD.
# '''[[#UsedBy tab page|UsedBy]]''' tab - This tab displays the PHREEQC model units referencing to this PHREEQC Model configuration unit.
# '''[[#Engines tab page|Engines]]''' tab - This tab contains information about the PHREEQC Engines.
# '''[[Common Data Sections#Common Data on Info Tab Page|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 ===

{{TPSModelCfg Tab Page | TPS=PHREEQC | example DB=phreeqc.dat|CheckDuplicates=true|AcidBase=true}}
|  colspan="3" font style="background: #ebebeb"    | ''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.  
|-
|  colspan="3" font style="background: #ebebeb"    | ''Adsorption'' (see also [[#Adsorption|Model Theory - Adsorption]])
|- 
| Adsorption.IncludeCalcs || Tickbox || If ticked additional fields will be shown on this tab and the [[#PHREEQC Config tab page|PHREEQCConfig]] tab page. These are parameters for the diffuse layer model of Dzombak and Morel (1990), used for multicomponent adsorption.  Default values for model parameters are taken from Dzombak and Morel (1990) for adsorption to hydrous ferric oxide.
|- 
|  colspan="3" font style="background: #ebebeb"    | Surf1...  (NOTE: the Adsorption fields below are displayed for each SURFACE species in the PHREEQC database file being used, so next section would be Surf2, Surf3, and so on.)
|- 
| Adsorption.MolesStrongPerMoleElem / X_sPerElem || Input || Only visible if ''Adsorption.IncludeCalcs'' has been enabled.  Default values are from Dzombak and Morel (1990) and should be changed with care.
|-
| Adsorption.MolesWeakPerMoleElem / X_wPerElem || Input || Only visible if ''Adsorption.IncludeCalcs'' has been enabled.  Default values are from Dzombak and Morel (1990) and should be changed with care.  PHREEQC databases assume these values in the specification of logK for surface reactions (see PHREEQC manual).
|-
| 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) and should be changed with care.  PHREEQC databases assume these values in the specification of logK for surface reactions (see PHREEQC manual).
|-
| Adsorption.KeyElement / Key.Elem|| List|| Only visible if ''Adsorption.IncludeCalcs'' has been enabled. The key element can be selected from a dropdown list.
|}

=== PHREEQC Config tab page ===

{{TPSConfig Tab Page|TPS=PHREEQC|speciestypes=species/ions|MapByMW=true|IncludeSuppress=No|Includelog10SatIdx=Yes|IncludeCFE=Yes|IncludeIons=Yes}}
|}

=== ScdSpMap tab page ===

{{TPSScdSpMap Tab Page|TPS=PHREEQC|IncludeMapType=Yes|IncludeSelect=Yes}}

=== ScdIonMap tab page ===

{{TPSScdIonMap Tab Page|TPS=PHREEQC}}

=== IonicBreakdown tab page ===

{{TPS IonicBreakdown Tab Page}}
NOTE:
The species listed on this page are determined by the phase selection in the "[[#PHREEQC_Config_tab_page|PHREEQC Config tab page]] - FwdIonMap.PhasesAllowed" option.

=== LogKAdjust tab page ===

{{Available139}} Only displayed if the ''ShowLogKTuning'' option is enabled on the first tab page. This allows the user to enter estimated LogK values directly into SysCAD. This can be done for a range of temperatures but the user must then develop the LogK(T) correlations for implementation in the PHREEQC database.

{|   border="1" cellpadding="5" cellspacing="0" 
| '''Tag (Long/Short)''' || '''Input / Calc''' || '''Description/Calculated Variables / Options'''
|-
| Contains || Input || Filter parameter to narrow down list of reactions shown to a single species/ion.
|-
| WriteToDB|| [[Image:WriteToDB Button.png]]|| This will write the entered LogK values to the database file, making any changes permanent. '''WARNING:''' This action can not be undone.
|-
| colspan="3" font style="background: #ebebeb" | Mod_LogK...
|-
| colspan="3" font style="background: #ebebeb" | (The table has the following columns (one row per reaction):)
|-
| Reaction|| style="background: #ebebeb" | Display || Chemical reaction as listed in the PHREEQC database.
|-
| LogK|| Input || Desired LogK value for given reaction. Values entered here will be used in the project but will not be permanent changes unless the ''WriteToDB'' button is pressed.
|-
|}

=== UsedBy tab page ===

{{TPS ConnectedUnits Tab Page|TPS=PHREEQC}}

=== Engines tab page ===

{{TPS Engines Tab Page|TPS=PHREEQC}}

== Adding this Model to a Project ==

{{TPS Add Model|TPS =PHREEQC|UnitOp=Chem Model Configuration|Group=General}}