comando.core module

Package for generic modeling of energy system design and operation.

class comando.core.Component(label)[source]

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)[source]: Insert the connector in connectors and add it as an attribute.

add_connectors(id=None, expr=None, **connectors)[source]

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)[source]: Add a constraint of the form lhs_expr = rhs_expr.

add_expression(identifier, expr)[source]: Add a named algebraic expression.

add_ge_constraint(lhs_expr, rhs_expr, name=None)[source]: Add a constraint of the form lhs_expr ≥ rhs_expr.

add_input(identifier, expr)[source]

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)[source]: Add a constraint of the form lhs_expr ≤ rhs_expr.

add_output(identifier, expr)[source]

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)[source]

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)[source]: 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), init_val=None)[source]: Create a design variable with a localized name & store it.

make_operational_variable(name, domain=Domain.REAL, bounds=(None, None), init_val=None)[source]: Create an operational variable with a localized name & store it.

make_parameter(name, value=None)[source]: 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)[source]

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)[source]

Bases: object

An interface used to connect one or more Component objects.

class comando.core.ConnectorUnion(component, name, *connectors)[source]

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]))[source]

Bases: SlotSerializationMixin

A proxy object to access and set data.

Callable: alias of Callable

Optional = typing.Optional

getter

setter

exception comando.core.ImpossibleConstraintException[source]: Bases: Exception

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

Bases: object

A simple optimization problem.

property T: Get the Problem’s end time.

add_symbols(syms)[source]: 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)[source]: 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)[source]: 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)[source]: Serialize current variable values and store in file.

subs(sym=None, rep=None, **reps)[source]: 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)[source]

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

Parameters:

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.System(label, components=None, connections=None)[source]

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)[source]: Add a Component to the system.

aggregate_component_expressions(id, aggregator=<built-in function sum>)[source]

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)[source]: 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)[source]: 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)[source]

Create a problem with the specified time and scenario structure.

Parameters:

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 timstep 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 likelyhoods 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)[source]: Detach all Connector`s in `connectors from the specified bus.

expose_connector(connector, alias=None)[source]: 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)[source]: Extend the connection to the outside of the system.

get_open_connectors()[source]: 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)[source]: 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.

comando.core.is_trivial(constraint, con_repr=None, warn=True)[source]: Handle constraints that are trivially true or false.