wntr.network.controls module¶
The wntr.network.controls module includes methods to define network controls and control actions. These controls modify parameters in the network during simulation.
Contents
|
A subject base class for the observer design pattern |
|
A base class for observers in the observer design pattern. |
|
An enum class for comparison operators. |
|
An enum class for control priorities. |
A base class for control conditions |
|
|
Time-of-day or "clocktime" based condition statement. |
|
Condition based on time since start of the simulation. |
|
Compare a network element attribute to a set value. |
|
A special type of ValueCondition for tank levels/heads/pressures. |
|
Compare attributes of two different objects (e.g., levels from tanks 1 and 2) This type of condition does not work with the EpanetSimulator, only the WNTRSimulator. |
|
Combine two WNTR Conditions with an OR. |
|
Combine two WNTR Conditions with an AND |
A base class for deriving new control actions. |
|
|
A general class for specifying a control action that simply modifies the attribute of an object (target). |
This is the base class for all control objects. |
|
|
A class for controls. |
- class wntr.network.controls.Subject[source]¶
Bases:
object
A subject base class for the observer design pattern
- subscribe(observer)[source]¶
Subscribe observer to this subject. The update method of any observers of this subject will be called when notify is called on this subject.
- Parameters
observer (Observer) –
- class wntr.network.controls.Observer[source]¶
Bases:
object
A base class for observers in the observer design pattern.
- class wntr.network.controls.Comparison(value)[source]¶
Bases:
enum.Enum
An enum class for comparison operators.
Enum Members
gt
greater than
ge
greater than or equal to
lt
less than
le
less than or equal to
eq
equal to
ne
not equal to
- property func¶
The function call to use for this comparison
- class wntr.network.controls.ControlPriority(value)[source]¶
Bases:
enum.IntEnum
An enum class for control priorities.
Enum Members
very_low
very low priority
low
low priority
medium_low
medium low priority
medium
medium priority
medium_high
medium high priority
high
high priority
very_high
very high priority
- class wntr.network.controls.ControlCondition[source]¶
Bases:
object
A base class for control conditions
- abstract requires()[source]¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.TimeOfDayCondition(model, relation, threshold, repeat=True, first_day=0)[source]¶
Bases:
wntr.network.controls.ControlCondition
Time-of-day or “clocktime” based condition statement. Resets automatically at 12 AM in clock time (shifted time) every day simulated. Evaluated from 12 AM the first day of the simulation, even if this is prior to simulation start. Unlike the
SimTimeCondition
, greater-than and less-than relationships make sense, and reset at midnight.- Parameters
model (WaterNetworkModel) – The model that the time is being compared against
relation (str or None) – String options are ‘at’, ‘after’ or ‘before’. The ‘at’ and None are equivalent, and only evaluate as True during the simulation step the time occurs. after evaluates as True from the time specified until midnight, before evaluates as True from midnight until the specified time.
threshold (float or str) – The time (a
float
in decimal hours since 12 AM) used in the condition; if provided as a string in ‘hh:mm[:ss] [am|pm]’ format, the time will be parsed from the stringrepeat (bool, optional) – True by default; if False, allows for a single, timed trigger, and probably needs an entry for first_day; in this case a relation of after becomes True from the time until the end of the simulation, and before is True from the beginning of the simulation until the time specified.
first_day (float, default=0) – Start rule on day first_day, with the first day of simulation as day 0
TODO (WE ARE NOT TESTING THIS!!!!) –
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.SimTimeCondition(model, relation, threshold, repeat=False, first_time=0)[source]¶
Bases:
wntr.network.controls.ControlCondition
Condition based on time since start of the simulation. Generally, the relation should be
None
(converted to “at”) – then it is only evaluated “at” specific times. Using greater-than or less-than type relationships should be reserved for complex, multi-condition statements and should not be used for simple controls. Ifrepeat
is used, the relationship will automatically be changed to an “at time” evaluation, and a warning will be raised.- Parameters
model (WaterNetworkModel) – The model that the time threshold is being compared against
relation (str or None) – String options are ‘at’, ‘after’ or ‘before’. The ‘at’ and None are equivalent, and only evaluate as True during the simulation step the time occurs. After evaluates as True from the time specified until the end of simulation, before evaluates as True from start of simulation until the specified time.
threshold (float or str) – The time (a
float
in decimal hours) used in the condition; if provided as a string in ‘[dd-]hh:mm[:ss]’ format, then the time will be parsed from the string;repeat (bool or float, default=False) – If True, then repeat every 24-hours; if non-zero float, reset the condition every repeat seconds after the first_time.
first_time (float, default=0) – Start rule at first_time, using that time as 0 for the condition evaluation
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.ValueCondition(source_obj, source_attr, relation, threshold)[source]¶
Bases:
wntr.network.controls.ControlCondition
Compare a network element attribute to a set value.
- Parameters
source_obj (object) – The object (such as a Junction, Tank, Pipe, etc.) to use in the comparison
source_attr (str) – The attribute of the object (such as level, pressure, setting, etc.) to compare against the threshold
operation (function or str) – A two-parameter comparison function (e.g., numpy.greater, numpy.less_equal), or a string describing the comparison (e.g., ‘=’, ‘below’, ‘is’, ‘>=’, etc.) Words, such as ‘below’, are only accepted from the EPANET rules conditions list (see …)
threshold (float) – A value to compare the source object attribute against
- requires()[source]¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.FunctionCondition(func, func_kwargs=None, requires=None)[source]¶
Bases:
wntr.network.controls.ControlCondition
A ControlCondition which calls a function to determine if the control needs activated or not. If the function returns True, then the control is activated.
- requires()[source]¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- property backtrack¶
The amount of time by which the simulation should be backed up. Should be updated by the
evaluate
method if appropriate.- Returns
backtrack (int)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.TankLevelCondition(source_obj, source_attr, relation, threshold)[source]¶
Bases:
wntr.network.controls.ValueCondition
A special type of ValueCondition for tank levels/heads/pressures.
- property backtrack¶
The amount of time by which the simulation should be backed up. Should be updated by the
evaluate
method if appropriate.- Returns
backtrack (int)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- requires()¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- class wntr.network.controls.RelativeCondition(source_obj, source_attr, relation, threshold_obj, threshold_attr)[source]¶
Bases:
wntr.network.controls.ControlCondition
Compare attributes of two different objects (e.g., levels from tanks 1 and 2) This type of condition does not work with the EpanetSimulator, only the WNTRSimulator.
- Parameters
source_obj (object) – The object (such as a Junction, Tank, Pipe, etc.) to use in the comparison
source_attr (str) – The attribute of the object (such as level, pressure, setting, etc.) to compare against the threshold
relation (function) – A numpy or other comparison method that takes two values and returns a bool (e.g., numpy.greater, numpy.less_equal)
threshold_obj (object) – The object (such as a Junction, Tank, Pipe, etc.) to use in the comparison of attributes
threshold_attr (str) – The attribute to used in the comparison evaluation
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.OrCondition(cond1, cond2)[source]¶
Bases:
wntr.network.controls.ControlCondition
Combine two WNTR Conditions with an OR.
- Parameters
cond1 (ControlCondition) – The first condition
cond2 (ControlCondition) – The second condition
- property backtrack¶
The amount of time by which the simulation should be backed up. Should be updated by the
evaluate
method if appropriate.- Returns
backtrack (int)
- requires()[source]¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.AndCondition(cond1, cond2)[source]¶
Bases:
wntr.network.controls.ControlCondition
Combine two WNTR Conditions with an AND
- Parameters
cond1 (ControlCondition) – The first condition
cond2 (ControlCondition) – The second condition
- property backtrack¶
The amount of time by which the simulation should be backed up. Should be updated by the
evaluate
method if appropriate.- Returns
backtrack (int)
- requires()[source]¶
Returns a set of objects required to evaluate this condition
- Returns
required_objects (OrderedSet of object)
- property name¶
Returns the string representation of the condition.
- Returns
name (str)
- class wntr.network.controls.BaseControlAction[source]¶
Bases:
wntr.network.controls.Subject
A base class for deriving new control actions. The control action is run by calling run_control_action. This class is not meant to be used directly. Derived classes must implement the run_control_action, requires, and target methods.
- abstract run_control_action()[source]¶
This method is called to run the corresponding control action.
- abstract requires()[source]¶
Returns a set of objects used to evaluate the control
- Returns
req (OrderedSet) – The objects required to run the control action.
- abstract target()[source]¶
Returns a tuple (object, attribute) containing the object and attribute that the control action may change
- Returns
target (tuple) – A tuple containing the target object and the attribute to be changed (target, attr).
- notify()¶
Call the update method for all observers of this subject.
- class wntr.network.controls.ControlAction(target_obj, attribute, value)[source]¶
Bases:
wntr.network.controls.BaseControlAction
A general class for specifying a control action that simply modifies the attribute of an object (target).
- Parameters
target_obj (object) – The object whose attribute will be changed when the control runs.
attribute (string) – The attribute that will be changed on the target_obj when the control runs.
value (any) – The new value for target_obj.attribute when the control runs.
- requires()[source]¶
Returns a set of objects used to evaluate the control
- Returns
req (OrderedSet) – The objects required to run the control action.
- target()[source]¶
Returns a tuple (object, attribute) containing the object and attribute that the control action may change
- Returns
target (tuple) – A tuple containing the target object and the attribute to be changed (target, attr).
- notify()¶
Call the update method for all observers of this subject.
- class wntr.network.controls.ControlBase[source]¶
Bases:
object
This is the base class for all control objects. Control objects are used to check the conditions under which a ControlAction should be run. For example, if a pump is supposed to be turned on when the simulation time reaches 6 AM, the ControlAction would be “turn the pump on”, and the ControlCondition would be “when the simulation reaches 6 AM”.
- abstract is_control_action_required()[source]¶
This method is called to see if any action is required by this control object. This method returns a tuple that indicates if action is required (a bool) and a recommended time for the simulation to backup (in seconds as a positive int).
- Returns
req (tuple) – A tuple (bool, int) indicating if an action should be run and how far to back up the simulation.
- abstract run_control_action()[source]¶
This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
- class wntr.network.controls.Rule(condition, then_actions, else_actions=None, priority=ControlPriority.medium, name=None)[source]¶
Bases:
wntr.network.controls.ControlBase
A very general and flexible class for defining both controls rules.
- Parameters
condition (ControlCondition) – The condition that should be used to determine when the actions need to be activated. When the condition evaluates to True, the then_actions are activated. When the condition evaluates to False, the else_actions are activated.
then_actions (Iterable of ControlAction) – The actions that should be activated when the condition evaluates to True.
else_actions (Iterable of ControlAction) – The actions that should be activated when the condition evaluates to False.
priority (ControlPriority) – The priority of the control. Default is ControlPriority.medium
name (str) – The name of the control
- property epanet_control_type¶
The control type. Note that presolve and postsolve controls are both simple controls in Epanet.
- Returns
control_type (_ControlType)
- requires()[source]¶
Returns a set of objects required for this control.
- Returns
required_objects (OrderedSet of object)
- actions()[source]¶
Returns a list of all actions used by this control.
- Returns
act (list of BaseControlAction)
- property name¶
A string representation of the Control.
- is_control_action_required()[source]¶
This method is called to see if any action is required by this control object. This method returns a tuple that indicates if action is required (a bool) and a recommended time for the simulation to backup (in seconds as a positive int).
- Returns
req (tuple) – A tuple (bool, int) indicating if an action should be run and how far to back up the simulation.
- run_control_action()[source]¶
This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
- update_condition(condition: wntr.network.controls.ControlCondition)[source]¶
Update the controls condition in place
- Parameters
condition (ControlCondition) – The new condition for this control to use
- Raises
ValueError – If the provided condition isn’t a valid ControlCondition
- update_then_actions(then_actions: Iterable[wntr.network.controls.ControlAction])[source]¶
Update the controls then_actions in place
- Parameters
then_actions (Iterable[ControlAction]) – The new then_actions for this control to use
- update_else_actions(else_actions: Iterable[wntr.network.controls.ControlAction])[source]¶
Update the controls else_actions in place
- Parameters
else_actions (Iterable[ControlAction]) – The new else_actions for this control to use
- update_priority(priority: wntr.network.controls.ControlPriority)[source]¶
Update the controls priority in place
- Parameters
priority (ControlPriority) – The new priority for this control to use
- class wntr.network.controls.Control(condition, then_action: wntr.network.controls.BaseControlAction, priority=ControlPriority.medium, name=None)[source]¶
Bases:
wntr.network.controls.Rule
A class for controls.
- Parameters
condition (ControlCondition) – The condition that should be used to determine when the actions need to be activated. When the condition evaluates to True, the then_actions are activated. When the condition evaluates to False, the else_actions are activated.
then_action (BaseControlAction) – The action that should be activated when the condition evaluates to True.
priority (ControlPriority) – The priority of the control. Default is ControlPriority.medium
name (str) – The name of the control
- actions()¶
Returns a list of all actions used by this control.
- Returns
act (list of BaseControlAction)
- property epanet_control_type¶
The control type. Note that presolve and postsolve controls are both simple controls in Epanet.
- Returns
control_type (_ControlType)
- is_control_action_required()¶
This method is called to see if any action is required by this control object. This method returns a tuple that indicates if action is required (a bool) and a recommended time for the simulation to backup (in seconds as a positive int).
- Returns
req (tuple) – A tuple (bool, int) indicating if an action should be run and how far to back up the simulation.
- property name¶
A string representation of the Control.
- requires()¶
Returns a set of objects required for this control.
- Returns
required_objects (OrderedSet of object)
- run_control_action()¶
This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
- update_condition(condition: wntr.network.controls.ControlCondition)¶
Update the controls condition in place
- Parameters
condition (ControlCondition) – The new condition for this control to use
- Raises
ValueError – If the provided condition isn’t a valid ControlCondition
- update_else_actions(else_actions: Iterable[wntr.network.controls.ControlAction])¶
Update the controls else_actions in place
- Parameters
else_actions (Iterable[ControlAction]) – The new else_actions for this control to use
- update_priority(priority: wntr.network.controls.ControlPriority)¶
Update the controls priority in place
- Parameters
priority (ControlPriority) – The new priority for this control to use
- update_then_actions(then_actions: Iterable[wntr.network.controls.ControlAction])¶
Update the controls then_actions in place
- Parameters
then_actions (Iterable[ControlAction]) – The new then_actions for this control to use
- class wntr.network.controls.ControlChangeTracker[source]¶
Bases:
wntr.network.controls.Observer
- update(subject)[source]¶
The update method gets called when a subject (control action) is activated.
- Parameters
subject (BaseControlAction) –
- register_control(control)[source]¶
Register a control with the ControlManager
- Parameters
control (ControlBase) –
- get_changes(ref_point)[source]¶
A generator for iterating over the objects, attributes that were changed.
- Returns
changes (tuple) – (object, attr)
- deregister(control)[source]¶
Deregister a control with the ControlManager
- Parameters
control (ControlBase) –