DDSum()

Format

DDSum(Input Values)

Returns

Sums the input values for each timestamp. Typically this function is used on the return value of a DDGet() or DDGetAttributes() call since these functions can return multiple values for a single timestamp (by fetching the attribute of several entities).

It is possible to retrieve very large volumes of data through indiscriminate use of this function. Retrieving large amounts of Historian data across a slow network can affect system performance for all users of the system.

Inputs

Input Values: A collection of values where each value contains the necessary metadata (see Useful to Know below) which indicates the name of the source entity (DDGet() and DDGetAttributes() can produce such return values).
Behaviour: Required
Dimensions: MultiCollection
Valid data types: Decimal, Integer

How to format data types

Error Conditions

An error will be thrown if:

• A tag or entity supplied as an argument does not exist.
• The data type of a parameter is not valid.
• There is a mix of decimals and integers in the same collection - this may occur if your input is a DD function with a level deeper than 1 and where the lowest level returns an integer (e.g. DDSum(DDGet("P2 Corporate", 4, entity, ":Status")).
  • Error: Parameter no. 1 of function 'DDSum' is incorrect. Expected parameter type(s): collection. Supplied parameter type: error.
    The type of the supplied VariableValue ("Integer") is not compatible with the type of the VariableValueCollection ("Decimal").

Useful to Know

In the calculation engine, values returned by DD() functions have metadata assigned to them, such as entity name and start/end times. Other DD() functions can use this metadata to assign additional information to values they receive. In this way, the metadata is used by nested DD() functions to reduce complexity but increase versatility. Which metadata is used and how it is used is specific to each function, and is described in the Input Values section above, where applicable.

Examples

Expression: DDSum(DDGetAttributes(DDGetEntities("myHierarchy", 2, "rootEntity"), ":myAttribute"))
Description: This expression produces a similar result to "Sum({childEntity1:myAttribute}, {childEntity2:myAttribute},... {childEntityN:myAttribute})".
Result: Returns the sum of all fetched values of "myAttribute" for each child entity maximum 2 levels below the "rootEntity" in "myHierarchy".

Tip: If you have access to the sample data, try running the following examples using the calculation tester. 

Expression: DDSum({SampleDDGet})
Returns: The sum of all fetched values in the SampleDDGet calculation tag. This tag is actually the same as the DDGet() function in the below example.
Result: 608.7259133387012

Expression: DDSum(DDGet("P2 Corporate", 5, "Western Australia", ":Oil Production", "{[Oil Producing Well]:Status} == 0", "Oil Producing Well"))
Returns: The total oil production, for each timestamp, of each Oil Producing Well in Western Australia, in the P2 Corporate hierarchy, where the well is online (status is 0).
Result: 608.7259133387012

Related Functions

The following table illustrates the difference between the Sum_Sampled(), Sum(), and DDSum() functions. The following calculations were used to sum a row (Sum_Sampled) or column (Sum and DDSum):

Total Daily Oil Production for all online wells:
DDSum(DDGet("Hierarchy", 2, "Field1", ":Oil Production", "{[Well]:Status} == 'Online'", "Well"))
Sum({Well 1:Oil Production},{Well 2:Oil Production})
Sum({Well 1:Oil Production},{Well 2:Oil Production},{Well 3:Oil Production})

Total Weekly Oil Production for a well:
Sum_Sampled({Well 1:Oil Production},"Monday","Friday")
Sum_Sampled({Well 2:Oil Production},"Monday","Friday")
Sum_Sampled({Well 3:Oil Production},"Tuesday","Friday")

In this example, Well 3 did not exist before Tuesday, and the Sum() and Sum_Sampled() calculations will throw an error if an entity does not exist.

Entity/Attributes			Timestamps
			Monday**	Tuesday	Wednesday	Thursday	Friday	Total Weekly Oil Production Using Sum_Sampled()^	Calc Used:
Field 1	Well 1	Production (bbl):	1	3	2	4	2	12	Sum_Sampled({Well 1:Oil Production},"Monday","Friday")
		Status:	Online	Offline	Online	Online	Online
	Well 2	Production (bbl):	2	1	1	3	2	9	Sum_Sampled({Well 2:Oil Production},"Monday","Friday")
		Status:	Online	Online	Offline	Online	Online
	Well 3*	Production (bbl):	DID NOT EXIST	2	1	2	2	7*	Sum_Sampled({Well 3:Oil Production},"Tuesday","Friday")
		Status:		Online	Online	Offline	Online
Total Daily Oil Production Using Sum()			3**	6	4	9	6
			Sum({Well 1:Oil Production},{Well 2:Oil Production})	Sum({Well 1:Oil Production},{Well 2:Oil Production},{Well 3:Oil Production})	Sum({Well 1:Oil Production},{Well 2:Oil Production},{Well 3:Oil Production})	Sum({Well 1:Oil Production},{Well 2:Oil Production},{Well 3:Oil Production})	Sum({Well 1:Oil Production},{Well 2:Oil Production},{Well 3:Oil Production})
Total Daily Oil Production Using DDSum()^ DDSum(DDGet("Hierarchy", 2, "Field1", ":Oil Production", "{[Well]:Status} == 'Online'", "Well"))			Error: Well 3:Status doesn't exist	3	3	7	6

Notes:

* For Well 3, the Sum_Sampled() calculation should not include Monday, because it did not exist then. It will throw an error if you try to evaluate Well 3 starting from Monday, but will return a value if you evaluate it from Tuesday.

** On Monday, the Sum() calculation should not include Well 3, because it did not exist then and will throw an error. Well 3 can only be included in the calculation from Tuesday onwards.

^ For an explanation of how the values for Sum_Sampled() and Sum() are calculated, refer to their respective pages.

Release History

• DDSum() 4.6.5
  • Changed InputValues parameter dimension from Collection to MultiCollection.
• DDSum() 4.5.0
  • Initial version