WEAPVariable and WEAPVariables API Classes

The WEAPVariable class represents a Variable for a single Branch (e.g., Consumption for Branch \Demand Sites\South City), whereas WEAPVariables is a collection of all Variables for a given Branch (e.g., all variables for \Demand Sites\South City ).

A WEAPVariables collection comes from the Variables property of a WEAPBranch:

  1. WEAPBranch.Variables, e.g., WEAP.Branch("\Demand Sites\South City").Variables

You can get access to a WEAPVariable from the Variables collection:

  1. WEAPVariables(VariableName or Index), specifying either the name of the variable or a number from 1 to WEAPVariables.Count, e.g., WEAP.Branch("\Demand Sites\South City").Variables("Consumption") or WEAP.Branch("\Demand Sites\South City").Variables(1)

WEAPVariables Properties and Methods

Example (using VB script)

Count: Get the number of variables in the collection. Read only.

FOR i = 1 to WEAP.Branch("\Demand Sites\South City").Variables.Count;
  PRINT WEAP.Branch("\Demand Sites\South City").Variables(i).Name
NEXT

Exists(VariableName): Returns true if VariableName exists in the collection of variables for a branch.  Branch.Variables.Exists(VariableName) is equivalent to Branch.VariableExists(VariableName).  Read only.

IF WEAP.Branch("\Demand Sites\South City").Variables.Exists("Consumption") THEN
...

Item(Index): Get the variable identified by name or number (from 1 to Count).  Item is the "default" property, and therefore is usually omitted. Thus, the first two examples to the right are equivalent, as are the third and fourth examples.

PRINT WEAP.Branch("\Demand Sites\South City").Variables.Item(2).Name
PRINT WEAP.Branch("\Demand Sites\South City").Variables(2).Name

PRINT WEAP.Branch("\Demand Sites\South City").Variables.Item("Consumption").Name
PRINT WEAP.Branch("\Demand Sites\South City").Variables("Consumption").Name

NameList: Get a list of variables separated by character specified by optional parameter ListSeparator (which defaults to comma). Read only.

PRINT "South City Variables: " & WEAP.Branch("\Demand Sites\South City").Variables.NameList

 

WEAPVariable Properties and Methods

Example (using VB script)

DataSourceType(Scenario): Set or get the data source type (Enter Expression, Water Year Method, or Read from File) for the variable (only valid for the following inflow variables: river headflow, groundwater natural recharge, local reservoir inflow, other local supply inflow, surface water inflow) for the specified scenario (optional -- if blank it defaults to active scenario).

WEAP.Branch("Supply and Resources\River\Blue River").Variables("Headflow").DataSourceType("Current Accounts") = "Enter Expression"

WEAP.Branch("Supply and Resources\River\Weaping River").Variables("Headflow").DataSourceType("Reference") = "Water Year Method"

WEAP.Branch("Supply and Resources\River\Grey River").Variables("Headflow").DataSourceType("") = "Water Year Method"

Expression(InheritIfNecessary): Set or get the data expression for the variable. Because a blank expression will default to the expression from the parent scenario, use FALSE for the optional parameter InheritIfNecessary to prevent inheriting from the scenario.  Will apply to the active scenario.

V = WEAP.Branch("\Demand Sites\South City").Variables("Annual Activity Level") ' So we don't have to specify branch and variable every time

V.Expression = "Growth(3%)"

PRINT V.Expression

IF V.Expression(FALSE) = "" THEN 'check if blank in active scenario
  V.Expression = "Growth(3%)"
END IF

' You can also set the method for Demand Sites, Catchments and Groundwater
WEAP.Branch("\Demand Sites\West City").Variables("Method").Expression = "Specify monthly demand"

WEAP.Branch("\Demand Sites\Catchment 1").Variables("Method").Expression = "Rainfall Runoff (soil moisture method)"

WEAP.Branch("\Demand Sites\Catchment 1").Variables("Method").Expression = "MABIA"

WEAP.Branch("\Supply and Resources\Groundwater\North Aquifer").Variables("Method").Expression = "Model GW-SW Flows

IsReadOnly: Is this variable locked for editing?  If so, the default value or expression will be used.  Read only.

FOR EACH V in WEAP.Branch("\Demand Sites\South City").Variables

     IF V.IsReadOnly THEN
    PRINT V.Name + " is read only"
  ELSE
    PRINT V.Name + " is not read only"
NEXT

IsResultVariable: Is this a result variable (vs. a data variable).  Read only.

PRINT WEAP.Branch("\Demand Sites\South City").Variables("Consumption").IsResultVariable  ' This is false

PRINT WEAP.Branch("\Demand Sites\South City").Variables("Reliability").IsResultVariable  ' This is true

Name: Get the name of the variable. Read only.

PRINT WEAP.Branch("\Demand Sites\South City").Variables(1).Name

ResultExists(Year, TimeStepNumber, Scenario): Return TRUE if the result exists for that scenario, year and timestep, FALSE if not.  (For example, River Flood Inflow only exists for catchment branches if there is non-zero flooding inflow in that timestep.)

IF NOT WEAP.ResultExists(2015, 7, "Reference") THEN

  Print "Cannot find river flood inflow result"

END IF

ResultValues(Year1, Year2, Scenario): Get array of result values for every timestep in one or more years.  If Year2 is omitted, values for Year1 are returned.  If Scenario is omitted, the active scenario will be used. If the result variable is daily, then 365 (or 366 for leap years if leap days are used) values per year will be returned, regardless of the area timestep.  Precision will depend on value of WEAP.ResultsExportPrecision.

' Get results for all years at once (much faster than one at a time with WEAPVariable.ResultValue)

Results = WEAP.Branch("Central Reservoir").Variables("Storage Volume").ResultValues(WEAP.BaseYear, WEAP.EndYear, "Reference")

i = 0

FOR Y = WEAP.BaseYear TO WEAP.EndYear

  FOR TS = 1 TO WEAP.NumTimesteps

    i = i + 1

    PRINT Y & "," & TS & "," & Results(i)

  NEXT

NEXT

Scale: Get the numerical value of the scale, e.g., if ScaleUnit = "Million m^3", Scale = 1000000

' Calculate the total population of all demands sites downsteam of North Reservoir

TotalPopulation = 0

FOR EACH Br IN WEAP.Branch("North Reservoir").DownstreamNodes(True).FilterByType("Demand Site")

  IF Br.Variable("Annual Activity Level").Unit = "cap" THEN    ' is the unit population?

    Population = Br.Variable("Annual Activity Level").Scale * Br.Variable("Annual Activity Level").ResultValue(WEAP.BaseYear, 1)

    Print Br.FullName & " population = " & Population

    TotalPopulation = TotalPopulation + Population

  END IF

NEXT

PRINT

Print "Total population = " & TotalPopulation

ScaleUnit: Set or get a string containing the scale and units of the variable (works with both data and results variables). Only demand and key assumptions variables' units can be changed.

WEAP.Branch("\Demand Sites\West City").Variables("Annual Activity Level").ScaleUnit = "Million Person"

WEAP.Branch("\Demand Sites\West City").Variables("Annual Water Use Rate").ScaleUnit = "1000 m^3"

WEAP.Branch("\Key Assumptions\Drivers\GDP").Variables("Annual Activity Level").ScaleUnit = "European Euro"

PRINT WEAP.Branch("\Demand Sites\South City").Variables("Annual Activity Level").ScaleUnit  ' This is "Million cap"

PRINT WEAP.Branch("\Supply and Resources\River\Weaping River\Reservoirs\Central Reservoir:Storage Volume").ScaleUnit  ' This is m^3

Unit: Get a string containing the units of the data value, e.g., "m^3" or "CFS".

' Calculate the total population of all demands sites downsteam of North Reservoir

TotalPopulation = 0

FOR EACH Br IN WEAP.Branch("North Reservoir").DownstreamNodes(True).FilterByType("Demand Site")

  IF Br.Variable("Annual Activity Level").Unit = "cap" THEN    ' is the unit population?

    Population = Br.Variable("Annual Activity Level").Scale * Br.Variable("Annual Activity Level").ResultValue(WEAP.BaseYear, 1)

    Print Br.FullName & "  " & WEAP.BaseYear & " population = " & Population

    TotalPopulation = TotalPopulation + Population

  END IF

NEXT

PRINT

Print "Total " & WEAP.BaseYear & " population = " & TotalPopulation

Value(Year, TimeStepNumber, Scenario, Year2, TimeStep2, FunctionType, PercentileValue): Get a single result value or an aggregate result value (e.g., sum or average over time). TimeStepNumber is the index of the timestep, e.g., for June, the TimeStepNumber is 6 (assuming the water year begins in January). The Year and TimeStepNumber parameters are omitted for variables that have a single value for the entire study period (e.g., Demand Site Reliability). Omit Year2 and TimeStepNumber2 to get a single value. Available functions for FunctionType are: Total, Average, Median, Minimum, Maximum, Percentile and CV (coefficient of variation). If FunctionType is omitted, the Total will be calculated. PercentileValue is only used if FunctionType is Percentile. If the Scenario parameter is omitted, the active scenario will be used. Will switch to Results View if necessary, calculating results as needed. Read only.

Note: WEAP.Branch(BranchName).Variables(VariableName).Value(Year, ....) is equivalent to WEAP.ResultValue(BranchName:VariableName, Year, ...), although WEAP.ResultValue lets you choose the scale and unit to report.  

A few result variables have extra "dimensions," e.g., Supply Delivered has a Source dimension, River Water Quality has a Water Quality Constituent dimension, and Net Benefit has a Cost/Benefit dimension.  The WEAPVariable.Value method cannot access individual items in a dimension; instead, WEAP will sum up the values across all items, e.g., for costs, it will add Capital Costs, Operating Costs and Benefits.  Because you cannot sum across Water Quality Constituents, you cannot use the Variable.Value method to access River Water Quality results.  NB: WEAP.ResultValue is able to select individual items in a dimension -- see WEAP.ResultValue for more information.

The result will be written in the default unit for that unit class:

 

Unit Class

Default Unit

Area

Square Meter (m^2)

Concentration

Gram/Liter (g/l)

Currency

US Dollar ($)

Energy

Gigajoule (GJ)

Flow

Cubic Meters per Second (CMS)

Length

Meter (m)

Mass

Kilogram (kg)

Power

Kilowatt (kW)

Velocity

Meters/Second (m/s)

Volume

Cubic Meter (m^3)

PRINT WEAP.Branch("\Demand Sites\South City").Variables("Reliability").Value 'Reliability is for the entire study period, so doesn't have a year or time step parameter

V = WEAP.Branch("\Supply and Resources\River\Weaping River\Reservoirs\Central Reservoir").Variables("Storage Volume") ' So we don't have to specify branch and variable every time

PRINT V.Value(2010, 7)

PRINT V.Value(2015, 7, "Reference")

V = WEAP.Branch("\Demand Sites\Industry East").Variables("Unmet Demand") ' So we don't have to specify branch and variable every time

PRINT V.Value(2015, 1, "Reference", 2015, WEAP.NumTimeSteps) ' total unmet demand for 2015

PRINT V.Value(WEAP.BaseYear, 1, "Reference", WEAP.EndYear, WEAP.NumTimeSteps) ' total unmet demand for entire study period

PRINT V.Value(WEAP.BaseYear, 1, "Reference", WEAP.EndYear, WEAP.NumTimeSteps, "Average") ' average unmet demand for entire study period

PRINT V.Value(WEAP.BaseYear, 1, "Reference", WEAP.EndYear, WEAP.NumTimeSteps, "Percentile", 90) ' the 90th percentile value for unmet demand for entire study period