Electrolyte Database (EDB)

Overview
Workflows
Python API
edb command-line
EDB schemas

Overview 

The Electrolyte Database (EDB) stores metadata and data about chemical species, called here components, and reactions. It is accessed through a Python API to return well-defined Python objects.

The data are stored in MongoDB, so they can be queried in a number of ways, and the system is extensible to new use-cases. The native storage format for MongoDB is a JSON document, and the expected structure and fields of the component and reaction data is defined by a JSON Schema. Validation using those schemas is built into the API (though it can be disabled).

To interface with the IDAES Core Modeling Framework (IDAES-CMF, which underlies WaterTAP), add components and reactions to a “base” object and fetch the result as a Python dict. This result can be used to configure and build IDAES objects (ParameterBlocks, ReactionBlocks, etc.). The API also has methods to construct component and reaction objects from IDAES configurations.

Workflows 

The EDB is intended to support some known workflows out of the box, with lower-level functions available when these are not sufficient.

Note

This content is not yet finished.

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.

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[watertap.edb.data_model.Result, watertap.edb.data_model.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) → watertap.edb.data_model.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[watertap.edb.data_model.Result, watertap.edb.data_model.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) → watertap.edb.data_model.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)

load(data: Union[Dict, List[Dict], watertap.edb.data_model.DataWrapper, List[watertap.edb.data_model.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.

add(item: watertap.edb.data_model.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]

classmethod from_idaes_config(config: Dict) → List[watertap.edb.data_model.Component][source]: See documentation on parent class.

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

classmethod from_idaes_config(config: Dict) → List[watertap.edb.data_model.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)

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

root name

Type: string

The chemical name of the component

Examples:

"HPO4 2-"

"H3PO4"

"NH4 +"

root valid_phase_types

Type: array of string

Each item of this array must be:

root valid_phase_types items

Type: string

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

Example:

[
    "PT.liquidPhase"
]

root phase_equilibrium_form

Type: object

root phase_equilibrium_form Vap

Type: string

root phase_equilibrium_form Liq

Type: string

root parameter_data

Type: object
No Additional Properties

root parameter_data mw

Type: array of object

List of parameter values

Each item of this array must be:

root parameter_data mw items

Type: object

Value, units, etc. for a parameter

root parameter_data mw items v

Type: number

value

root parameter_data mw items u

Type: string

units

root parameter_data mw items i

root parameter_data mw items i oneOf item 0

Type: string

string index

root parameter_data mw items i oneOf item 1

Type: number

numeric index

root parameter_data pressure_crit

Type: array of object

List of parameter values

Same definition as mw

root parameter_data temperature_crit

Type: array of object

List of parameter values

Same definition as mw

Pattern Property

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

Property name regular expression: ^.*_coeff$

root parameter_data parameter

Type: array of object

List of parameter values

Same definition as mw

Pattern Property

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

Property name regular expression: ^.*_ref$

root parameter_data parameter

Type: array of object

List of parameter values

Same definition as mw

Pattern Property

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

Property name regular expression: _comp

root _comp

Type: string

Reaction schema

Schema Docs

Type: object

The stoichiometry and properties of a reaction

root type

Type: enum (of string)

Type of reaction

Must be one of:

"equilibrium"

root name

Type: string

Name of reaction

root stoichiometry

Type: object

root stoichiometry Liq

Type: object

Stoichiometry for a reaction

Pattern Property

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

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

root stoichiometry Liq ^[A-Z].*$

Type: number

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

root stoichiometry Vap

Type: object

Stoichiometry for a reaction

Same definition as Liq

root heat_of_reaction

Type: string

root equilibrium_constant

Type: string

root equilibrium_form

Type: string

root concentration_form

Type: string

root parameter_data

Type: object
No Additional Properties

Pattern Property

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

Property name regular expression: _ref

root parameter_data parameter

Type: array of object

List of parameter values

Each item of this array must be:

root parameter_data _ref items

Type: object

Value, units, etc. for a parameter

root parameter_data _ref items v

Type: number

value

root parameter_data _ref items u

Type: string

units

root parameter_data _ref items i

One of

Option 1
Option 2

root parameter_data _ref items i oneOf item 0

Type: string

string index

root parameter_data _ref items i oneOf item 1

Type: number

numeric index

Electrolyte Database (EDB)

Overview

Workflows

Python API

Database API

Data object API

edb command-line

edb base

edb base options

edb load

edb load options

edb dump

edb dump options

edb schema

edb schema options

EDB schemas

Component schema

name Required

valid_phase_types

Each item of this array must be:

phase_equilibrium_form

Vap

Liq

parameter_data Required

mw

Each item of this array must be:

v Required

u Required

i

One of

pressure_crit

temperature_crit

^.*_coeff$ Pattern Property

Pattern Property

^.*_ref$ Pattern Property

Pattern Property

_comp Pattern Property

Pattern Property

Reaction schema

type

Must be one of:

name Required

stoichiometry

Liq

^[A-Z].*$ Pattern Property

Pattern Property

Vap

heat_of_reaction

equilibrium_constant

equilibrium_form

concentration_form

parameter_data Required

_ref Pattern Property

Pattern Property

Each item of this array must be:

v Required

u Required

i

One of

Overview 

Workflows 

Python API 

edb command-line 

EDB schemas 