Thermodynamic dataset editor

TEdit is a graphical editor in the GWB for creating and modifying thermodynamic and surface reaction datasets.


Getting started

Opening TEdit
Click on TEdit in the GWB dashboard or double-click any “.tdat” or “.sdat” file.

Load a datset
Go to File → Open… and browse to open a dataset, or drag any “.tdat” or “.sdat” file (or “.dat”, for very old datasets) from your Desktop or File Explorer into TEdit

Navigate the datset
Click to expand any section, then click on any species to view it.

Summary of entries
Click on a section header to see a list of entries, their properties, or reactions.

The “Minerals” section, shown below, displays a list of the minerals in “thermo.tdat” in a condensed view

Double-click on an entry to go to its editing pane. Use the Add, Delete, and Extract buttons to add or remove entries from the dataset, as described below, or use the various right-click options.

Change the pulldown from “List” to “Details” to see properties of the entries

or “Reactions” to see their reactions and log K values at 25°C

In any case, you can use the “element” pulldown or “match” box to limit the entries shown in the list. In the screenshot above, “alb” was typed into the “match” box to compare the stability of albite with its polymorphs.

You can also change the pulldown to “Redox reactions” to see only oxidation-reduction reactions, as described below.

Filter by composition
Right-click on an entry, then click Apply Filter.

For example, to filter on the element carbon, right-click on “C” and choose Apply Filter

The tree will show only those species containing carbon

To filter on inorganic carbon only, choose the basis entry “HCO3−”. You can apply the filter from the tree, as before, or from the “Basis species” section header pane

In this case, the tree only lists inorganic carbon species.

To include additional oxidation states, check “Follow redox couples” before applying the filter

Search
Go to Edit → Find…, then type in your search string.

For example, to find goethite in the dataset, type into the box labeled “Find:”

then double-click on the search result to open the entry.

As a second example, you might search for minerals labeled “feldspar” for “Mineral type”

You can uncheck options under “Sections” or “Search fields” as desired to limit the search results.


Editing a thermo dataset

Add an entry
Click on a section header (e.g. “Minerals”), then right-click → Add to create a new entry.

To add the complex dissociation reaction FeCl3(aq) = FeCl2+ + Cl to “thermo.tdat”, right-click on “Aqueous species” (or any species within that section) and choose Add.

In the blank pane that opens, type “FeCl3(aq)” as the species name. Set the mole weight to “162.206” and the ion size to “4”

Under “Species in reaction”, click add then change the pulldown to show “All Aqueous species”

Double-click the species “FeCl2+”, or select it then hit the Enter key or click Add. Note, you can type to move your cursor to the first species beginning with that sequence. Continue by adding “Cl-” as well, then close the dialog.

Set a reaction coefficient of “1” for each (a negative coefficient would add a species to the left side of the reaction) and enter the log K value at one or more temperatures

Delete an entry
Click on the entry to delete, then tap the Delete key.

You can make your selections from the tree, or from each section header pane

A popup dialog will appear listing the chosen species, along with any dependent species. For example, if you delete the redox species “Fe+++”, all ferric iron species and minerals will also be deleted

You may choose “OK” to delete all the species, or “Cancel” to retain them.

Extract entries
Click on the entries to keep, then right-click → Extract.

For example, you could use the “Extract” functionality to cut “thermo.tdat” down to a simple set of reactions for calculating carbonate speciation and mineral saturation in the presence of calcium. To do so, go to the “Basis species” section header, select “Ca++”, “H+”, “H2O”, and “HCO3-”, then click Extract

A popup dialog will appear listing the species to be deleted. In this case, we'll delete the other 43 basis species, along with all reactions that depend on them.

You may choose “OK” to delete all the species, or “Cancel” to retain them.

Expanding the sections in the tree, we see a concise dataset. A summary of the reactions for all secondary aqueous species is shown below.

Copy an entry
Select an entry on the tree, then right-click → Copy to copy it to the clipboard.

To copy cadmium species into thermo.tdat, for example, open a dataset like thermo.com.V8.R6+.tdat and hold Ctrl while you select the element “Cd”, the basis species “Cd++”, and other species or minerals of interest (we've applied a filter to make this easier), then right-click one of them and select Copy (Ctrl+C) to copy them to the clipboard.

TEdit keeps track of each species type, so you need only open your target dataset, click anywhere on the tree, and select Edit → Paste (Ctrl+V) to transfer the entry

You can similarly drag one or more selected entries to transfer them to another dataset.

Note, every entry must be fully defined in the target dataset for it to be transferred. You cannot add the basis species “Cd++” without first adding the element “Cd”, for example, and you won't be able to add a complex like “Cd(For)+” to a datset without first adding “Formic_acid(aq)”.

Move an entry
To move the phthalate redox species in “thermo.tdat” to be with the other carbon species acetate and methane, for example, select the species

To move the phthalate redox species in “thermo.tdat” to be with the other carbon species acetate and methane, for example, select the species

then hold the left mouse button and drag it down below “CH4(aq)”, then release


Rebalancing reactions

Rebalance a reaction
Click the swap button next to a species, then choose the species to replace it with.

To rebalance the mineral calcite in terms of the carbonate ion, rather than the basis species bicarbonate, click the swap button next to “HCO3-”, then choose Aqueous… → “CO3--”

The reaction to swap out “HCO3-” for “CO3--” will be shown between the original and resulting reactions, and the log K values will similarly be displayed in separate rows

Click apply to accept the rebalanced reaction.

Reduce a reaction to the set of basis and redox species
Click the reduce pulldown button, then choose reduce to basis or reduce to redox and basis.

The redox coupling reaction for Np+++ in “thermo_sit.tdat” is written as a half-cell reaction in terms of redox species Np++++ and the free electron

To recast it in terms of O2(aq), click reduce → Reduce to redox and basis

Review the rebalanced reaction and recalcalculated log K values (or coefficients)

then click apply to update the entry

Alternatively, choosing Reduce to basis would have additionally swapped out the redox species Np++++ for the basis species NpO2++

Exchange species' positions
Right-click on an entry under “Basis species”, “Redox couples”, or “Aqueous species”, then choose Exchange with…, and select a species of a different type to exchange places with.

For example, to replace the basis species “HCO3-” in thermo.tdat with the aqueous species “CO3--”, right-click on “HCO3-” then choose Exchange with… → Aqueous… → “CO3--”

TEdit will rebalance all reactions written in terms of “HCO3-“ to instead use “CO3--”. Hover over an entry to see how it will be rebalanced, then select OK.

TEdit exchanges the species' positions in the dataset, as you can see in the tree structure

and rewrites the reactions between them, along with dependent reactions. The reaction for Calcite, for example, changes from “Calcite + H+ = Ca++ + HCO3” to “Calcite = Ca++ + CO3−−”, and the log K refigured accordingly.


Adjusting redox coupling

Couple a redox reaction
Right-click on a species under “Redox couples”, then choose Couple.

For example, to decouple “Fe+++” in thermo.tdat, right-click on “Fe+++” then choose Couple

When the program prompts

select Yes. The reaction will be moved from under “Redox couples” to “Aqueous species”.

Next, the program will offer to rebalance all reactions written in terms of the coupled species. Hover over an entry to see how it will be rebalanced

Click OK to rebalance the reactions, or Cancel to skip the rebalancing.

In this case, the reaction for Fe(OH)3(ppd) changes from “Fe(OH)3(ppd) + 3 H+ = Fe+++ + 3 H2O” to “Fe(OH)3(ppd) + 2 H+ = 2.5 H2O + Fe++ + .25 O2(aq)”, and the log K refigured accordingly.

Decouple a redox reaction
Right-click on a species under “Aqueous species”, then choose Decouple.

For example, to recouple “Fe+++” after the previous operation, right-click on “Fe+++” then choose Decouple

When the program prompts

select Yes. The reaction will be moved from under “Aqueous species” to “Redox couples”.

Next, the program will offer to rebalance all redox reactions for which a change in oxidation state can be eliminated by including Fe+++. Hover over an entry to see how it will be rebalanced

Click OK to rebalance the reactions, or Cancel to skip the rebalancing.

In this case, the reaction for Fe(OH)3(ppd) reverts to its original format, before the coupling.

Make a coupling reaction for a Basis species
Right-click on a Basis species, then choose Make Couple.

In thermo_sit.tdat, right-click on “Acetate-”, then select Make Couple

When the program prompts

select Yes. The entry will be moved from under “Basis species” to “Redox couples”.

Under “Species in reaction”, click add to define a reaction linking “Acetate-” to “CO3--”, then supply the log K values or polynomial coefficients.

Identify redox reactions
Go to a section header and change the pulldown to “Redox reactions”.

In thermo_sit.tdat, for example, click on “Aqueous species”, then choose “Redox reactions” from the pulldown to show redox reactions within that section

The reaction for “ClO4-” for example, might be decoupled (see above) so as to allow disequilibrium between perchlorate and chloride ions in a calculation involving some constraint on the oxidation state.

Similarly, several selenium-cyanide complexes are identified as redox reactions.

Rebalancing each with “SeCn-” in place of “Cn-” and “HSe-” would eliminate their change in oxidation state. Decoupling “SeCn-” would make it a “Redox couple” and trigger TEdit to swap it into the complexes' reactions.

Change the redox pivot
Using the Exchange with… functionality, exchange the position of O2(aq) and H2(aq).

In thermo.tdat, right-click on “O2(aq)”, then select Exchange with… → Redox… → “H2(aq)”

TEdit will rebalance all reactions written in terms of “O2(aq)“ to instead use “H2(aq)”. Hover over an entry to see how it will be rebalanced, then select OK.

TEdit exchanges the species' positions in the dataset, as you can see in the tree structure

and rewrites the reactions between them, along with dependent reactions.


Quality control

Charge and mass balance
Each entry's editing pane shows a status message.

As you fill in the data template TEdit will check the charge and mole weight you supply against the species in the reaction, and will flag imbalances

Hover over the status warning to see an explanation.

To remedy the error, define the species in the reaction and set their coefficients. The reaction below is not fully defined, so it is unbalanced with respect to charge and mass

The completed reaction below is charge and mass-balanced, but one issue persists. A log K value must be supplied for at least one of the principal temperatures (500 indicates no data)

After supplying a log K value, TEdit indicates that no errors have been found

Global error checks
Go to File → Troubleshoot… to check for imbalances, omissions, and other issues.

TEdit will additionally open the Troubleshoot… dialog if it finds any errors when you open or attempt to save a dataset.

The dialog lists warnings for specific entries, such as charge or mass imbalances, that can typically be fixed within TEdit. Double-click on an entry to go to its editing pane.

The errors above arise when the surface dataset “FeOH.sdat” is set to draw species from “thermo.com.V8.R6+.tdat”, instead of “thermo.tdat”, due to different spellings of the As(OH)3, B(OH)3, and Fe(OH)3(ppd) species. To fix the first two warnings, go to the editing pane for >(w)FeH2AsO3 and replace the As(OH)3 in its reaction with the equivalent species As(OH)3(aq).

You can also use the right-click menu to apply a filter with the selected entries or delete them from the dataset.

A second set of errors describes omissions, broader dataset problems, and issues that may need to be fixed in a text editor.

A surface dataset imported from PhreeqC, for example, will not include a sorbing mineral, since that information is typically specified within PhreeqC's input script. To complete the GWB dataset, specify a sorbing mineral (or minerals); each requires a specific surface area and site density.

Global mole weight adjustments
Go to Edit → Mole Weight… to find and adjust mass imbalances.

The Mole Weight… dialog lists imbalances between a species' supplied mole weight and that calculated from its elemental composition.

By default, it lists imbalances exceeding a threshold of 0.9 g mol−1, in descending order. Any imbalance above that value likely indicates a problem with the reaction's stoichiometry. You can double-click on a species to view its entry.

Adjust the threshold to a smaller value for finer adjustment. Different sources often use slightly different mole weights for various elements and species, so the dialogue allows you to find small discrepancies and make corrections.

Assuming the stoichiometry is correct, you can select one or more rows in the dialog and click Adjust to recalculate mole weights to match those calculated from elemental compositions.


Importing and exporting data from other modeling programs

Import a PhreeqC dataset
Drag a dataset into TEdit and save the resulting thermo (.tdat) and surface (.sdat) files for use in the GWB apps.

Alternatively, go to File → Import → PhreeqC… and browse to the dataset. TEdit will walk you through the conversion.

Choose where to save the dataset, and whether or not to import datasets of surface reactions. Specify as well an appropriate temperature range for the dataset

TEdit generates separate thermo (.tdat) and surface (.sdat) datasets, which you can browse in separate tabs

Correct fictive elements in PhreeqC dataset
Use an existing element, create a fictive element, or supply the elemental composition of a compound.

If you import file “phreeqc.dat”, you'll notice it contains a few fictive elements

TEdit gives you several options to handle them, including creating custom elements

or specifying the real element or elements in PhreeqC's master species

In this case, we specify that “Sg” is really H2S.

PhreeqC surface data
Add sorbing minerals and specify capacitance or potential values as necessary.

TEdit splits the surface reactions it finds into separate “.sdat” files, one for each distinct ion-exchange, two-layer, or CD-MUSIC surface. It creates surface datasets by default, but you can uncheck “Create surface datasets” to skip them.

Each surface dataset is set to draw aqueous species from the newly created thermo dataset.

TEdit combines PhreeqC's ion-exchange half-reactions into full reactions following the Gaines-Thomas convention, and transforms log Ks to linear values.

To complete a two-layer or CD-MUSIC dataset, add a sorbing mineral (or minerals), along with its specific surface area and site density

For the CD-MUSIC model, set capacitance values C1 and C2 (in F/m2) on the Header pane.

If using the non-electrostatic or constant capacitance version of the two-layer model, set a single value for the potential (0 mV) or capacitance, respectively.

Import an EQ3/6 dataset
Drag an EQ3/6 dataset into TEdit to convert for use in the GWB apps.

Alternatively, on the TEdit menubar, go to File → Import → EQ3/6… and browse to the dataset.

TEdit automatically saves new GWB thermo (.tdat) file in the same directory as the original EQ3/6 dataset.

View new GWB dataset in TEdit. The activity model is determined by the keywords encountered in the EQ3/6 dataset. Text and reference blocks from the top and bottom of the original dataset is preserved in the “Preamble” and “Bibliography” sections respectively.

TEdit will launch the Troubleshoot… dialog if it finds any issues with the dataset. You will need to correct the issues identified before using the dataset.

Export an EQ3/6 dataset
Use TEdit to export GWB datasets to use with the EQ3/6 software.

Open the GWB dataset you wish to export in TEdit. Go to File → Export → EQ3/6…

Browse to the directory that you wish to save your dataset and supply a name for the EQ3/6 “data0.xxx” file. Hit Save.

You can view the dataset in a text editor. Information pertaining to the original GWB dataset, time and date of the conversion, and user name is located at the top of the file, followed by the any information from the “Preamble” in the Headers pane.