wntr.network.controls module

Classes

Subject() A subject base class for the observer design pattern
Observer A base class for observers in the observer design pattern.
Comparison An enum class for comparison operators.
ControlPriority An enum class for control priorities.
ControlCondition() A base class for control conditions
TimeOfDayCondition(model, relation, threshold) Time-of-day or “clocktime” based condition statement.
SimTimeCondition(model, relation, threshold) Condition based on time since start of the simulation.
ValueCondition(source_obj, source_attr, …) Compare a network element attribute to a set value.
TankLevelCondition(source_obj, source_attr, …) A special type of ValueCondition for tank levels/heads/pressures.
RelativeCondition(source_obj, source_attr, …) 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.
OrCondition(cond1, cond2) Combine two WNTR Conditions with an OR.
AndCondition(cond1, cond2) Combine two WNTR Conditions with an AND
BaseControlAction() A base class for deriving new control actions.
ControlAction(target_obj, attribute, value) A general class for specifying a control action that simply modifies the attribute of an object (target).
ControlBase This is the base class for all control objects.
Control(condition, then_actions[, …]) A very general and flexible class for defining both controls and rules.
ControlManager() A class for managing controls and identifying changes made by those controls.

The wntr.network.controls module includes methods to define network controls and control actions. These controls modify parameters in the network during simulation.

class wntr.network.controls.Subject[source]

Bases: object

A subject base class for the observer design pattern

Methods

notify() Call the update method for all observers of this subject.
subscribe(observer) Subscribe observer to this subject.
unsubscribe(observer) Unsubscribe observer from this subject.
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
unsubscribe(observer)[source]

Unsubscribe observer from this subject.

Parameters:observer: Observer
notify()[source]

Call the update method for all observers of this subject.

class wntr.network.controls.Observer[source]

Bases: object

A base class for observers in the observer design pattern.

Methods

update(subject) This method is called when the subject being observed calls notify.
update(subject)[source]

This method is called when the subject being observed calls notify.

Parameters:

subject: Subject

The subject that called notify.

class wntr.network.controls.Comparison[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

Methods

eq
ge
gt
le
lt
ne
class wntr.network.controls.ControlPriority[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

Attributes

backtrack The amount of time by which the simulation should be backed up.
name Returns the string representation of the condition.

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
name

Returns the string representation of the condition.

Returns:name: str
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
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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 string

repeat : 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

Attributes

backtrack The amount of time by which the simulation should be backed up.
name

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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
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. If repeat 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

Attributes

backtrack The amount of time by which the simulation should be backed up.
name

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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
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

Attributes

backtrack The amount of time by which the simulation should be backed up.
name

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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
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.

Attributes

backtrack The amount of time by which the simulation should be backed up.
name

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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()

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

Attributes

backtrack The amount of time by which the simulation should be backed up.
name

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
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
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

Attributes

backtrack
name Returns the string representation of the condition.

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
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

Attributes

backtrack
name Returns the string representation of the condition.

Methods

evaluate() Check if the condition is satisfied.
requires() Returns a set of objects required to evaluate this condition
evaluate()[source]

Check if the condition is satisfied.

Returns:check: bool
requires()[source]

Returns a set of objects required to evaluate this condition

Returns:required_objects: OrderedSet of object
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.

Methods

notify() Call the update method for all observers of this subject.
requires() Returns a set of objects used to evaluate the control
run_control_action() This method is called to run the corresponding control action.
subscribe(observer) Subscribe observer to this subject.
target() Returns a tuple (object, attribute) containing the object and attribute that the control action may change
unsubscribe(observer) Unsubscribe observer from this subject.
run_control_action()[source]

This method is called to run the corresponding control action.

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.

subscribe(observer)

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
unsubscribe(observer)

Unsubscribe observer from this subject.

Parameters:observer: Observer
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.

Methods

notify() Call the update method for all observers of this subject.
requires() Returns a set of objects used to evaluate the control
run_control_action() This method is called to run the corresponding control action.
subscribe(observer) Subscribe observer to this subject.
target() Returns a tuple (object, attribute) containing the object and attribute that the control action may change
unsubscribe(observer) Unsubscribe observer from this subject.
requires()[source]

Returns a set of objects used to evaluate the control

Returns:

req: OrderedSet

The objects required to run the control action.

run_control_action()[source]

This method is called to run the corresponding 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.

subscribe(observer)

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
unsubscribe(observer)

Unsubscribe observer from this subject.

Parameters:observer: Observer
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”.

Methods

actions() Returns a list of all actions used by this control.
is_control_action_required() This method is called to see if any action is required by this control object.
requires() Returns a set of objects required for this control.
run_control_action() This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
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.

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
class wntr.network.controls.Control(condition, then_actions, else_actions=None, priority=<ControlPriority.medium: 3>, name=None)[source]

Bases: wntr.network.controls.ControlBase

A very general and flexible class for defining both controls and rules.

Attributes

epanet_control_type The control type.
name A string representation of the Control.

Methods

actions() Returns a list of all actions used by this control.
conditional_control(source_obj, source_attr, …) This is a class method for creating simple conditional controls.
is_control_action_required() This method is called to see if any action is required by this control object.
requires() Returns a set of objects required for this control.
run_control_action() This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
time_control(wnm, run_at_time, time_flag, …) This is a class method for creating simple time 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_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

Attributes

epanet_control_type The control type.
name A string representation of the Control.

Methods

actions() Returns a list of all actions used by this control.
conditional_control(source_obj, source_attr, …) This is a class method for creating simple conditional controls.
is_control_action_required() This method is called to see if any action is required by this control object.
requires() Returns a set of objects required for this control.
run_control_action() This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
time_control(wnm, run_at_time, time_flag, …) This is a class method for creating simple time controls.
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
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.

classmethod time_control(wnm, run_at_time, time_flag, daily_flag, control_action, name=None)[source]

This is a class method for creating simple time controls.

Parameters:

wnm: wntr.network.WaterNetworkModel

The WaterNetworkModel instance this control will be added to.

run_at_time: int

The time to activate the control action.

time_flag: str

Options are ‘SIM_TIME’ and ‘CLOCK_TIME’. SIM_TIME indicates that run_at_time is the time since the start of the simulation. CLOCK_TIME indicates that run_at_time is the time of day.

daily_flag: bool

If True, then the control will repeat every day.

control_action: BaseControlAction

The control action that should occur at run_at_time.

name: str

An optional name for the control.

Returns:

ctrl: Control

classmethod conditional_control(source_obj, source_attr, operation, threshold, control_action, name=None)[source]

This is a class method for creating simple conditional controls.

Parameters:

source_obj: object

The object whose source_attr attribute will be compared to threshold to determine if control_action needs activated.

source_attr: str

The attribute of source_obj to compare to threshold.

operation: Comparison

The comparison function used to compare the source_attr attribute of source_obj to threshold.

threshold: any

The threshold used in the comparison.

control_action: ControlAction

The control action that should occur when operation(getattr(source_obj, source_attr), threshold) is True.

name: str

An optional name for the control

Returns:

ctrl: Control

class wntr.network.controls.ControlManager[source]

Bases: wntr.network.controls.Observer

A class for managing controls and identifying changes made by those controls.

Methods

changes_made() Specifies if changes were made.
check() Check which controls have actions that need activated.
deregister(control) Deregister a control with the ControlManager
get_changes() A generator for iterating over the objects, attributes that were changed.
register_control(control) Register a control with the ControlManager
reset() Reset the _previous_values.
update(subject) The update method gets called when a subject (control action) is activated.
update(subject)[source]

The update method gets called when a subject (control action) is activated.

register_control(control)[source]

Register a control with the ControlManager

Parameters:control: Control
reset()[source]

Reset the _previous_values. This should be called before activating any control actions so that changes made by the control actions can be tracked.

changes_made()[source]

Specifies if changes were made.

Returns:changes: bool
get_changes()[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: Control
check()[source]

Check which controls have actions that need activated.

Returns:

controls_to_run: list of tuple

The tuple is (Control, backtrack)