comando.core module

Package for generic modeling of energy system design and operation.

class comando.core.Component(label)

Bases: object

A component representing a part of an energy system.

The Component class is a model of a generic real-world component of an energy system, represented by a collection of algebraic and logical expressions which describe how the component can be controlled, its limitations and its interactions with other components.

For every component, two kinds of decisions may be taken: - design decisions a.k.a. ‘here-and-now’ decisions - operational decisions a.k.a. ‘wait-and-see’ decisions The former constitute decisions that are taken once, prior to all operation while the operational decisions need to be taken for every time-point under consideration.

The component may define named expressions that can be accessed at any time for informational purposes. These expressions may also be used to impose additional constraints at a later stage, or to aggregate information from multiple different components. In a similar way an objective for a system optimization can be generated by aggregating different types of costs defined by some subset of the system’s components.

Parameters that are contained in the various expressions may or may not be given a default value that can be changed at a later stage.

Variables:

• label (str) – A unique sting that serves as an identifier

• parameters (set of Symbol) – Set of unspecified system parameters the user can assign values to.

• design_variables (set of Variable) – Set of variables of the design stage, i.e. time-independent variables such as the number or size of newly added components.

• operational_variables (set of Variable) – Set of unique names for variables of the operational stage, e.g. the output of a given component or an operational state.

• states (dict) – Dictionary mapping a subset of operational_variables to automatically created Variables, representing the corresponding time derivatives. Examples are the SOC of a battery, the fill-level of a tank, etc.

• constraints (dict of sympy.core.relational.Relational) – Dictionary of relational sympy expressions that represent constraints.

• expressions (dict) – mapping of shared identifiers to algebraic sympy expressions. The expressions different Component instances associate with a shared identifier may be aggregated to additional constraints or objectives.

• connectors (dict) – mapping of strings to algebraic expressions representing in or outputs to the component. When multiple connectors are connected to each other, the connection represents the requirement that the sum of their expressions need to be equal to zero.

add_connector(id, expr)

Insert the connector in connectors and add it as an attribute.

add_connectors(id=None, expr=None, **connectors)

Add one or more named connectors to this component.

Examples

>>> self.add_connectors('A', sympy.S('A'))
>>> self.add_connectors(B=sympy.S('B'), C=sympy.S('C'))

add_eq_constraint(lhs_expr, rhs_expr, name=None)

Add a constraint of the form lhs_expr = rhs_expr.

add_expression(identifier, expr)

Add a named algebraic expression.

add_ge_constraint(lhs_expr, rhs_expr, name=None)

Add a constraint of the form lhs_expr ≥ rhs_expr.

add_input(identifier, expr)

Add a connector that corresponds to an input into the component.

The expr is assumed to always be positive and is thus bounded by 0 from below. By convention the input into a Component is positive so the new Connector’s expression corresponds to expr.

add_le_constraint(lhs_expr, rhs_expr, name=None)

Add a constraint of the form lhs_expr ≤ rhs_expr.

add_output(identifier, expr)

Add a connector that corresponds to an output from the component.

The expr is assumed to always be positive and is thus bounded by 0 from below. By convention the output from a Component is negative so the new Connector’s expression corresponds to the negated expr.

property constraints

Get a set of the Component’s constraints.

property constraints_dict

Get a dictionary of the Component’s constraints.

declare_state(var, rate_of_change=None, init_state=nan, der_bounds=(None, None), der_init_val=None)

Declare var to be a state.

A state is an operational variable whose time derivative is described by the rate_of_change expression, beginning at an initial_state.

property design_variables

Get a set of the Component’s design_variables.

property design_variables_dict

Get a dictionary of the Component’s design_variables.

existing_components = {}

property expressions

Get a set of the Component’s expressions.

property expressions_dict

Get a dictionary of the Component’s expressions.

get_expression(identifier, default=None)

Get the expression corresponding to the identifier.

property label

Get the Component’s unique label.

make_design_variable(name, domain=Domain.REAL, bounds=(None, None), discretization=None, init_val=None)

Create a design variable with a localized name & store it.

make_operational_variable(name, domain=Domain.REAL, bounds=(None, None), discretization=None, init_val=None)

Create an operational variable with a localized name & store it.

make_parameter(name, value=None)

Create a parameter with a localized name & store it.

make_state(name, rate_of_change=None, init_state=nan, domain=Domain.REAL, bounds=(None, None), der_bounds=(None, None), init_val=None, der_init_val=None)

Create a state with a localized name, its derivative and store them.

A state is an operational variable whose time derivative is described by the rate_of_change expression, beginning at an initial_state.

property operational_variables

Get a set of the Component’s operational_variables.

property operational_variables_dict

Get a dictionary of the Component’s operational_variables.

property parameters

Get a set of the Component’s parameters.

property parameters_dict

Get a dictionary of the Component’s parameters.

property states

property states_dict

class comando.core.Connector(component, name, expr)

Bases: object

An interface used to connect one or more Component objects.

class comando.core.ConnectorUnion(component, name, *connectors)

Bases: Connector

A union of multiple Connectors.

property expr

Return an expression for the flow through the ConnectorUnion.

class comando.core.DataProxy(getter: Callable(Optional[object]), setter: Callable(str, [int, float]))

Bases: SlotSerializationMixin

A proxy object to access and set data.

Callable

alias of Callable

Optional = typing.Optional

getter

setter

class comando.core.DiscretizationParameters(lower_bound, upper_bound, step_size)

Bases: object

A set of parameters defining discretization

exception comando.core.ImpossibleConstraintException

Bases: Exception

class comando.core.Parameter(name, value=nan, parent=None)

Bases: Symbol

A Symbol representing a parameter whose value is known.

property elements

expand(data)

Expand the Parameter with indexed data.

expansion

property indices

property is_indexed

Check whether the Parameter is indexed or not.

property items

property parent

Return the parent of this parameter.

property value

Return the value or values of the Parameter.

class comando.core.Problem(design_objective=0, operational_objective=0, constraints=None, states=None, timesteps=None, scenarios=None, data=None, name='Unnamed Problem')

Bases: object

A simple optimization problem.

property T

Get the Problem’s end time.

add_symbols(syms)

Sort symbols into parameters, design- and operational variables.

property data

Aggregate and return the parameter data.

property design

Collect the design variable values in a DataFrame.

property design_objective

get_constraint_violations(larger_than=0)

Collect the current constraint violations in a DataFrame.

property index

Get the index of the Problem.

property initial_states

Aggregate and return the parameter data.

load_variable_values(filename)

Collect variable values from file.

property num_cons

Get the total number of variables.

property num_vars

Get the total number of variables.

property objective

Get the objective expression of the problem.

property operation

Collect the operational variable values in a DataFrame.

property operational_objective

property scenario_weights

Get the Problem’s scenario weights.

property scenarios

Get the Problem’s scenarios.

store_variable_values(filename)

Serialize current variable values and store in file.

subs(sym=None, rep=None, **reps)

Substitute an individual or multiple symbols in the problem.

property timesteps

Get the length of the Problem’s timesteps.

weighted_sum(op_expr, symbolic=True)

Compute the scenario- and/or time-weighted sum of an expression.

Arguments:

• op_expr (Expression) – an operational expression that is to be weighted

• symbolic (bool) – if True creates a new expression (default) if False evaluate numerically

class comando.core.SlotSerializationMixin

Bases: object

A Mixin to make classes with slots serializable.

class comando.core.Symbol(name, **assumptions)

Bases: SlotSerializationMixin, Symbol

A placeholder for a value which can occur within expressions.

property is_indexed

Check if the Symbol is indexed.

property value

Get the Symbol’s value.

class comando.core.System(label, components=None, connections=None)

Bases: Component

A class for a generic system, made up of individual components.

Note that a system is itself a component and can therefore function as a subsystem for a larger system, allowing for nested structures!

Variables:

• components (iterable of Component) – components that form part of the considered energy system

• connections (dict) – mapping of str to an iterable of Connector. The in- and outputs of all connectors within an iterable are assumed to balance each other.

add(component)

Add a Component to the system.

aggregate_component_expressions(id, aggregator=<built-in function sum>)

Aggregate expressions from the components matching the identifier.

The passed identifier is used to look up matching expressions in the components of this system. The resulting expressions are then aggregated using the passed aggregator function and the resulting expression is returned.

close_connector(connector, expr=0)

Specify the flow over the connector (default 0).

property components

Get the set of components that are part of the system.

connect(bus_id, connectors)

Connect all elements of connectors to a bus with id bus_id.

property constraints

Get a set of the System’s constraints.

property constraints_dict

Get a dictionary of the System’s constraints.

create_problem(design_objective=0, operational_objective=0, timesteps=None, scenarios=None, data=None, name=None)

Create a problem with the specified time and scenario structure.

Arguments:

• T (The end time of the operational period (default 8760)) – If T is not specified, timesteps needs to be a mapping (see below).

• timesteps (tuple, Mapping or Series.) – If timesteps is tuple it is assumed to consist of timestep labels and data for the time horizon T. This data may be a scalar numeric value, a Mapping or a Series. In the latter two cases T maps from different scenarios s to corresponding time horizons T[s]. If timesteps is a Mapping, it can either be mapping from timestep labels to timestep lengths or from scenarios to a corresponding specification of the time structure, consisting of either the tuple representation or the timestep mapping.

• scenarios (None or an iterable of timestep labels.) – If scenarios is a Mapping or pandas Series, the values are interpreted as the probabilities / relative likelihoods of the individual scenarios.

property design_variables

Get a set of the System’s design_variables.

property design_variables_dict

Get a dictionary of the System’s design_variables.

detach(bus_id, connectors=None)

Detach all Connector`s in `connectors from the specified bus.

expose_connector(connector, alias=None)

Expose an existing connector to the outside of the system.

property expressions

Get a set of the System’s expressions.

property expressions_dict

Get a dictionary of the System’s expressions.

extend_connection(bus_id, alias=None)

Extend the connection to the outside of the system.

get_open_connectors()

Return the set of all connectors that are not connected yet.

property operational_variables

Get a set of the System’s operational_variables.

property operational_variables_dict

Get a dictionary of the System’s operational_variables.

property parameters

Get a set of the System’s parameters.

property parameters_dict

Get a dictionary of the System’s parameters.

remove(component)

Remove a Component from the system.

property states

Get a set of the System’s states.

property states_dict

Get a set of the System’s states.

class comando.core.Variable(name, domain=Domain.REAL, bounds=(None, None), discretization: DiscretizationParameters = None, init_val=None, indexed=False, parent=None)

Bases: Symbol

A Symbol representing a variable whose value is unknown.

property bounds

property discretization

property domain

fix(value=None)

Fix the variable by setting both bounds to value.

property init_val

property is_binary

property is_integer

property is_negative

Check if all possible values of the variable are negative.

We can assert negativity if the upper bound is negative, otherwise we can assert nonnegativity if the lower bound is nonnegative. If we cannot assert either of these facts, the variable may contain both positive and negative values. To reflect this we return None.

property is_nonnegative

Check if all possible values of the variable are negative.

This is the fuzzy not of self.is_negative

property is_nonpositive

Check if all possible values of the variable are negative.

This is the fuzzy not of self.is_negative

property is_positive

Check if all possible values of the variable are positive.

We can assert positivity if the lower bound is positive, otherwise we can assert nonpositivity if the upper bound is nonpositive. If we cannot assert either of these facts, the variable may contain both positive and negative values. To reflect this we return None.

property lb

property parent

Return the parent of this variable.

property ub

unfix()

Recover the original bounds.

property value

Get the Symbol’s value.

class comando.core.VariableVector(name, domain=Domain.REAL, bounds=(None, None), discretization: DiscretizationParameters = None, init_val=None)

Bases: Symbol

A Symbol representing a vector of Variables.

property bounds

property discretization

property domain

property elements

expansion

fix(value=None)

Fix self.elements by setting both bounds to value.

property indices

property init_val

instantiate(index)

Create Variable instances for every element in index.

property is_binary

property is_expanded

property is_indexed

Check if the Symbol is indexed.

property is_integer

property is_negative

Check if all possible values of the variable are negative.

We can assert negativity if the upper bound is negative, otherwise we can assert nonnegativity if the lower bound is nonnegative. If we cannot assert either of these facts, the variable may contain both positive and negative values. To reflect this we return None.

property is_nonnegative

Check if all possible values of the variable are negative.

This is the fuzzy not of self.is_negative

property is_nonpositive

Check if all possible values of the variable are negative.

This is the fuzzy not of self.is_negative

property is_positive

Check if all possible values of the variable are positive.

We can assert positivity if the lower bound is positive, otherwise we can assert nonpositivity if the upper bound is nonpositive. If we cannot assert either of these facts, the variable may contain both positive and negative values. To reflect this we return None.

property items

property lb

property ub

unfix()

Recover the original bounds.

property value

Get the Symbol’s value.

comando.core.is_trivial(constraint, con_repr=None, warn=True)

Handle constraints that are trivially true or false.