lib-energy 库参考

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

导读： 本页为 lib-energy 的 API / 标签 / 函数参考文档。

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

---

目录（导读）

• lib
• meta
• docs
• tags
• apps
• funcs
• views
• def
• supertypes
• Model
• Meter Points
• Baseline Functions
• Normalization Functions
• elecKwToKwhHis(rec, dates, opts, yield)
  • src
• energyBaselinePrevMonth(points, dates)
• energyBaselinePrevYear(points, dates)
• energyNormByArea(hisData)
• energyNormByDegreeDay(hisData)

---

概述（中译）

能源分析

---

API 正文（英文）

docs

Model • Meter Points • Baseline Functions • Normalization Functions

---

tags

energyBaselineFunc	Marker tag on a function which can be used to generate a baseline curve
energyNormFunc	Marker tag on a function which can be used to normalize energy data
meterPoints	This point, configured on the uiMeta record, defines the meter points that will be available in the energy app

---

apps

energy	Views used to visualize and analyze energy data

---

funcs

elecKwToKwhHis	Function to create a computed history for energy kWh electrical consumption from demand "kW" electrical demand
energyBaselinePrevMonth	Generate a baseline his grid based on last month's data
energyBaselinePrevYear	Generate a baseline his grid based on last year's data
energyNormByArea	Given a his grid, normalize the values by area in m² or ft²
energyNormByDegreeDay	Given a his grid, normalize the values by heating or cooling degree-day

---

views

energyOperation	Analyze energy usage at the site level against equipment runtime
energyProfile	Analyze energy usage profiles at the site level
energySwivel	Analyze energy usage at the portfolio level using graphical pivot tables
energyUsage	Analyze energy usage at the portfolio level across sites

---

---

def

app:energy

Views used to visualize and analyze energy data

---

meta

def	app:energy
disKey	ui::energy
icon	bolt
is	app
lib	lib:energy

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
app	UI application grouping of views

---

lib energy

Model

See Project Haystack for modeling details.

Meter Points

The haystack model defines several types of meter (e.g elec, water, gas, etc.). Each of these meters could have many different types of points under it. In practice, most projects have a small subset of the available meters and points. The energy app allows you to specify exactly which points should be available for energy analysis. This is done by configuring the meterPoints tag on the uiMeta record.

By default, if this tag is not configured, only electric consumption and electric demand points will be available in the energy app. The meterPoints tag is stored as a Dict[]. The easiest way to configure this tag is go to the UI view in the Settings app for your project. The Config Target action allows you to configure several different targets. You will want to configure the meter target tag. This dialog allows you to edit the meterPoints tag as Trio. Here is an example that configures two meter points: 1) elec demand, and 2) water volume.

dis:"Elec Demand"
filter:"demand and sensor and equipRef->elec"
quantity:power
---
dis:"Water Volume"
filter:"volume and sensor and equipRef->water"
quantity:volume

The most important tag for each meter point definition is the filter tag. When you are working in the energy app and select a particular meter point to analyze, points that match this filter will be selected.

The quantity tag is optional, but useful for specifying what units the point can be converted to. The full list of quantities is available in the unit database.

The meterPoints in the demo database has example points for elec, water, and gas points.

Baseline Functions

Often when analyzing energy usage, it is useful to compare against a baseline. A baseline may mean many different things such as past energy usage for the site or desired/target energy usage. In SkySpark, the term baseline is generically used to indicate any history curve used for comparisons.

SkySpark includes a couple of baselines out-of-the-box:

• energyBaselinePrevMonth(): compare against previous month (28 days ago)
• energyBaselinePrevYear(): compare against previous year (364 days ago)

You can plug-in your own custom baseline functions:

• Function must have energyBaselineFunc marker tag
• Function must have dis tag
• Function should take two parameters: (points, dates)

The baseline function is given the points to compare against and the desired date range. For example, the point list might be one or more demand points. The baseline function must return a his grid shaped as hisRead() would return for the given date range.

For robustness your baseline function should accept both points and dates in any of the formats supported by hisRead(). The following technique may be used:

(points, dates) => do
  points = toRecList(point)    // ensure points is Dict[]
  dates  = toDateSpan(dates)   // ensures startDate..endDate
  // return his grid
end

The baseline can return past data too, although the time-shift of timestamps between the requested data and returned data must be an exact number of days. If your baseline returns past (or future) data, then a time-shift is automatically applied to the ts columns and the hisStart / hisEnd grid meta to align it against the required date range. Normalizations such as degree-day are applied before the time-shift so that the baseline is correctly normalized. Example to get previous four weeks of data:

// energyBaselinePrevMonth
(points, dates) => do
  hisRead(points, toDateSpan(dates) - 28day)
end

Normalization Functions

Effective analysis of energy often requires normalization. SkySpark includes a couple standard functions for normalization:

• energyNormByArea(): normalize by site's area in m² or ft²
• energyNormByDegreeDay(): normalize by site's degree-day weather conditions

You can plug-in your own custom normalization functions:

• Function must have energyNormFunc marker tag
• Function must have dis tag
• Function should take one parameter which is a history grid of the meters, potentially rolled up by hisRollupAuto()

---

---

def

energyBaselineFunc

Marker tag on a function which can be used to generate a baseline curve. See energy

---

meta

def	energyBaselineFunc
is	marker
lib	lib:energy

---

supertypes

marker	Marker labels a dict with typing information

---

---

def

energyNormFunc

Marker tag on a function which can be used to normalize energy data. See energy

---

meta

def	energyNormFunc
is	marker
lib	lib:energy

---

supertypes

marker	Marker labels a dict with typing information

---

---

def

func:elecKwToKwhHis

elecKwToKwhHis(rec, dates, opts, yield)

Function to create a computed history for energy kWh electrical consumption from demand "kW" electrical demand. This function creates an average hourly rollup from the kW data, but in order to work correctly the kW samples must be uniformly sampled across the hour (such as every 15min), and the point should have hisMode set to consumption.

---

meta

def	func:elecKwToKwhHis
hisFuncReady	✓
is	func
lib	lib:energy
name	elecKwToKwhHis
overridable	✓

---

supertypes

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

---

src

(rec, dates, opts, yield) => do
  read((kw or demand) and equipRef == rec->equipRef)
    .hisRead(dates, opts)
    .hisRollup(avg, 1hr)
    .each( row => do
        v0: row["v0"]
        val: if (v0 == na()) na() else v0.as(1kWh)
        yield(row->ts, val)
      end)
end

---

---

def

func:energyBaselinePrevMonth

energyBaselinePrevMonth(points, dates)

Generate a baseline his grid based on last month's data. Data from exactly 28days ago is used to ensure alignment by weekday.

---

meta

def	func:energyBaselinePrevMonth
disKey	ui::baselinePrevMonth
energyBaselineFunc	✓
is	func
lib	lib:energy
name	energyBaselinePrevMonth

---

supertypes

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

---

src

(points, dates) => do
  hisRead(points, toDateSpan(dates) - 28day, {limit:null})
end

---

---

def

func:energyBaselinePrevYear

energyBaselinePrevYear(points, dates)

Generate a baseline his grid based on last year's data. Data from exactly 364days ago is used to ensure alignment by weekday.

---

meta

def	func:energyBaselinePrevYear
disKey	ui::baselinePrevYear
energyBaselineFunc	✓
is	func
lib	lib:energy
name	energyBaselinePrevYear

---

supertypes

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

---

src

(points, dates) => do
  hisRead(points, toDateSpan(dates) - 364day, {limit:null})
end

---

---

def

func:energyNormByArea

energyNormByArea(hisData)

Given a his grid, normalize the values by area in m² or ft². Each value column must have a siteRef which references a site with the area tag.

---

meta

def	func:energyNormByArea
disKey	ui::normByArea
energyNormFunc	✓
is	func
lib	lib:energy
name	energyNormByArea

---

supertypes

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

---

src

(hisData) => do
  hisMap(hisData) (val, ts, his) => val / his->siteRef->area
end

---

---

def

func:energyNormByDegreeDay

energyNormByDegreeDay(hisData)

Given a his grid, normalize the values by heating or cooling degree-day. Each value column must have a siteRef which references a site with the weatherStationRef tag.

---

meta

def	func:energyNormByDegreeDay
disKey	ui::normByDegreeDay
energyNormFunc	✓
is	func
lib	lib:energy
name	energyNormByDegreeDay

---

supertypes

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

---

---

def

meterPoints

This point, configured on the uiMeta record, defines the meter points that will be available in the energy app. See Meter Points

---

meta

def	meterPoints
is	list
lib	lib:energy
of	dict

---

supertypes

val	Data value type
list	Ordered list of zero or more values

---

---

def

view:energyOperation

Analyze energy usage at the site level against equipment runtime

---

meta

appName	energy
def	view:energyOperation
disKey	ui::operation
icon	view
is	view
lib	lib:energy
order	51

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:   {inherit:"chart"}
meters: {input var kind:"Ref<meter>" navCluster share}
span:   {input var kind:"Span" defVal:Span("today") share}
opts:Trio:
  var
  kind:"Dict"
  disKey:"ui::options"
  input
  uiInput:"energyExt::OperationOptsInput"
  templateName:"energyOperationOpts"
  defVal:Trio:
    mode:"lineChart"
    unit:""
    norms:[]
    loads:"on"
    showWeather:false
menu:   {action:"uiContextMenu" selInput:"meters"}
data:   {expr:"energyOperation({{meters}}, {{span}}, {{opts}})"}

---

---

def

view:energyProfile

Analyze energy usage profiles at the site level

---

meta

appName	energy
def	view:energyProfile
disKey	ui::profile
icon	view
is	view
lib	lib:energy
order	52

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:   {inherit:"chart"}
meters: {input var kind:"Ref<meter>" navCluster share}
span:   {input var kind:"Span" defVal:Span("today") share}
opts:Trio:
  var
  kind:"Dict"
  disKey:"ui::options"
  input
  uiInput: "energyExt::ProfileOptsInput"
  templateName:"energyProfileOpts"
  defVal:Trio:
    mode:"dailyAverage"
    norms:[]
    baseline:"none"
    includeSubmeters:true
    days:"all"
    unit:""
menu:   {action:"uiContextMenu" selInput:"meters"}
data:   {expr:"energyProfile({{meters}}, {{span}}, {{opts}})"}

---

---

def

view:energySwivel

Analyze energy usage at the portfolio level using graphical pivot tables. The energy swivel view will always do a daily rollup using hisRollupAuto(). This rollup is applied prior to any cell options you have configured.

---

meta

appName	energy
def	view:energySwivel
disKey	ui::swivel
icon	view
is	view
lib	lib:energy
order	53

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

uiViewBar: {var navPath:"sites"}
view:      {uiType:"uiMisc::SwivelView"}
sites:     {input var disKey:"ui::sites" kind:"Ref<site>[]" navCluster navSelAny share}
span:      {input var kind:"Span" defVal:Span("today") share}
opts:      {var input uiInput:"energyExt::EnergySwivelInput" kind:"Dict" defVal:{}}
data:      {expr:"energySwivel({{sites}}, {{span}}, {{opts}})"}

---

---

def

view:energyUsage

Analyze energy usage at the portfolio level across sites

---

meta

appName	energy
def	view:energyUsage
disKey	ui::usage
icon	view
is	view
lib	lib:energy
order	50

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:   {inherit:"chart"}
sites:  {input var disKey:"ui::sites" kind:"Ref<site>[]" navCluster navSelAny share}
span:   {input var kind:"Span" defVal:Span("today") share}
opts:Trio:
  var
  kind:"Dict"
  disKey:"ui::options"
  input
  uiInput:"energyExt::UsageOptsInput"
  templateName:"energyUsageOpts"
  defVal:Trio:
    mode:"lineChart"
    unit:""
    rollup:{fold:"auto" interval:"auto"}
    norms:[]
    baseline:"none"
    days:"all"
menu:   {action:"uiContextMenu" selInput:"sites"}
data:   {expr:"energyUsage({{sites}}, {{span}}, {{opts}})"}