Additional pvwatts fixes by paulf81 · Pull Request #252 · NatLabRockies/hercules

paulf81 · 2026-04-24T20:57:18Z

Recently, #250 made some improvements to Hercules PVWatts implementation for the solar component. This PR makes a few additional corrections for consistency:

Previously, the DC output of the array was used as the output, however, since the user can specify inverter losses and clipping, it makes more sense assume the AC power as the component output power
The DC power prior to the inverter is saved as a separate output

Smaller change is removal of a self.target_dc_ac_ratio which was not used anywhere and is now confusing since dc_ac_ratio is specified within model_params.

Changes to tests to confirm the correct AC output are included, and updates to docs to reflect the current state of the code.

Copilot

Pull request overview

This PR adjusts the Hercules PySAM PVWatts solar component so that the component’s delivered power output is based on PVWatts AC output (post-inverter), while also exposing the model’s uncurtailed DC power as a separate output for diagnostics/analysis.

Changes:

Switch solar component output to PVWatts Outputs.ac (AC) and add dc_power_uncurtailed from Outputs.dc.
Remove the unused target_dc_ac_ratio and simplify PVWatts parameter assignment structure.
Update unit/regression tests and documentation to reflect the new AC/DC output semantics.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`hercules/plant_components/solar_pysam_pvwatts.py`	Store uncurtailed AC and DC arrays from PVWatts outputs; simplify `model_params` structure.
`hercules/plant_components/solar_pysam_base.py`	Rename/route solar outputs to use AC power array and expose `dc_power_uncurtailed` through `h_dict`.
`tests/solar_pysam_pvwatts_test.py`	Update unit tests to validate AC output and renamed uncurtailed arrays.
`tests/example_regression_tests/example_03_regression_test.py`	Update expected regression outputs to match AC-based solar power.
`docs/solar_pv.md`	Update solar docs to describe AC `power` and DC diagnostic output and logging channels.
`docs/output_files.md`	Document new HDF5 channel for `dc_power_uncurtailed`.
`docs/h_dict.md`	Update `h_dict` schema for solar inputs/log channels and initial conditions description.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-24T21:01:21Z

            "array_type": 3.0,  # single axis backtracking
            "azimuth": 180.0,
-            "dc_ac_ratio": 1.0,  # default is 1.0 so there are no inverter losses.
+            "dc_ac_ratio": 1.0,  # inverter kWac nameplate / array kWdc STC; 1.0 is a common default


The inline description of dc_ac_ratio appears reversed. In PVWatts/SAM this parameter is typically the DC/AC ratio (array kWdc STC divided by inverter kWac nameplate), so describing it as kWac / kWdc is misleading and could cause users to size the inverter incorrectly. Please update the comment to reflect the correct direction of the ratio (and keep terminology consistent with PVWatts docs).

Suggested change

"dc_ac_ratio": 1.0, # inverter kWac nameplate / array kWdc STC; 1.0 is a common default

"dc_ac_ratio": 1.0, # array kWdc STC / inverter kWac nameplate; 1.0 is a common default

removed comment

Copilot · 2026-04-24T21:01:22Z

-| `log_channels` | list | List of channels to log (e.g., ["power", "dni", "poa", "aoi"]) |
-| `initial_conditions` | dict | Initial power, DNI, POA |
+| `log_channels` | list | Channels to log (e.g. `power`, `dc_power_uncurtailed`, `dni`, `poa`, `aoi`) — see [Solar PV](solar_pv.md) |
+| `initial_conditions` | dict | Initial `power`, `dni`, `poa` (placeholders; PVWatts overwrites with modeled values on init) |


The initial_conditions description says PVWatts overwrites these with modeled values on init, but SolarPySAMPVWatts currently leaves self.power set to the configured placeholder until the first step() (only dc_power_uncurtailed gets set from the precomputed array during init). Please either adjust this documentation to match current behavior or update initialization/metadata so power reflects the modeled initial AC value.

Suggested change

| `initial_conditions` | dict | Initial `power`, `dni`, `poa` (placeholders; PVWatts overwrites with modeled values on init) |

| `initial_conditions` | dict | Initial `power`, `dni`, `poa` placeholders; modeled values are not all applied on init, and `power` is updated to the modeled AC value on the first `step()` |

paulf81 · 2026-04-28T18:12:35Z

ok @genevievestarke, I fixed the name of things and believe this PR is now ready for review

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-28T18:17:27Z

      array_type: 3.0  # single axis backtracking
      azimuth: 170.0
-      dc_ac_ratio: 1.0  # Force to 1.0
+      dc_ac_ratio: 1.0  # kWac nameplate / kWdc STC; common default


The inline comment for dc_ac_ratio is inverted. In PVWatts/SAM, dc_ac_ratio is typically defined as array kWdc (STC) divided by inverter kWac nameplate (DC/AC), so describing it as kWac / kWdc could cause users to size the inverter incorrectly. Update the comment to reflect DC/AC (kWdc/kWac).

Suggested change

dc_ac_ratio: 1.0 # kWac nameplate / kWdc STC; common default

dc_ac_ratio: 1.0 # kWdc STC / kWac nameplate; common default

Deleted comment

Co-authored-by: Copilot <[email protected]>

genevievestarke

Looks pretty good, thank you @paulf81 ! Just some small comments and some NREL references slipping through.

genevievestarke · 2026-04-28T22:58:35Z

 # Solar PV

-The solar PV modules use the [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) package for the National Laboratory of the Rockies's System Advisor Model (SAM) to predict the power output of the solar PV plant.
+Hercules uses NREL [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) to drive NREL [System Advisor Model (SAM)](https://sam.nrel.gov) PV technology models.


Suggested change

Hercules uses NREL [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) to drive NREL [System Advisor Model (SAM)](https://sam.nrel.gov) PV technology models.

Hercules uses NLR [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) to drive NLR [System Advisor Model (SAM)](https://sam.nlr.gov) PV technology models.

genevievestarke · 2026-04-28T22:59:16Z

+The only solar implementation currently in Hercules is:

-1. **`SolarPySAMPVWatts`** - Uses the [PVWatts model](https://sam.nrel.gov/photovoltaic.html) in [`Pvwattsv8`](https://nrel-pysam.readthedocs.io/en/main/modules/Pvwattsv8.html), which calculates estimated PV electrical output with configurable efficiency and loss parameters. This model is less detailed but more time-efficient, making it suitable for longer duration simulations (approximately 1 year). Set `component_type: SolarPySAMPVWatts` in the component's YAML section. The section key is a user-chosen `component_name` (e.g. `solar_farm`); see [Component Names, Types, and Categories](component_types.md) for details.
+1. **`SolarPySAMPVWatts`** — [PVWatts](https://sam.nrel.gov/photovoltaic.html) via PySAM [`Pvwattsv8`](https://nrel-pysam.readthedocs.io/en/main/modules/Pvwattsv8.html). It is fast and suitable for long runs (e.g. about one year). Set `component_type: SolarPySAMPVWatts` in the component YAML. The section key is a user-chosen `component_name` (e.g. `solar_farm`); see [Component Names, Types, and Categories](component_types.md).


Suggested change

1. **`SolarPySAMPVWatts`** — [PVWatts](https://sam.nrel.gov/photovoltaic.html) via PySAM [`Pvwattsv8`](https://nrel-pysam.readthedocs.io/en/main/modules/Pvwattsv8.html). It is fast and suitable for long runs (e.g. about one year). Set `component_type: SolarPySAMPVWatts` in the component YAML. The section key is a user-chosen `component_name` (e.g. `solar_farm`); see [Component Names, Types, and Categories](component_types.md).

1. **`SolarPySAMPVWatts`** — [PVWatts](https://sam.nlr.gov/photovoltaic.html) via PySAM [`Pvwattsv8`](https://nrel-pysam.readthedocs.io/en/main/modules/Pvwattsv8.html). It is fast and suitable for long runs (e.g. about one year). Set `component_type: SolarPySAMPVWatts` in the component YAML. The section key is a user-chosen `component_name` (e.g. `solar_farm`); see [Component Names, Types, and Categories](component_types.md).

genevievestarke · 2026-04-28T23:01:56Z

+At each time step, `h_dict[component_name]` is updated with `power`,
+`ac_power_available`, and `dc_power_available` (all in kW), as well as the
+weather/geometry diagnostics (`dni`, `poa`, `aoi`). All three power quantities
+can be selected for HDF5 logging via `log_channels` (see below).


Suggested change

can be selected for HDF5 logging via `log_channels` (see below).

can be selected for HDF5 logging via `log_channels` (see below), though the `power` variable is always logged by default.

genevievestarke · 2026-04-28T23:03:41Z


 ## References
-PySAM. National Laboratory of the Rockies. Golden, CO. https://github.com/nrel/pysam
+PySAM (NREL). https://github.com/nrel/pysam


Suggested change

PySAM (NREL). https://github.com/nrel/pysam

PySAM (NLR). https://github.com/NatLabRockies/pysam

genevievestarke · 2026-04-28T23:06:02Z

+PVWatts `SolarPySAMPVWatts` includes lumped and inverter-related terms; the ones exposed in typical Hercules YAML are:

-The system capacity can be changed in the `.yaml` file, but the DC/AC ratio is fixed at 1.0.
+- **`losses`**: system losses as a percentage (0–100). Affects the modeled **DC** side before the inverter in PVWatts. A common default is `0`.


Do you think it's slightly weird here not to mention tilt? Since it's the other parameter set at the top level of the solar dict?

Good catch, re-arranging the docs a little so tilt gets more intentionally described. But arranging just a little so tilt doesn't get listed under losses (see above)

paulf81 added 3 commits April 24, 2026 14:48

clarify ac/dc power

47bb0b2

update tests

faf8137

update docs

8614bc5

paulf81 requested review from Copilot, genevievestarke and misi9170 April 24, 2026 20:57

Copilot started reviewing on behalf of paulf81 April 24, 2026 20:57 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

paulf81 added 4 commits April 28, 2026 12:08

Add drawgin

01f26ef

update ac/dc names

2255e31

update docs

0b66ec3

remove comment

da8ffa0

paulf81 requested a review from Copilot April 28, 2026 18:12

paulf81 added bug Something isn't working Ready for review labels Apr 28, 2026

Copilot started reviewing on behalf of paulf81 April 28, 2026 18:12 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

genevievestarke and others added 2 commits April 28, 2026 18:52

Merge branch 'develop' into bugfix/power_uncurtailesd

b153945

Apply suggestion from @Copilot

b045086

Co-authored-by: Copilot <[email protected]>

genevievestarke reviewed Apr 28, 2026

View reviewed changes

Addressing comments

351b110

genevievestarke approved these changes Apr 29, 2026

View reviewed changes

genevievestarke merged commit 76d3fc3 into develop Apr 29, 2026
6 checks passed

paulf81 deleted the bugfix/power_uncurtailesd branch April 29, 2026 16:35

	"dc_ac_ratio": 1.0, # inverter kWac nameplate / array kWdc STC; 1.0 is a common default
	"dc_ac_ratio": 1.0, # array kWdc STC / inverter kWac nameplate; 1.0 is a common default

	\| `initial_conditions` \| dict \| Initial `power`, `dni`, `poa` (placeholders; PVWatts overwrites with modeled values on init) \|
	\| `initial_conditions` \| dict \| Initial `power`, `dni`, `poa` placeholders; modeled values are not all applied on init, and `power` is updated to the modeled AC value on the first `step()` \|

	dc_ac_ratio: 1.0 # kWac nameplate / kWdc STC; common default
	dc_ac_ratio: 1.0 # kWdc STC / kWac nameplate; common default

	Hercules uses NREL [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) to drive NREL [System Advisor Model (SAM)](https://sam.nrel.gov) PV technology models.
	Hercules uses NLR [PySAM](https://nrel-pysam.readthedocs.io/en/main/overview.html) to drive NLR [System Advisor Model (SAM)](https://sam.nlr.gov) PV technology models.

	can be selected for HDF5 logging via `log_channels` (see below).
	can be selected for HDF5 logging via `log_channels` (see below), though the `power` variable is always logged by default.

	PySAM (NREL). https://github.com/nrel/pysam
	PySAM (NLR). https://github.com/NatLabRockies/pysam

Conversation

paulf81 commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paulf81 commented Apr 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

genevievestarke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants