Skip to content

Commit

Permalink
Merge pull request #31 from mvdh7/develop
Browse files Browse the repository at this point in the history 
Merge for v0.3.0 release
  • Loading branch information
@mvdh7
mvdh7 authored Apr 12, 2019
2 parents dd19832 + bc6b684 commit bf9e486
Show file tree
Hide file tree
Showing 38 changed files with 4,681 additions and 3,457 deletions.
10 changes: 6 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# pytzer
# Pytzer

[![Codacy Badge](https://api.codacy.com/project/badge/Grade/2e98427c04a64c8fbc2dbf785a6a383a)](https://app.codacy.com/app/mvdh7/pytzer?utm_source=github.com&utm_medium=referral&utm_content=mvdh7/pytzer&utm_campaign=Badge_Grade_Dashboard)
[![pypi badge](https://img.shields.io/pypi/v/pytzer.svg?style=popout)](https://pypi.org/project/pytzer/)

Pitzer model for chemical activities in aqueous solutions, undergoing beta testing and development.

Installation:
**Installation:**

```shell
pip install pytzer
pip install git+https://github.com/mvdh7/autograd#egg=autograd --upgrade --no-cache-dir
```

Further documentation available: [pytzer.readthedocs.io](https://pytzer.readthedocs.io/en/latest/), including a [quick-start guide](https://pytzer.readthedocs.io/en/latest/quick-start/).
The second line above is strongly recommended, but optional. It upgrades [Autograd](https://github.com/HIPS/autograd) to the latest version that has been tested with Pytzer, which eliminates some deprecation warnings that may appear when using the relatively old Autograd version available from PyPI. You could also switch `mvdh7` in the URL to `HIPS` to get the very latest Autograd straight from the horse's mouth.

**Documentation:** [pytzer.readthedocs.io](https://pytzer.readthedocs.io/en/latest/), including a [quick-start guide](https://pytzer.readthedocs.io/en/latest/quick-start/).

Implemented and maintained by [Matthew P. Humphreys](https://mvdh.xyz), University of East Anglia, Norwich, UK.
Binary file removed docs/img/1920px-GPLv3_Logo.svg.png
View file
Binary file not shown.
69 changes: 29 additions & 40 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,85 +1,74 @@
<!--<script src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML' async></script>-->

# pytzer
# Pytzer v0.3.0

**pytzer** is a Python 3.6+ implementation of the Pitzer model for chemical activities in aqueous solutions (Pitzer, 1991).
**Pytzer** is a Python 3.6+ implementation of the Pitzer model for chemical activities in aqueous solutions [[P91](references/#P91)].


# Installation
## Installation

If using conda, first create and activate a new environment with Python 3.6 and numpy 1.15. Then:
If using Conda, first create and activate a new environment with Python v3.6+, NumPy v1.15+ and SciPy v1.2+. Other versions are probably fine, but untested. Activate the environment, and then enter:

```shell
pip install pytzer
pip install git+https://github.com/mvdh7/autograd#egg=autograd --upgrade --no-cache-dir
```

Other versions are probably fine, but untested. We are using Python 3.6 rather than 3.7 to enable planned integration with MATLAB.
The second line above is strongly recommended, but optional. It upgrades [Autograd](https://github.com/HIPS/autograd) to the latest version that has been tested with Pytzer, which eliminates some deprecation warnings that may appear when using the relatively old Autograd version available from PyPI. You could also switch `mvdh7` in the URL to `HIPS` to get the very latest Autograd straight from the horse's mouth.

See the [quick-start guide](quick-start) for more detailed instructions and examples.


# Development status
## Development status

**pytzer** is in beta. Tests of the accuracy of its coefficients and equations are underway, so results may change. API may change and functions may be added or removed. Use at your own peril!
Pytzer is in beta. Tests of the accuracy of its coefficients and equations are underway, so results may change. API may change and functions may be added or removed. Use at your own peril!


# Modules
## Modules

<table><tr>

<td><strong>Module</strong></td>
<td><strong>Purpose</strong></td>

</tr><tr>
<td><code>.io</code></td>
</tr><tr><td><code>.io</code></td>
<td><a href="modules/io">Import and export data</a></td>

</tr><tr>
<td><code>.cflibs</code></td>
<td><a href="modules/cflibs">Define combinations of model coefficients to use</a></td>

</tr><tr>
<td><code>.model</code></td>
</tr><tr><td><code>.model</code></td>
<td><a href="modules/model">Implement the Pitzer model</a></td>

</tr><tr>
<td><code>.coeffs</code></td>
<td><a href="modules/coeffs">Define functions to evaluate model coefficients</a></td>
</tr><tr><td><code>.cflibs</code></td>
<td><a href="modules/cflibs">Define combinations of model coefficients to use</a></td>

</tr><tr><td><code>.coeffs</code></td>
<td><a href="modules/coeffs">Define functions to evaluate Pitzer model coefficients</a></td>

</tr><tr>
<td><code>.tables</code></td>
</tr><tr><td><code>.tables</code></td>
<td><a href="modules/tables">Store tables of coefficient values</a></td>

</tr><tr>
<td><code>.jfuncs</code></td>
</tr><tr><td><code>.jfuncs</code></td>
<td><a href="modules/jfuncs">Define unsymmetrical mixing functions</a></td>

</tr><tr>
<td><code>.props</code></td>
</tr><tr><td><code>.props</code></td>
<td><a href="modules/props">Define universal ionic properties</a></td>

</tr><tr>
<td><code>.constants</code></td>
</tr><tr><td><code>.constants</code></td>
<td><a href="modules/constants">Define physical constants</a></td>

</tr><tr>
<td><code>.meta</code></td>
</tr><tr><td><code>.teos10</code></td>
<td><a href="modules/teos10">Calculate properties of pure water</a></td>

</tr><tr><td><code>.meta</code></td>
<td><a href="modules/meta">Define package metadata</a></td>

</tr></table>

# Acknowledgements

**pytzer** is maintained by [Dr Matthew P. Humphreys](https://mvdh.xyz) at the Centre for Ocean and Atmospheric Sciences, School of Environmental Sciences, University of East Anglia, Norwich, UK.

Its ongoing development is funded by the [Natural Environment Research Council](https://nerc.ukri.org/) (NERC, UK) through *NSFGEO-NERC: A Thermodynamic Chemical Speciation Model for the Oceans, Seas, and Estuaries* (NE/P012361/1).

# License
## Acknowledgements

<img src="img/1920px-GPLv3_Logo.svg.png" width="25%" />
Pytzer is maintained by [Dr Matthew P. Humphreys](https://mvdh.xyz) at the Centre for Ocean and Atmospheric Sciences, School of Environmental Sciences, University of East Anglia, Norwich, UK.

The entirety of **pytzer** is licensed under the [GNU General Public License version 3 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.en.html).
Its ongoing development is funded by the Natural Environment Research Council (NERC, UK) through grant NE/P012361/1: *NSFGEO-NERC: A Thermodynamic Chemical Speciation Model for the Oceans, Seas, and Estuaries*.

# References
## License

Pitzer, K. S. (1991). “Ion Interaction Approach: Theory and Data Correlation,” in *Activity Coefficients in Electrolyte Solutions, 2nd Edition*, ed. K. S. Pitzer (CRC Press, Florida, USA), 75–153.
Pytzer is licensed under the [GNU General Public License version 3 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.en.html).
62 changes: 32 additions & 30 deletions docs/modules/cflibs.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,32 @@
<script type="text/x-mathjax-config">
MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML' async></script>
MathJax.Ajax.config.path["mhchem"] =
"https://cdnjs.cloudflare.com/ajax/libs/mathjax-mhchem/3.3.2";
MathJax.Hub.Config({TeX: {extensions: ["[mhchem]/mhchem.js"]}});
</script><script src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML' async></script>

# Coefficient libraries

**pytzer.cflibs** provides specific combinations of coefficients that have been used in published Pitzer models, to use with **pytzer**.
*The casual user has no need to explicitly call this module.*

To use a Pitzer model we need to define a set of coefficients that quantify the interactions between different combinations of ions. We do this by creating a **coefficient library**, which contains functions that evaluate the coefficients for every possible interaction. The functions themselves are defined separately, in **pytzer.coeffs**.
`.cflibs` provides specific combinations of coefficients that have been used in published Pitzer models, to use with Pytzer.

To use a Pitzer model we need to define a set of coefficients that quantify the interactions between different combinations of ions. We do this by creating a **coefficient library**, which contains functions that evaluate the coefficients for every possible interaction. The functions themselves [are defined separately](../coeffs).

A number of [pre-defined coefficient libraries](#pre-defined-coefficient-libraries) are included in **pytzer.cflibs**. To use these, all you need to do is assign the variable `cflib` appropriately:

```python
import pytzer as pz

# Use M88 coefficients
cflib = pz.cflibs.M88
>>> import pytzer as pz
>>> cflib = pz.cflibs.M88 # Use M88 coefficients
```

This `cflib` can then be passed into all of the **pytzer.model** functions.
This `cflib` can then be passed into all of the [Pitzer model functions](../model).

<hr />

# Pre-defined coefficient libraries
## Pre-defined coefficient libraries

Several ready-to-use coefficient libraries are available in this module. To decode their sources, see the [literature references table](../../name-conventions/#literature-references).
Several ready-to-use coefficient libraries are available in this module. To decode their sources, see the [literature references table](../../references).

<table><tr>

Expand All @@ -34,29 +36,29 @@ Several ready-to-use coefficient libraries are available in this module. To deco

</tr><tr>
<td>CRP94</td>
<td>H<sup>+</sup> :: HSO<sub>4</sub><sup>−</sup> :: SO<sub>4</sub><sup>2−</sup></td>
<td>Clegg et al. (1994)</td>
<td>$\ce{H^+}$, $\ce{HSO4^-}$, $\ce{SO4^2-}$</td>
<td><a href="../../references/#CRP94">CRP94</a></td>

</tr><tr>
<td>GM89</td>
<td>Ca<sup>2+</sup> :: Cl<sup>−</sup> :: K<sup>+</sup> :: Na<sup>+</sup> :: SO<sub>4</sub><sup>2−</sup></td>
<td>Greenberg and Møller (1989)</td>
<td>$\ce{Ca^2+}$, $\ce{Cl^-}$, $\ce{K^+}$, $\ce{Na^+}$, $\ce{SO4^2-}$</td>
<td><a href="../../references/#GM89">GM89</a></td>

</tr><tr>
<td>M88</td>
<td>Ca<sup>2+</sup> :: Cl<sup>−</sup> :: Na<sup>+</sup> :: SO<sub>4</sub><sup>2−</sup></td>
<td>Møller (1988)</td>
<td>$\ce{Ca^2+}$, $\ce{Cl^-}$, $\ce{Na^+}$, $\ce{SO4^2-}$</td>
<td><a href="../../references/#M88">M88</a></td>

</tr><tr>
<td>WM13</td>
<td>Ca<sup>2+</sup> :: Cl<sup>−</sup> :: H<sup>+</sup> :: HSO<sub>4</sub><sup>−</sup> :: K<sup>+</sup> :: Mg<sup>2+</sup> :: MgOH<sup>+</sup> :: Na<sup>+</sup> :: OH<sup>−</sup> :: SO<sub>4</sub><sup>2−</sup></td>
<td>Waters and Millero (2013)</td>
<td>$\ce{Ca^2+}$, $\ce{Cl^-}$, $\ce{H^+}$, $\ce{HSO4^-}$, $\ce{K^+}$, $\ce{Mg^2+}$, $\ce{MgOH^+}$, $\ce{Na^+}$, $\ce{OH^-}$, $\ce{SO4^2-}$</td>
<td><a href="../../references/#WM13">WM13</a></td>

</tr></table>

<hr />

# cflib methods
## cflib methods

A few handy methods are provided as part of the **CoeffLib** class. Brief summaries are provided below, and here is a usage example of all of them together:

Expand Down Expand Up @@ -87,26 +89,26 @@ cflib.print_coeffs(298.15,'coeff_file.txt')

The methods are as follows:

## .add_zeros
### .add_zeros

`CoeffLib.add_zeros(ions)` adds zero-functions for all missing interactions, given a list of ions.

## .get_contents
### .get_contents

`CoeffLib.get_contents()` scans through all functions within the **CoeffLib**, and puts lists of all ions and of all sources in its **ions** and **srcs** fields.

The list of ions is determined from the dict keys, while sources are determined from the function names.

## .print_coeffs
### .print_coeffs

`CoeffLib.print_coeffs(T,filename)` evaluates all coefficients in a **cflib** at a single input temperature (`T`), and prints the results to a text file (`filename`).
`CoeffLib.print_coeffs(T,filename)` evaluates all coefficients in a **cflib** at a single input temperature and pressure, and prints the results to a text file (`filename`).


<hr />

# How a CoeffLib works
## How a CoeffLib works

To modify an existing **CoeffLib**, or create a new one, it is first necessary to understand how they are used within **pytzer**, as follows. A basic understanding of the workings of the Pitzer model is assumed.
To modify an existing **CoeffLib**, or create a new one, it is first necessary to understand how they are used within Pytzer, as follows. A basic understanding of the workings of the Pitzer model is assumed.

A **CoeffLib** or **cflib** is an object of the class `CoeffLib` as defined within **pytzer.cflibs**. From the initalisation function we can see that it contains the following fields:

Expand All @@ -130,7 +132,7 @@ class CoeffLib:
self.srcs = []
```

Each field is then filled with functions from **pytzer.coeffs** or **pytzer.jfuncs** that define the Pitzer model interaction coefficients, as follows. (Descriptions of the required contents of the functions themselves are in the separate <a href="../coeffs"><strong>pytzer.coeffs</strong> documentation</a>.)
Each field is then filled with functions from **pytzer.debyehueckel**, **pytzer.coeffs** or **pytzer.jfuncs** that define the Pitzer model interaction coefficients, as follows. (Descriptions of the required contents of the functions themselves are in the separate <a href="../coeffs"><strong>pytzer.coeffs</strong> documentation</a>.)


### Debye-Hückel limiting slope
Expand Down Expand Up @@ -199,7 +201,7 @@ Different options for the functions needed here can be found in **pytzer.jfuncs*
<hr />


# Modify an existing cflib
## Modify an existing cflib

The functions within an existing cflib can easily be switched by reassignment. For example, if you wanted to use the Møller (1988) model, but replace only the Na-Cl interaction equations with the model of Archer (1992), you could write:

Expand Down Expand Up @@ -229,7 +231,7 @@ cflib.bC['Na-Cl'] = pz.coeffs.bC_Na_Cl_A92ii

<hr />

# Build your own
## Build your own

You can also construct your own **cflib** from scratch. In the example below, we initialise a `cflib` using the `pytzer.cflibs.CoeffLib` class. We add functions from `pytzer.coeffs` for the system Na-Ca-Cl using functions from Møller (1988). Finally, we use the method `add_zeros` to fill out any interactions that we have neglected to provide functions for with zeros.

Expand Down Expand Up @@ -272,7 +274,7 @@ mycflib.psi['H-Mg-OH'] = coeffs.psi_zero # ignore H-Mg-OH interactions

## Print out coefficients

You can use the function **CoeffLib.print_coeffs** to create a file containing every coefficient, evaluated at a single input temperature of your choice. For example:
You can use the function **CoeffLib.print_coeffs** to create a file containing every coefficient, evaluated at a single input temperature and pressure of your choice. For example:

```python
mycflib.print_coeffs(298.15,'myCoeffs.txt')
Expand Down
Loading

0 comments on commit bf9e486

Please sign in to comment.