plexosdb

Notes

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

add_band(data_id, band_id, /, *, state=None)#

Add a band to a property data record.

Parameters:

data_id (int) – ID of the data record to add the band to
band_id (int) – ID of the band to add
state (int | None, optional) – State value, by default None

Return type:

None

add_category(class_enum, /, name)#

Add a new category for a given class.

Creates a new category for the specified class. If the category already exists, it returns the ID of the existing category.

Parameters:

class_name (ClassEnum) – Class enumeration for the category, e.g., for generators use ClassEnum.Generator
name (str) – Name of the category to be added
class_enum (ClassEnum)

Returns:

The ID of the created or existing category

Return type:

See also

check_category_exists: Check if a category exists for a specific class
get_category_id: Get the ID for an existing category
get_category_max_id: Get the maximum rank ID for a class’s categories
get_class_id: Get the ID for a class

Notes

The database schema does not enforce uniqueness on the class_id, which means multiple categories with the same name can exist for different classes. The category’s unique identifier is automatically handled by the database.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_category("mycategory", ClassEnum.Generator)
1

add_custom_column(class_enum, name, /, *, position=None)#

Add a custom column to a class.

Parameters:

class_enum (ClassEnum)
name (str)
position (int | None)

Return type:

add_datafile_tag(data_id, file_path, /, *, description=None)#

Add a Data File tag to a property data record.

Parameters:

data_id (int)
file_path (str)
description (str | None)

Return type:

add_membership(parent_class_enum, child_class_enum, parent_object_name, child_object_name, collection_enum)#

Add a membership between two objects for a given collection.

Creates a relationship between parent and child objects within the specified collection.

Parameters:

parent_class_enum (ClassEnum) – Class enumeration of the parent object
child_class_enum (ClassEnum) – Class enumeration of the child object
parent_object_name (str) – Name of the parent object
child_object_name (str) – Name of the child object
collection_enum (CollectionEnum) – Collection enumeration defining the relationship type

Returns:

ID of the created membership

Return type:

See also

get_class_id: Get the ID for a class
get_object_id: Get the ID for an object
get_collection_id: Get the ID for a collection
get_membership_id: Get the ID for an existing membership

Notes

This method establishes relationships between objects in the PLEXOS model. The database enforces uniqueness for parent-child-collection combinations.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Region, "Parent")
>>> db.add_object(ClassEnum.Node, "Child")
>>> db.add_membership(ClassEnum.Region, ClassEnum.Node, "Parent", "Child")
1

add_memberships_from_records(records, /, *, chunksize=10000)#

Bulk insert multiple memberships from a list of records.

Efficiently adds multiple membership relationships between objects in batches. This method is much more efficient than calling add_membership multiple times.

Parameters:

records (list[dict[str, int]]) – List of membership records. Each record should be a dictionary with these fields: - ‘parent_class_id’: int - ID of the parent class - ‘parent_object_id’: int - ID of the parent object - ‘collection_id’: int - ID of the collection - ‘child_class_id’: int - ID of the child class - ‘child_object_id’: int - ID of the child object
chunksize (int, optional) – Number of records to process in each batch, by default 10_000. Useful for controlling memory usage with large datasets.

Returns:

True if the operation was successful

Return type:

Raises:

KeyError – If any records are missing required fields

See also

add_membership: Add a single membership between two objects
check_memberships_from_records: Validate membership records format
create_membership_record: Helper to create membership record dictionaries

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> # Create parent and children objects
>>> parent_id = db.add_object(ClassEnum.Region, "Region1")
>>> child_ids = []
>>> for i in range(5):
...     child_ids.append(db.add_object(ClassEnum.Node, f"Node{i}"))
>>> # Prepare membership records
>>> parent_class_id = db.get_class_id(ClassEnum.Region)
>>> child_class_id = db.get_class_id(ClassEnum.Node)
>>> collection_id = db.get_collection_id(
...     CollectionEnum.RegionNodes,
...     parent_class_enum=ClassEnum.Region,
...     child_class_enum=ClassEnum.Node,
... )
>>> # Create records
>>> records = []
>>> for child_id in child_ids:
...     records.append(
...         {
...             "parent_class_id": parent_class_id,
...             "parent_object_id": parent_id,
...             "collection_id": collection_id,
...             "child_class_id": child_class_id,
...             "child_object_id": child_id,
...         }
...     )
>>> # Bulk insert all memberships at once
>>> db.add_memberships_from_records(records)
True

add_metadata(entity_type, entity_id, class_name, property_name, value, /, *, state=None)#

Add metadata to an entity (object, membership, or data).

Parameters:

entity_type (Literal['object', 'membership', 'data'])
entity_id (int)
class_name (str)
property_name (str)
value (str)
state (int | None)

Return type:

None

add_object(class_enum, /, name, *, description=None, category=None, collection_enum=None)#

Add an object to the database and append a system membership.

Creates a new object in the database with the given name and class. Automatically creates a system membership for the object.

Parameters:

name (str) – Name of the object to be added
class_enum (ClassEnum) – Class enumeration of the object, e.g., ClassEnum.Generator for a generator object
category (str, optional) – Category of the object, by default “-”
description (str | None, optional) – Description of the object, by default None
collection_enum (CollectionEnum | None, optional) – Collection for the system membership. If None, a default collection is determined based on the class, by default None

Returns:

ID of the created object

Return type:

Raises:

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

See also

check_category_exists: Check if a category exists for a specific class
add_category: Add a new category for a given class
get_default_collection: Get the default collection for a class
add_membership: Add a membership between two objects

Notes

All objects need to have a system membership. If you want to add additional membership(s) to other object(s), consider add_membership or add_memberships.

The database enforces uniqueness on the combination of name and class_id.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> object_id = db.add_object("TestGenerator", ClassEnum.Generator)
1

add_objects(*object_names, class_enum, category=None)#

Add multiple objects of the same class to the database in bulk.

This method efficiently adds multiple objects to the database in a single operation, which is much more performant than calling add_object() multiple times. It also creates system memberships for all objects in bulk.

Parameters:

object_names (Iterable[str]) – Names of the objects to be added
class_enum (ClassEnum) – Class enumeration of the objects
category (str | None, optional) – Category of the objects, by default None (which uses “-” as default category)

Return type:

None

See also

add_object: Add a single object
add_memberships_from_records: Add multiple memberships in bulk
normalize_names: Normalize object names for consistency
get_default_collection: Get the default collection for a class

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> # Add multiple generators at once
>>> generator_names = ["Gen1", "Gen2", "Gen3", "Gen4", "Gen5"]
>>> db.add_objects(generator_names, class_enum=ClassEnum.Generator, category="Thermal")

add_properties_from_records(records, /, *, object_class, parent_class=ClassEnum.System, parent_object_name='System', collection, scenario, chunksize=10000)#

Bulk insert multiple properties from a list of records.

Efficiently adds multiple properties to multiple objects in batches using transactions, which is significantly faster than calling add_property repeatedly.

Each record should contain an ‘object_name’ field and property-value pairs. All properties are automatically marked as dynamic and enabled in the database.

Parameters:

records (list[dict]) – List of records where each record is a dictionary with: - ‘object_name’: str - Name of the object - property1: value1, property2: value2, … - Property name-value pairs
object_class (ClassEnum) – Class enumeration of the objects (e.g., ClassEnum.Generator)
parent_class (ClassEnum, optional) – Parent class enumeration, by default ClassEnum.System
parent_object_name (str, optional) – Name of the parent object, by default “System”
collection (CollectionEnum) – Collection enumeration for the properties (e.g., CollectionEnum.GeneratorProperties)
scenario (str) – Scenario name to associate with all properties
chunksize (int, optional) – Number of records to process in each batch to control memory usage, by default 10_000

Return type:

None

Raises:

ValueError – If records are improperly formatted or missing required fields
KeyError – If an object name doesn’t exist in the database

See also

add_property: Add a single property
check_property_exists: Check if properties exist for a collection
add_memberships_from_records: Bulk insert multiple memberships
prepare_sql_data_params: Utility for preparing SQL parameters from records

Notes

This method uses SQLite transactions to ensure all insertions are atomic. If an error occurs during processing, the entire transaction is rolled back.

Properties are inserted directly using SQL for optimal performance, and all added properties are automatically marked as dynamic and enabled.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> # Create objects first
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.add_object(ClassEnum.Generator, "Generator2")
>>> # Prepare property records
>>> records = [
...     {"object_name": "Generator1", "Max Capacity": 100.0, "Min Stable Level": 20.0},
...     {"object_name": "Generator2", "Max Capacity": 150.0, "Min Stable Level": 30.0},
... ]
>>> # Add properties in bulk
>>> db.add_properties_from_records(
...     records,
...     object_class=ClassEnum.Generator,
...     collection=CollectionEnum.GeneratorProperties,
...     scenario="Base Case",
... )

add_property(object_class_enum, /, object_name, name, value, *, scenario=None, band=None, date_from=None, text=None, collection_enum=None, parent_class_enum=None, parent_object_name=None)#

Add a property for a given object in the database.

Adds a property with the specified value to an object, optionally associating it with a scenario, band, date range, and text data.

Parameters:

object_class_enum (ClassEnum) – Class enumeration of the object
object_name (str) – Name of the object to add the property to
name (str) – Name of the property to add
value (str | int | float) – Value to assign to the property
scenario (str | None, optional) – Name of the scenario to associate with this property, by default None
band (str | int | None, optional) – Band to associate with this property, by default None
date_from (str | None, optional) – Start date for this property, by default None
date_to (str | None, optional) – End date for this property, by default None
text (dict[ClassEnum, Any] | None, optional) – Additional text data to associate with this property, by default None
collection_enum (CollectionEnum | None, optional) – Collection enumeration for the property. If None, a default is determined based on the object class, by default None
parent_class_enum (ClassEnum | None, optional) – Class enumeration of the parent object. If None, defaults to ClassEnum.System, by default None
parent_object_name (str | None, optional) – Name of the parent object. If None, defaults to “System”, by default None

Returns:

ID of the created property data record

Return type:

Raises:

NameError – If the property name does not exist for the specified collection If the object name does not exist

See also

get_object_id: Get the ID for an object
get_default_collection: Get the default collection for a class
list_valid_properties: List valid property names for a collection
get_property_id: Get the ID for a property
get_membership_id: Get the ID for a membership
check_scenario_exists: Check if a scenario exists
add_object: Add a new object to the database

Notes

The method validates that the property name is valid for the given collection. If a scenario is provided but doesn’t exist, it will be created automatically. Text data can include additional information associated with different classes.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.add_property(ClassEnum.Generator, "Generator1", "Max Capacity", 100.0)
1

add_report(*, object_name, property, collection, parent_class, child_class, phase_id=4, report_period=None, report_summary=True, report_statistics=None, report_samples=None, write_flat_files=False)#

Add a report configuration to the database.

Creates a new report in the database with the specified properties and output options. Reports define what data will be available for post-processing after simulation runs.

Parameters:

object_name (str) – Name of the report object to add the configuration to
property (str) – Name of the property to report on
collection (CollectionEnum) – Collection enumeration that contains the property
parent_class (ClassEnum) – Parent class enumeration for the collection
child_class (ClassEnum) – Child class enumeration for the collection
phase_id (int, optional) – Phase ID for the report (1=ST, 2=MT, 3=PASA, 4=LT), by default 4 (Long Term)
report_period (bool | None, optional) – Whether to report period data, by default None
report_summary (bool | None, optional) – Whether to report summary data, by default True
report_statistics (bool | None, optional) – Whether to report statistics, by default None
report_samples (bool | None, optional) – Whether to report samples, by default None
write_flat_files (bool, optional) – Whether to output flat files, by default False

Raises:

NameError – If the specified property does not exist for the collection

Return type:

None

See also

get_object_id: Get the ID for an object
get_collection_id: Get the ID for a collection
list_valid_properties_report: List valid report properties for a collection

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Report, "GeneratorOutput")
>>> db.add_report(
...     object_name="GeneratorOutput",
...     property="Generation",
...     collection=CollectionEnum.Generators,
...     parent_class=ClassEnum.System,
...     child_class=ClassEnum.Generator,
...     report_period=True,
...     report_summary=True,
... )

add_scenario(name, category=None)#

Add a scenario object in the database.

Parameters:

name (str) – Name of the scenario
category (str | None) – Name of the category for the scenario

Return type:

See also

get_scenario_id: Get the ID for a scenario
list_scenarios: List all available scenarios in the database

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_scenario("TestScenario")
>>> db.list_scenarios()
[("TestScenario")]

add_text(text_class, text_value, data_id)#

Add text data to a property data record.

Parameters:

text_class (ClassEnum) – Name of the Text class to be added
text_value (str) – Value of the text to be added
data_id (int) – Data to be tagged with the Text object

Raises:

AssertionError – If the class does not exist

Returns:

True if the query was succesfull

Return type:

add_time_slice(name, /, *, interval, start_datetime, end_datetime, description=None)#

Add a time slice definition to the database.

Parameters:

name (str)
interval (str)
start_datetime (str)
end_datetime (str)
description (str | None)

Return type:

add_variable_tag(data_id, variable_name, /, *, value=None)#

Add a Variable tag to a property data record.

Parameters:

data_id (int)
variable_name (str)
value (str | float | None)

Return type:

backup_database(target_path)#

Backup the in-memory database to a file.

Parameters:: target_path (str | Path)
Return type:: None

check_attribute_exists(attribute_name, /, *, object_name, object_class)#

Check if an attribute exists for a specific object.

Parameters:

attribute_name (str)
object_name (str)
object_class (ClassEnum)

Return type:

check_category_exists(class_enum, name)#

Check if a category exists for a specific class.

Determines whether a category with the given name exists for the specified class.

Parameters:

class_enum (ClassEnum) – Class enumeration to check the category for
category (str) – Name of the category to check
name (str)

Returns:

True if the category exists, False otherwise

Return type:

See also

get_class_id: Get the ID for a class
add_category: Add a new category

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_category(ClassEnum.Generator, "my_category")
>>> db.check_category_exists(ClassEnum.Generator, "my_category")
True
>>> db.check_category_exists(ClassEnum.Generator, "nonexistent")
False

check_membership_exists(parent_object_name, child_object_name, /, *, parent_class, child_class, collection)#

Check if a membership exists between two objects.

Parameters:

parent_object_name (str)
child_object_name (str)
parent_class (ClassEnum)
child_class (ClassEnum)
collection (CollectionEnum)

Return type:

check_object_exists(class_enum, name)#

Check if an object exists in the database.

Determines whether an object with the given name and class exists.

Parameters:

class_enum (ClassEnum) – Class enumeration of the object
name (str) – Name of the object to check

Returns:

True if the object exists, False otherwise

Return type:

See also

get_class_id: Get the ID for a class
get_object_id: Get the ID for an object
add_object: Add an object to the database

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "TestObject")
>>> db.check_object_exists(ClassEnum.Generator, "TestObject")
True
>>> db.check_object_exists(ClassEnum.Generator, "NonExistent")
False

check_property_exists(collection_enum, /, object_class, property_names, *, parent_class=None)#

Check if properties exist for a specific collection and class.

Verifies that all specified property names are valid for the given collection and class.

Parameters:

collection_enum (CollectionEnum) – Collection enumeration the properties should belong to
object_class (ClassEnum) – Class enumeration of the object
property_names (str | Iterable[str]) – Property name or names to check
parent_class (ClassEnum | None, optional) – Class enumeration of the parent object, by default None

Returns:

True if all properties exist, False otherwise

Return type:

See also

list_valid_properties: Get list of valid property names for a collection
normalize_names: Normalize property names for checking

Notes

If any property in the list is invalid, the function returns False and logs the invalid properties.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.check_property_exists(CollectionEnum.Generators, ClassEnum.Generator, "Max Capacity")
True
>>> db.check_property_exists(CollectionEnum.Generators, ClassEnum.Generator, ["Invalid Property"])
False

check_scenario_exists(name)#

Check if a scenario exists in the database.

Determines whether a scenario with the given name exists.

Parameters:: name (str) – Name of the scenario to check
Returns:: True if the scenario exists, False otherwise
Return type:: bool

See also

get_class_id: Get the ID for a class
ClassEnum.Scenario: Scenario class enumeration

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object("Base Scenario", ClassEnum.Scenario)
>>> db.check_scenario_exists("Base Scenario")
True
>>> db.check_scenario_exists("Nonexistent Scenario")
False

copy_object(object_class, original_object_name, new_object_name, copy_properties=True)#

Copy an object and its properties, tags, and texts.

Parameters:

object_class (ClassEnum)
original_object_name (str)
new_object_name (str)
copy_properties (bool)

Return type:

copy_object_memberships(object_class, original_name, new_name)#

Copy all existing memberships of old object to the new object.

Parameters:

original_name (str)
new_name (str)

Return type:

dict[int, int]

create_object_scenario(object_name, scenario_name, properties, /, *, object_class, description=None, collection=None, parent_class=None, base_scenario=None)#

Create a new scenario with specific property values for an object.

Parameters:

object_name (str)
scenario_name (str)
properties (dict[str, Any])
object_class (ClassEnum)
description (str | None)
collection (CollectionEnum | None)
parent_class (ClassEnum | None)
base_scenario (str | None)

Return type:

create_schema(schema=None)#

Create database schema from SQL script.

Initializes the database schema by executing SQL statements, either from the default schema or from a provided schema string.

Parameters:: schema (str | None, optional) – Direct SQL schema content to execute. If None, uses the default schema, by default None
Returns:: True if the creation succeeded, False if it failed
Return type:: bool

See also

_db.executescript: Execute a SQL script in the database
PLEXOS_DEFAULT_SCHEMA: Default schema SQL content

Notes

This is typically the first method called after initializing a new PlexosDB instance, as it sets up all the required tables for the database.

Examples

>>> db = PlexosDB()
>>> db.create_schema()
True

delete_attribute(attribute_name, /, *, object_name, object_class)#

Delete an attribute from an object.

Parameters:

attribute_name (str)
object_name (str)
object_class (ClassEnum)

Return type:

None

delete_category(category, /, *, class_name)#

Delete a category from the database.

Parameters:

category (str)
class_name (ClassEnum)

Return type:

None

delete_membership(parent_object_name, child_object_name, /, *, parent_class, child_class, collection)#

Delete a membership between two objects.

Parameters:

parent_object_name (str)
child_object_name (str)
parent_class (ClassEnum)
child_class (ClassEnum)
collection (CollectionEnum)

Return type:

None

delete_metadata(entity_type, entity_id, class_name, property_name)#

Delete metadata from an entity.

Parameters:

entity_type (Literal['object', 'membership', 'data'])
entity_id (int)
class_name (str)
property_name (str)

Return type:

None

delete_object(object_name, /, *, class_enum, cascade=True)#

Delete an object from the database.

Parameters:

object_name (str)
class_enum (ClassEnum)
cascade (bool)

Return type:

None

delete_property(property_name, /, *, object_name, object_class, collection, parent_class=None, scenario=None)#

Delete a property from an object.

Parameters:

property_name (str)
object_name (str)
object_class (ClassEnum)
collection (CollectionEnum)
parent_class (ClassEnum | None)
scenario (str | None)

Return type:

None

delete_text(data_id, /, *, class_id)#

Delete text data from a property data record.

Parameters:

data_id (int)
class_id (int)

Return type:

None

classmethod from_xml(xml_path, schema=None, **kwargs)#

Construct a PlexosDB instance from an XML file.

This factory method creates a new PlexosDB instance and populates it with data from the provided XML file. It creates the database schema and processes all valid XML elements into their corresponding database tables.

Parameters:

xml_path (str | Path) – Path to the XML file to import data from
schema (str | None) – SQL schema to initialize the database
**kwargs (dict) – Additional keyword arguments to pass to the PlexosDB constructor

Returns:

A new PlexosDB instance initialized with data from the XML file

Return type:

PlexosDB

Raises:

FileNotFoundError – If the specified XML file does not exist

See also

PlexosDB: PLEXOS SQLite manager
create_schema: Creates the database schema
XMLHandler.parse: Parses the XML file
str2enum: Converts XML tag names to schema enumerations

Notes

This method groups records by their column structure to handle varying record formats in the XML data. Each group of records with consistent structure is processed separately to avoid SQL errors from column mismatches.

This constructor assumes we are creating a new database. If you want to add data to an existing database, you should use other methods.

Examples

>>> db = PlexosDB.from_xml("model.xml")
>>> print(db.version)
'8.3.0'

get_attribute(object_class, /, *, object_name, attribute_name)#

Get attribute details for a specific object.

Parameters:

object_class (ClassEnum)
object_name (str)
attribute_name (str)

Return type:

dict

get_attribute_id(class_enum, /, name)#

Return the ID for a given attribute.

Retrieves the unique identifier for an attribute with the specified name and class.

Parameters:

class_enum (ClassEnum) – Class enumeration the category belongs to
name (str) – Name of the attribute

Returns:

ID of the category

Return type:

Raises:

AssertionError – If the category does not exist

get_attributes(object_name, /, *, object_class, attribute_names=None)#

Get all attributes for a specific object.

Parameters:

object_name (str)
object_class (ClassEnum)
attribute_names (list[str] | None)

Return type:

get_category_id(class_enum, /, name)#

Return the ID for a given category.

Retrieves the unique identifier for a category with the specified name and class.

Parameters:

category (str) – Name of the category
class_enum (ClassEnum) – Class enumeration the category belongs to
name (str)

Returns:

ID of the category

Return type:

Raises:

AssertionError – If the category does not exist

See also

check_category_exists: Check if a category exists
add_category: Add a new category

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_category(ClassEnum.Generator, "my_category")
>>> db.get_category_id(ClasEnum.Generator, "my_category")
1

get_category_max_id(class_enum)#

Return the current maximum rank for a given category class.

Determines the highest rank value currently assigned to any category of the specified class, useful for adding new categories with unique ranks.

Parameters:: class_enum (ClassEnum) – Class enumeration to check
Returns:: Maximum rank value for the class’s categories
Return type:: int
Raises:: AssertionError – If the query fails

See also

add_category: Add a new category

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_category("Category1", ClassEnum.Generator)
>>> db.get_category_max_id(ClassEnum.Generator)
1

get_class_id(class_enum)#

Return the ID for a given class.

Retrieves the unique identifier for the specified class enumeration.

Parameters:: class_enum (ClassEnum) – Class enumeration to get the ID for
Returns:: ID of the class
Return type:: int
Raises:: AssertionError – If the class does not exist

See also

ClassEnum: Enumeration of available classes

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.get_class_id(ClassEnum.Generator)
15  # Example ID

get_collection_id(collection, /, parent_class_enum, child_class_enum)#

Return the ID for a given collection.

Retrieves the unique identifier for a collection based on its name and associated parent and child classes.

Parameters:

collection (CollectionEnum) – Collection enumeration to get the ID for
parent_class_enum (ClassEnum) – Parent class enumeration for the collection
child_class_enum (ClassEnum) – Child class enumeration for the collection

Returns:

ID of the collection

Return type:

Raises:

AssertionError – If the collection does not exist with the specified parent and child classes

See also

CollectionEnum: Enumeration of available collections
get_class_id: Get the ID for a class

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.get_collection_id(CollectionEnum.SystemGenerators, ClassEnum.System, ClassEnum.Generator)
25  # Example ID

get_config(element=None)#

Get configuration values from the database.

Parameters:: element (str | None)
Return type:: dict | list[dict]

get_custom_columns(class_enum=None)#

Get custom columns, optionally filtered by class.

Parameters:: class_enum (ClassEnum | None)
Return type:: list[dict]

get_membership_id(parent_name, child_name, collection)#

Return the ID for a given membership.

Retrieves the unique identifier for a membership between parent and child objects in the specified collection.

Parameters:

parent_name (str) – Name of the parent object
child_name (str) – Name of the child object
collection (CollectionEnum) – Collection enumeration defining the relationship type

Returns:

ID of the membership

Return type:

Raises:

AssertionError – If the membership does not exist

See also

add_membership: Add a new membership between objects

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.System, "System")
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.add_membership(
...     "System", "Generator1", ClassEnum.System, ClassEnum.Generator, CollectionEnum.SystemGenerators
... )
>>> db.get_membership_id("System", "Generator1", CollectionEnum.SystemGenerators)
1

get_memberships_system(*object_names, object_class, category=None, collection=None)#

Retrieve system memberships for the given object(s).

Parameters:

object_names (str or list[str]) – Name or list of names of the objects to get their memberships. You can pass multiple string arguments or a single list of strings.
object_class (ClassEnum) – Class of the objects.
collection (CollectionEnum | None, optional) – Collection to filter memberships.
category (str | None)

Returns:

A list of tuples representing memberships of the object to the system.

Return type:

list[tuple]

Raises:

KeyError – If any of the object_names do not exist.

get_metadata(entity_type, entity_id, /, *, class_name=None, property_name=None)#

Retrieve metadata for an entity.

Parameters:

entity_type (Literal['object', 'membership', 'data'])
entity_id (int)
class_name (str | None)
property_name (str | None)

Return type:

get_object_data_ids(class_enum, /, name, property_names=None, *, parent_class_enum=ClassEnum.System, collection_enum=None, category=None)#

Get all the data_id values for a given object in the database.

Retrieves all data IDs that match the specified criteria for an object, optionally filtered by property names, parent class, collection, and category.

Parameters:

class_enum (ClassEnum) – Class enumeration of the object
name (str) – Name of the object to retrieve data IDs for
property_names (str | Iterable[str] | None, optional) – Names of specific properties to filter by, by default None
parent_class_enum (ClassEnum, optional) – Parent class enumeration, by default ClassEnum.System
collection_enum (CollectionEnum | None, optional) – Collection enumeration to filter by, by default None (if not specified, the default collection for the class is used)
category (str | None, optional) – Category to filter by, by default None

Returns:

List of data_id values that match the criteria

Return type:

list[int]

Raises:

KeyError – If the specified category does not exist
NameError – If any specified property does not exist for the collection

See also

check_property_exists: Check if properties exist for a collection
check_category_exists: Check if a category exists
list_valid_properties: List valid property names for a collection

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.add_property(ClassEnum.Generator, "Generator1", "Max Capacity", 100.0)
>>> db.get_object_data_ids(ClassEnum.Generator, "Generator1")
[1]

get_object_id(class_enum, /, name, *, category=None)#

Return the ID for a given object.

Retrieves the unique identifier for an object with the specified name and class, optionally filtering by category.

Parameters:

object_name (str) – Name of the object
class_enum (ClassEnum) – Class enumeration of the object
category (str | None, optional) – Category name to filter by, by default None
name (str)

Returns:

ID of the object

Return type:

Raises:

AssertionError – If the object does not exist
KeyError – If no object matches the criteria

See also

check_object_exists: Check if an object exists
add_object: Add a new object to the database
get_category_id: Get the ID for a category

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "Generator1" category="Thermal")
>>> db.get_object_id("Generator1", ClassEnum.Generator)
1

get_object_memberships(*object_names, class_enum, parent_class_enum=None, category=None, collection_enum=None, include_system_membership=False)#

Retrieve all memberships for the given object(s).

Parameters:

object_names (str or list[str]) – Name or list of names of the objects to get their memberships. You can pass multiple string arguments or a single list of strings.
class_enum (ClassEnum) – Class of the objects.
parent_class_enum (ClassEnum | None, optional) – Class of the parent object. Defaults to object_class if not provided.
collection (CollectionEnum | None, optional) – Collection to filter memberships.
include_system_membership (bool, optional) – If False (default), exclude system memberships (where parent_class is System). If True, include them.
category (str | None)
collection_enum (CollectionEnum | None)

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 self.query(query_string=query_string, params=params) parent_class_name, collection_name).

Return type:

list[tuple]

Raises:

KeyError – If any of the object_names do not exist.

get_object_properties(class_enum, /, name, property_names=None, *, parent_class_enum=None, collection_enum=None, category=None, chunk_size=1000)#

Retrieve properties for a specific object with efficient memory handling.

Gets properties for the specified object, with support for chunked processing to prevent memory issues when dealing with large datasets.

Parameters:

class_enum (ClassEnum) – Class enumeration of the object
name (str) – Name of the object to retrieve properties for
property_names (str | Iterable[str] | None, optional) – Names of specific properties to retrieve. If None, gets all properties, by default None
parent_class_enum (ClassEnum | None, optional) – Parent class enumeration for filtering properties, by default None (defaults to ClassEnum.System if not specified)
collection_enum (CollectionEnum | None, optional) – Collection enumeration to filter properties by, by default None (if not specified, the default collection for the class is used)
category (str | None, optional) – Category to filter by, by default None
chunk_size (int, optional) – Number of data IDs to process in each chunk, by default 1000

Returns:

List of dictionaries containing property information with keys: - name: Object name - property: Property name - value: Property value - unit: Unit of measurement - texts: Associated text data - tags: Associated tags - bands: Associated bands - scenario: Associated scenario name - scenario_category: Category of the associated scenario

Return type:

Raises:

NameError – If the specified property does not exist for the collection
KeyError – If the specified category does not exist

See also

get_data_ids: Get data IDs for an object
check_property_exists: Check if properties exist for a collection
list_valid_properties: List valid property names for a collection

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.add_property(ClassEnum.Generator, "Generator1", "Max Capacity", 100.0)
>>> properties = db.get_object_properties(ClassEnum.Generator, "Generator1")
>>> properties[0]["property"]
'Max Capacity'
>>> properties[0]["value"]
100.0

get_objects_id(*object_names, class_enum)#

Get object_ids for a list of names for a given class.

Parameters:

object_names (Iterable[str] | str)
class_enum (ClassEnum)

Return type:

list[int]

get_plexos_version()#

Return the version information of the PLEXOS model.

Return type:: tuple[int, …] | None

get_property_id(property_name, /, *, collection_enum, child_class_enum, parent_class_enum=None)#

Return the ID for a given property.

Retrieves the unique identifier for a property based on its name and associated collection and classes.

Parameters:

property_name (str) – Name of the property
collection_enum (CollectionEnum) – Collection enumeration the property belongs to
child_class_enum (ClassEnum) – Child class enumeration for the property
parent_class_enum (ClassEnum | None, optional) – Parent class enumeration for the property, by default None

Returns:

ID of the property

Return type:

Raises:

AssertionError – If the property does not exist

See also

get_collection_id: Get the ID for a collection
list_valid_properties: List valid property names for a collection

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.get_property_id(
...     "Max Capacity",
...     collection_enum=CollectionEnum.GeneratorProperties,
...     child_class_enum=ClassEnum.Generator,
...     parent_class_enum=ClassEnum.System,
... )
42  # Example ID

get_property_unit(property_name, /, collection_enum, parent_class_enum, child_class_enum)#

Get the unit for a specific property.

Parameters:

property_name (str)
collection_enum (CollectionEnum)
parent_class_enum (ClassEnum)
child_class_enum (ClassEnum)

Return type:

str

get_scenario_id(name)#

Return the ID for a given scenario.

Retrieves the object id for a scenario based on its name.

Parameters:: name (str) – Name of the scenario
Returns:: ID of the property
Return type:: int
Raises:: AssertionError – If the property does not exist

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_scenario("TestScenario")
42  # Example ID
>>> db.get_scenario_id("TestScenario")
42

get_text(data_id, /, *, class_id=None)#

Retrieve text data associated with a property data record.

Parameters:

data_id (int)
class_id (int | None)

Return type:

get_unit(unit_id)#

Get details for a specific unit.

Parameters:: unit_id (int)
Return type:: dict

has_properties(class_enum, /, name, *, collection_enum=None, category=None)#

Check if the given object has any properties associated with it.

Determines whether an object has any properties in the database that match the specified criteria, optionally filtered by collection and category.

Parameters:

class_enum (ClassEnum) – Class enumeration of the object
name (str) – Name of the object to check
collection_enum (CollectionEnum | None, optional) – Collection enumeration to filter by, by default None (if not specified, the default collection for the class is used)
category (str | None, optional) – Category to filter by, by default None

Returns:

True if the object has at least one property matching the criteria, False otherwise

Return type:

Raises:

KeyError – If the specified category does not exist

See also

get_object_properties: Get properties for an object
check_category_exists: Check if a category exists
get_default_collection: Get the default collection for a class

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object(ClassEnum.Generator, "Generator1")
>>> db.has_properties(ClassEnum.Generator, "Generator1")
False
>>> db.add_property(ClassEnum.Generator, "Generator1", "Max Capacity", 100.0)
>>> db.has_properties(ClassEnum.Generator, "Generator1")
True

import_from_csv(source_path, /, *, tables=None)#

Import data from CSV files into the database.

Parameters:

source_path (str | Path)
tables (list[str] | None)

Return type:

None

iterate_properties(class_enum, /, *, object_names=None, property_names=None, parent_class=None, collection=None, chunk_size=1000)#

Iterate through properties with chunked processing to handle large datasets efficiently.

Parameters:

class_enum (ClassEnum)
object_names (str | Iterable[str] | None)
property_names (str | Iterable[str] | None)
parent_class (ClassEnum | None)
collection (CollectionEnum | None)
chunk_size (int)

Return type:

Iterator[dict]

list_attributes(class_enum)#

Get all attributes for a specific class.

Retrieves the names of attributes associated with the specified class.

Parameters:: class_enum (ClassEnum) – Class enumeration to list categories for
Returns:: List of attributes names
Return type:: list[str]
Raises:: AssertionError – If the query fails

list_categories(class_enum)#

Get all categories for a specific class.

Retrieves the names of all categories associated with the specified class.

Parameters:: class_enum (ClassEnum) – Class enumeration to list categories for
Returns:: List of category names
Return type:: list[str]
Raises:: AssertionError – If the query fails

See also

add_category: Add a new category
check_category_exists: Check if a category exists

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_category("Thermal", ClassEnum.Generator)
>>> db.add_category("Renewable", ClassEnum.Generator)
>>> db.list_categories(ClassEnum.Generator)
['Thermal', 'Renewable']

list_child_objects(object_name, /, *, parent_class, child_class=None, collection=None)#

List all child objects for a given parent object.

Parameters:

object_name (str)
parent_class (ClassEnum)
child_class (ClassEnum | None)
collection (CollectionEnum | None)

Return type:

list_classes()#

Return all classes names in the database.

Returns:: List of valid classes names
Return type:: list[str]
Raises:: AssertionError – If the query fails

See also

query: Query the SQL database

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.list_classes()
["System", "Generator", ...]

list_collections(*, parent_class=None, child_class=None)#

List all available collections in the database.

Parameters:

parent_class (ClassEnum | None, optional) – Filter by parent class, by default None
child_class (ClassEnum | None, optional) – Filter by child class, by default None

Returns:

List of collections with their details including id, name, parent_class, child_class, description, etc.

Return type:

list_models()#

Return all models in the database.

Return type:: list[dict]

list_objects_by_class(class_enum, /, *, category=None)#

Return all objects of a specific class.

Retrieves names of all objects belonging to the specified class, optionally filtered by category.

Parameters:

class_enum (ClassEnum) – Class enumeration to filter oRaises
category (str | None, optional) – Category name to filter by, by default None

Raises:

AssertionError – If the query fails

Return type:

See also

get_class_id: Get the ID for a class
add_object: Add an object to the database
query: Query the SQL database bjects by

Returns:

List of object names

Return type:

Raises:

AssertionError – If the query fails

Parameters:

class_enum (ClassEnum)
category (str | None)

See also

get_class_id: Get the ID for a class
add_object: Add an object to the database
query: Query the SQL database

Examples

>>> db = PlexosDB()
>>> db.create_schema()
>>> db.add_object("Generator1", ClassEnum.Generator)
>>> db.add_object("Generator2", ClassEnum.Generator)
>>> db.list_objects_by_class(ClassEnum.Generator)
['Generator1', 'Generator2']

list_parent_objects(object_name, /, *, child_class, parent_class=None, collection=None)#

List all parent objects for a given child object.

Parameters:

object_name (str)
child_class (ClassEnum)
parent_class (ClassEnum | None)
collection (CollectionEnum | None)

Return type: