`lib-tariff` 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793259390/FIN+5.3.1+lib-tariff 中文整理基于 FIN 5.3.1

导读： 公用事业费率引擎

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

lib
meta
docs
tags
funcs
views
Overview
Tariffs
Charges
- Usage-Based Charges
- Consumption Charges
- Demand Charges
- Fixed Charges
- Percentage Charges
- Axon Charges
Configuring Bill Periods
Historical Fees
Utility Functions
- def
tariffBillPeriod(meter, date)
- supertypes
tariffConsumptionCharge(tariff, dis, meterType, strategy, ranges, optTags: {})
tariffCost(meter, dates, opts: {})
tariffCostToHis(rec, dates, opts, yield)
- src
tariffCreate(dis, currency)
tariffCreateBillHis(rec: null, his: null, opts: {})
tariffDemandCharge(tariff, dis, meterType, strategy, ranges, optTags: {})
tariffFixedCharge(tariff, dis, fee, freq: "bill")
tariffPercentageCharge(tariff, dis, percentage, charges)
- tags
- usage
- subtypes
- enum

概述（中译）

公用事业费率引擎

API 正文（英文）

docs

Overview • Tariffs • Charges • Configuring Bill Periods • Historical Fees • Utility Functions

tags


tariff	A tariff rec
tariffAxonCharge	An Axon charge rec
tariffCharge	A tariff charge rec
tariffChargeFunc	The name of the function that tariff engine should call to compute the cost
tariffChargeRef	Reference to an entity
tariffChargeRefs	The charges that a percentage charge applies to
tariffConsumptionCharge	A consumption charge rec
tariffContractMin	The minimum contractual demand necessary for this charge to apply
tariffDemandCharge	A demand charge rec
tariffFee	A fixed numeric fee for the charge
tariffFeeFreq	The frequency that the charge applies per bill period
tariffFeeHisRef	The ref to the history point that contains the historical fee data
tariffFixedCharge	A fixed charge rec
tariffHis	Identifies the tariff history point for a meter
tariffHisRef	If multiple meters share the same tariff history, then you can use this tag to reference the "master" point containing the tariff history
tariffPercentageCharge	A percentage charge rec
tariffRangeStrategy	When a charge has multiple ranges this tag indicates to the tariff engine how to interpret and calculate costs based on those ranges
tariffRanges	The fee ranges for a usage-based charge
tariffRatchetPercentage	The peak demand identified during the ratchet period will be multiplied by this percentage to obtain the minimum peak demand
tariffRatchetPeriod	A value representing how far back to go when calculating the minimum peak demand for a billing period
tariffRef	The tariff a charge belongs to
tariffUsageOn	An axon filter used by the tariff engine to identify the charge's historical usage data

funcs


tariffBillPeriod	For the given meter, get the date span of the bill period containing the given date
tariffConsumptionCharge	Create a consumption charge
tariffCost	Calculate the cost of energy for a meter
tariffCostToHis	Function to create a computed history for the tariff cost associated with that meter
tariffCreate	Create a new tariff
tariffCreateBillHis	Create the billing period history point
tariffDemandCharge	Create a demand charge
tariffFixedCharge	Create a fixed charge
tariffPercentageCharge	Create a percentage charge

views


tariffBillPeriods	Manage tariff billing periods
tariffCost	Analyze tariff costs against energy usage
tariffs	Tariff builder used to edit tariff and charge records

lib tariff

Overview

The TariffExt provides a common model for describing energy tariffs in SkySpark.

To setup a tariff and apply it to a meter, the following high-level steps need to be completed. The rest of this guide describes these steps in more details

Create a tariff record
Create records for all the charges in your tariff
Create the tariff history point that defines the bill periods for your meter

Tariffs

A tariff models a collection of charges that apply to an energy meter. The following tags are used on records to define a tariff.

tariff: Marker tag that identifies the record as a tariff.
currency: Str for the currency unit of this tariff. All charges in the tariff must be expressed in terms of this unit.

dis: "Schedule 1B"
tariff
currency: "€"

Charges

A charge is the term used to describe the different cost components of a tariff. Energy tariffs often define many cost components. For example: service charges, consumption and demand charges, and taxes. The tariff ext provides models for these different kinds of charges.

All charges share the following tags.

tariffCharge: Marker tag that identifies the record as a tariff charge.
tariffRef: Ref of the tariff that this charge belongs to.
scheduleRef: (optional) Ref for the schedule that defines when this charge applies.
scheduleVal: Str. When a schedule is applied to this charge, the charge only applies when the schedule has this value. Schedules are most commonly used with "usage-based" charges. For example, if the tag's value is onPeak, then only data in the periods when the schedule's value is onPeak will be used for calculating the charge. This tag is required if scheduleRef is specified.

The following sections describe the different charge types in more detail.

Usage-Based Charges

A usage-based charge is any charge this is calculated as a function of usage data. Usage data in the tariff ext falls into one of two categories: 1) consumption, and 2) demand. Consumption data measures the amount of energy/resource consumed, and demand data measures the rate at which the energy/resource is consumed.

A usage-based charge uses the tariffUsageOn tag to define an Axon filter to find the sensor point that contains the historical usage data for that charge. The filter is based on the meter type (elec, gas, water), and whether the charge is for consumption or demand. The tariff engine will ensure the filter is applied to the relevant meter. For example, this filter will would find the energy consumption data:

energy and sensor

Internally, the engine will constrain this filter to the current meter as

energy and sensor and equipRef == meterRef

The history data from the matched point is then used for calculating the cost of the charge.

Ranges

It is common for usage-based charges to have different costs based on the amount of energy/resource used. For example, a consumption charge might be specified as:

First 1,400 kWh @ 3.722¢ per kWh
Over 1,400 kWh @ 4.995¢ per kWh

Ranges allow us to express these types of charge costs. Ranges are modeled as a grid on the usage charge and are stored in the tariffRanges tag. The rows specify ranges, and the columns are

min: (Number) the minimum value for this range (exclusive).
max: (Number) the maximum value for this range (inclusive).
tariffFee: (Number) the numeric fee for this range.
tariffFeeHisRef: (Ref) the point with historical fee data for this range

You must specify a min, max, and one of tariffFee or tariffFeeHisRef.

So, for the example above, the ranges tag would be

tariffRanges:Zinc:
  ver:"3.0"
  min,  max,   tariffFee
  0,    1400,  3.722
  1400, INF,   4.995

All usage charges must have at least one range. It is not necessary for the ranges to be contiguous. The tariff ext will fill all gaps with zero-cost ranges.

Single, all-inclusive range:

tariffRanges:Zinc:
  ver:"3.0"
  min,  max,   tariffFee
  0,    INF,   4.115

Partial, non-contiguous range:

tariffRanges:Zinc:
  ver:"3.0"
  min,  max,   tariffFee
  1400, INF,   4.995

Range Strategy

The tariffRanges tag allows us to define the ranges for our usage-based charges. The tariffRangeStrategy tag tells the tariff engine how to calculate the cost for a usage-based charge based on those defined ranges. It can have one of three values:

cumulative: All ranges up-to-and-including the range containing the total/peak usage are used in calculating the cost.
inRange: Only the range containing the total/peak usage is used in calculating the cost.
perReading: Instead of looking at the total or peak usage, the cost for each individual data reading is calculated based on the range it falls in.

To illustrate the difference between the strategies, consider this demand charge specification

0-100 kW @ $1.00 per kW
100-150 kW @ $2.00 per kW
Over 150 kW @ $3.00 per kW

Suppose the customer's peak demand is 125 kW. For the cumulative range strategy we look at each range and calculate the cost based on how much of that range contributed to the total/peak usage. In this case, all 100kW of the first range contributed to the peak demand of 125kW. For the second range, only 25kW contributed, and for the last range 0kW contributed. So the cost is:

(100kW * $1.00/kW) + (25kW * $2.00/kW) + (0kW * $3.00/kW) = $150

For the inRange strategy, we find the one and only range that contains the total/peak usage and use that for calculating the cost. Since 125kW falls into the second range the cost is:

(125kW * $2.00/kW) = $250

The cumulative and inRange strategies are essentially looking at rolled up values - total (sum) for consumption data, and peak (max) for demand data. The perReading strategy looks at each individual data reading and calculates the cost for that reading based on the range it falls into. This table shows how the cost would be calculated for the given demand data based on the different strategies.

ts      demand  perReading Cost  cumulative Cost  inRange Cost
-----   ------  ---------------  ---------------  ------------
00:00   5 kW    $5               $0               $0
00:15   50 kW   $50              $0               $0
00:30   125 kW  $250             $150             $250
00:45   10 kW   $10              $0               $0

Consumption Charges

A consumption charge is a usage-based charge that calculates cost based on the amount of energy/resource consumed. It applies only to consumption sensor data. A consumption charge is tagged with the tariffCharge and tariffConsumptionCharge tags. There are no additional tags required to configure a consumption charge.

Consider this example consumption charge specification

Generation kWh Charge
1. For the Billing Months of June - September
  1. First 1,400 kWh @ 3.722¢ per kWh
  2. Over 1,400 kWh @ 4.995¢ per kWh

If the tariff's currency is in $, then this consumption charge could be modeled as

dis: "Generation kWh Charge - Summer"
tariffRef: @ExampleTariff
tariffUsageOn: "energy and sensor"
tariffCharge
tariffConsumptionCharge
scheduleRef: @SeasonSchedule
scheduleVal: "summer"
tariffRangeStrategy: "cumulative"
tariffRanges:Zinc:
  ver:"3.0"
  min,    max,    tariffFee
  0,      1400,   0.03722
  1400,   INF,    0.04995

Demand Charges

A demand charge is a usage-based charge that calculates cost based on the rate at which energy or a resource is consumed. It applies only to demand sensor data. A deman charge is tagged with the tariffCharge and tariffDemandCharge tags. Except in the case where the range strategy is perReading, a demand charge looks at historical usage and finds the peak (maximum) demand interval. It then uses this peak value as the basis for calculating the cost.

In addition to all the standard charge and usage-based charge tags, a demand charge may be configured with the following optional tags

tariffContractMin: (Number) - the minimum contracted demand for this charge. When specified, the peak demand used to calculate the cost is never less than this value. This is sometimes referred to as a simple "ratchet" demand charge.
tariffRatchetPeriod: (Str) - A value representing how far back to go when calculating the minimum peak demand for a billing period. This is sometimes referred to as a "historical" ratchet.
Currently, the tariff engine can only look back by bill periods. Its value must be of the form "{N}bills", where "N" is the number of bill periods to consider and includes the current bill period. For example, 12bills indicates we should look at this bill period's data as well as the previous 11 months to determine the minimum peak demand.
NOTE: the tariffContractMin is still in effect if both are specified.
tariffRatchetPercentage: (Number) - This tag is only valid when tariffRatchetPeriod is also specified. When this tag is present, the peak demand identified during the ratchet period is multiplied by this percentage to obtain the minimum peak demand. If it is not specified, the default value is logically 100%.

The following is an example of modeling a basic peak demand charge.

Generation Demand Charge
1. For the Billing Months of June - September
  All kW of Demand @ $2.119 per kW
2. For the Billing Months of October - May
  All kW of Demand @ $0.681 per kW

dis: "Generation Demand Charge - Summer"
tariffRef: @ExampleTariff
tariffUsageOn: "demand and sensor"
tariffCharge
tariffDemandCharge
scheduleRef: @SeasonSchedule
scheduleVal: "summer"
tariffRangeStrategy: "inRange"
tariffRanges:Zinc:
  ver:"3.0"
  min,    max,    tariffFee
  0,      INF,    2.119

dis: "Generation Demand Charge - Winter"
tariffRef: @ExampleTariff
tariffUsageOn: "demand and sensor"
tariffCharge
tariffDemandCharge
scheduleRef: @SeasonSchedule
scheduleVal: "winter"
tariffRangeStrategy: "inRange"
tariffRanges:Zinc:
  ver:"3.0"
  min,    max,    tariffFee
  0,      INF,    0.681

This example demonstrates modeling a peak demand charge with a historical ratchet and contract minimum.

The distribution demand shall be such as may be contracted for but not less than the highest of:
1. The highest average kW measured at the location during any 30-minute interval of the current and previous 11 billing months.
2. 30 kW.
Transmission Demand Charge
1. All on-peak ES kW of Demand @ $2.313 per kW

dis: "On-Peak Demand Charge Winter"
tariffRef: @ExampleTariff
tariffUsageOn: "demand and sensor"
scheduleRef: @TOUSched
scheduleVal: "onPeak"
tariffCharge
tariffDemandCharge
tariffRangeStrategy: "inRange"
tariffRanges:Zinc:
  ver:"3.0"
  min,    max,    tariffFee
  0,      INF,    2.313
tariffContractMin: 30
tariffRatchetPeriod: "12bills"
tariffRatchetPercentage: 100

Fixed Charges

A fixed charge is for a charge that applies on a regular interval. A fixed charge is tagged with the tariffCharge and tariffFixedCharge tags. Typical examples of fixed charges are service charges, or rental fees. A fixed charge defines some additional configuration tags:

tariffFee (Number): The numeric fee for the charge.
tariffFeeHisRef (Ref): The Ref to a history point that contains the historical fee data
tariffFeeFreq (optional) (Str): the frequency that the charge applies within a bill period. It supports two types of values:
1. If set to "bill" then the charge applies per bill period. This is the default value.
2. The Str encoding of a Duration. In this case it specifies how often within a bill period the charge applies. For example "1day", or "1hr"

dis: "Service Charge"
tariffRef: @ExampleTariff
tariffCharge
tariffFixedCharge
tariffFee: 102.50
tariffFeeFreq: "bill"

dis: "Rental Fee"
tariffRef: @ExampleTariff
tariffCharge
tariffFixedCharge
tariffFee: 2.50
tariffFeeFreq: "1day"

Percentage Charges

A percentage charge is used for any cost component that represents a percentage of one or more other cost components. The typical use case is for taxes. A percentage charge is tagged with the tariffCharge and tariffPercentageCharge tags. A percentage charge defines some additional configuration tags:

tariffChargeRefs (Ref[]) - The refs of the charges that this percentage charge applies to It is valid to reference other percentage charges, but it is an error to create a circular dependency.
percentage (Number): The percentage to apply to the sum of the referenced charges. This should be a number between 0 and 100.

// a 3.5% state tax on the service charge and consumption charge
dis: "State Tax"
tariffRef: @ExampleTariff
tariffCharge
tariffPercentageCharge
percentage: 3.5
tariffChargeRefs: [@ServiceCharge,@ConsumptionCharge]

Axon Charges

(This charge type is incubating and is subject to change)

An axon charge allows you to delegate the cost calculation to a custom Axon function that you have written. Is can be used if one of the other charge types does not adequately model your charge. Ax Axon charge is tagged with the tariffCharge and tariffAxonCharge tags. An axon charge defines some additional configuration tags:

tariffChargeFunc (Str) - The name of the axon function that performs the cost calculation.

The func must have the following signature

myChargeFunc(meter, dates, charge)

It is passed the meter to calculate cost against, the date span of the current billing period being calculated, and the axon charge record itself. You should put any custom configuration tags on the charge record. The function should return a grid with a single row, and the following columns

"cost" (Grid) - This column is required. Its value is a history grid. The history grid should be the computed cost for the entire date span passed into the axon charge function.
"data" (Grid) - You may optionally return a history grid containing the raw data values used to calculate the cost for the axon charge.

Note: the tariff engine completely delegates computation to the axon function. In particular, it does not do any schedule filtering.

dis: "Custom Charge"
tariffRef: @ExampleTariff
tariffCharge
tariffAxonCharge
tariffChargeFunc: "myChargeFunc"

Here is a very simple axon charge function that calculates just a constant value

(meter, dates, charge) => do
   {
     cost: {ts: dates.start, v0: 100$}.toGrid
   }.toGrid
end

Configuring Bill Periods

A meter is billed by an energy company on a semi-regular basis. The date span for each bill is called the bill period. In order to more accurately report the cost for arbitrary date ranges, the tariff engine needs to know when a bill period begins, and how long it lasts. Further, it needs to know which tariff to apply for a given bill period.

The tariff engine models a bill period as a historized point on an energy meter. The timestamp of each record indicates when a bill period begins. The value of the record is the id of the tariff to use for that bill period. A bill period implicitly ends when the next one begins.

To setup a meter's bill period history do the following:

Create a standard history point with type Str
Add the tariffHis marker tag to the point
Add an equipRef tag that points to the meter

For example, if you have an elec meter called @ElecMeterMain, you would create a point with at least these tags:

his
point
hisSize: 0
kind: "Str"
tz: "New_York"
tariffHis
siteRef: @Campus
equipRef: @ElecMeterMain

If this meter is billed on the first of each month, then its bill period history might look like this.

ts                 v0
----------------   ----------------------
2015-01-01T00:00   Tariff-SmallCommercial
2015-02-01T00:00   Tariff-SmallCommercial
2015-03-01T00:00   Tariff-MediumCommmercialTOU
2015-04-01T00:00   Tariff-MediumCommmercialTOU
...

If you have multiple meters that share the same tariff history, you don't have to create a tariffHis point for each of them. Instead, create the tariffHis point once as indicated above, then on subsequent meters you can use the tariffHisRef tag to reference that point.

Historical Fees

It is common for the fee within a charge to change on a regular basis (e.g. daily or monthly). Anywhere a fee tag is used, instead of using a Number you can give a Ref to a history point that tracks the fee for that charge.

Utility Functions

The tariffCreate() function can be used to create a tariff.
The tariffConsumptionCharge() function can be used to create a consumption charge.
The tariffDemandCharge() function can be used to create a demand charge.
The tariffFixedCharge() function can be used to create a fixed charge.
The tariffPercentageCharge() function can be used to create a fixed charge.
The tariffCreateBillHis() function can be used to create an initial bill history.


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

lib-tariff 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

funcs ​

views ​

lib tariff ​

Overview ​

Tariffs ​

Charges ​

Usage-Based Charges ​

Ranges ​

Range Strategy ​

Consumption Charges ​

Demand Charges ​

Fixed Charges ​

Percentage Charges ​

Axon Charges ​

Configuring Bill Periods ​

Historical Fees ​

Utility Functions ​

func:tariffBillPeriod ​

tariffBillPeriod(meter, date) ​

func:tariffConsumptionCharge ​

tariffConsumptionCharge(tariff, dis, meterType, strategy, ranges, optTags: {}) ​

func:tariffCost ​

tariffCost(meter, dates, opts: {}) ​

func:tariffCostToHis ​

tariffCostToHis(rec, dates, opts, yield) ​

src ​

func:tariffCreate ​

tariffCreate(dis, currency) ​

func:tariffCreateBillHis ​

tariffCreateBillHis(rec: null, his: null, opts: {}) ​

func:tariffDemandCharge ​

tariffDemandCharge(tariff, dis, meterType, strategy, ranges, optTags: {}) ​

func:tariffFixedCharge ​

tariffFixedCharge(tariff, dis, fee, freq: "bill") ​

func:tariffPercentageCharge ​

tariffPercentageCharge(tariff, dis, percentage, charges) ​

tariff ​

tariffAxonCharge ​

tariffCharge ​

tariffChargeFunc ​

tariffChargeRef ​

tariffChargeRefs ​

tariffConsumptionCharge ​

tariffContractMin ​

tariffDemandCharge ​

tariffFee ​

tariffFeeFreq ​

tariffFeeHisRef ​

tariffFixedCharge ​

tariffHis ​

tariffHisRef ​

`lib-tariff` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

funcs

views

lib tariff

Overview

Tariffs

Charges

Usage-Based Charges

Ranges

Range Strategy

Consumption Charges

Demand Charges

Fixed Charges

Percentage Charges

Axon Charges

Configuring Bill Periods

Historical Fees

Utility Functions

func:tariffBillPeriod

tariffBillPeriod(meter, date)

func:tariffConsumptionCharge

tariffConsumptionCharge(tariff, dis, meterType, strategy, ranges, optTags: {})

func:tariffCost

tariffCost(meter, dates, opts: {})

func:tariffCostToHis

tariffCostToHis(rec, dates, opts, yield)

src

func:tariffCreate

tariffCreate(dis, currency)

func:tariffCreateBillHis

tariffCreateBillHis(rec: null, his: null, opts: {})

func:tariffDemandCharge

tariffDemandCharge(tariff, dis, meterType, strategy, ranges, optTags: {})

func:tariffFixedCharge

tariffFixedCharge(tariff, dis, fee, freq: "bill")

func:tariffPercentageCharge

tariffPercentageCharge(tariff, dis, percentage, charges)

tariff

tariffAxonCharge

tariffCharge

tariffChargeFunc

tariffChargeRef

tariffChargeRefs

tariffConsumptionCharge

tariffContractMin

tariffDemandCharge

tariffFee

tariffFeeFreq

tariffFeeHisRef

tariffFixedCharge

tariffHis

tariffHisRef