commonpower.modeling.base.ModelEntity

class ModelEntity(name: str, config: dict = {})

Bases: object

This class abstracts power system entities which have a pyomo model representation. It also bundles all interfaces needed to interact with their model. Subclasses of ModelEntity implement certain methods which specify the model elements associated to instances of that class.

Parameters:

• name (str) – Descriptive name of the entity. It will not be used within the pyomo model and is merely for human interpretability.

• config (dict, optional) – Configuration dict of the entity. The content required depends on the modelling of the specific subclass. Defaults to {}.

Methods

add_data_provider	Adds a data provider to the entity.
add_to_model	This method adds the calling entity to the given (global) pyomo model. To this end, we - declare and add a new pyomo block named by self.id (the entity's global id). - call _get_model_elements() to retrieve the entity's model elements (variables and parameters). - call _augment_model_elements() to add additional model elements (constraints etc.). - check the configuration dict for completeness based on the defined model elements. - add all model elements to the previously declared pyomo block.
clear_data_providers
cost_fcn	Returns the pyomo expression of the entity's cost function.
get_children
get_pyomo_element	Gets a pyomo element referenced by name from the given model.
get_pyomo_element_id	Constructs the global element name from the local name.
get_self_as_pyomo_block	Retrieves the pyomo block of the calling entity from a global model (based on the entity's global id).
get_value	Gets the value of the specified model element.
has_pyomo_element	This is essentially an indicator wrapper around get_pyomo_element() which returns False if no corresponding model element could be found (instead of raising an error).
info	Prints some information about this entity.
set_value	Sets the value of the specified model element to the specified value.

_add_constraints(model_elements: list[ModelElement]) → list[ModelElement]

Adds model elements of type constraint.

Parameters:

model_elements (list[ModelElement]) – Primary model elements.

Returns:

list[ModelElement] – Model elements augmented by constraint elements.

_add_model_element(element: ModelElement) → None

Adds the specified model element to self.model (by invoking element.add_to_model()). This method decouples ModelElements from the entity config by extracting configured initalization values and variable bounds.

Parameters:

element (ModelElement) – Model element to add to self.model.

classmethod _augment_model_elements(model_elements: list[ModelElement]) → list[ModelElement]

This method augments the list of model elements. It might add initial state variables, cost variables etc. Its purpose is to decouple a “leaf” object’s model elements (retrieved from ._get_model_elements()) from generic elements inherited by its parent class. It does not need to be implemented by subclasses.

Parameters:

model_elements (list[ModelElement]) – List of main variables and parameters.

Returns:

list[ModelElement] – List of the given model_elements augmented by additional elements.

_check_config(config: dict[str, int | float]) → None

Checks if all required configurations have been defined in the configuration dict passed to the class constructor. Namely, it is checked if the config contains

• either a scalar value or an instance of ParamInitializer for all model elements of type CONSTANT.

• bounds for all model elements of type INPUT, VAR, STATE which do not already have (default) bounds.

Parameters:

config (dict[str, Union[int, float]]) – Configuration dict.

Raises:

EntityError – If configurations are missing and prints a list of the missing entries.

classmethod _get_model_elements() → list[ModelElement]

This is the central method which all subclasses must implement. Here, the model elements of the entity are defined. For clarity, specify main variables and parameters here and specify constraints and auxiliary variables in _augment_model_elements().

Returns:

list[ModelElement] – List of model elements which will represent the entity in the pyomo model.

add_data_provider(data_provider: DataProvider) → ModelEntity

Adds a data provider to the entity. It will be checked during validation if all model elements which require a data provider are covered.

Parameters:

data_provider (DataProvider) – Data provider instance.

Returns:

ModelEntity – ModelEntity instance.

add_to_model(model: ConcreteModel, **kwargs) → None

This method adds the calling entity to the given (global) pyomo model. To this end, we

• declare and add a new pyomo block named by self.id (the entity’s global id).

• call _get_model_elements() to retrieve the entity’s model elements (variables and parameters).

• call _augment_model_elements() to add additional model elements (constraints etc.).

• check the configuration dict for completeness based on the defined model elements.

• add all model elements to the previously declared pyomo block.

We also store a reference to the global model in self.model.

Parameters:

model (ConcreteModel) – Global pyomo model.

cost_fcn(scenario: CostScenario, model: ConcreteModel, t: int = 0) → Expression

Returns the pyomo expression of the entity’s cost function.

Parameters:

• model (ConcreteModel) – Model to refer to.

• t (int, optional) – Time. Defaults to 0.

Returns:

Expression – Cost function.

get_pyomo_element(name: str, model: ConcreteModel) → Var | Param | Set | Constraint | Objective

Gets a pyomo element referenced by name from the given model. The name can be local (e.g. “p”, i.e. from the perspective of the calling block) or non-local (e.g. “n1.n12.p”, i.e. from the perspective of a higher block). The given model can also be local (of the calling block) or of a block higher in the hierarchy. We first get the root of the passed model and constuct the element id for the global model. This will find the correct element if the passed model is the global model. For any sub-global model, we iteratively make the element id “more local” until we find the right element. We ensure that the element is on the model branch of the calling entity, i.e., one cannot access elements of other entities.

Parameters:

• name (str) – Name of the model element (can be local or global).

• model (ConcreteModel) – Model to get the variable from.

Raises:

EntityError – If element not found.

Returns:

Union[Var, Param, Set, Constraint, Objective] – The referenced variable from the given model.

get_pyomo_element_id(name: str) → str

Constructs the global element name from the local name.

Parameters:

name (str) – Local element name.

Returns:

str – Global element name.

get_self_as_pyomo_block(model: ConcreteModel) → Block

Retrieves the pyomo block of the calling entity from a global model (based on the entity’s global id).

Parameters:

model (ConcreteModel) – Global pyomo model to access.

Returns:

Block – Pyomo block corresponding to the calling entity.

get_value(instance: ConcreteModel, name: str) → int | float | ndarray

Gets the value of the specified model element.

Parameters:

• instance (ConcreteModel) – Pyomo model to access.

• name (str) – Name of the element relative to the given instance (e.g. global id for global instance).

Returns:

Union[int, float, np.ndarray] –

Value of the model element.

If the element is indexed, we return a np.ndarray.

has_pyomo_element(name: str, model: ConcreteModel) → bool

This is essentially an indicator wrapper around get_pyomo_element() which returns False if no corresponding model element could be found (instead of raising an error).

Parameters:

• name (str) – Name of the model element (can be local or global).

• model (ConcreteModel) – Model to get the variable from.

Returns:

bool – False if no corresponding model element could be found, True otherwise.

classmethod info() → None

Prints some information about this entity. Included are ModelEntities with the corresponding configurations and data providers.

set_value(instance: ConcreteModel, name: str, val: int | float | ndarray, idx: None | int | list[int] = None, fix_value: bool = False) → None

Sets the value of the specified model element to the specified value. Allows to specify specific indices to manipulate and to fix the variable values after setting them.

Parameters:

• instance (ConcreteModel) – Pyomo model to manipulate.

• name (str) – Name of the element relative to the given instance (e.g. global id for global instance).

• val (Union[int, float, np.ndarray]) – Value to set the element to. For indexed elements, an array can be passed.

• idx (Union[None, int, list[int]], optional) – If only specific indices of an indexed element should be set, it can be specified here. If not given, it is assumed that all indices should be menipulated. Defaults to None.

• fix_value (bool, optional) – Specifies if the values should be fixed. Defaults to False.

Raises:

EntityError – If an array is passed for a scalar element or if a scalar is passed for an indexed variable without specifying an index or if a list of indices is passed for a scalar element or if fix_value is True for an element of pyomo class Param.