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.

class wntr.network.controls.ControlCondition[source]

Bases: object

A base class for control conditions

Attributes

backtrack Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires() Returns a list of objects required to evaluate this condition
requires()[source]

Returns a list of objects required to evaluate this condition

backtrack

Should be updated by the evaluate method if appropriate.

class wntr.network.controls.SimpleNodeCondition(source_obj, relation, threshold)[source]

Bases: wntr.network.controls.ControlCondition

Conditional based only on the pressure of a junction or the level of a tank.

Parameters:

source_obj : wntr.network.model.Junction, wntr.network.model.Tank

The junction or tank to use as a comparison

relation : ‘above’, ‘below’, or function

Accepts the words above or below, or accepts a function taking two arguments that returns a true or false. Usually a numpy.ufunc such as np.less or np.greater_equal

threshold : float

The pressure or tank level to use in the condition

Attributes

backtrack Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires()
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 Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires() Returns a list of objects required to evaluate this condition
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 Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires() Returns a list of objects required to evaluate this condition
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 This type of condition can be converted to an EPANET control or rule conditional clause.

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 Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires()
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 Should be updated by the evaluate method if appropriate.
name

Methods

evaluate()
requires()
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

Returns

——-

bool

True if either condition evaluates to True; otherwise False

Attributes

backtrack
name

Methods

evaluate()
requires()
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

Returns

——-

bool

True if both conditions evaluate to True; otherwise False

Attributes

backtrack
name

Methods

evaluate()
requires()
class wntr.network.controls.BaseControlAction[source]

Bases: object

A base class for deriving new control actions. The control action is run by calling RunControlAction This class is not meant to be used directly. Derived classes must implement the RunControlActionImpl method.

Methods

RunControlAction(control_name) This method is called to run the corresponding control action.
requires() Returns a list of objects used to evaluate the control
RunControlAction(control_name)[source]

This method is called to run the corresponding control action.

requires()[source]

Returns a list of objects used to evaluate the control

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

RunControlAction(control_name) This method is called to run the corresponding control action.
requires()
class wntr.network.controls.Control[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 Control would be “when the simulation reaches 6 AM”. From an implementation standpoint, derived Control classes implement a particular mechanism for monitoring state (e.g. checking the simulation time to see if a change should be made). Then, they typically call RunControlAction on a derived ControlAction class. New Control classes (classes derived from Control) must implement the following methods: - _IsControlActionRequiredImpl(self, wnm, presolve_flag) - _RunControlActionImpl(self, wnm, priority)

Methods

IsControlActionRequired(wnm, presolve_flag) This method is called to see if any action is required by this control object.
RunControlAction(wnm, priority) This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
requires() Returns a list of objects required to evaluate this control
IsControlActionRequired(wnm, presolve_flag)[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).

Parameters:

wnm : WaterNetworkModel

An instance of the current WaterNetworkModel object that is being simulated.

presolve_flag : bool

This is true if we are calling before the solve, and false if we are calling after the solve (within the current timestep).

RunControlAction(wnm, priority)[source]

This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required. Note: Derived classes should not override this method, but should override _RunControlActionImpl instead.

Parameters:

wnm : WaterNetworkModel

An instance of the current WaterNetworkModel object that is being simulated/modified.

priority : int

A priority value. The action is only run if priority == self._priority.

requires()[source]

Returns a list of objects required to evaluate this control

class wntr.network.controls.IfThenElseControl(condition, then_actions, else_actions=None, priority=None, name=None)[source]

Bases: wntr.network.controls.Control

If-Then[-Else] contol

Attributes

name

Methods

IsControlActionRequired(wnm, presolve_flag) This method is called to see if any action is required by this control object.
RunControlAction(wnm, priority) This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
requires()
class wntr.network.controls.TimeControl(wnm, run_at_time, time_flag, daily_flag, control_action)[source]

Bases: wntr.network.controls.Control

A class for creating time controls to run a control action at a particular time. At the specified time, control_action will be run/activated.

Parameters:

wnm : WaterNetworkModel

The instance of the WaterNetworkModel class that is being simulated/modified.

run_at_time : int

Time (in seconds) when the control_action should be run.

time_flag : string

Options include SIM_TIME and SHIFTED_TIME * SIM_TIME indicates that the value of run_at_time is in seconds since

the start of the simulation

  • SHIFTED_TIME indicates that the value of run_at_time is shifted by the start time of the simulations. That is, run_at_time is in seconds since 12 AM on the first day of the simulation. Therefore, 7200 refers to 2:00 AM regardless of the start time of the simulation.

daily_flag : bool

  • False indicates that control will execute once when time is first encountered
  • True indicates that control will execute at the same time daily

control_action : An object derived from BaseControlAction

Examples: ControlAction This is the actual change that will occur at the specified time.

Methods

IsControlActionRequired(wnm, presolve_flag) This method is called to see if any action is required by this control object.
RunControlAction(wnm, priority) This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
requires()
class wntr.network.controls.ConditionalControl(source, operation, threshold, control_action)[source]

Bases: wntr.network.controls.Control

A class for creating controls that run when a specified condition is satisfied. The control_action is run/activated when the operation evaluated on the source object/attribute and the threshold is True.

Parameters:

source : tuple

A two-tuple. The first value should be an object (such as a Junction, Tank, Reservoir, Pipe, Pump, Valve, WaterNetworkModel, etc.). The second value should be an attribute of the object.

operation : numpy comparison method

Examples: numpy.greater, numpy.less_equal

threshold : float

A value to compare the source object attribute against

control_action : An object derived from BaseControlAction

Examples: ControlAction This object defines the actual change that will occur when the specified condition is satisfied.

Methods

IsControlActionRequired(wnm, presolve_flag) This method is called to see if any action is required by this control object.
RunControlAction(wnm, priority) This method is called to run the control action after a call to IsControlActionRequired indicates that an action is required.
requires()