Understanding Formulas
Use formula properties to understand how Arcadia calculates derived tariff values such as billing factors, demand values, and tier limits.
Use formula properties to trace how calculated tariff values are derived from other properties, limits, or variables.
Understand formulas
A formula is a data type that allows the calculation engine to compute values based on other property values or variables. Formulas define relationships between properties and return a result based on that relationship.
Understand functions in formulas
Functions can be invoked within formulas to specify which limit should be respected. The available functions are Min and Max, aliased as fnMinUpperLimit and fnMaxUpperLimit. In the context of tiered rates, the upper limit refers to the consumption or demand limit specified for each tier within a tariff rate. By finding the maximum upper limit, you can identify the highest limit value among the tiers. Conversely, you can identify the lowest limit value among the tiers by finding the minimum upper limit.
| Display Name | Type | Description | Example |
|---|---|---|---|
| Min | Function | The minimum function takes a List of items and determines the smallest value in it. | # fnMin( {2 , 1.1, 3.6} ) returns 1.1 |
| Max | Function | The max function takes a List of items and determines the largest value in it. | # fnMax( {2 , 1.1, 3.6} ) returns 3.6 |
| fnMinUpperLimit | Alias | Minimum Upper Limit will work with different types of objects related to upper limits (including null for no upper limit) and determine the min. | # fnMinUpperLimit( { ( #tariffRateBand.propertyUpperLimit?:9999999 ) * #billingDemand2416 , ( #tariffRateBand.prevUpperLimit + ( #tariffRateBand.consumptionUpperLimit?:9999999 ) ) } ) |
| fnMaxUpperLimit | Alias | Maximum Upper Limit will work with different types of objects related to upper limits (including null for no upper limit) and determine the max. | # fnMaxUpperLimit( { ( #tariffRateBand.propertyUpperLimit?:9999999 ) * #billingDemand2416 , ( #tariffRateBand.prevUpperLimit + ( #tariffRateBand.consumptionUpperLimit?:9999999 ) ) } ) |
Review the anatomy of a formula
This is an example of a relatively simple FORMULA that takes the number of billing days and divides that value by 365 (days in a standard calendar year).
GET /rest/public/properties/billingPeriodYearFactor{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "billingPeriodYearFactor",
"displayName": "Billing Period Factor",
"family": "formula",
"keyspace": "tariff",
"description": "Total Billing Days divided by 365",
"dataType": "FORMULA",
"formulaDetail": "( #billingPeriod.days / 365.00 )"
}
]
}A DEMAND type PropertyKey can contain a formula or be a part of another formula. This example adds the results from two different PropertyKey objects to return a single result.
GET /rest/public/properties/billing2Demand1517?fields=ext{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "billing2Demand1517",
"displayName": "Total Billing Demand",
"family": "formula",
"keyspace": "tariff",
"description": "Total kW metered during the billing period",
"dataType": "DEMAND",
"formulaDetail": "#offPeakBillingDemand1517 + #onPeakBillingDemand1517",
"lookbackPeriod": "",
"entityId": 1517,
"entityType": "LSE",
"privacy": "PUBLIC"
}
]
}In each example, the formulaDetail field provides the mathematical expression used in the formula.
Walk through a formula
Let's take everything we have covered thus far and walk through a more complex formula example.
GET /rest/public/properties/ratchet2wBillingDemand2437?fields=ext{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "ratchet2wBillingDemand2437",
"displayName": "Ratchet Billing Demand",
"family": "ratchetDemand",
"keyspace": "tariff",
"description": "The highest of the 1) On-peak 15 minute interval in the previous month, 2) 90% of the on-peak kVA demand, 3) Off-peak 15 minute interval discounted by 55% and 4) 90% of the off-peak kVA demand discounted by 55%.",
"dataType": "DEMAND",
"quantityUnit": "",
"formulaDetail": "#fnMaxUpperLimit ( { #winterOnPeakBillingDemand2437 , #winterOnPeakKVADemand2437 * 0.9 , #winterOffPeakBillingDemand2437 * 0.45 , #winterOffPeakKVADemand2437 * 0.405 } )",
"lookbackPeriod": "",
"entityId": 2437,
"entityType": "LSE",
"privacy": "PUBLIC"
}
]
}The formulaDetail key uses the fnMaxUpperLimit function to find the maximum value across four PropertyKey objects.
| # fnMaxUpperLimit |
|---|
| # winterOnPeakBillingDemand2437 |
| # winterOnPeakKVADemand2437 * 0.9 |
| # winterOffPeakBillingDemand2437 * 0.45 |
| # winterOffPeakKVADemand2437 * 0.405 |
You can identify each PropertyKey object in the formula to understand how those values are calculated and fed into the larger formula.
We will focus on winterOffPeakBillingDemand2437 specifically, but note that this process would be the same for the others. Using the Property Key API we pass in our keyName and instruct the API to return all available fields via fields=ext.
GET /rest/public/properties/winterOffPeakBillingDemand2437?fields=ext{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "winterOffPeakBillingDemand2437",
"displayName": "Winter Off-Peak Billing Demand",
"family": "peakDemand",
"keyspace": "tariff",
"description": "The peak 15 minute interval in the Off-Peak period during the previous month.",
"dataType": "DEMAND",
"quantityUnit": "kW",
"lookbackIntervalQuantity": 15,
"lookbackQuantity": 1,
"lookbackPeriod": "BILLING_PERIOD",
"lookbackTimeOfUseId": 1102,
"entityId": 2437,
"entityType": "LSE",
"privacy": "PUBLIC"
}
]
}The description field provides a human-readable overview of what this PropertyKey represents. In this case, it represents "The peak 15 minute interval in the Off-Peak period during the previous month." Fields prefixed by lookback provide additional context into how usage data is observed to derive the peak interval.
| Key | Description |
|---|---|
| lookbackIntervalQuantity | The segment of data that is being observed in minutes. |
| lookbackQuantity | A numeric value that scales the lookbackPeriod. |
| lookbackPeriod | A string indicating the time period for the lookback calculation, which is always BILLING_PERIOD. The lookbackQuantity specifies how many periods to look back. |
| lookbackTimeOfUseId | An ID used to identify the corresponding time of use (TOU) object. Use this ID to retrieve the TOU definition from the Time of Use API. |
| lookbackSeasonId | An ID used to identify the corresponding season object. Use this ID to retrieve the season definition from the Seasons API. |
Follow these steps for the other PropertyKey objects to understand how usage data determines rates within the selected tariff.
Related guides
Updated 1 day ago