Electrolyte Database (EDB)
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 ProteusLib), 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 proteuslib.edb.db_api.ElectrolyteDB(url='mongodb://localhost:27017', db='electrolytedb')[source]
Interface to the Electrolyte database.
This uses MongoDB as the underlying data store.
- 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_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_reactions(component_names: Optional[List] = None, phases: Optional[Union[List[str], str]] = None, any_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. Currently implemented only when any_components is False.
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.
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], 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
subclassrec_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 │
│ ├────────────────────────────────────┤ │ ProteusLib │
│ │+DataWrapper(data, config_gen_class)│ │ │
└───┼────────────────────────────────────┤ └──────────────────────┘
│+idaes_config: dict │
│+merge_keys: tuple[str] │
└────────────────────────────────────┘
- class proteuslib.edb.data_model.Base(data: Dict)[source]
Wrapper for ‘base’ information to which a component or reaction is added.
- 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 proteuslib.edb.data_model.Component(data: Dict, validation=True)[source]
- class proteuslib.edb.data_model.Reaction(data: Dict, validation=True)[source]
- classmethod from_idaes_config(config: Dict) List[Reaction] [source]
See documentation on parent class.
- set_reaction_order(phase: str, lhs: List[str], rhs: List[str], lhs_value: int = 0, rhs_value: int = 1) Dict [source]
Set the reaction order (if it differs from stoichiometry).
- Parameters
phase – ‘Liq’ or ‘Vap’
lhs – Left-hand side of equation components
rhs – Right-hand side of equation components
lhs_value – Integer value for LHS components
rhs_value – Integer value for RHS components
- Returns
Reaction order for all phases, which can be modified further in-place
- Raises
KeyError – something is missing in the data structure
- class proteuslib.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
A chemical species that is a component in a reaction
No Additional PropertiesThe chemical name of the component
"HPO4 2-"
"H3PO4"
"NH4 +"
Each item of this array must be:
Valid phase types should start with 'PT.' and then match attributes in idaes.core.phases.PhaseType
[
"PT.liquidPhase"
]
No Additional Properties
List of parameter values
Each item of this array must be:
Value, units, etc. for a parameter
value
units
string index
numeric index
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 mwAll 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 mwAll property whose name matches the following regular expression must respect the following conditions
Property name regular expression:_comp
Type: string
Reaction schema
The stoichiometry and properties of a reaction
Type of reaction
Must be one of:
- "equilibrium"
Name of reaction
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
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:
Value, units, etc. for a parameter
value
units
string index
numeric index