Welcome

Welcome to Proximal Energy's documentation website. This website is intended to provide a comprehensive guide to the various aspects of Proximal Energy's software. The website is divided into several sections, each of which is designed to provide a detailed explanation of a specific aspect of each of the main functionalities of the platform.

Hints

• The entire documentation set can be exported as PDF by clicking on the printer icon in the top right hand corner of the page.
• You can press the left and right arrow keys on your keyboard to navigate to the previous and next page respectively.

Commissioning Overview

This document describes all of the things necessary to commission a project in Proximal. It can be used as a checklist for each project you would like to bring online.

System and SCADA Definition

Required Documents

Your contact at Proximal will provide you a Google Sheet to fill out for your specific project. This google sheet mirrors a combiner shedule diagram in your IFC or as-built construction documents and will be used by our team to set up your project in our database.

Performance Modeling

Required Documents

• PAN file: Used for module modeling
• OND file: Used for inverter modeling
• Transformer Spec Sheet

Events

Description

Events are a term used to describe any type of addressable underperformance of a project or its components. If a device is underperforming, the time frame is identified and energy production and financial impact is calculated. Failure Mode and Root Cause analysis are used to identify causes and remedies to each Event.

Event Types

1. Project Offline
2. Device Offline
3. Device Underperforming*
4. Tracker Underperforming
5. Curtailment*
6. Soiling*

*These Event types are currently under development.

Event Detection

Event detection is an automated process that identifies events heuristically. This process runs for each project every 15 minutes, and analyses the previous 1 hour of data. Every 6 hours, the day so far is re-processed to ensure completeness with backfilled data. Every 24 hours, the previous 3 days are re-processed for the same reason.

Energy Production and Financial Impact

Once an Event is detected, the energy production and financial impact can be calculated by comparing the expected energy production against the actual energy production. Multiplying energy production impact by a project's PPA price gives the financial impact of the event. This occurs on every Event detection run.

Parent-Child Relationships

To minimize the number of events detected, a device-wise hierarchy is used to group devices and identify dependent Events. For example if an inverter is offline, an Event will be opened for that inverter, but not for any of its constituent combiner boxes or trackers. This methodology ensures that any Events displayed are the highest addressable level, and prevents sending field technicians to fix a device that is not the root cause of the problem. If an Event is detected on a child device before its parent device, the child Event remains open until the parent Event is closed. It is assumed in this case that the Events are distinct from each other, and that the parent device is not root cause of the child Event.

Event Detection Filters

Event detection is valid only if a device could be reasonably expected to operate. To this end, Events are only detected if the average irradiance onsite is above 100 W/m^2^. This value is intended to minimize the number of Events associated with low-irradiance conditions such as late start Events. If the filters are not met during Event detection, each device is considered to be in the same state as previously known. If a device is repaired overnight, the Event will not be closed until the next day when the irradiance conditions are again valid.

Failure Mode and Root Cause Analysis

The term "Failure Mode" is used to describe the first cause of an Event and is detectable from data analysis alone, while the term "Root Cause" is used to describe the underlying issue and is often not detectable from data. For example, if an inverter begins to derate on a hot summer day, the failure mode may be temperature derating identified from the inverter's internal temperature sensor. The root cause may be a broken or dusty cooling fan, which is not detectable from data.

Tracker Events

Tracker Events are detected by comparing the actual tracking pattern against an ideal tracking pattern. The ideal pattern takes both true-tracking and backtracking behaviors into account. Typically, tracker rows are assigned Events if the issue is localized to a single tracker row. If all tracker rows in a tracker zone are not tracking at the same time, the Event is elevated to a tracker zone Event. Tracker stow information is displayed in an Event's failure mode.

KPI Overview

KPIs (Key Performance Indicators) are a set of metrics that are used to measure the performance of a system. Calculated on a daily basis, KPIs can be used to characterize a system either at a point in time or to trend data over a longer period.

KPIs are separated into two categories: Benchmark & Contractual.

Benchmark KPIs are used to characterize a system's performance relative to itself and other projects in a user's portfolio. These KPIs are consistent across all projects. Proximal intends to provide industry-supplied values to compare an individual project or portfolio to.

Contractual KPIs are used to track the specific behavior of a system or component as defined by a contract between two parties. These KPIs are project-specific, and are created by the Proximal team individually for each project. As such, documentation for these KPIs cannot be found in these pages, but will be more thoroughly documented in the KPI page on the Proximal platform. These KPIs are not available for benchmarking against other projects, nor industry standards. They have an associated contract available to view, and typically have an incurred liquidated damages calculation as well as the liable party.

PV

Combiner Field Health KPI

Description

The Combiner Field Health KPI measures the DC health of a project based on combiner current data. Each combiner receives a daily health score ranging from 0 to 1, where a score of 1 indicates the healthiest combiners on the project.

Methodology

1. Retrieve DC combiner current data for each combiner box on a 5-minute interval. The data is filtered to focus on the time window from 11:30 AM to 12:30 PM to capture peak irradiance conditions.
2. Normalize each combiner's current against its own DC capacity to account for differences in combiner size.
3. Identify the "ideal" combiner by calculating the 99th percentile of all normalized combiner currents. The 99% threshold is chosen to exclude outliers and focus on typical combiner performance.
4. Normalize all combiners' ratios against the ideal combiner. This gives the ideal combiner a score of 1.0, with all other combiners having a score ranging from 0 to 1. Outliers may exceed a score of 1.0.
5. Calculate the daily mean score of each combiner trace to calculate the overall DC Field Health for each combiner on that day.
6. Calculate the mean of all combiner scores to derive the overall DC Field Health for the project on that day.

Trackers

Description

Tracker KPIs are used to monitor performance of single-axis trackers. Multiple KPIs are calculated for each project.

1. Row position deviation from setpoint.
2. Row setpoint deviation from the project median setpoint.
3. Row availability (when the prior two metrics are both less than 5°).

These KPIs can help identify offline trackers, errant zone controller setpoints, and communication issues.

Filters

To exclude time periods when trackers are not in use, any time intervals in which the sun elevation angle is less than or equal to 0° are excluded from the calculations.

Position Deviation from Setpoint

1. Query 5-minute position and setpoint data for each row.
2. Compare position to setpoint for each 5-minute interval for each row. Average the absolute value of the difference between these values for the entire day.
3. Aggregate each tracker row into blocks, averaging the values again.

Setpoint Deviation from Median

1. Query 5-minute setpoint data for each row.
2. Calculate the median setpoint for the project.
3. Compare setpoint to project median for each 5-minute interval for each row. Average the absolute value of the difference between these values for the entire day.
4. Aggregate each tracker row into blocks, averaging the values again.

Availability

1. Query 5-minute position and setpoint data for each row.
2. Compare position to setpoint for each 5-minute interval for each row.
3. If both the position and setpoint deviations are less than 5° for a given interval, the row is considered available.
4. Aggregate each tracker row into blocks, averaging the values again.

Specific Yield KPI

Description

The Specific Yield KPI quantifies how much AC energy is delivered per unit of installed DC capacity. It provides a normalized metric for evaluating site performance independent of plant size and is especially useful for comparing across projects.

This KPI is calculated daily and expressed in units of kWh/kWp.

Methodology

1. Retrieve time-series data for:

   • meter_active_power: AC power delivered by the site over the day.

2. Clean and aggregate the data:

   • Clip negative values to zero to eliminate erroneous readings.
   • Resample data to hourly averages to standardize granularity.

3. Calculate total energy delivered:

   • Integrate the hourly AC power measurements to get total daily energy output in kWh.

4. Normalize by DC capacity:

   • Divide the total energy output by the site’s installed DC capacity (also referred to as kW-peak, or kWp) to get the specific yield.

5. Compute Specific Yield:

   • The formula is:

     $$\text{Specific Yield}=\frac{\sum \text{AC Energy Output (kWh)}}{{\text{Capacity}}_{DC}\text{ (kWp)}}$$

6. Store the KPI result:

   • The resulting value is stored as a project-level KPI for the corresponding date.

Performance Ratio KPI

Description

The Performance Ratio KPI quantifies the overall efficiency of a PV site by comparing the actual energy produced to the theoretical maximum possible under prevailing irradiance. This KPI helps identify underperformance due to issues such as soiling, inverter clipping, or balance of system losses.

The KPI is calculated daily and results in a dimensionless number typically between 0 and 1, where 1 represents a perfectly efficient system.

Methodology

1. Retrieve time-series data at hourly resolution for:

   • meter_active_power: Total AC power delivered by the site.
   • met_station_poa: Plane-of-array irradiance from on-site weather stations.

2. Clean the data by:

   • Removing any columns (sensor streams) where the maximum value is less than or equal to 0.
   • Clipping all negative values to zero to remove erroneous negative readings.
   • Averaging the values to a uniform hourly granularity.

3. Calculate Specific Yield:

   • Total AC energy delivered by the site (sum of meter_active_power across all meters) divided by the total DC capacity of the project.
   • Units: kWh/kWp
   • See also: Specific Yield

4. Calculate Reference Yield:

   • Total POA irradiance summed across all sensors, averaged, and then normalized by a reference peak irradiance value of 1000 Wp/m² (Watt-peak per square meter). $$\text{Reference Yield (kWh / kWp)}=\frac{\sum \text{POA Irradiance (Wh/m²)}}{\text{Reference Irradiance (Wp/m²)}}$$

5. Compute Performance Ratio: $$\text{Performance Ratio}=\frac{\text{Specific Yield (kWh / kWp)}}{\text{Reference Yield (kWh / kWp)}}$$

   • This results in a dimensionless efficiency metric.

6. Store the KPI result:

   • The daily PR value is inserted as a project-level KPI for the given date.

BESS

State of Charge

Description

State of Charge (SOC) KPIs monitor BESS performance and health. Two key metrics help identify utilization patterns and operational efficiency:

1. Average SOC - The mean state of charge over a time period
2. Resting SOC - The state of charge when the battery is idle

Average SOC

Why It Matters

• Battery Health: Extreme SOC levels (very high or very low) accelerate battery degradation
• Longevity: Operating within optimal SOC ranges extends battery lifespan
• Performance: Consistent extreme SOC can reduce capacity and power capability over time

How It's Calculated

1. Collect SOC data at regular intervals
2. Calculate the arithmetic mean for the time period

Resting SOC

Why It Matters

• Battery Stress: Prolonged storage at extreme SOC levels causes chemical stress
• Aging: High resting SOC increases calendar aging, low resting SOC can cause capacity fade
• Safety: Extreme resting SOC levels may indicate potential safety concerns

How It's Calculated

1. Collect SOC and power flow data
2. Identify periods with minimal power flow
3. Calculate mean SOC during these resting periods

Depth of Discharge KPI

Description

The Depth of Discharge (DoD) KPI quantifies the average depth to which a battery storage system is discharged during a given day. It is calculated as the inverse of the average State of Charge (SOC). A higher DoD indicates that the battery is being used more deeply, while a lower DoD suggests more conservative usage.

This KPI is useful for assessing operational behavior and wear-and-tear on battery storage systems. It is reported daily as a percentage between 0 and 1, where 1 means fully discharged on average, and 0 means fully charged on average.

Methodology

1. Retrieve time-series data for:

   • project_soc_percent: The State of Charge (%) of the project’s battery storage system.

2. Convert timestamp index:

   • The index is converted to the project’s local timezone for consistent daily aggregation.

3. Calculate average SOC:

   • Take the mean of all State of Charge (SOC) readings for the day. SOC values are expected to be in the range [0, 1].

4. Calculate Depth of Discharge:

   • DoD is the complement of SOC:

     $$\text{DoD}=1-\text{SOC}$$

   • The result is rounded to four decimal places.

5. Store the KPI result:

   • The daily average DoD is inserted as a project-level KPI for the corresponding date.

Project Cycle Count KPI

Description

The Project Cycle Count KPI estimates the number of full charge-discharge cycles a battery storage system performs in a single day. This KPI is essential for understanding battery utilization and degradation over time.

The KPI is calculated daily and reported as a floating-point number, where 1.0 represents one full cycle (100% discharge followed by 100% recharge, or equivalent cumulative partial cycles).

Methodology

1. Retrieve time-series data for:

   • project_soc_percent: The State of Charge (%) of the project’s battery system over the day.

2. Convert timestamp index:

   • The index is standardized to ensure consistent time stepping.

3. Calculate absolute changes in SOC:

   • Take the absolute difference in SOC between each pair of consecutive time steps.

     $$\Delta {\text{SOC}}_i=\left|{\text{SOC}}_i-{\text{SOC}}_{i-1}\right|$$

4. Sum the absolute changes and normalize by 2:

   • The total cycle count is estimated by summing all absolute SOC changes and dividing by 2. This accounts for the fact that a full cycle consists of both discharge and charge.

     $$\text{Cycle Count}=\frac{1}{2}\sum _i\left|{\text{SOC}}_i-{\text{SOC}}_{i-1}\right|$$

5. Round and store the KPI result:

   • The daily cycle count is rounded to four decimal places and stored as a project-level KPI for the given date.

Reports Overview

Reports are automated, or semi-automated, studies performed by the Proximal platform which can keep you informed about the health of various aspects of the power plant. These reports generally have intelligent data filters which can be modified by a human in the loop.

The outputs of these reports are generated so that they can be shared with internal and external stakeholders who may or may not have access to the Proximal platform. The XLSX and CSV download features allow users to take the data generated by a report and do further manual analysis.

DC Amperage Report

Overview

This report shows the normalized current at every combiner at the PV power plant filtered for clearsky conditions. Combiner current is normalized based off of the nameplate capacity of each combiner. This makes it so that combiners with different amounts of dc capacity can be compared against one another on an apples-to-apples basis.

Different combiners may have different DC capacity due to differences in the number of strings attached to each combiner, module bin class, etc.

Filters

The analysis is generated with user input for clearsky data on a given day. Users may select thresholds for minimum POA, maximum POA derviative, and maximum POA derivative standard deviation. The input data is sampled at 5-minute intervals by default, which can be changed via the settings dropdown located in the filters card. The maximum POA derivative and maximum POA derivative standard deviation thresholds may be turned off at the risk of reduced report accuracy.

POA derivative is the rate of change of POA with respect to time. A lower POA derivative indicates a more stable POA, correlating to fewer moving clouds over the array. Proximal recommends a maximum POA derivative of 1 W/m^2^/minute.

POA derivative standard deviation is the standard deviation of the POA derivative over each 5-minute interval. A lower POA derivative standard deviation indicates that all sensors are moving in a similar way at the same time, indicating that the entire site is experiencing similar sky conditions. Proximal recommends a maximum POA derivative standard deviation of 1 W/m^2^/minute.

Both POA derivative and POA derivative standard deviation are calculated using the selected sample rate of the data, then aggregated to a 1-hour moving average.

Calculation

This report is calculated by pulling the 5-minute combiner current data, finding the nominal string current at the maximum voltage of the modules, then normalizing the actual current by the nominal string current. This normalization is then compared to the median combiner current for either the inverter associated with that combiner or the site as a whole. The intermediate calculations are available in the output XLSX file.

Outputs

By default, this report shows the normalzied DC performance of each combiner compared to its peers on the same inverter. Via the settings dropdown, this normalization can be changed to compare to the combiner performance of the entire site. Results are displayed as a normalized value, where 1.0 indicates that the combiner is operating at an equal level to the median combiner. Combiners colored in green are performing within 5% of the median combiner, while those colored in red are at least 5% below the median and those colored in pink are at least 5% above the median. This 5% threshold can be changed via the settings dropdown.

The combiner performance can be downloaded as an Excel file in the top-right corner of the page, while the raw POA and combiner current data can be downloaded as CSV files in the output settings dropdown.

Caveats

• There must be at least one clearsky timestamp during the day for this report to be generated.
• If the system definition is incorrect, (for example if the DC capacity reported to Proximal during commissioning was incorrect) then the report will be incorrect for those combiners which are defined incorrectly since the combiner DC capacity is used in the normalization calculation.

Module State of Health Report

Overview

This report is designed to characterize the performance of the modules using the combiners as a proxy. Through heavy filtering, the report aims to analyze only the combiners that are performing at the highest level, to achieve a picture representative of the best possible performance of the modules. The filters are designed to remove any effects that can be attributed to the underperformance of inverters, trackers, or other non-DC related effects.

After filtering, the performance of each combiner is characterized through the following formula:

$$\text{DC Performance}=1-\frac{E_{\text{modeled}}-E_{\text{actual}}}{E_{\text{modeled}}}$$

Where:

• $E_{\text{modeled}}$ is the expected energy production of the combiner, detailed in the PV Model Overview. $E_{\text{modeled}}$ is representative of the warranted degradation curve of the modules at the time of analysis.
• $E_{\text{actual}}$ is the actual energy production of the combiner, calculated as the combiner current × inverter DC voltage.

The resulting metric is representative of the performance of the modules, with 100% indicating that the modules are performing at the expected level.

Filters

Unlike the DC Amperage report, the module state of health report is not capable of user-defined filters. Instead, the report has a defined set of filters that are applied to the data, and the analysis is automatically generated on a daily basis. In addition to clearsky filters, several performance-based filters are applied to ensure that the analysis is only performed on combiners that can be considered representative of high performance.

Clearsky Filters

• Minimum POA: 250 W/m²
• Maximum POA Derivative: 2 W/m²/minute
• Standard Deviation filters
  • Maximum POA Standard Deviation: 7.5 W/m²
  • Maximum POA Derivative Standard Deviation: 0.25 W/m²/minute
  • To filter on standard deviation and derivative standard deviation, both conditions must be met to exclude data. All other conditions are applied individually.
• POA sensors on errant trackers are excluded analytically
• At least 1 hour of clearsky-filtered data

Performance-Based Filters

• Inverter AC output between 5% and 95% of the inverter's nameplate capacity
  • This ensures the inverter is online and not AC clipping
• Inverter module voltages are within 5V of each other (as applicable)
  • Since combiner power must be calculated as (combiner current) × (inverter DC voltage), the module voltages must be within a narrow band to ensure that the voltage is representative of the combiners.
• Combiner DC Field Health is at least 97.5% of the project nonzero mean per day.
  • If a combiner fails the fuse health filter, it is removed from the analysis.
• Tracker position deviating from setpoint is less than 1° on average per day.
• Tracker setpoint deviating from median is less than 1° on average per day
  • Both tracker filters are applied to entire blocks. If a block fails the analysis, all combiners on the block are excluded for that day.

Other

• Soiling is accounted for in the expected performance calculation through the onsite soiling sensors. Since this adjustment is applied to both expected and actual performance, it is assumed to cancel out in the performance calculation and is not considered in the analysis.

Manual Filtering

• On the Clearsky tab, users may select individual days to view. The individual days show combiner-level performance as well as the clearsky POA data shaded in green for timestamps selected for analysis.
• On all tabs, users may select a specific date range to view. It is recommended to select a date range that is at least one month long to ensure enough data is available for analysis.
• The report is presented for the previous year of data by default, but either of these filters are applied to data presentation on all tabs.

Outputs

Outputs are available for each combiner, as well as various summary statistics. Graphics are available on the project level, individual combiner level, and aggregates for inverter and circuit level roll-ups. Combiner-level graphics are colored based on the capacity and bin classification of modules associated with each combiner. On the GIS tab, the report is available on a combiner-level basis.

Caveats

• Due to the heavy filtering applied to the data, the report may not generate for some days.
• If the system definition is incorrect, (for example if the DC capacity reported to Proximal during commissioning was incorrect) then the report will contains inaccuracies for those combiners which are defined incorrectly since the combiner DC capacity is used in the normalization calculation.

Inverter Availability

Description

Inverter availability KPIs measure how often each inverter (and, when present, its internal power-conversion modules) is producing at least a minimum power output under valid irradiance conditions.

One daily report is produced containing:

1. Inverter Availability – percentage of daylight intervals in which each inverter’s AC power exceeds a user-defined threshold.
2. Module Availability – same calculation applied to individual inverter-module channels (only shown if the project reports module-level power).

This report helps identify offline or under-performing inverters, balance-of-plant outages, and data-quality issues.

Parameters (default values)

Filters

An individual 5-minute interval is excluded from availability calculations if:

1. Plane-of-array irradiance ≤ Irradiance Min.

All other samples form the valid daylight set for the day.

Method – Inverter Availability

1. Query 5-minute pv_pcs_ac_power and met_station_poa for every inverter in the project.
2. Validate irradiance – keep only timestamps where POA > Irradiance Min.
3. Evaluate power threshold – for each inverter, flag samples where
   [ P_{\text{inv}}(t) > \text{Available Min} ]
4. Compute availability per inverter
   [ A*{\text{inv}}=\frac{\text{count}\left(P*{\text{inv}}> \text{Available Min}\right)} {\text{count(valid daylight samples)}} ]
5. Export an Excel workbook containing:
   • Parameters – editable inputs & live output KPIs.
   • Inverter Availability – % available for each inverter.
   • Inverter Power – raw 5-minute power time-series.
   • Irradiance – POA irradiance (mean + individual sensors).

Availability formulas live in Excel, so users can adjust Available Min or Irradiance Min and see KPIs update instantly.

Module Availability (when reported)

If the project provides PV PCS Module AC Power:

1. Repeat Steps 1-4 using module-level power.
2. Add sheets – Module Availability and Module Power – mirroring the inverter sheets.

Tracker Availability

Description

Tracker availability KPIs quantify how often each tracker row is correctly following its expected angle.
Two daily reports are generated:

1. Row vs Row Setpoint – compares each row’s measured position to its own controller setpoint.
2. Row vs Zone Median Setpoint – compares each row’s position to the median setpoint of all rows in its zone.

A row is considered available when the absolute position error is within an acceptable tolerance. These KPIs surface drifted trackers, stow-logic faults, communication drop-outs, and other issues.

Parameters (default values)

Filters

Before availability is calculated, any 5-minute interval is discarded if any of the following are true:

1. Tracker position or setpoint is blank.
2. Plane-of-array irradiance ≤ Irradiance Min.
3. Exclude Stow Periods is TRUE and the tracker zone is reported as stowed.
4. |Position − Setpoint| ≥ 120°.
5. |Setpoint(t) − Setpoint(t-1)| > Maximum Setpoint Change. (Rule 5 is skipped for the first sample of the day.)

Method 1 – Row vs Row Setpoint

1. Query 5-minute tracker position, tracker setpoint, met station poa, and tracker zone status for every row in the project.
2. Apply filters listed above to build the valid-data mask.
3. Calculate position error
   [ \Delta\theta*{\text{row}}(t)=\left|\text{Position}*{\text{row}}(t)-\text{Setpoint}_{\text{row}}(t)\right| ]
4. Compute availability for each row
   [ A*{\text{row}}=\frac{\text{count}\left(\Delta\theta*{\text{row}}\le\text{Available Max}\right)} {\text{count(valid samples)}} ]
5. Export an Excel workbook containing:
   • Parameters – editable inputs & descriptions.
   • Availability – one value per row (percent).
   • Difference – per-sample (\Delta\theta_{\text{row}}) table.
   • Raw data sheets: Position, Setpoint, Stow, Irradiance.

Method 2 – Row vs Zone Median Setpoint

1. Derive zone setpoints by taking the median of all row setpoints within each zone at every 5-minute timestamp.
2. Repeat Steps 2-5 from Method 1, replacing Setpoint₍row₎(t) with Setpoint₍zone median₎(t) in the error formula.
3. The workbook layout is identical; the Setpoint sheet now shows zone medians (prefixed “Zone”).

Usage Notes

• All calculations occur in the exported Excel file via formulas, allowing users to adjust parameters post-hoc.

PV Model Overview

Why Proximal

The Proximal PV performance model has been specifically designed with operating assets in mind. The following are a few highlights of the model that distinguish it from other PV models used in asset management.

Built on Open Source

Modern, tested, transparent, trusted by the community. By building on top of pvlib, we can ensure that the proximal energy model is understandable by all users and easily extendable.

⑃

Nodal

Expected energy can be calculated at the combiner, inverter, array, or substation level.

🕑

Sub-Hourly

Operating assets emit high frequency data which is captured by the energy model.

🗺️

Geospatial

Each block of the system uses the meteorological data that is closest to it which can yield great improvements for large systems with passing clouds.

📄

Documented

Each step of the model is documented in detail through pvlib and through this documentation set.

♲

Efficient

Inputs to each individual model are automatically factored into unique combinations. This makes the model capable of handling large systems with high levels of detail at high frequency possible.

Model Chain

The proximal performance model at a high level is comprised of 6 major sub-models. Clicking on any of the models will take you to the actual model steps that occur in each sub-model.

flowchart TD

%% --- CLASSES ---
classDef source fill:#6B7A8F, color:#CCCCCC
classDef model fill:#202020, color:#CCCCCC
classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
classDef inputs fill:#1A1A1A, color:#CCCCCC
classDef outputs fill:#B39245, color:#CCCCCC

met_params[Meteorological Parameters]:::source
click met_params "./meteorological_parameters.html"

tracker_rotation_angles[Tracker Rotation Angles]:::source
click tracker_rotation_angles "./tracker_rotation_angles.html"

poai[Plane of Array Irradiance]:::source
click poai "./plane_of_array_irradiance.html"

epoai[
    Effective
    Plane of Array Irradiance
]:::source
click epoai "./effective_plane_of_array_irradiance.html"

DC[DC System Losses]:::source
click DC "dc_system_losses.html"

AC[AC System Losses]:::source
click AC "ac_system_losses.html"

met_params --> tracker_rotation_angles
tracker_rotation_angles --> poai
poai --> epoai
epoai --> DC
DC --> AC

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

Simulation Docs

Meteorological Parameters

General

The first step of the Proximal expected energy simulation is to ingest data from the project meteorological stations. This data is then used to calculate the intermediate meteorological parameters that are required to calculate the Plane of Array Irradiance (POAI).

This section of the documentation shows all models in the order that they are calculated in the simulation.

Met Station Assignments

The Proximal performance model treats weather data slightly differently than other performance models users may be familiar with. Instead of using a single set of weather data for every electrical component being modeled, Proximal assigns electrical components to individual blocks and then assigns those blocks a met station to use for modeling purposes. Each block is then modeled with the data that corresponds to its assigned met station. Generally the closest met station to the block is chosen to be that blocks assigned met station.

F.A.Q.

• Why not interpolate geospatially between weather stations?
  • Because passing clouds create a hard edge of irradiance, interpolating irradiance between sensors would create non-physical values in the data stream.

Acronyms:

• DHI: Diffuse Horizontal Irradiance
• DNI: Direct Normal Irradiance
• extraDNI: Extraterrestrial Direct Normal Irradiance
• PWAT: Precipitable Water
• RH: Relative Humidity

Simulation Pipeline

The following flow diagram shows how meteorological parameters is calculated in the Proximal expected energy simulation. The flow chart is meant to be interactive. Clicking on any of the modeling step nodes will take you to the documentation for that modeling step.

You may need to zoom in to be able to better see all of the details in the flow chart.

Legend

  flowchart LR

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  database[(Database)]:::source
  model_step[[
    Modeling Step
    DEFAULT MODEL CHOICE
  ]]:::model
  model_inputs[\
    Input Parameters
    for Modeling Step
  /]:::inputs
  model_outputs([Calculated Parameters]):::outputs

  database --> model_inputs
  model_inputs --> model_step --> model_outputs --> model_inputs

Model Chain

flowchart TD

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  %% --- SOURCES ---

  pv_system[(
    --- PV SYSTEM ---
    elevation
  )]:::source
  pv_system --> calc_pressure_inputs

  met_station[(
    --- MET STATION ---
    time
    ambient_temperature
    global_horizontal_radiation
    relative_humidity
    wind_speed
    *albedo
  )]:::source
  met_station --> TDEW_inputs
  met_station --> solar_position_inputs
  met_station --> extraDNI_inputs
  met_station --> DHI_inputs

  %% --- ATMOSPHERIC PRESSURE ---
  calc_pressure_inputs[\elevation/]:::inputs
  calc_pressure_inputs --> calc_pressure

  calc_pressure[[
    pvlib.atmosphere
    .alt2pres
    ]]:::model
  calc_pressure --> calc_pressure_outputs
  click calc_pressure "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.atmosphere.alt2pres.html"

  calc_pressure_outputs([
    pressure
  ]):::outputs
  calc_pressure_outputs --> DNI_inputs

  %% --- SOLAR POSITION ---
  solar_position_inputs[\
    time
    ambient_temperature
    latitude
    longitude
    altitude
  /]:::inputs
  solar_position_inputs --> solar_position

  solar_position[[
    pvlib.solarposition
    .get_solarposition
    NREL_2008
    ]]:::model
  solar_position --> solar_position_outputs
  click solar_position "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.solarposition.get_solarposition.html#pvlib.solarposition.get_solarposition"

  solar_position_outputs([
    apparent_zenith
    azimuth
  ]):::outputs
  solar_position_outputs --> DNI_inputs
  solar_position_outputs --> DHI_inputs
  solar_position_outputs --> airmass_inputs

  %% --- AIRMASS ---
  airmass_inputs[\
    apparent_zenith
  /]:::inputs
  airmass_inputs --> airmass

  airmass[[
    pvlib.atmosphere
    .get_relative_airmass
    KASTEN_YOUNG_1989
  ]]:::model
  airmass --> airmass_outputs
  click airmass "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.location.Location.get_airmass.html#pvlib.location.Location.get_airmass"

  airmass_outputs([
    airmass
    ]):::outputs

  %% --- EXTRATERRESTRIAL DNI ---
  extraDNI_inputs[\
  time
  solar_constant=1360.8
  epoch_year=2014
  /]:::inputs
  extraDNI_inputs --> extraDNI

  extraDNI[[
    pvlib.irradiance
    .get_extra_radiation
    SPENCER
    ]]:::model
  extraDNI --> extraDNI_outputs
  click extraDNI "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.get_extra_radiation.html#pvlib.irradiance.get_extra_radiation"

  extraDNI_outputs([
    extraterrestrial_DNI
    ]):::outputs

  %% --- TDEW ---

  TDEW_inputs[\
    relative_humidity
  /]:::inputs
  TDEW_inputs --> TDEW

  TDEW[[
    pvlib.atmosphere
    .tdew_from_rh
    MAGNUS_TETENS
    ]]:::model_dashed
  TDEW --> TDEW_outputs
  click TDEW "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.atmosphere.tdew_from_rh.html#pvlib.atmosphere.tdew_from_rh"

  TDEW_outputs([
    temp_dew_point
    ]):::outputs
  TDEW_outputs --> DNI_inputs

  %% --- DNI ---

  DNI_inputs[\
    solar_zenith
    ghi
    pressure
    temp_dew
    use_delta_kt_prime=False,
    min_cos_zenith=0.065
    max_zenith=87
  /]:::inputs
  DNI_inputs --> DNI

  DNI[[
    pvlib.irradiance
    .dirint
    DIRINT
  ]]:::model
  DNI --> DNI_outputs
  click DNI "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.dirint.html#pvlib.irradiance.dirint"

  DNI_outputs([
    DNI
  ]):::outputs
  DNI_outputs --> DHI_inputs

  %% --- DHI ---
  DHI_inputs[\
    GHI
    DNI
    solar_zenith
  /]:::inputs
  DHI_inputs --> DHI

  DHI[[
    pvlib.irradiance
    .complete_irradiance
    GEOMETRIC
  ]]:::model
  DHI --> DHI_outputs
  click DHI "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.complete_irradiance.html#pvlib.irradiance.complete_irradiance"

  DHI_outputs([
    DHI
    ]):::outputs

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

Tracker Rotation Angles

General

This section describes how tracker rotation angles are calculated in the Proximal Performance Model.

Caveats

• At the moment, only two dimensional modeling is taken into account. This means that 3D models such as terrain avoidance are not implemented (yet).
• At the moment, only solar position is taken into account. This means that tracker algorithms which take into account all-sky conditions are not implemented (yet).
• At the moment, only full cell module algorithms are taken into account. This means that tracker algorithms which take into account half-cell shading electrical effects are not implemented (yet).

Acronyms:

• Tracking
• aoi: Angle of Incidence

Legend

  flowchart LR

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  database[(Database)]:::source
  previous{{Previous Calculation}}:::previous
  model_step[[
    Modeling Step
    DEFAULT MODEL CHOICE
  ]]:::model
  model_inputs[\
    Input Parameters
    for Modeling Step
  /]:::inputs
  model_outputs([Calculated Parameters]):::outputs

  database --> model_inputs
  previous --> model_inputs
  model_inputs --> model_step --> model_outputs --> model_inputs

Model Chain

  flowchart TD

  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  %% --- Data Sources ---
  met_params{{
    --- MET PARAMS ---
    apparent_zenith
    azimuth
  }}:::previous
  met_params --> tracker_rotation_angles_inputs
  click met_params "meteorological_parameters.html"

  pv_system[(
    --- PV SYSTEM ---
    tracker_tilt
    tracker_azimuth
    tracker_max_angle
    tracking_type
    gcr
  )]:::source
  pv_system --> tracker_rotation_angles_inputs

  %% --- Tracker Rotation Angles ---
  tracker_rotation_angles_inputs[\
    apparent_zenith
    azimuth
    tracker_tilt
    tracker_azimuth
    tracker_max_angle
    tracking_type
    gcr
    /]:::inputs
  tracker_rotation_angles_inputs --> tracker_rotation_angles

  tracker_rotation_angles[[
    pvlib.tracking
    .single_axis
    ANDERSON_MIKOFSKI_2020
    ]]:::model
  tracker_rotation_angles --> tracker_rotation_angles_outputs
  click tracker_rotation_angles "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.tracking.singleaxis.html#pvlib.tracking.singleaxis"

  tracker_rotation_angles_outputs([
    tracker_rotation_angle
    surface_tilt
    surface_azimuth
    aoi
    ]):::outputs

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

Plane of Array Irradiance

General

The Plane of Array Irradiance (POAI) is the amount of irradiance that is incident upon the front face of the photovoltaic array.

This section of the documentation explains all of the different models and sub-models required to calculate POAI in the order that they are calculated in the simulation.

Switching Behavior

The Proximal Performance Model behaves different from other performance modeling software the user may be familiar with. It automatically switches between using the POA sensor as the input to the POA components model and the GHI sensor as the input to the POA components model. The model does this to account for the tendency of POA sensors to get shaded by nearby racks and become out of position due to tracking faults. When the predicted POA from the GHI sensor is greater than ten percent above the measured POA data, then the decomposed and transposed components from the GHI sensor are used for the rest of the model. This behavior is then noted in the data stream as lower quality data.

Acronyms:

• extraDNI: Extraterrestrial Direct Normal Irradiance
• DNI: Direct Normal Irradiance
• DHI: Diffuse Horizontal Irradiance
• RHI: Reflected Horizontal Irradiance
• POAI: Plane of Array Irradiance

Simulation Pipeline

The following flow diagram shows how the Plane of Array Irradiance is calculated in the Proximal expected energy simulation. The flow chart is meant to be interactive. Clicking on any of the modeling step nodes will take you to the documentation for that modeling step.

You may need to zoom in to be able to better see all of the details in the flow chart.

Legend

  flowchart LR

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  database[(Database)]:::source
  previous{{Previous Calculation}}:::previous
  model_step[[
    Modeling Step
    DEFAULT MODEL CHOICE
  ]]:::model
  model_inputs[\
    Input Parameters
    for Modeling Step
  /]:::inputs
  model_outputs([Calculated Parameters]):::outputs

  database --> model_inputs
  previous --> model_inputs
  model_inputs --> model_step --> model_outputs --> model_inputs

Model Chain

flowchart TD

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  %% --- SOURCES ---
  met_station[(
    --- MET STATION ---
    ghi
  )]:::source
  met_station --> ground_diffuse_inputs

  tracker_params{{
    --- TRACKER PARAMS ---
    tracker_rotation_angle
    tracker_surface_tilt
    tracker_surface_azimuth
    aoi
  }}:::previous
  click tracker_params "tracker_rotation_angles.html"
  tracker_params --> sky_diffuse_inputs
  tracker_params --> ground_diffuse_inputs
  tracker_params --> beam_inputs

  met_params{{
    --- MET PARAMS ---
    dhi
    dni
    dni_extra
    apparent_zenith
    azimuth
    airmass_relative
  }}:::previous
  met_params --> sky_diffuse_inputs
  met_params --> beam_inputs
  click met_params "meteorological_parameters.html"

  %% --- Ground Diffuse ---
  ground_diffuse_inputs[\
    surface_tilt
    ghi
    albedo
    /]:::inputs
  ground_diffuse_inputs --> ground_diffuse

  ground_diffuse[[
    pvlib.irradiance
    .ground_diffuse
    GEOMETRIC
    ]]:::model
  ground_diffuse --> ground_diffuse_outputs
  click ground_diffuse "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.get_ground_diffuse.html"

  ground_diffuse_outputs([
    ground_diffuse
    ]):::outputs
  ground_diffuse_outputs --> poai_inputs

  %% --- Sky Diffuse ---
  sky_diffuse_inputs[\
    surface_tilt
    surface_azimuth
    dhi
    dni
    dni_extra
    apparent_zenith
    azimuth
    airmass_relative
    /]:::inputs
  sky_diffuse_inputs --> sky_diffuse

  sky_diffuse[[
    pvlib.irradiance
    .perez_driesse
    POAI
  ]]:::model
  sky_diffuse --> sky_diffuse_outputs
  click sky_diffuse "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.perez_driesse.html#pvlib.irradiance.perez_driesse"

  sky_diffuse_outputs([
    isotropic
    horizon
    circumsolar
    ]):::outputs
  sky_diffuse_outputs --> poai_inputs

  %% --- BEAM ---
  beam_inputs[\
    surface_tilt
    surface_azimuth
    solar_zenith
    solar_azimuth
    dni
    /]:::inputs
  beam_inputs --> beam

  beam[[
    pvlib.irradiance
    .beam_component
    GEOMETRIC
    ]]:::model
  beam --> beam_outputs
  click beam "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.irradiance.beam.html"

  beam_outputs([
    beam
    ]):::outputs
  beam_outputs --> poai_inputs

  %% --- POAI ---
  poai_inputs[\
    isotropic
    circumsolar
    horizon
    ground_diffuse
    beam
    /]:::inputs
  poai_inputs --> poai

  poai[[
    proximal.poai_components
    SUM
  ]]:::model
  poai --> poai_outputs


  poai_outputs([
    poai_global
    ]):::outputs

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

Effective Irradiance

General

The Effective Plane of Array Irradiance (EPOAI) is the amount of irradiance that is incident upon the active cell area of the photovoltaic array. This is differentiated from the Plane of Array Irradiance (POAI) which is the amount of irradiance that is incident upon the front face of the photovoltaic array glass.

Conceptually, losses calculated while calculating the effective plane of array irradiance are generally calculated in the same order as the physical losses that occur between the sun's rays and t`he cell active material. For example, soiling loss on top of the module glass is calculated before the incidence angle effect inside of the module glass. On the other hand, some losses such as spectral correction, which are actually material science losses are calculated empirical losses in effective plane of array irradiance.

Acronyms:

• Irradiance
  • POAI: Plane of Array Irradiance
• EPOAI: Effective Plane of Array Irradiance

Simulation Pipeline

The following flow diagram shows how the Effective Plane of Array Irradiance is calculated in the Proximal expected energy simulation. The flow chart is meant to be interactive. Clicking on any of the modeling step nodes will take you to the documentation for that modeling step.

You may need to zoom in to be able to better see all of the details in the flow chart.

Legend

  flowchart LR

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  database[(Database)]:::source
  previous{{Previous Calculation}}:::previous
  model_step[[
    Modeling Step
    DEFAULT MODEL CHOICE
  ]]:::model
  model_inputs[\
    Input Parameters
    for Modeling Step
  /]:::inputs
  model_outputs([Calculated Parameters]):::outputs

  database --> model_inputs
  previous --> model_inputs
  model_inputs --> model_step --> model_outputs --> model_inputs

Model Chain

flowchart TD

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  %% --- SOURCES ---
  met_station[(
    --- MET STATION ---
    soiling
  )]:::source
  met_station --> soiling_inputs

  pv_system[(
    --- PV Modules ---
    n
    K
    L
    n_ar
    cell_technology
  )]:::source
  pv_system --> direct_iam_inputs
  pv_system --> spectral_inputs

  tracker_params{{
    --- TRACKER PARAMS ---
    rotation_angle
    surface_tilt
    surface_azimuth
    aoi
  }}:::previous
  click tracker_params "tracker_rotation_angles.html"
  tracker_params --> direct_shade_inputs
  tracker_params --> direct_iam_inputs

  met_params{{
    --- MET PARAMS ---
    dhi
    dni
    dni_extra
    apparent_zenith
    azimuth
    airmass_relative
  }}:::previous
  click met_params "meteorological_parameters.html"
  met_params --> direct_shade_inputs
  met_params --> spectral_inputs

  poai_params{{
    --- POAI PARAMS ---
    isotropic
    horizon
    ground_diffuse
    circumsolar
    beam
  }}:::previous
  click poai_params "plane_of_array_irradiance.html"
  poai_params --> direct_shade_inputs

  %% --- Direct Shade ---
  direct_shade_inputs[\
    apparent_zenith
    azimuth
    axis_tilt
    axis_azimuth
    rotation_angle
    collector_width
    pitch
    surface_to_axis_offset
    cross_axis_slope
    shading_row_rotation
    /]:::inputs
  direct_shade_inputs --> direct_shade

  direct_shade[[
    pvlib.shading
    .shaded_fraction_1d
    ]]:::model
  click direct_shade "https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.shading.shaded_fraction1d.html"
  direct_shade --> direct_shade_outputs

  direct_shade_outputs([
      isotropic
      horizon
      ground_diffuse
      circumsolar - shade?
      beam - shade
    ]):::outputs
  direct_shade_outputs --> soiling_inputs

  %% --- Soiling ---
  soiling_inputs[\
    soiling_loss
    /]:::inputs
  soiling_inputs --> soiling

  soiling[[
    proximal.soiling
    RATIO
  ]]:::model
  soiling --> soiling_outputs

  soiling_outputs([
    isotropic - soil
    horizon - soil
    ground_diffuse - soil
    circumsolar - soil
    beam - soil
    ]):::outputs
  soiling_outputs --> direct_iam_inputs

  %% --- Direct IAM ---
  direct_iam_inputs[\
  aoi
  n
  K
  L
  n_ar
  /]:::inputs
  direct_iam_inputs --> direct_iam

  direct_iam[[
    pvlib.iam.physical
    PHYSICAL
  ]]:::model
  click direct_iam "https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.iam.physical.html"
  direct_iam --> direct_iam_outputs

  direct_iam_outputs([
      isotropic
      horizon
      ground_diffuse
      circumsolar - iam?
      beam - iam
    ]):::outputs
  direct_iam_outputs --> spectral_inputs

  %% --- Spectral ---
  spectral_inputs[\
      prcipitable_water
      airmass_absolute
      cdte_coefficients
      min_p_wat=0.1
      max_p_wat=8.0
      min_airmass_abs=0.58
      max_airmass_abs=10.0
    /]:::inputs
  spectral_inputs --> spectral

  spectral[[
    pvlib.spectral.spectral
    SPECTRAL
  ]]:::model
  spectral --> spectral_outputs

  spectral_outputs([
    isotropic - spectral
    horizon - spectral
    ground_diffuse - spectral
    circumsolar - spectral
    beam - spectral
    ]):::outputs
  spectral_outputs --> epoai_inputs

  %% --- EPOIA ---
  epoai_inputs[\
      isotropic
      horizon
      ground_diffuse
      circumsolar
      beam
      /]:::inputs
  epoai_inputs --> epoai

  epoai[[
    proximal.epoai_components
    SUM
  ]]:::model
  epoai --> epoai_outputs

  epoai_outputs([
    epoai_global
    ]):::outputs

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

DC System Losses

General

DC system losses include losses that occur between the photovoltaic cell and the DC wiring to the inverter. In the diagrams, steps for combining power into strings and into combiners has been left out for the sake of brevity.

Acronyms:

• DC: Direct Current
• EPOAI: Effective Plane of Array Irradiance
• i: Current
• v: Voltage
• p: Power
• mp: Maximum Power
• oc: Open Circuit

Simulation Pipeline

The following flow diagram shows how DC system losses are calculated in the Proximal expected energy simulation. The flow chart is meant to be interactive. Clicking on any of the modeling step nodes will take you to the documentation for that modeling step.

You may need to zoom in to be able to better see all of the details in the flow chart.

Legend

  flowchart LR

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  database[(Database)]:::source
  previous{{Previous Calculation}}:::previous
  model_step[[
    Modeling Step
    DEFAULT MODEL CHOICE
  ]]:::model
  model_inputs[\
    Input Parameters
    for Modeling Step
  /]:::inputs
  model_outputs([Calculated Parameters]):::outputs

  database --> model_inputs
  previous --> model_inputs
  model_inputs --> model_step --> model_outputs --> model_inputs

Model Chain

flowchart TD

  %% --- CLASSES ---
  classDef source fill:#6B7A8F, color:#CCCCCC
  classDef previous fill:#4F5B6F,color:#CCCCCC
  classDef model fill:#202020, color:#CCCCCC
  classDef model_dashed fill:#202020, color:#CCCCCC, stroke-dasharray: 5 5
  classDef inputs fill:#1A1A1A, color:#CCCCCC
  classDef outputs fill:#B39245, color:#CCCCCC

  %% --- SOURCES ---
  met_station[(
    --- MET STATION ---
    ambient temperature
    wind speed
  )]:::source
  met_station --> cell_temperature_inputs

  epoai{{
    --- EPOAI ---
    epoai
  }}:::previous
  click tracker_params "effective_plane_of_array_irradiance.html"
  epoai --> cell_temperature_inputs
  epoai --> single_diode_inputs

  %% --- Cell Temperature ---
  cell_temperature_inputs[\
    epoai
    ambient temperature
    wind speed
    /]:::inputs
  cell_temperature_inputs --> cell_temperature

  cell_temperature[[
    pvlib.temperature
    .pvsyst_cell
    PVSYST_CELL
    ]]:::model
  cell_temperature --> cell_temperature_outputs
  click cell_temperature "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.temperature.pvsyst_cell.html#pvlib.temperature.pvsyst_cell"

  cell_temperature_outputs([
    cell_temperature
    ]):::outputs
  cell_temperature_outputs --> single_diode_inputs

  %% --- Single Diode Model ---
  single_diode_inputs[\
    epoai
    cell temperature
    module parameters
    /]:::inputs
  single_diode_inputs --> single_diode

  single_diode[[
    pvlib.pvsystem
    .calcparams_desoto
    DESOTO
    ]]:::model
  click single_diode "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.pvsystem.calcparams_desoto.html#pvlib-pvsystem-calcparams-desoto"
  single_diode --> single_diode_outputs

  single_diode_outputs([
    single diode parameters
  ]):::outputs
  single_diode_outputs --> iv_inputs

  %% --- IV Curve ---
  iv_inputs[\
    single diode parameters
    /]:::inputs
  iv_inputs --> iv

  iv[[
    pvlib.pvsystem
    .singlediode
    ]]:::Model
  click iv "https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.pvsystem.singlediode.html#pvlib.pvsystem.singlediode"
  iv --> iv_outputs

  iv_outputs([
    iv_curve
  ]):::outputs
  iv_outputs --> degradation_inputs

  %% --- Degradation ---
  degradation_inputs[\
    iv_curve
    /]:::inputs
  degradation_inputs --> degradation

  degradation[[
    proximal.degradation
    RATIO
  ]]:::model
  degradation --> degradation_outputs

  degradation_outputs([
    iv_curve
  ]):::outputs
  degradation_outputs --> wiring_inputs

  %% --- DC Wiring to Combiner ---
  wiring_inputs[\
    iv_curve
    /]:::inputs
  wiring_inputs --> wiring

  wiring[[
    proximal.target_stc
    TARGET LOSS AT STC
    ]]:::model
  wiring --> wiring_outputs

  wiring_outputs([
    iv_curve
  ]):::outputs

Edits and Additions

If you would like to see support for another algorithm or would like to suggest edits or additions to this documentation page, please open an issue on the Proximal GitHub repository.

PV Module Definition

Single Diode Model Parameters

The single diode model requires a set of PV module parameters. These parameters are generally calculated at a test lab and placed inside of a .PAN file. The Proximal platform can read data from a .PAN file or from the CEC database of pv modules.

Other Parameters

There are other parameters that may or may not be included in the .PAN file that Proximal needs for performance modeling purposes. These parameters may appear on a data sheet or can be found by contacting the manufacturer.

• Warranted Degradation Rate
• Warranted Degradation at Year Zero
• Length
• Width
• Frame overhang: Describes the non-active PV between the PV active cell and the edge of the module frame
• AR coating presence

Degradation

General

The Proximal platform automatically creates a model with warranted module degradation baked in. This module degradation occurs on the DC side of the plant and therefore cannot be post-processed due to the effects of clipping.

The warranted module degradation curve is module specific and usually comes in the form of an initial degradation value at year zero and a linear or piecewise linear drop from year one on-wards.

Degradation in PV modules can occur in both current and voltage. The Proximal model currently assumes a 50% degradation in current and 50% degradation in voltage for a given warranted degradation in power.

A different assumption can be used for a given PV module technology, if specified by the user.

AC System Losses

Quality Control Docs

General

Even more important than the performance model (at times) are the quality control measures used to make sure that the input data to the model is correct. The following sections detail how input data is filtered in the proximal performance model.

Soiling Sensors

Measurement Uncertainty

General

All data in the Proximal platform is inherently uncertain. This is due to the fact that sensors have inherent uncertainty and models have uncertainty on top of that. The following tables are a reference for users to use in order to understand the data and models being reported by the platform.

Defaults

By default all reported values below are:

• 95% Uncertainty (Expanded) (U)

Irradiance Sensor Uncertainty

Soiling Sensor Uncertainty

Notes

• Optical sensors may not capture the IAM effects of soiling
• Cell-Cell sensors will not capture the effects of non-uniform soiling
• Cell-Cell sensors may have a different glass than the install PV modules and may soil differently

Inverter

Meter

References

1. WMO 1.7-12
2. Atonometrics Whitepaper
3. IEC 61724-1:2021 Section 11.1
4. IEC 62053-22:2020

Changelog

2025-07-28

New Features

• Unveiling the new Portfolio Calendar View! Visualize your project timelines and key dates across your entire portfolio at a glance.
• Introducing dynamic Single Line Diagrams for projects, providing a clear visual representation of your electrical systems.
• Welcome the brand-new Oriden theme for a fresh, customized look and feel.
• Customize your workspace with the vibrant new Lightsource theme.

Improvements

• Enhanced performance and stability when processing large datasets, ensuring a smoother and more reliable experience.

Bug Fixes

• Resolved an edge-case issue to improve overall platform stability.

2025-07-07

Improvements

• Enhanced the KPI project comparison plot to display full legend names, making it easier to identify and compare different projects.

2025-06-30

New Features

• Added real-time data support for BESS (Battery Energy Storage Systems), enhancing visibility and operational insights.

Improvements

• Refactored PV equipment logic for improved performance and maintainability.

Bug Fixes

• Fixed an issue with the API endpoint for updating user projects in the admin module.

2025-06-23

New Features

• Custom Theming: Added extensive theming capabilities to provide a more customized user experience.
• KPI Portfolio Comparison: KPI reports can now include portfolio-level comparisons, enabling broader performance analysis across multiple projects.

Improvements

• GIS Map: The GIS map on the project Home page now features a new layer selector, making it easier to switch between different map views.
• Project Calendar: A Project calendar is now available for users to add project-related reporting deadlines, site visits and other items.
• Performance: Optimized the loading of pages that display open event counts.
• BESS Analysis: The date range selector for BESS Equipment Analysis has been updated for better usability.

Bug Fixes

• Navigation: Corrected navigation links from the Equipment Analysis page to Project Energy KPI and from Uptime metrics to Data Browsing.
• Real-Time Page: Added missing axis labels to heatmaps for improved clarity.
• Data Visualization: Resolved an issue where plots would not update correctly after changing filter selections.
• UI: Fixed a minor visual glitch in the calendar display.

2025-06-16

New Features

• Real Time Page: Added a x-axis labels to graphs on the real time page

Bug Fixes

• GIS Maps: Hovering over a met station no longer shows PCS data

2025-06-09

New Features

• Weather & Forecast: Improved display and added appropriate attribution to OpenWeatherMap.

Bug Fixes

• DC Amperage Report: Improved error handling to display feedback to user if the report fails to complete.
• CMMS Tab: Corrected error handling that would cause the page to crash.

2025-06-02

New Features

• Inverter Availability Report: A new report page has been added to monitor inverter availability across projects. The report is downloadable as an Excel file, allowing users to modify input parameters directly within the spreadsheet to perform custom analyses or generate updated availability metrics.

• Admin User Management: Introduced a comprehensive admin dashboard for managing users, assigning projects, and more.

• CMMS Tab for All Projects: All projects now have access to the CMMS tab, streamlining asset ticket management.

Other Improvements

• Cleaned up UI in several report pages to improve clarity and consistency.