Database System

pyEQL creates a database to collect various parameters needed to perform it’s calculations. pyEQL’s default database includes a collection of the following parameters for some common electrolytes:

  • Diffusion coefficients for 104 ions
  • Pitzer model activity correction coefficients for 157 salts
  • Pitzer model partial molar volume coefficients for 120 salts
  • Jones-Dole “B” coefficients for 83 ions
  • Hydrated and ionic radii for 23 ions
  • Dielectric constant model parameters for 18 ions
  • Partial molar volumes for 10 ions

Basics

The Paramsdb class creates a container for parameters. Each paramter is an object which contains not only the value, but also information about the units, the reference, and the conditions of measurement. paramsdb() also defines several methods that are helpful for retrieving parameters.

pyEQL automatically initializes an instance of Paramsdb under the name ‘db’. You can access database methods like this:

>>> import pyEQL
>>> pyEQL.db
<pyEQL.database.Paramsdb at 0x7fead183f240>
>>> pyEQL.db.has_species('H+')
True

Anytime a new solute is added to a solution, the search_parameters() method is called. This method searches every database file within the search path (by default, only pyEQL’s built-in databases) for any parameters associated with that solute, and adds them to the database.

Adding your own Database Files

Custom Search Paths

The database system is meant to be easily extensible. To include your own parameters, first you need to add a directory of your choosing to the search path.

>>> pyEQL.db.add_path('/home/user')

You can always check to see which paths pyEQL is searching by using list_path():

>>> pyEQL.db.list_path()
<default installation directory>/database
/home/user

Then, place your custom database file inside that directory. NOTE: custom database files are searched IN ADDITION TO the default databases. You don’t need to re-create the information from the built-in files. Custom databases only need to contain extra parameters that are not included already.

File Format

Databases are formatted as TAB-SEPARATED text files and carry the .tsv extension. The intent of this format is to make database files easy to edit with common spreadsheet software.

Warning

If you open an existing or template database file for editing, some spreadsheet software will try to replace the tabs with commas when you save it again. pyEQL does NOT read comma-separated files.

Since pyEQL compiles the database from multiple files, the intent is for each file to contain values for one type of parameter (such as a diffusion coefficient) from one source. The file can then list values of that parameter for a number of different solutes.

The upper section of each file contains information about the source of the data, the units, the name of the parameter, and the conditions of measurement. The top of each database file must, at a minimum, contain rows for ‘Name’ and ‘Units’. Preferably, other information such as conditions, notes and a reference are also supplied. See template.tsv in the database subdirectory for an example.

The remainder of the file contains solute formulas in the first column (see Chemical Formulas) and corresponding values of the parameter in the following columns. Sets of parameters (such as activity correction coefficients) can be specified by using more than one column.

Warning

Currently there is no way to handle duplicated parameters. So if you supply a parameter with the same name as a built-in one, unexpected behavior may result.

Special Names

The name of a parameter is used as a kind of index within pyEQL. Certain methods expect certain parameter names. The following are the currently-used internal names:

  • ‘diffusion_coefficient’ - diffusion coefficient
  • ‘pitzer_parameters_activity’ - coefficients for the Pitzer model for activity correction
  • ‘pitzer_parameters_volume’- coefficients for the Pitzer model for partial molar volume
  • ‘erying_viscosity_coefficients’ - coefficients for an Erying-type viscosity correction model
  • ‘partial_molar_volume’- the partial molar volume (used if Pitzer parameters are not available)
  • ‘hydrated_radius’ - hydrated radius
  • ‘ionic_radius’ - ionic radius
  • ‘jones_dole_B’ - Jones-Dole “B” coefficient

If you wish to supply these parameters for a custom solute not included in the built-in database, make sure to format the name exactly the same way.

You can also specify a custom parameter name, and retrieve it using the get_parameter() method. If the solute is ‘Na+’

>>> pyEQL.db.get_parameter('Na+','my_parameter_name')

Viewing the Database

You can view the entire contents of the database using the print_database() method. Since pyEQL searches for parameters as they are added, the database will only contain parameters for solutes that have actually been used during the execution of your script. The output is organized by solute.

>>> pyEQL.db.print_database()

>>> s1 = pyEQL.Solution([['Na+','0.5 mol/kg'],['Cl-','0.5 mol/kg']])
>>> pyEQL.db.print_database()
Parameters for species Cl-:
--------------------------
Parameter diffusion_coefficient
Diffusion Coefficient
-------------------------------------------
Value: 2.032e-05 cm²/s
Conditions (T,P,Ionic Strength): 25 celsius, 1 atm, 0
Notes: For most ions, increases 2-3% per degree above 25C
Reference: CRC Handbook of Chemistry and Physics, 92nd Ed., pp. 5-77 to 5-79

Parameter partial_molar_volume
Partial molar volume
-------------------------------------------
Value: 21.6 cm³/mol
Conditions (T,P,Ionic Strength): 25 celsius, 1 atm, 0
Notes: correction factor 5e-4 cm3/g-K
Reference: Durchschlag, H., Zipper, P., 1994. "Calculation of the Partial Molal Volume of Organic Compounds and Polymers." Progress in Colloid & Polymer Science (94), 20-39.
...

API Documentation (database.py)

This module contains classes, functions, and methods for reading input files and assembling database entries for use by pyEQL.

By default, pyEQL searches all files in the /database subdirectory for parameters.

copyright:2013-2016 by Ryan S. Kingsbury
license:LGPL, see LICENSE for more details.
class pyEQL.database.Paramsdb

create a global dictionary to contain a dynamically-generated list of Parameters for solute species. The dictionary keys are the individual chemical species formulas. The dictionary’s values are a python set object containing all parameters that apply to the species.

Methods

add_parameter(formula, parameter) Add a parameter to the database
add_path(path) Add a user-defined directory to the database search path
get_parameter(formula, name) Retrieve a parameter from the database
has_parameter(formula, name) Boolean test to determine whether a parameter exists in the database for a given species
has_species(formula) Boolean test to determine whether a species is present in the database
list_path() List all search paths for database files
print_database([solute]) Function to generate a human-friendly summary of all the database parameters
search_parameters(formula) Each time a new solute species is created in a solution, this function:
add_parameter(formula, parameter)

Add a parameter to the database

add_path(path)

Add a user-defined directory to the database search path

get_parameter(formula, name)

Retrieve a parameter from the database

has_parameter(formula, name)

Boolean test to determine whether a parameter exists in the database for a given species

has_species(formula)

Boolean test to determine whether a species is present in the database

list_path()

List all search paths for database files

print_database(solute=None)

Function to generate a human-friendly summary of all the database parameters that are actually used in the simulation

Parameters:

solute : str, optional

The chemical formula for a species. If this argument of supplied, the output will contain only the database entries for this species. Otherwise, all database entries will be printed.

search_parameters(formula)

Each time a new solute species is created in a solution, this function:

1) searches to see whether a list of parameters for the species has already been compiled from the database 2) searches all files in the specified database directory(ies) for the species 3) creates a Parameter object for each value found 4) compiles these objects into a set 5) adds the set to a dictionary indexed by species name (formula) 6) points the new solute object to the dictionary

formula : str
String representing the chemical formula of the species.

API Documentation (parameter.py)

This module implements the Parameter() class, which is used to store values, units, uncertainties, and reference data for various quantities used throughout pyEQL.

copyright:2013-2016 by Ryan S. Kingsbury
license:LGPL, see LICENSE for more details.
class pyEQL.parameter.Parameter(name, magnitude, units='', **kwargs)

Class for storing and retrieving measured parameter values together with their units, context, and reference information.

Some pyEQL functions search for specific parameter names, such as: diffusion_coefficient

Methods

get_dimensions() Return the dimensions of the parameter.
get_magnitude([temperature, pressure, ...]) Return the magnitude of a parameter at the specified conditions.
get_name() Return the name of the parameter.
get_units() Return the units of a parameter
get_value([temperature, pressure, ...]) Return the value of a parameter at the specified conditions.
get_dimensions()

Return the dimensions of the parameter.

get_magnitude(temperature=None, pressure=None, ionic_strength=None)

Return the magnitude of a parameter at the specified conditions.

Parameters:

temperature : str, optional

The temperature at which ‘magnitude’ was measured in degrees Celsius. Specify the temperature as a string containing the magnitude and a unit, e.g. ‘25 degC’, ‘32 degF’, ‘298 kelvin’, and ‘500 degR’

pressure : str, optional

The pressure at which ‘magnitude’ was measured in Pascals Specify the pressure as a string containing the magnitude and a unit. e.g. ‘101 kPa’. Typical valid units are ‘Pa’, ‘atm’, or ‘torr’.

ionic_strength : str, optional

The ionic strength of the solution in which ‘magnitude’ was measured. Specify the ionic strength as a string containing the magnitude and a unit. e.g. ‘2 mol/kg’

Returns:

Number

The magnitude of the parameter at the specified conditions.

get_name()

Return the name of the parameter.

Parameters:

None

Returns:

str

The name of the parameter

get_units()

Return the units of a parameter

get_value(temperature=None, pressure=None, ionic_strength=None)

Return the value of a parameter at the specified conditions.

Parameters:

temperature : str, optional

The temperature at which ‘magnitude’ was measured in degrees Celsius. Specify the temperature as a string containing the magnitude and a unit, e.g. ‘25 degC’, ‘32 degF’, ‘298 kelvin’, and ‘500 degR’

pressure : str, optional

The pressure at which ‘magnitude’ was measured in Pascals Specify the pressure as a string containing the magnitude and a unit. e.g. ‘101 kPa’. Typical valid units are ‘Pa’, ‘atm’, or ‘torr’.

ionic_strength : str, optional

The ionic strength of the solution in which ‘magnitude’ was measured. Specify the ionic strength as a string containing the magnitude and a unit. e.g. ‘2 mol/kg’

Returns:

Quantity

The value of the parameter at the specified conditions.