app.infra.relation
Relation and expression system for energy community modeling.
This module provides the core expression system for representing and converting mathematical relations in energy system optimization models. It supports arithmetic operations, comparisons, entity references with time offsets, and specialized expression types for conditional and temporal constraints.
AssignmentExpression
Bases: Expression
convert(converter, t, time_set=None, new_freq=None)
Convert assignment expression using the provided converter
BinaryExpression
Bases: Expression
convert(converter, t, time_set=None, new_freq=None)
Convert binary expression using the provided converter
parse_binary(expr)
classmethod
Parse constraint expressions like 'battery1.discharge_power(t) < 2 * battery1.discharge_power(t-1)'
EntityReference
Bases: Expression
Expression representing a reference to an entity with optional time offset.
Entity references are used to access variables or properties of energy system components at specific time steps. Examples include 'battery1.discharge_power(t)' or 'pv1.generation(t-1)'.
__init__(entity_id, time_offset=0)
Initialize entity reference.
Parameters
entity_id : str Identifier for the entity (e.g., 'battery1.discharge_power') time_offset : int, default=0 Time offset relative to current time step: - 0 for current time (t) - -1 for previous time step (t-1) - +1 for next time step (t+1)
__str__()
Return string representation with time offset notation.
convert(converter, t, time_set=None, new_freq=None)
Convert entity reference using the provided converter.
Parameters
converter : Any Converter object that handles format-specific conversion t : int Current time step time_set : int, optional Time set for constraint generation new_freq : str, optional Frequency specification for time conversion
Returns
Any Converted entity reference representation
get_ids()
Return list containing this entity's ID.
Returns
List[str] List with single entity ID
Expression
Bases: ABC
Abstract base class for all mathematical expressions.
This class defines the interface that all expression types must implement for parsing, conversion, and entity ID extraction. Expression objects form a tree structure representing mathematical operations.
__str__()
abstractmethod
Return string representation of the expression.
Returns
str Human-readable string representation
convert(converter, t, time_set=None, new_freq=None)
abstractmethod
Convert expression using the provided converter.
This method implements the visitor pattern, delegating conversion logic to the converter object which knows how to handle specific target formats (PuLP, pandapower, etc.).
Parameters
converter : Any Converter object that handles format-specific conversion t : int Current time step time_set : int, optional Time set for constraint generation new_freq : str, optional Frequency specification for time conversion
Returns
Any Converted representation (format depends on converter)
get_ids()
abstractmethod
Extract all entity IDs referenced in this expression.
Returns
List[str] List of unique entity IDs used in the expression
IfThenExpression
Bases: Expression
convert(converter, t, time_set=None, new_freq=None)
Convert if-then expression using the provided converter
Literal
Bases: Expression
Expression representing a literal numeric value.
Literals are terminal nodes in expression trees that contain constant numeric values (integers or floats).
__init__(value)
Initialize literal with numeric value.
Parameters
value : Union[int, float] The numeric value this literal represents
__str__()
Return string representation of the literal value.
convert(converter, t, time_set=None, new_freq=None)
Convert literal using the provided converter.
Parameters
converter : Any Converter object that handles format-specific conversion t : int Current time step (unused for literals) time_set : int, optional Time set for constraint generation (unused for literals) new_freq : str, optional Frequency specification (unused for literals)
Returns
Any Converted literal representation
get_ids()
Return empty list as literals contain no entity references.
Returns
List[str] Empty list (literals have no entity IDs)
Operator
Bases: Enum
Enumeration of supported mathematical and comparison operators.
This enum defines all operators that can be used in mathematical expressions within the energy system modeling framework. Each operator contains both its string representation and category information for proper handling.
category
property
Return the category of the operator (comparison or arithmetic).
symbol
property
Return the string representation of the operator.
__str__()
Return string representation of the operator.
arithmetic_operators()
classmethod
Return all arithmetic operators.
arithmetic_strings()
classmethod
Return string representations of arithmetic operators.
comparison_operators()
classmethod
Return all comparison operators.
comparison_strings()
classmethod
Return string representations of comparison operators.
from_symbol(symbol)
classmethod
Create an operator from its string symbol.
Relation
convert(converter, objects, time_set=None, new_freq=None)
Convert this relation using the provided converter for each time step.
This implements dependency inversion - the relation delegates to the converter, which contains all format-specific logic (PuLP, pandapower, etc.).
Parameters:
converter : object The converter that knows how to handle conversion (e.g., PulpConverter) objects : dict Dictionary mapping entity IDs to their variables/objects time_set : int The time set to iterate over new_freq : str Frequency (optional)
Returns:
dict Dictionary containing the constraint name and the list of constraints
parse(expr)
Parse the expression string into an Expression tree
TimeConditionExpression
Bases: Expression
convert(converter, t, time_set=None, new_freq=None)
Convert time condition expression using the provided converter