Expected Energy Calculation Setup

How to use SolarNetwork expected energy calculations for more fine-tuned results

Preview feature. Two setup paths: the quick setup using the Ecosuite package, or the manual setup for custom algorithms. The manual path assumes familiarity with SolarNode expressions.

Overview

By default, Ecosuite computes expected energy from each SolarNetwork datum using the configured solar array. This setup lets you compute expectedWattHours inside SolarNetwork instead, giving you full control over the algorithm and the ability to layer in things like GHI→POA transposition later.

At a glance:

1. Get an expectedWattHours field onto your GEN source datums, either via the Ecosuite package (recommended) or by configuring datum filters manually.

2. Tick Calculate Expected in SolarNetwork on the corresponding Ecosuite system.

Quick setup (recommended)

If you just want expected energy working, install the Ecosuite ecosuite-solarnode-config-expected-energy package on the node - it provisions the datum filter chain, the irradiancePOA filter, and the expectedWattHours filter for you. After install, you configure everything through an Expected Energy System Configuration menu rather than writing SpEL by hand.

1. Install the package on the SolarNode.

2. Open the Expected Energy System Configuration menu and fill in your system characteristics (panel area, efficiency, performance ratio, tilt factor, degradation rate, commission date, nameplate AC max power, PYR source ID, GEN source ID, timezone).

3. Save. The package writes the underlying metadata and datum filters automatically.

4. Enable in Ecosuite - on the matching system, tick Calculate Expected in SolarNetwork on the GEN source.

Skip to Verifying to confirm it's working.

If you need a custom algorithm (e.g. a different formula, GHI→POA transposition via a microservice, or anything the menu doesn't expose), use the manual setup below instead, or use it on top of the package by editing the filters it created.

Verifying

Fetch the latest datum for the GEN source and confirm expectedWattHours is present:

{
  "sourceId": "/FOO/BAR/BAZ/GEN/1",
  "created": "2025-05-14 23:54:37.003Z",
  "expectedWattHours": 439,
  "wattHours": 1758767000,
  "...": "..."
}

If it's missing or wrong, check:

• The package's menu fields are all populated (quick setup), or service names match across the datum filter chain and its components (manual setup).

• Required metadata is set.

• SpEL syntax - see the SolarNode logs for evaluation errors, or refer to the SolarNetwork SpEL tests for inspiration.

---

Manual setup (advanced)

The package above does all of this for you. Follow this section only if you want a custom algorithm, are working on a node where the package isn't available, or want to understand what the package is doing under the hood.

Paths below use /FOO/BAR/BAZ/** as a placeholder - swap in your own.

1. Create a datum filter chain

If one doesn't already exist on the node, create a new datum filter chain. It will hold two components in order:

1. Irradiance POA

2. Expected Generation

Service names are arbitrary, but keep them consistent across the chain and the individual filters.

2. Populate irradiancePOA

Create an expression datum filter component attached to the PYR device. Set Property to irradiancePOA and Property Type to Instantaneous.

latest('/FOO/BAR/BAZ/PYR/1')?.irradiance != null
  ? latest('/FOO/BAR/BAZ/PYR/1')?.irradiance
  : null

This copies irradiance to irradiancePOA unchanged. The separate field is useful later if you want to swap in GHI→POA transposition — for example, calling a microservice:

has('irradiance') ? httpGet('http://example.solarnetwork:8000/ghi-to-poa', union(nodeMetadata('/pm/pv-characteristics-poa'), {
  date: local(timestamp.atZone(nodeMetadata('/pm/pv-characteristics-poa/zone'))),
  irradiance: irradiance
}), {'Authorization': httpBasic('foo', 'bar')})?.data?.poa_global : null

Downstream filters that need POA irradiance then read it directly from SolarNetwork. You can add this transposition later, start with the simple copy.

3. Add system metadata

Store configurable values (panel area, efficiency, performance ratio, tilt factor, degradation rate, commission date, timezone, nameplate AC max power) as SolarNetwork node metadata rather than hardcoding them.

If you already use the POAI Calculator metadata, reuse that pv-characteristics path. Otherwise pick your own, the pm namespace is arbitrary.

4. Populate expectedWattHours

This step is required: Ecosuite reads this field by name.

Create an expression datum filter component on the GEN source. Set Property to expectedWattHours and Property Type to Instantaneous.

The algorithm:

$$E = \min\left(\left\lfloor I_{POA} \cdot A_p \cdot \eta_p \cdot R_{perf} \cdot F_{tilt} \cdot \min\left((1-d)^y,\, 1\right) \right\rfloor,\ P_{max}\right)$$

Symbol	Meaning
$I_{POA}$	Irradiance on plane of array
$A_p$	Panel area
$\eta_p$	Panel efficiency
$R_{perf}$	Performance ratio (system losses)
$F_{tilt}$	Array tilt factor
$d$	Annual degradation rate
$y$	Years since commission date
$P_{max}$	Nameplate AC max power

If irradiancePOA or panelArea is missing, return null. Otherwise compute the product, floor it, and clip to nameplate.

If you skipped step 2, substitute irradiance for irradiancePOA in the snippets below.

With metadata (recommended)

latest('/FOO/BAR/BAZ/PYR/1')?.irradiancePOA != null
  && getInfoNumber('pv-characteristics', 'panelArea') != null
? min(roundDown(latest('/FOO/BAR/BAZ/PYR/1')?.irradiancePOA
    * getInfoNumber('pv-characteristics', 'panelArea')
    * getInfoNumber('pv-characteristics', 'panelEfficiency')
    * getInfoNumber('pv-characteristics', 'performanceRatio')
    * getInfoNumber('pv-characteristics', 'panelArrayTiltFactor')
    * min(pow(
        1 - getInfoNumber('pv-characteristics', 'degradationRate'),
        yearsBetween(
          date(getInfoString('pv-characteristics', 'pvArrayCommissionDate')),
          today(getInfoString('pv-characteristics', 'zone'))
        )
      ), 1)
  , 0), getInfoNumber('pv-characteristics', 'nameplateAcMaxPower'))
: null

Without metadata (hardcoded)

5. Enable in Ecosuite

On the matching system in Ecosuite, tick Calculate Expected in SolarNetwork on the GEN source. Ecosuite will now use the pre-calculated expectedWattHours from each datum instead of computing it.

Extending

Because the calculation lives in SolarNetwork, you can evolve it without Ecosuite knowing. For example, swap step 2 for a GHI→POA transposition microservice backed by pvlib, and every downstream calculation picks it up automatically.

Cloud Integrations setup

The setup above runs on a SolarNode. If a system's irradiance and generation data instead arrives through a Cloud Integration, the same expectedWattHours field is produced with expression Mapping Properties on the Cloud Datum Stream Mapping rather than expression datum filter components. The algorithm is identical; only where you configure it changes. The ecosuite-solarnode-config-expected-energy package does not apply here - this is the manual path for cloud-sourced systems.

Paths below use PYR/1 and GEN/1 as placeholders - swap in your own source IDs.

1. Confirm both streams share a mapping

Expression Mapping Properties are evaluated against all resolved datum for a request, so the expectedWattHours expression on the GEN stream can read the PYR stream's values. For this to work within a single request, both streams must be produced by the same Cloud Datum Stream Mapping.

2. Populate irradiancePOA

Add an expression Mapping Property with Property Type Instantaneous (i) and Property Name irradiancePOA, restricted to the PYR stream:

sourceId == 'PYR/1' ? irradiance : null

As in the manual setup, this copies irradiance unchanged, and you can later swap in a GHI→POA transposition microservice:

sourceId == 'PYR/1' && has('irradiance')
  ? httpGet('https://example.com/ghi-to-poa',
      union(nodeMetadata('/pm/pv-characteristics'), {
        date: local(timestamp.atZone(nodeMetadata('/pm/pv-characteristics/zone'))),
        irradiance: irradiance
      }), {'Authorization': httpBasic('foo', 'bar')})?.data?.poa_global
  : null

Define this expression before the expectedWattHours expression - Mapping Property expressions evaluate in the order configured.

3. Add node metadata

Store the system characteristics as SolarNetwork node metadata on the node ID configured on the Cloud Datum Stream, exactly as in step 3 of the manual setup.

4. Populate expectedWattHours

Add an expression Mapping Property with Property Type Instantaneous (i) and Property Name expectedWattHours, restricted to the GEN stream. Same algorithm, reading the PYR stream's irradiancePOA via latest() and the characteristics via nodeMetadata():

sourceId == 'GEN/1'
  && latest('PYR/1', timestamp)?.irradiancePOA != null
  && nodeMetadata('/pm/pv-characteristics/panelArea') != null
? min(roundDown(latest('PYR/1', timestamp).irradiancePOA
    * nodeMetadata('/pm/pv-characteristics/panelArea')
    * nodeMetadata('/pm/pv-characteristics/panelEfficiency')
    * nodeMetadata('/pm/pv-characteristics/performanceRatio')
    * nodeMetadata('/pm/pv-characteristics/panelArrayTiltFactor')
    * min(pow(
        1 - nodeMetadata('/pm/pv-characteristics/degradationRate'),
        yearsBetween(
          date(nodeMetadata('/pm/pv-characteristics/pvArrayCommissionDate')),
          today(nodeMetadata('/pm/pv-characteristics/zone'))
        )
      ), 1)
  , 0), nodeMetadata('/pm/pv-characteristics/nameplateAcMaxPower'))
: null

nodeMetadata('/pm/pv-characteristics/panelArea') is the Cloud expression equivalent of the SolarNode getInfoNumber('pv-characteristics', 'panelArea').

5. Enable in Ecosuite

Tick Calculate Expected in SolarNetwork on the GEN source as before. Ecosuite uses the pre-calculated expectedWattHours regardless of whether it came from a node datum filter or a Cloud Datum Stream Mapping expression.

Caveats

• Expression order matters. irradiancePOA must be configured before expectedWattHours. If a derived property on one stream isn't visible to a later expression, persist irradiancePOA so latest() reads it back from stored data on subsequent requests, or inline the copy into the expectedWattHours expression.

• Time alignment. Cloud Datum Streams poll on a schedule. Passing timestamp as the date argument selects the PYR datum nearest in time to the GEN datum being evaluated.