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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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