Electrolyte Database (EDB)

Overview

The Electrolyte Database (EDB) stores data about chemical species. It is accessed through a Python API to return well-defined Python objects.

The data are stored in a database called MongoDB. MongoDB is open-source and free software, so you can install and use the database locally. You may also use our open cloud-hosted version of the database. See the MongoDB installation instructions for more details.

The native storage format for MongoDB is a JSON object, which MongoDB calls a “document”. The expected structure of the EDB data is defined by a JSON Schema. Most users will not need to deal with the MongoDB documents, as there is a Python data API for searching the database and building IDAES “config blocks” from the components and reactions.

Workflows

The EDB is intended to support some known workflows out of the box, with lower-level functions available when these are not sufficient. Example workflows can be seen in the how to guides from the link above.

Python API

Database API

Connect to the database and create, read, update and delete its contents.

Database operations API

class watertap.edb.db_api.ElectrolyteDB(url: str = 'mongodb://localhost:27017', db: str = 'electrolytedb', check_connection: bool = True)[source]

Interface to the Electrolyte database.

This uses MongoDB as the underlying data store.

__init__(url: str = 'mongodb://localhost:27017', db: str = 'electrolytedb', check_connection: bool = True)[source]

Constructor.

Parameters
  • url – MongoDB server URL

  • db – MongoDB ‘database’ (namespace) to use

  • check_connection – If True, check immediately if we can connect to the server at the provided url. Otherwise defer this check until the first operation (at which point a stack trace may occur).

Raises

pymongo.errors.ConnectionFailure – if check_connection is True, and the connection fails

classmethod can_connect(url=None, db=None) bool[source]
Convenience method to check if a connection can be made without having

to instantiate the database object.

Parameters
  • url – Same as constructor

  • db – Same as constructor

Returns

cannot connect

Return type

True, yes can connect; False

static drop_database(url, db)[source]

Drop a database.

Parameters
  • url – MongoDB server URL

  • db – Database name

Returns

None

Raises

anything pymongo.MongoClient() can raise

get_base(name: Optional[str] = None) Union[Result, Base][source]

Get base information by name of its type.

Parameters

name – Name of the base type.

Returns

If no name is given, a Result iterator over all the bases. Otherwise, a single Base object.

get_components(component_names: Optional[List[str]] = None, element_names: Optional[List[str]] = None) Result[source]

Get thermodynamic information for components of reactions.

Parameters
  • component_names – List of component names

  • element_names – List of element names (ignored if component_names is given)

Returns

All components matching the criteria (or all if none specified)

get_one_base(name: Optional[str] = None) Union[Result, Base]

Get base information by name of its type.

Parameters

name – Name of the base type.

Returns

If no name is given, a Result iterator over all the bases. Otherwise, a single Base object.

get_reactions(component_names: Optional[List] = None, phases: Optional[Union[List[str], str]] = None, any_components: bool = False, include_new_components: bool = False, reaction_names: Optional[List] = None) Result[source]

Get reaction information.

Parameters
  • component_names – List of component names

  • phases – Phase(s) to include; if not given allow any.

  • any_components – If False, the default, only return reactions where one side of the reaction has all components provided. If true, return the (potentially larger) set of reactions where any of the components listed are present.

  • include_new_components – If False, the default, only return reactions where all given components are found in that reaction (and no new components) are used in that reaction.

  • reaction_names – List of reaction names instead of component names

Returns

All reactions containing any of the names (or all reactions, if not specified)

list_bases()[source]

List the currently loaded bases and provide brief description

Parameters

None

Returns

No return, just display info to console

load(data: Union[Dict, List[Dict], DataWrapper, List[DataWrapper]], rec_type: str = 'base') int[source]

Load a single record or list of records.

Parameters
  • data – Data to load, as a single or list of dictionaries or DataWrapper subclass

  • rec_type – If input is a dict, the type of record. This argument is ignored if the input is a subclass of DataWrapper.

Returns

Number of records loaded

Data object API

Data models for components and reactions, including conversion to IDAES config objects.

Data model for electrolyte database.

Usage to get configuration for IDAES:

base = <query database for Base config of interest>
c_list = <get Components from database>
# add all the components to the base
for c in c_list:
    base.add(c)
# get the merged configuration for IDAES functions
config = base.idaes_config

Class diagram:

        ┌────────────────────────────────┐
        │ ConfigGenerator   <<abstract>> │
uses    ├────────────────────────────────┤
 ┌─────►│+ConfigGenerator(data)          │
 │      │                                │
 │      ├────────────────────────────────┤
 │      │+config                         │
 │      │_transform(data)                │
 │      └────────────┬───────────────────┘
 │                   │
 │                   ├───────────┬───────────────────────┐
 │                   │           │                       │
 │    ┌──────────────┴┐       ┌──┴──────────┐      ┌─────┴─────┐
 │    │ ReactionConfig│       │ ThermoConfig│      │ BaseConfig│
 │    └─────▲─────────┘       └─▲───────────┘      └───────▲───┘
 │          │                   │                          │
 │          │                   │                          │
 │          │                   │                          │
 │          │uses               │uses                      │uses
 │          │                   │                          │
 │          │                   │                          │
 │  ┌───────┼───────────────────┼──────────────────────────┼────────────┐
 │  │       │                   │                          │            │
 │  │  ┌────┴─────┐   ┌─────────┴───┐    ┌─────────────────┴─────────┐  │
 │  │  │ Reaction │   │  Component  │    │ Base                      │  │
 │  │  └─────┬────┘   └──────┬──────┘    │                           │  │
 │  │        │               │           │ +add(item:DataWrapper)    │  │
 │  │        │               │           └─────────┬─────────────────┘  │
 │  │        │               │                     │                    │
 │  │        │               │                     │                    │
 │  │        ├───────────────┴─────────────────────┘                    │
 │  │        │                                                          │
 │  │        │                                                          │
 │  └────────┼──────────────────────────────────────────────────┬───────┘
 │           │                                                  │
 │           │                                                  │
 │           │                                         ┌────────┴─────────────┐
 │           │ subclass                                │                      │
 │   ┌───────▼────────────────────────────┐            │ Public interface to  │
 │   │DataWrapper      <<abstract>>       │            │ the rest of          │
 │   ├────────────────────────────────────┤            │ WaterTAP           │
 │   │+DataWrapper(data, config_gen_class)│            │                      │
 └───┼────────────────────────────────────┤            └──────────────────────┘
     │+idaes_config: dict                 │
     │+merge_keys: tuple[str]             │
     └────────────────────────────────────┘
class watertap.edb.data_model.Base(data: Dict)[source]

Wrapper for ‘base’ information to which a component or reaction is added.

__init__(data: Dict)[source]

Ctor.

Parameters
  • data – Data from the DB

  • config_gen_class – Used to transform DB data to IDAES idaes_config

add(item: DataWrapper)[source]

Add wrapped data to this base object.

property idaes_config

“Get the data as an IDAES config dict.

Returns

Python dict that can be passed to the IDAES as a config.

class watertap.edb.data_model.Component(data: Dict, validation=True)[source]
__init__(data: Dict, validation=True)[source]

Constructor.

Parameters
  • data – Data from the DB

  • validation – If true, do schema validation of input

classmethod from_idaes_config(config: Dict) List[Component][source]

See documentation on parent class.

class watertap.edb.data_model.Reaction(data: Dict, validation=True)[source]
__init__(data: Dict, validation=True)[source]

Constructor.

Parameters
  • data – Data from the DB

  • validation – If true, do schema validation of input

classmethod from_idaes_config(config: Dict) List[Reaction][source]

See documentation on parent class.

set_reaction_order(phase: str, order: Union[List[Tuple[str, float]], Dict[str, float]], require_all: bool = False) None[source]

Set the reaction order for the given phase.

Parameters
  • phase – a value from self.PHASES

  • order – Either a dict or list of (element, value) pairs

  • require_all – If True, require that all components in the reaction be given an order. If False, it is OK if some components are missing.

Returns

None. Reaction order is modified in place.

Raises
  • KeyError – something is missing in the data structure, or unknown component provided

  • ValueError – Wrong or incomplete components provided

class watertap.edb.data_model.Result(iterator=None, item_class=None)[source]

Encapsulate one or more JSON objects in the appropriate DataWrapper subclass.

Users won’t need to instantiate this directly, just iterate over it to retrieve the result of a database query or other operation that returns EDB data objects.

For example:

result = db.get_reactions(..search-params...)
for reaction_obj in result:
    # ..work with instance of class Reaction..
    print(reaction_obj.name)
__init__(iterator=None, item_class=None)[source]

edb command-line

The edb command-line program lets you interact with the database and the data schemas from a terminal.

edb base

The work of the program is all done by subcommands.

edb base options

--help

Show options and subcommands

-v, --verbose

Increase verbosity

-q, --quiet

Increase quietness

edb load

Load JSON records into the EDB.

edb load options

-f, --file FILENAME

File to load [required]

-t, --type [component|reaction|base]

Type of records [required]

-u, --url TEXT

Database connection URL

-d, --database TEXT

Database name

--validate / -n, --no-validate

Turn on or off validation of input

-b, --bootstrap

Bootstrap a new database by loading in the standard base data.

edb dump

Dump JSON records from the EDB to a file.

edb dump options

-f, --file FILENAME

File to create (will overwrite existing files!) [required]

-t, --type [component|reaction|base]

Type of records (MongoDB collection name)

-u, --url TEXT

Database connection URL

-d, --database TEXT

Database name

edb schema

Show JSON schemas, in raw or readable forms, for the different record types.

edb schema options

-f, --file FILENAME

Write output to this file instead of printing to the screen

-o, --format [json|markdown|html|html-js]

Output format

-t, --type [component|reaction]

Type of records [required]

-u, --url TEXT

Database connection URL

-d, --database TEXT

Database name

EDB schemas

The EDB data is encoded in JSON. Naturally, the expected form of the records is specified as JSON Schema. There are schemas for the component and reaction records. Currently, there is no schema for base data (this will change soon, though).

Component schema

Schema Docs Type: object

A chemical species that is a component in a reaction

No Additional Properties

Type: string

The chemical name of the component


Examples:

"HPO4 2-"
"H3PO4"
"NH4 +"

Type: array of string

Each item of this array must be:

Type: string

Valid phase types should start with 'PT.' and then match attributes in idaes.core.base.phases.PhaseType


Example:

[
    "PT.liquidPhase"
]

Type: object

Type: string

Type: string

Type: object
No Additional Properties

Type: array of object

List of parameter values

Each item of this array must be:

Type: object

Value, units, etc. for a parameter

Type: number

value

Type: string

units


Type: string

string index

Type: number

numeric index

Type: array of object

List of parameter values

Same definition as mw

Type: array of object

List of parameter values

Same definition as mw

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^.*_coeff$
Type: array of object

List of parameter values

Same definition as mw

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^.*_ref$
Type: array of object

List of parameter values

Same definition as mw

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: _comp
Type: string

Reaction schema

Schema Docs Type: object

The stoichiometry and properties of a reaction

Type: enum (of string)

Type of reaction

Must be one of:

  • "equilibrium"

Type: string

Name of reaction

Type: object

Type: object

Stoichiometry for a reaction

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[A-Z].*$
Type: number

Moles for the given species in the reaction. Negative for LHS, positive for RHS

Type: object

Stoichiometry for a reaction

Same definition as Liq

Type: string

Type: string

Type: string

Type: string

Type: object
No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: _ref
Type: array of object

List of parameter values

Each item of this array must be:

Type: object

Value, units, etc. for a parameter

Type: number

value

Type: string

units


Type: string

string index

Type: number

numeric index

EDB base config options

The EDB data for the most common base configs are made available in the standard bootstrap bundled with WaterTAP. Those bases are listed below:

Base

Description

default_thermo

Default ThermoConfig: contains only AqueousPhase and uses FTPx state vars

thermo_Liq_FpcTP

ThermoConfig: contains only AqueousPhase and uses FpcTP state vars

thermo_Liq_Sol_FpcTP

ThermoConfig: contains AqueousPhase + SolidPhase and uses FpcTP state vars

thermo_Liq_Vap_FpcTP

ThermoConfig: contains AqueousPhase + VaporPhase and uses FpcTP state vars

reaction

ReactionConfig: Blank template for reaction configs

The naming convention for the thermo bases is as follows: (i) each section of the name is broken up by the underscore character (_), (ii) the first word in the name is always thermo to denote the type of base, (iii) the last word in the name always denotes the state_vars, and (iv) each word in between denotes the set of phases for the configuration file.