watertap.edb package

Submodules

watertap.edb.commands module

Commands for Electrolyte Database

exception watertap.edb.commands.DatabaseError(message: str)[source]

Bases: EDBCommandError

exit_code: ExitCode = 3: The exit code for this exception.

exception watertap.edb.commands.EDBCommandError(message: str)[source]: Bases: ClickException

class watertap.edb.commands.ExitCode(value)[source]

Bases: IntEnum

An enumeration.

exception watertap.edb.commands.MissingRequired(message: str)[source]

Bases: EDBCommandError

exit_code: ExitCode = 2: The exit code for this exception.

watertap.edb.commands.get_edb_data(filename: str) → Path[source]

Get an installed electrolyte DB data file filename.

Parameters: filename – File to get
Returns: Path object for file.

watertap.edb.data_model module

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]

Bases: DataWrapper

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.BaseConfig(data: Dict, name=None)[source]: Bases: ConfigGenerator

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

Bases: DataWrapper

__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.ConfigGenerator(data: Dict, name=None)[source]

Bases: object

Interface for getting an IDAES ‘idaes_config’ dict.

__init__(data: Dict, name=None)[source]

Constructor.

Parameters

data – Input data
name – Name of the component, e.g. “H2O”

class watertap.edb.data_model.DataWrapper(data: Dict, config_gen_class: Optional[Type[ConfigGenerator]] = None, validate_as_type=None)[source]

Bases: object

Interface to wrap data from DB in convenient ways for consumption by the rest of the library.

Do not use this class directly.

Derived classes will feed the data (from the database) and the appropriate subclass of GenerateConfig to the constructor. Then the IDAES config will be available from the idaes_config attribute. Note that no conversion work is done before the first access, and the converted result is cached to avoid extra work on repeated accesses.

__init__(data: Dict, config_gen_class: Optional[Type[ConfigGenerator]] = None, validate_as_type=None)[source]

Ctor.

Parameters

data – Data from the DB
config_gen_class – Used to transform DB data to IDAES idaes_config

classmethod from_idaes_config(config: Dict) → List[DataWrapper][source]

The inverse of the idaes_config property, this method constructs a new instance of the wrapped data from the IDAES config information.

Parameters: config – Valid IDAES configuration dictionary
Raises: BadConfiguration – If the configuration can’t be transformed into the EDB form due to missing/invalid fields.

property idaes_config: Dict

“Get the data as an IDAES config dict.

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

property json_data: Dict: Get the data in its “natural” form as a dict that can be serialized to JSON.

set_parameter(key: str, value, units: str = 'dimensionless', index=0)[source]

Add to existing parameters or create a new parameter value.

Parameters

key – Name of parameter
value – New value
units – Units for value
index – If parameter is a list of values, index to set. Otherwise. a list of length of 1 will be created with an index of 0.

Returns

None

Raises

KeyError – If the data structure doesn’t have a spot for parameters. This is likely a more basic problem with the current instance.

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

Bases: DataWrapper

__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.ReactionConfig(data, name='unknown', validation=True)[source]

Bases: ConfigGenerator

__init__(data, name='unknown', validation=True)[source]

Constructor.

Parameters

data – Input data
name – Name of the component, e.g. “H2O”
validation – If True, perform schema validation against input.

Raises

ValidationError – If the input is bad.

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

Bases: object

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]

class watertap.edb.data_model.ThermoConfig(data, name='unknown', validation=True)[source]

Bases: ConfigGenerator

__init__(data, name='unknown', validation=True)[source]

Constructor.

Parameters

data – Input data
name – Name of the component, e.g. “H2O”
validation – If True, perform schema validation against input.

Raises

ValidationError – If the input is bad.

watertap.edb.data_model.field(f)[source]: Clean way to use a field in block (see code below for lots of examples).

watertap.edb.db_api module

Database operations API

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

Bases: object

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

watertap.edb.error module

Error classes and utilities for the electrolyte database (EDB).

exception watertap.edb.error.BadConfiguration(whoami: str, config: Dict, missing: Optional[str] = None, why: Optional[str] = None)[source]

Bases: DataWrapperError

Bad configuration provided to build a DataWrapper class.

__init__(whoami: str, config: Dict, missing: Optional[str] = None, why: Optional[str] = None)[source]

exception watertap.edb.error.ConfigGeneratorError[source]

Bases: Error

Base class of errors for ConfigGenerator actions and effects.

exception watertap.edb.error.DataWrapperError[source]

Bases: Error

“Base class of errors for DataWrapper actions and effects.

exception watertap.edb.error.Error[source]

Bases: Exception

Abstract base class for all EDB errors.

exception watertap.edb.error.ValidationError(err)[source]

Bases: Error

Validation error.

__init__(err)[source]

watertap.edb.schemas module

JSON schema embedded as variables for:

component
reaction

watertap.edb.validate module

Validate input for electrolyte database.

watertap.edb.validate.validate(obj: Union[Dict, TextIO, Path, str, DataWrapper], obj_type='')[source]

Validate an input.

Parameters

obj – Input data, file, path, or DataWrapper to validate.
obj_type – Either ‘component’ or ‘reaction’. Ignored for DataWrapper inputs.

Raises

TypeError – If ‘obj’ is not an acceptable type of object
ValueError – If the ‘obj_type’ is not valid
ValidationError – If validation fails

Module contents

Electrolyte database.

Design:

 ┌────────────────────────────┐
 │           Validate         │
 │  ┌───────┐    ┌──────┐     │
 │  │JSON   │    │JSON  │     │
 │  │input  │    │schema│     │
 │  │data   │    │      │     │
 │  └───────┴┐ ┌─┴──────┘     │
 │           │ │              │
 │        ┌──▼─▼───┐          │
 │        │        │NO        │
 │        │ VALID? ├───►Error │
 │        └────┬───┘          │
 │             │              │
 │             │YES           │
 └─────────────┼──────────────┘
               │                      ┌───────────────┐
 DB API........│.....                 │  reaction     │
    ...    ┌───▼───┐ ..    ;;;;;;;;   ├───────────────┤
   ..      │Load   ├──.───►;      ;   │  component    │
  ..       └───────┘  .    ; DB   ;───┼───────────────┤
 .          ▲         ..   ;      ;   │  base         │
..          │          .   ;;;;;;;;   ├───────────────┤
.           │           ...           └───────────────┘
.           │              ...        ...........................
.   ┌───────▼┐    ┌─────────┐...    ...──────────┐   ┌───────────...
.   │ Search ├───►│ Fetch   │  .   .. │ Component◄──o│ HasConfig │ .
..  └────────┘    └────┬────┘  .  ..  └──────▲───┘   └───o───────┘  .
 ...                   │      .  ..          │           │          .
    ...                │    ...  .           │           │         ..
       .....           │  ...   ..   ┌───────x───┐       │         .
             . ... .. .│...     .    │ Reaction  │◄──────┘        ..
                       │        .    └─────▲─────┘                .
                       │        .          │                    ..
                       │        .  **┌─────x───┐               ..
                       └─────────.──►│ Result  │     Data model
                                 ... └─────────┘            ..
                                   .....                ....
                                        ............ ...