plexosdb

plexosdb#

Simple interface with the Plexos database.

class plexosdb.sqlite.PlexosSQLite(xml_fname=None, xml_handler=None, create_collations=True)#

Class that wraps the connection to the SQL database.

Since we always start from a file XML, the default behaviour is to create an in-memory representation of the database. The usage is not to persist it into disk since the output file is always a XML, but it is possible by using the method backup.

Parameters:

  • xml_fname (str | None)

  • xml_handler (XMLHandler | None)

  • create_collations (bool)

add_attribute(*, object_name, object_class, attribute_class, attribute_name, attribute_value)#

Add attribute to a given object.

Attributes are different from properties. They live on a separate table and are mostly used for model configuration.

Parameters:

  • object_name (str) – Name to be added to the object

  • class_id (ClassEnum) – ClassEnum from the object to be added. E.g., for generators class_id=ClassEnum.Generators

  • collection_id (CollectionEnum) – Collection for system membership. E.g., for generators class_enum=CollectionEnum.SystemGenerators

  • object_class (ClassEnum) – ClassEnum from the object to be added. E.g., for generators class_id=ClassEnum.Generators

  • attribute_class (ClassEnum) – Class of the attribute to be added

  • attribute_name (str) – Valid name of the attribute to be added for the given class

  • attribute_value (str | float | int) – Value to be added to the attribute

Returns:

attribute_id

Return type:

int

Notes

By default, we add all objects to the system membership.

add_category(category_name, /, *, class_name)#

Add a new category for a given class.

Parameters:

  • category_name – Name to be added to the object

  • class_name (ClassEnum) – ClassEnum from the category to be added. E.g., for generators class_name=ClassEnum.Generators

Returns:

category_id

Return type:

int

Raises:

  • KeyError – When the property is not a valid string for the collection.

  • TypeError – If the database could not return the category_id from the connection.

add_membership(parent_object_name, child_object_name, /, *, parent_class, child_class, collection, child_category=None)#

Add a memberships between two objects for a given collection.

Parameter#

parent_object_name

Name to parent

child_object_name

Name of the child

parent_class

Class of to parent

child_class

Class of the child

collection

Collection for membership to be added.

Parameters:

  • parent_class (ClassEnum)

  • child_class (ClassEnum)

  • collection (CollectionEnum)

  • child_category (str | None)

Return type:

int

add_object(object_name, class_name, collection_name, /, *, category_name='-', description=None)#

Add object to the database and append a system membership.

The base type on the plexos database are objects. Each object can have multiple memberships and belong to predetermined class.

Parameters:

  • object_name (str) – Name to be added to the object

  • class_id – ClassEnum from the object to be added. E.g., for generators class_id=ClassEnum.Generators

  • collection_name (CollectionEnum) – Collection for system membership. E.g., for generators class_enum=CollectionEnum.SystemGenerators

  • parent_class_name – Name of the parent class if different from System.

  • class_name (ClassEnum)

  • category_name (str)

  • description (str | None)

Notes

By default, we add all objects to the system membership.

Raises:

sqlite.IntegrityError – if an object is inserted without a unique name/class pair

Returns:

object_id

Return type:

int

Parameters:

  • object_name (str)

  • class_name (ClassEnum)

  • collection_name (CollectionEnum)

  • category_name (str)

  • description (str | None)

add_property(object_name, property_name, property_value, /, *, object_class, collection, parent_class=None, parent_object_name=None, scenario=None, text=None)#

Add property for a given object in the database.

Parameters:

  • object_name (str) – Name to be added to the object

  • property_name (str) – Valid plexos property to be added for the given collection

  • property_value (str | int | float) – Value to assign to the property

  • object_class (ClassEnum) – ClassEnum from the object to be added. E.g., for generators class_id=ClassEnum.Generators

  • parent_object_name (str | None) – Name of the parent object. User for creating the membership.

  • collection (CollectionEnum) – Collection for membership

  • scenario (str | None) – Scenario tag to add to the property

  • text (dict | None) – Additional text to add to the property. E.g., memo data or Data File.

  • parent_class (ClassEnum | None)

Returns:

data_id of the added property.

Return type:

int

Raises:

KeyError – When the property is not a valid string for the collection.

add_property_from_records(records, /, *, parent_class, parent_object_name='System', collection, scenario, chunksize=10000)#

Bulk insert multiple properties from a list of records.

Parameters:

  • records (list[dict])

  • parent_class (ClassEnum)

  • parent_object_name (str)

  • collection (CollectionEnum)

  • scenario (str)

  • chunksize (int)

Return type:

None

check_id_exists(table, object_name, /, *, class_name=None)#

Check if the id exist for the given object and table.

Parameters:

  • table (Schema) – The table from which to retrieve the ID.

  • object_name (ClassEnum) – The name of the object for which to retrieve the ID.

  • class_name (ClassEnum | None)

Returns:

True if the object was found.

Return type:

bool

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given filters.

execute_query(query, params=None)#

Execute of insert query to the database.

Parameters:

query (str)

Return type:

None

get_category_id(category_name, class_name)#

Return the ID for a given category.

Parameters:

  • category_name (str) – Name of the category to retrieve

  • class_name (ClassEnum) – ClassEnum of the class of the category. Used to filter memberships by class_id

Returns:

The ID corresponding to the category, or None if not found.

Return type:

int

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given category.

get_category_max_id(class_enum)#

Return the current max rank for a given category.

Parameters:

class_enum (ClassEnum)

Return type:

int

get_class_id(class_enum)#

Return the ID for a given class.

Parameters:

  • class_name (ClassEnum) – The enum collection from which to retrieve the ID.

  • class_enum (ClassEnum)

Returns:

The ID corresponding to the object, or None if not found.

Return type:

int

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given class.

get_collection_id(collection, parent_class=None, child_class=None)#

Return the ID for a given collection.

Parameters:

  • collection (CollectionEnum) – The enum collection from which to retrieve the ID.

  • parent_class (ClassEnum | None) – ClassEnum of the parent object. Used to filter memberships by parent_class_id

  • Optional – ClassEnum of the parent object. Used to filter memberships by parent_class_id

  • child_class (ClassEnum | None) – ClassEnum of the child object. Used to filter memberships by child_class_id

  • Optional – ClassEnum of the child object. Used to filter memberships by child_class_id

Returns:

The ID corresponding to the object, or None if not found.

Return type:

int

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given parent/child class provided.

get_membership_id(*, child_name, parent_name, child_class, parent_class, collection)#

Return the ID for a given membership.

Parameters:

  • child_name (str) – Name of the child to find. Used to filter child_object_name.

  • parent_name (str) – Name of the parent to find. Used to filter parent_object_name.

  • child_class (ClassEnum) – ClassEnum of the parent object. Used to filter memberships by parent_class_id.

  • parent_class (ClassEnum) – ClassEnum of the class of the category. Used to filter memberships by class_id.

  • collection (CollectionEnum) – The enum collection from which to retrieve the ID. Used to filter by collection_id.

Returns:

The ID corresponding to the object, or None if not found.

Return type:

int

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given parent/child class provided.

get_memberships(*object_names, object_class, parent_class=None, collection=None)#

Retrieve all memberships for the given object except the system membership.

This function returns a list of tuples representing memberships, which can be filtered by parent_class and collection if specified.

Parameters:

  • object_names (list[str]) – Name of the objects to get their memberships

  • object_class (ClassEnum) – Class of the objects

  • parent_class (ClassEnum | None) – Class of the parent object. Used to filter memberships by parent_class_id

  • Optional – Class of the parent object. Used to filter memberships by parent_class_id

  • collection (CollectionEnum | None) – Collection of the memberships. Used to filter memberships by collection_id

  • Optional – Collection of the memberships. Used to filter memberships by collection_id

Returns:

A list of tuples representing memberships. Each tuple is structured as: (parent_class_id, child_class_id, parent_object_name, child_object_name, collection_id).

Return type:

list of tuple

Raises:

  • KeyError – If any of the object_names do not exist or if the object_class is invalid.

  • sqlite3.OperationalError – If there is an error in executing the SQL query.

Examples

>>> db = PlexosSQLite("2-bus_example.xml")
>>> memberships = db.get_memberships("SolarPV_01", "ThermalCC", object_class=ClassEnum.Generators)
>>> print(memberships)
[(parent_class_id, child_class_id, parent_object_name, child_object_name, collection_id)]
get_object_id(object_name, class_name, category_name=None)#

Return the ID for a given object.

Parameters:

  • object_name (str) – Name of the object to find.

  • category_name (str | None) – Name of the category to retrieve

  • class_name (ClassEnum) – ClassEnum of the class of the category. Used to filter memberships by class_id

Returns:

The ID corresponding to the category, or None if not found.

Return type:

int

Raises:

  • KeyError – If ID does not exists on the database.

  • ValueError – If multiple IDs are returned for the given object.

get_property_id(property_name, collection, child_class, parent_class=None)#

Return the ID for a given collection.

Parameters:

  • property_name (str) – Name of the property to retrieve

  • collection (CollectionEnum) – The enum collection from which to retrieve the ID. Used for filter by collection_id.

  • parent_class (ClassEnum | None) – ClassEnum of the parent object. Used to filter memberships by parent_class_id

  • child_class (ClassEnum) – ClassEnum of the child object. Used to filter memberships by child_class_id

Returns:

The ID corresponding to the object, or None if not found.

Return type:

int

Raises:

  • KeyError – If name of the property does not exist for the collection id.

  • ValueError – If multiple IDs are returned for the given parent/child class provided.

get_scenario_id(scenario_name)#

Return scenario id for a given scenario name.

Parameters:

scenario_name (str)

Return type:

int

get_valid_properties(collection, parent_class=None, child_class=None)#

Return list of valid property names per collection.

Parameters:

  • collection (CollectionEnum)

  • parent_class (ClassEnum | None)

  • child_class (ClassEnum | None)

Return type:

list[str]

ingest_from_records(tag, record_data)#

Insert elements from xml to database.

Parameters:
query(query_string, params=None)#

Execute of query to the database.

This function just wraps the functionality of the SQLite API and fetch the results for us.

Parameters:

  • query – String to get passed to the database connector.

  • params – Tuple or dict for passing

  • query_string (str)

Return type:

list[tuple]

Note

We do not valid any query.

This function could be slow depending the complexity of the query passed.

save(fpath)#

Save memory representation to file format.

Parameters:

fpath (Path | str)

to_xml(fpath, namespace='http://tempuri.org/MasterDataSet.xsd')#

Convert SQLite to XML format.

This method takes all the tables of th SQLite and creates the appropiate tags based on the column name.

Parameters:

  • fpath (Path | str) – Path to serialize the database

  • namespace – Plexos MasterDataSet URI

Return type:

None