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
- Partial molar volumes
- Coefficients for activity correction equations (e.g. Pitzer model)
- Coefficients for viscosity equations
Note
Due to copyright restrictions, pyEQL’s built-in databases contain only a small selection of diffusion coefficients, partial molar volumes, and viscosity coefficients for some common ions like H+, Na+, Cl-, and OH-. We are working on securing permission to distribute a more complete dataset. In the mean time, see the references in the example databases for good data sources. Alternatively, you can provide your own parameters in a custom database (see below). pyEQL does already contain a fairly large collection of Pitzer parameters for both activity correction and partial molar volume; and this will be expanded in the future.
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 .csv 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.csv 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)
If you wish to supply these paramaters 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-2015 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
()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
()¶ Function to generate a human-friendly summary of all the database parameters that are actually used in the simulation
-
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-2015 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.
-