DemandPatternLibrary#

module wntr.library.demand_library

class DemandPatternLibrary[source]#

Bases: object

Demand pattern library class.

Parameters:

filename_or_data (str (optional)) – Filename or JSON data containing a demand pattern library. If None, the default DemandPatternLibrary.json file is loaded.

__init__(filename_or_data=None)[source]#
add_combined_pattern(name, patterns_to_combine, combine='Overlap', weights=None, durations=[86400], pattern_timestep=3600, start_clocktime=0, wrap=True, normalize=False)[source]#

Combine patterns (overlap or sequential) to create a new pattern

Parameters:

  • name (str) – Pattern name

  • patterns_to_combine (list of str) – List of pattern names to combine

  • combine (str) – Combine method, Overlap or Sequential

  • weights (list) – List of weight applied to each pattern. If no weights are provided (None), then the patterns are equally weighted.

  • durations (list of ints or floats) – If combine method is Overlap, the list contains only one entry which is the total duration of the pattern (in seconds). If combine method is Sequential, the list contains one duration for each pattern to combine (in seconds).

  • pattern_timestep (int) – Timestep (in seconds) of the pattern

  • start_clocktime (int) – Time of day (in seconds from midnight) at which pattern begins

  • wrap (bool) – Indicates if the sequence of pattern values repeats

  • normalize (bool) – Indicates if the pattern should be normalized

Return type:

pandas Series

add_gaussian_pattern(name, mean, std, duration=86400, pattern_timestep=3600, start_clocktime=0, wrap=True, invert=False, normalize=False)[source]#

Add a Guassian pattern to the library defined by a mean and standard deviation

Gaussian patterns can be used to model water demand that gradually increases to a max water use, followed by gradual decline.

Parameters:

  • name (str) – Pattern name

  • mean (int or float) – Mean of the Guassian distribution

  • std (int or float) – Standard deviation of the Guassian distribution

  • duration (int or float) – Duration (in seconds) of the pattern

  • pattern_timestep (int) – Timestep (in seconds) of the pattern

  • start_clocktime (int) – Time of day (in seconds from midnight) at which pattern begins

  • wrap (bool) – Indicates if the sequence of pattern values repeats

  • invert (bool) – Indicates if the on/off values should be switched

  • normalize (bool) – Indicates if the pattern should be normalized

Return type:

pandas Series

add_pattern(name, entry)[source]#

Add a pattern to the library

Parameters:

  • name (str) – Pattern name

  • entry (dict) –

    Pattern entry which contains the following dictionary keys

    • name: Pattern name (string)

    • category: Pattern category (string, optional)

    • description: Pattern description (string, optional)

    • citation: Pattern citation (string, optional)

    • start_clocktime: Time of day (in seconds from midnight) at which pattern begins (integer)

    • pattern_timestep: Pattern timestep in seconds (integer)

    • wrap: Indicates if the sequence of pattern values repeats (True or False)

    • multipliers: Pattern values (list of floats)

Return type:

pandas Series

add_pulse_pattern(name, on_off_sequence, duration=86400, pattern_timestep=3600, start_clocktime=0, wrap=True, invert=False, normalize=False)[source]#

Add a pulse pattern to the library using a sequence of on/off times

Pulse patterns can be used to model sudden changes in water demand, for example, from a fire hydrant.

This pattern replicates functionality in Pattern.binary_pattern

Parameters:

  • name (str) – Pattern name

  • on_off_sequence (list) – A list of times to turn the pattern on/off (starting with on)

  • duration (int or float) – Duration (in seconds) of the resampled pattern

  • pattern_timestep (int) – Timestep (in seconds) of the resampled pattern

  • start_clocktime (int) – Time of day (in seconds from midnight) at which pattern begins

  • wrap (bool) – Indicates if the sequence of pattern values repeats

  • invert (bool) – Indicates if the on/off values should be switched

  • normalize (bool) – Indicates if the pattern should be normalized

Return type:

pandas Series

add_triangular_pattern(name, start, peak, end, duration=86400, pattern_timestep=3600, start_clocktime=0, wrap=True, invert=False, normalize=False)[source]#

Add a triangular pattern to the library defined by a start time, peak time, and end time

Triangular patterns can be used to model water demand that uniformly increases to a max water use, followed by uniform decline.

Parameters:

  • name (str) – Pattern name

  • start (int or float) – Start time (in seconds) of the triangular distribution

  • peak (int or float) – Peak time (in seconds) of the triangular distribution

  • end (int or float) – End time (in seconds) of the triangular distribution

  • duration (int or float) – Duration (in seconds) of the pattern

  • pattern_timestep (int) – Timestep (in seconds) of the pattern

  • start_clocktime (int) – Time of day (in seconds from midnight) at which pattern begins

  • wrap (bool) – Indicates if the sequence of pattern values repeats

  • invert (bool) – Indicates if the on/off values should be switched

  • normalize (bool) – Indicates if the pattern should be normalized

Return type:

pandas Series

apply_noise(name, std, normalize=False, seed=None, inplace=True)[source]#

Apply gaussian random noise to a pattern

Parameters:

  • name (str) – Pattern name

  • std (int or float) – Standard deviation

  • normalize (bool) – Indicates if the pattern should be normalized

  • seed (int) – Seed for the gaussian distribution

  • inplace (bool) – Indicates if the pattern should be modified in place

Return type:

pandas Series

copy_pattern(name, new_name)[source]#

Add a copy of an existing pattern to the library

Parameters:

  • name (str) – Existing pattern name

  • new_name (str) – New pattern name

filter_by_category(category)[source]#

Return a subset of the library, filtered by category

Parameters:

category (str) – Category name

Return type:

list of dictionaries

get_pattern(name)[source]#

Return a pattern entry from the demand pattern library

Parameters:

name (str) – Pattern name

Return type:

dictionary

normalize_pattern(name, inplace=True)[source]#

Normalize values in a pattern so the mean equals 1

Parameters:

  • name (str) – Pattern name

  • inplace (bool) – Indicates if the pattern should be modified in place

Return type:

pandas Series

plot_patterns(names=None, duration=None, ax=None)[source]#

Plot patterns

Parameters:

  • names (list of str) – Pattern names, if None then all patterns are plotted

  • duration (int or float) – Pattern duration (in seconds). If None, then the duration from the pattern entry is used.

Return type:

matplotlib axes object

remove_pattern(name)[source]#

Remove a pattern from the demand pattern library

Parameters:

name (str) – Pattern name

resample_multipliers(name, duration=86400, pattern_timestep=3600, start_clocktime=0, wrap=True, inplace=True)[source]#

Resample multipliers, which can change if the start_clocktime, pattern_timestep, or wrap status changes

Parameters:

  • name (str) – Pattern name

  • duration (int or float) – Duration (in seconds) of the resampled pattern

  • pattern_timestep (int) – Timestep (in seconds) of the resampled pattern

  • start_clocktime (int) – Time of day (in seconds from midnight) at which pattern begins

  • wrap (bool) – Indicates if the sequence of pattern values repeats

  • inplace (bool) – Indicates if the pattern should be modified in place

Return type:

pandas Series

to_Pattern(name, time_options=None)[source]#

Convert the pattern library entry to a WNTR Pattern

Parameters:

  • name (str) – Pattern name

  • time_options (None or tuple) – Time options (pattern_start, pattern_timestep, pattern_interpolation) If None, then time options from the pattern are used (in seconds).

Return type:

WNTR Pattern object

to_Series(name, duration=None)[source]#

Convert the pattern library entry to a Pandas Series

Parameters:

  • name (str) – Pattern name

  • duration (int, float, or None) – Pattern duration (in seconds). If None, then the duration from the pattern entry is used.

Return type:

pandas Series

write_json(filename)[source]#

Write the library to a JSON file

Parameters:

filename (str) – Filename for the library JSON file

property pattern_name_list#

Return a list of demand pattern entry names

Return type:

list of strings