Help revisions for PV UI redesign

cpaulgilman · cpaulgilman · commit a28af1892299 · 2026-01-13T10:31:16.000-08:00
diff --git a/doc/readme.md b/doc/readme.md
@@ -1,16 +1,16 @@
-# SAM Help
+# SAM Help Build Guide
 
 These instructions are for writing and editing content and building SAM's Help system.
 
-The Help system is built with the Sphinx documentation generator that converts .rst source files into structured html documents.
-
 Help content is written in the reStructuredText (.rst) text markup language: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.
 
-Sphinx is a Python package that converts the content to HTML: https://www.sphinx-doc.org/en/master/.
+The Sphinx documentation generator converts .rst source files into structured HTML.
+
+Sphinx is a Python package: https://www.sphinx-doc.org/en/master/.
 
 SAM Help uses Sphinx Book Theme to apply formatting to the HTML: https://sphinx-book-theme.readthedocs.io/en/stable/index.html.
 
-The Sphinx Book Theme, Sphinx, and reStructuredText are all well documented. The documentation below describes the application of these tools to build SAM Help. Refer to the documentation above for detailed descriptions and for information about modifying or adding more features to SAM Help.
+Complete documentation for the Sphinx Book Theme, Sphinx, and reStructuredText is available at the links above. The documentation below describes the application of these tools to build SAM Help.
 
 ## Requirements
 
@@ -70,6 +70,8 @@ Tested on Windows with Python 3.12.10 and GNU Make 4.4.1.
 
    To clean the build using Make, run `make clean`.
 
+   To see a list of Make targets, run `make`.
+
 4. If there are any build errors, fix them by editing the appropriate .rst file(s).
 
 5. When the build finishes, HTML and associated files should be in the `../doc/build/html` folder. (The `../doc/build/doctrees` folder is used during the build and not needed to display the HTML files.)
@@ -213,6 +215,12 @@ The `../doc/includes` folder contains files with text "snippets" or reusable tex
 
 For example the `../doc/includes/snip_system_availability.rst` is a description of the system availability losses that is used in descriptions of each of the performance models, such as in the Detailed PV model's "Electrical Losses" topic, and the Physical Trough model's "System Control" topic.
 
+To insert the content of `snip_system_availability.rst` from a file in a `../doc/source` subfolder:
+
+```
+.. include:: ../includes/snip_system_availability.rst
+```
+
 **Important note about snippets**: Do not include targets (`.. _target-name-in-snippet`), cross references references to targets in other snippet files, or cross references to other snippet files in snippet files. Doing so results in duplicate target names which breaks the Sphinx build. You can include cross references in snippet files to topic files that are not in the `../doc/includes` folder.
 
 ## Headings
diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css
@@ -1,16 +1,16 @@
 h1 {
-    font-size: 1.75em;
+    font-size: 2em;
 }
 
 h2 {
-    font-size: 1.5em;
+    font-size: 1.75em;
 }
 
 h3 {
-    font-size: 1.25em;
+    font-size: 1.5em;
 }
 
 h4 {
-    font-size: 1em;
+    font-size: 1.25em;
     font-weight: bold;
 }
diff --git a/doc/source/detailed-photovoltaic-model/pv_inverter.rst b/doc/source/detailed-photovoltaic-model/pv_inverter.rst
diff --git a/doc/source/detailed-photovoltaic-model/pv_module.rst b/doc/source/detailed-photovoltaic-model/pv_module.rst
diff --git a/doc/source/detailed-photovoltaic-model/pv_overview.rst b/doc/source/detailed-photovoltaic-model/pv_overview.rst
@@ -1,83 +1,48 @@
-Detailed Photovoltaic Model
-===========================
+Getting Started with the Detailed Photovoltaic Model
+====================================================
 
-The following overview is to help you get started modeling  a photovoltaic system with the detailed photovoltaic model. For a description of the model, see :doc:`Performance Models <../introduction/technology_options>`.
+The following overview is to help you get started modeling a photovoltaic system with the detailed photovoltaic model. For a description of the model, see :doc:`Performance Models <../introduction/technology_options>`.
+
+.. note:: If you only have basic information about the photovoltaic system's design like the system size and orientation, you can use the :doc:`../pvwatts/pvwatts` model instead of the Detailed Photovoltaic model. PVWatts does not require detailed information about the module, inverter, and array layout.
 
 For a complete technical description of SAM's photovoltaic model, see Gilman, P. (2015). SAM Photovoltaic Model Technical Reference. National Renewable Energy Laboratory. 59 pp.; NREL/TP-6A20-64102. (`PDF 840 KB <https://docs.nrel.gov/docs/fy15osti/64102.pdf>`__)
 
-Basic Steps
------------
+Follow the steps below to get started using the detailed photovoltaic model. If you are unsure of an input, use its default value. After running simulations, exploring results, and collecting more information about your project, you can refine the inputs.
 
 **1. Choose a weather file**
 
-* On the :doc:`Location and Resource <pv_location_and_resource>` page, choose a weather file to represent the solar resource at the project location.
+* On the :doc:`Location and Resource <pv_location_and_resource>` page, choose or download a weather file to represent the solar resource at the project location.
 
 **2. Specify the system's characteristics**
 
 #. On the :doc:`Module <pv_module>` page, choose a model option and module.
 
-   For most applications, use the CEC Performance Model with Module Database model unless your module is not in the list, in which case you can use the CEC Performance Model with User Specifications.
+   For most applications, use the CEC Performance Model with Module Database model. If your module is not in the list, use the CEC Performance Model with User Specifications.
 
 #. On the :doc:`Inverter <pv_inverter>` page, choose a model option and inverter. 
 
    Use the Inverter CEC Database option. For an inverter that is not in the list, if you have the manufacturer's data sheet, choose the Inverter Datasheet model.
 
 #. On the :doc:`pv_system_size` page, specify the system's size and array tracking options.
 
-   Use the specify desired array size option for preliminary analysis, and then use specify modules and inverters to refine the system design.
+   Use **Specify desired size and DC/AC ratio** for preliminary analysis, and then use **Specify number of modules and inverters** to refine the system design.
 
-#. If you want to account for shading losses, use the :doc:`pv_soiling_shading_snow` page for external shading by nearby objects, array self-shading, or to account for losses due to the array being covered by snow when your weather data includes snow depth data.
+#. To account for soiling, shading, or snow losses, use the :doc:`pv_soiling_shading_snow` page. By default, SAM assumes no shading or snow losses, and 5% soiling losses.
 
-#. Account for soiling losses, DC power losses, AC power losses, and losses due to system availability requirements on the :doc:`pv_electrical_losses` page. You can use the default values if you do not have detailed information about those losses for your system.
+#. Account for DC power losses, AC power losses, and losses due to system availability requirements on the :doc:`pv_electrical_losses` page. You can use the default values if you do not have detailed information about those losses for your system.
 
 **3. Specify the project costs**
 
-* On the :doc:`Installation costs <../installation-costs/cc_pv>` and :doc:`Operating costs <../operating-costs/oc_operating>` pages, specify values for capital cost and operation and maintenance costs.
+If you are using the detailed photovoltaic model with a financial model, specify capital costs on the :doc:`Installation costs <../installation-costs/cc_pv>` page, and operation and maintenance costs on the :doc:`Operating costs <../operating-costs/oc_operating>` pages.
+
+**4. Review financial assumptions**
+
+The inputs on the remaining pages are inputs to the financial model. For your first simulation runs as you learn to use SAM, use the default values and review results to see how the model works. The default values are reasonable for a typical project in the United States. As you become familiar with the model, you can modify the financial inputs as appropriate for your analysis.
 
 **4. Run a simulation and review results**
 
-* Click Simulate, and review :doc:`results <pv_results>` on the :doc:`Results Page <../getting-started/results_page>`.
+* Click **Simulate**, and review :doc:`results <pv_results>` on the :doc:`Results Page <../getting-started/results_page>`.
 
 .. image:: ../images/SS_MainWindow-RunAllSimulationsButton.png
    :align: center
    :alt: SS_MainWindow-RunAllSimulationsButton.png
-
-.. _postsimulationwarnings:
-
-Post-simulation Notices
------------------------
-
-After completing a simulation, SAM checks to see whether the inverter appears to be over- or under-sized based on the actual DC output of the array. If it finds any problems, it displays :doc:`notices <../results/notices>` after simulations are complete.
-
-**Inverter undersized**
-  The array output is greater than inverter rated capacity for one or more of the 8,760 hours in one year. SAM reports the number of hours that the array's simulated DC output is greater than the inverter's AC rated capacity.
-
-  If the number of hours is small compared to the 8,760 hours in a year, you may choose to ignore the message. Otherwise, you may want to try increasing the inverter capacity.
-
-  For example, for a system with 400 kWdc array capacity and 150 kWac total inverter capacity, SAM displays the following warning message: "pvsamv1: Inverter undersized: The array output exceeded the inverter rating 157.62 kWdc for 2128 hours."
-
-  The following :doc:`time series graphs <../results/timeseries>` show the array's DC output in red, and the system's AC output in blue, indicating that the inverter capacity is limiting the system's AC output.
-  
-  This graph shows the time series data for one year:
-
-  .. image:: ../images/IMG_PVError-time-series-inverter-undersized.png
-     :align: center
-     :alt: IMG_PVError-time-series-inverter-undersized.png
-
-  And this one shows the same data zoomed in to five days:
-
-  .. image:: ../images/IMG_PVError-days-inverter-undersized.png
-     :align: center
-     :alt: IMG_PVError-days-inverter-undersized.png
-
-**Inverter output less than 75 percent of inverter rated capacity**
-  SAM compares the inverter's maximum AC output to the total inverter AC capacity and displays a simulation warning if the inverter's maximum AC output is less than 75% of the total inverter rated AC capacity.
-
-  For example, for a system with 400 kWdc array capacity and 750 kWac inverter capacity, SAM displays the following warning message: "pvsamv1: Inverter oversized: The maximum inverter output was 43.13% of the rated value 750 kWac."
-
-  In this case, the time series graph of gross AC output shows that the inverter output never reaches the 750 kWac capacity.
-
-  .. image:: ../images/IMG_PVError-time-series-inverter-oversized.png
-     :align: center
-     :alt: IMG_PVError-time-series-inverter-oversized.png
-
diff --git a/doc/source/images/SS_MainWindow-RunAllSimulationsButton.png b/doc/source/images/SS_MainWindow-RunAllSimulationsButton.png
diff --git a/doc/source/includes/snip_pv_inverter_temperature_curves.rst b/doc/source/includes/snip_pv_inverter_temperature_curves.rst
@@ -1,7 +1,3 @@
-
-Inverter Temperature Derate Curves
-..................................
-
 Temperature derating is an inverter function that decreases inverter power to prevent heat-related damage to internal components when the ambient temperature increases above a pre-defined value. SAM uses the information from the inverter temperature derate curves with ambient temperature data from the weather file to adjust the inverter efficiency in each time step of the simulation. As ambient temperature increases, the inverter efficiency decreases based on the data in the table. You can see the effect of inverter temperature derating using the following results variables:
 
 * **Inverter thermal derate DC power loss (kWh/yr)**
@@ -10,6 +6,8 @@ Temperature derating is an inverter function that decreases inverter power to pr
 
 * **Inverter thermal derate DC power loss (kW)**
 
+SAM adjusts the inverter efficiency based on the ambient temperature in the weather file based on the Efficiency - Ambient Temperature curve under **Inverter Temperature Derate Curves**. The default curve decreases the inverter efficiency as the ambient temperature increases above 52.8 degrees Celsius at a rate of 0.021% per degree of temperature increases. You can edit the values in the efficiency table to change the shape of the curve.
+
 Temperature derating data is not included in the inverter library, but may be available on the inverter manufacturer datasheet. The default generic temperature derating curve is for an inverter that starts derating when the ambient temperature reaches 50°C at 1300 Vdc and shuts the inverter down when the ambient temperature reaches 55°C. You can use the default data if you do not expect the inverter to be exposed to high temperatures.
 
 The following example shows SAM derating data for the inverter described in the SMA technical document "SUNNY BOY / SUNNY TRIPOWER Temperature Derating" available at https://files.sma.de/downloads/Temp-Derating-TI-en-15.pdf.
@@ -36,9 +34,6 @@ The following example shows SAM derating data for the inverter described in the
 **Update plot**
   After changing values in the table, click **Update plot** to change the graph.
 
- 
-
-
 .. note:: To avoid excessive temperature derating losses for large inverters, make sure the highest Vdc voltage value in the temperature derate curves is greater than or equal to the inverter's maximum VDC voltage rating.
 
 
diff --git a/doc/source/includes/snip_pv_transient_thermal_model.rst b/doc/source/includes/snip_pv_transient_thermal_model.rst
@@ -1,7 +1,3 @@
-
-Transient Thermal Model Correction
-..................................
-
 When the simulation time step determined by the number of records in the weather file is 20 minutes or less, SAM automatically applies a correction to account for temperature changes driven by wind speed and the mass of the module using the method described in Prilliman (2020) listed on the `PV Publications <https://sam.nrel.gov/photovoltaic/pv-publications.html>`__ page of the SAM website..
 
 **Module unit mass, kg/m²**
diff --git a/doc/source/reference/libraries.rst b/doc/source/reference/libraries.rst
@@ -1,10 +1,12 @@
 Libraries
 =========
 
-A library is a text file of comma-separated values that stores sets of data associated with a SAM input in the libraries folder of your SAM installation folder. SAM displays the library contents in a :ref:`library browser <librarybrowser>` where you choose an item from the library to populate values of a set of input variables. For example, the detailed photovoltaic model uses a library to store inverter parameters. By choosing an inverter name, you populate the 16 input variables required to specify an inverter using the CEC inverter model.
+A library is a text file of comma-separated values (CSV) that stores sets of data associated with a SAM input in the libraries folder of your SAM installation folder. SAM displays the library contents in a :ref:`library browser <librarybrowser>` where you choose an item from the library to populate values of a set of input variables. For example, the detailed photovoltaic model uses a library to store inverter parameters. By choosing an inverter name, you populate the 16 input variables required to specify an inverter using the CEC inverter model.
 
 .. note:: In addition to the parameter libraries shown in the table below, SAM also creates libraries as temporary files on your computer to store information about your wind and solar resource data files. For more about weather file libraries, see :doc:`Weather Files and Libraries <../weather-data/weather_manage_folders>`.
 
+   You can find copies of the SAM library CSV files at https://github.com/NREL/SAM/tree/develop/deploy/libraries.
+
 .. list-table::
    :width: 100%
    :align: center
@@ -17,11 +19,11 @@ A library is a text file of comma-separated values that stores sets of data asso
    * - CEC Inverters
      - Photovoltaic inverters
      - Detailed photovoltaic
-     - Go Solar California
+     - California Energy Commission
    * - CEC Modules
      - Photovoltaic modules
      - Detailed photovoltaic
-     - Go Solar California
+     - California Energy Commission
    * - Empirical Trough HCEs
      - Parabolic trough receivers
      - Empirical trough
@@ -91,9 +93,11 @@ For most applications, you do not need to modify libraries. However, if you have
 
 .. note:: If you modify a library, do not change the first three rows of the library file.
 
+   Each version of SAM has a separate installation folder. If you modify a library file for one version of SAM, it will only affect that version, and may be deleted when you remove (uninstall) that version.
+
 The library file format is defined as follows:
 
-* Library files use the .csv file name extension and are stored in the Libraries folder of your SAM installation.
+* Library files use the .csv extension and are stored in the Libraries folder in the :ref:`installationfolder`.
 
 * The first row of a library file is a list of the labels describing the input variables stored in the library. SAM displays these labels in the library browser. It does not use these labels in calculations.
 

Original file line number	Diff line number	Diff line change
`@@ -1,16 +1,16 @@`
`1`	`1`	`h1 {`
`2`		`- font-size: 1.75em;`
	`2`	`+ font-size: 2em;`
`3`	`3`	`}`
`4`	`4`
`5`	`5`	`h2 {`
`6`		`- font-size: 1.5em;`
	`6`	`+ font-size: 1.75em;`
`7`	`7`	`}`
`8`	`8`
`9`	`9`	`h3 {`
`10`		`- font-size: 1.25em;`
	`10`	`+ font-size: 1.5em;`
`11`	`11`	`}`
`12`	`12`
`13`	`13`	`h4 {`
`14`		`- font-size: 1em;`
	`14`	`+ font-size: 1.25em;`
`15`	`15`	`font-weight: bold;`
`16`	`16`	`}`