NREL
diff --git a/‎.github/workflows/Publish_ROSCO.yml‎
Lines changed: 15 additions & 15 deletions b/‎.github/workflows/Publish_ROSCO.yml‎
Lines changed: 15 additions & 15 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 1 deletion b/‎.gitignore‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.readthedocs.yaml‎
Lines changed: 7 additions & 1 deletion b/‎.readthedocs.yaml‎
Lines changed: 7 additions & 1 deletion
diff --git a/‎Examples/01_turbine_model.py‎
Lines changed: 10 additions & 3 deletions b/‎Examples/01_turbine_model.py‎
Lines changed: 10 additions & 3 deletions
diff --git a/‎Examples/02_ccblade.py‎
Lines changed: 1 addition & 1 deletion b/‎Examples/02_ccblade.py‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎Examples/03_tune_controller.py‎
Lines changed: 11 additions & 6 deletions b/‎Examples/03_tune_controller.py‎
Lines changed: 11 additions & 6 deletions
diff --git a/‎Examples/04_simple_sim.py‎
Lines changed: 15 additions & 9 deletions b/‎Examples/04_simple_sim.py‎
Lines changed: 15 additions & 9 deletions
diff --git a/‎Examples/05_openfast_sim.py‎
Lines changed: 5 additions & 9 deletions b/‎Examples/05_openfast_sim.py‎
Lines changed: 5 additions & 9 deletions
diff --git a/‎Examples/06_peak_shaving.py‎
Lines changed: 25 additions & 7 deletions b/‎Examples/06_peak_shaving.py‎
Lines changed: 25 additions & 7 deletions
diff --git a/‎Examples/07_openfast_outputs.py‎
Lines changed: 6 additions & 6 deletions b/‎Examples/07_openfast_outputs.py‎
Lines changed: 6 additions & 6 deletions
@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macOS-latest]
+        os: [ubuntu-latest, windows-latest, macos-13, macos-14, macos-15]
 
     steps:
       - name: Set up QEMU
@@ -23,7 +23,7 @@ jobs:
 
       - name: Setup GNU Fortran
         if: false == contains( matrix.os, 'windows')
-        uses: awvwgk/setup-fortran@v1
+        uses: fortran-lang/setup-fortran@v1
 
       - name: Install compiler
         if: false == contains( matrix.os, 'windows')
@@ -59,38 +59,38 @@ jobs:
 
       - name: Build wheels linux
         if: contains( matrix.os, 'ubuntu')
-        uses: pypa/cibuildwheel@v2.18.1
+        uses: pypa/cibuildwheel@v2.23.3
         env:
           CC: ${{ steps.install_cc.outputs.cc }}
           CXX: ${{ steps.install_cc.outputs.cxx }}
 
-      - name: Build wheels mac-12
-        if: contains( matrix.os, 'macos-12')
-        uses: pypa/[email protected]
-        env:
-          CC: ${{ steps.install_cc.outputs.cc }}
-          CXX: ${{ steps.install_cc.outputs.cxx }}
-          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET="12.0"
-
       - name: Build wheels mac-13
         if: contains( matrix.os, 'macos-13')
-        uses: pypa/cibuildwheel@v2.18.1
+        uses: pypa/cibuildwheel@v2.23.3
         env:
           CC: ${{ steps.install_cc.outputs.cc }}
           CXX: ${{ steps.install_cc.outputs.cxx }}
           CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET="13.0"
 
       - name: Build wheels mac-14
         if: contains( matrix.os, 'macos-14')
-        uses: pypa/cibuildwheel@v2.18.1
+        uses: pypa/cibuildwheel@v2.23.3
         env:
           CC: ${{ steps.install_cc.outputs.cc }}
           CXX: ${{ steps.install_cc.outputs.cxx }}
           CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET="14.0"
 
+      - name: Build wheels mac-15
+        if: contains( matrix.os, 'macos-15')
+        uses: pypa/[email protected]
+        env:
+          CC: ${{ steps.install_cc.outputs.cc }}
+          CXX: ${{ steps.install_cc.outputs.cxx }}
+          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET="15.0"
+
       - name: Build wheels windows
         if: contains( matrix.os, 'windows')
-        uses: pypa/cibuildwheel@v2.18.1
+        uses: pypa/cibuildwheel@v2.23.3
 
       - uses: actions/upload-artifact@v4
         with:
@@ -101,7 +101,7 @@ jobs:
     name: Build source distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Build sdist
         run: pipx run build --sdist
 
@@ -67,7 +67,7 @@ _build
 # Binaries
 *.dylib
 *.so
-*.dll
+*.dll.*
 *.bts
 
 # Other
 
@@ -13,8 +13,14 @@ build:
   jobs:
     # Read the docs needs a couple packages not in the environment file
     pre_install:
-      - conda install -y cmake compilers sphinx sphinxcontrib-bibtex
+      - conda install -y cmake compilers sphinx sphinxcontrib-bibtex sphinx-jsonschema
       - conda install sphinx_rtd_theme>=1.3
+      - pip install json-schema-for-humans 
+    pre_build:
+      - pwd
+      - ls
+      - pip install -e .
+      - generate-schema-doc --no-copy-css --no-copy-js rosco/toolbox/inputs/toolbox_schema.yaml docs/_static/toolbox_doc.html
 
 conda:
   environment: environment.yml
 
@@ -1,13 +1,20 @@
 """
 01_turbine_model
 ----------------
-Load and save a turbine model.
+Interact with a ROSCO turbine model:
 
 * Read .yaml input file
 * Load an openfast turbine model
-* Read text file with rotor performance properties
+* Read text file with rotor performance properties (Cp, Ct, and Cq surface)
 * Print some basic turbine properties
-* Save the turbine as a picklle
+* Save the turbine as a pickle
+* Plot the Cp surface
+
+.. figure:: /images/examples/01_NREL5MW_Cp.png
+   :align: center
+   :width: 70%
+
+
 
 Note: Uses the NREL 5MW included in the Test Cases and is a part of the OpenFAST distribution
 """
 
@@ -7,7 +7,7 @@
 * Read .yaml input file
 * Load an openfast turbine model
 * Run ccblade to get rotor performance properties
-* Write a text file with rotor performance properties
+* Write a text file (``'02_Cp_Ct_Cq.Ex03.txt'``) with rotor performance properties
 """
 
 # Python modules
 
@@ -5,10 +5,15 @@
 In this example:
 
 * Read a .yaml file
-* Load a turbine model from OpenFAST
-* Tune a controller
-* Write a controller input file
-* Plot gain schedule
+* Create a ROSCO turbine object fromt he OpenFAST model
+* Tune a ROSCO controller object
+* Write a controller input file (``'03_DISCON.IN'``)
+* Plot gain schedule (``PC_GS_KP`` and ``PC_GS_KI`` versus ``PS_GS_angles``):
+
+.. figure:: /images/examples/03_GainSched.png
+   :align: center
+   :width: 70%
+
 """
 
 # Python modules
@@ -46,7 +51,8 @@ def main():
     controller.tune_controller(turbine)
 
     # Write parameter input file
-    param_file = os.path.join(this_dir,'DISCON.IN')
+    example_out_dir = os.path.join(this_dir,'examples_out')
+    param_file = os.path.join(example_out_dir,'03_DISCON.IN')
     write_DISCON(turbine,controller,
     param_file=param_file, 
     txt_filename=cp_filename
@@ -71,7 +77,6 @@ def main():
 
     plt.suptitle('Pitch Controller Gains')
 
-    example_out_dir = os.path.join(this_dir,'examples_out')
     if not os.path.isdir(example_out_dir):
         os.makedirs(example_out_dir)
 
 
@@ -1,17 +1,24 @@
 """
 04_simple_sim
 -------------
-Run and plot a simple simple step wind simulation
+Demonstrate the simple 1-DOF wind turbine simulator with ROSCO
+
 In this example:
 
-* Load turbine from saved pickle
-* Tune a controller
-* Run and plot a simple step wind simulation
+* Load turbine from saved pickle and tune a ROSCO controller
+* Run and plot a step wind simulation using 1-DOF model in ``rosco.toolbox.sim`` and the ROSCO dynamic library
+
+.. figure:: /images/examples/03_GainSched.png
+   :align: center
+   :width: 70%
+
 
 Notes:
 
-* You will need to have a compiled controller in ROSCO, and properly point to it in the `lib_name` variable.
-* Using wind speed estimators in this simple simulation is known to cause problems. We suggesting using WE_Mode = 0 in DISCON.IN or increasing sampling rate of simulation
+* You must have a compiled controller in ROSCO/rosco/lib/, and properly point to it using the `lib_name` variable.
+* Using wind speed estimators in this simple simulation is known to cause problems. We suggest using WE_Mode = 0 in the DISCON.IN or increasing sampling rate of simulation as workarounds.
+* The simple simulation is run twice to check that arrays are deallocated properly.
+
 """
 # Python modules
 import matplotlib.pyplot as plt 
@@ -46,7 +53,6 @@ def main():
     # # Load turbine model from saved pickle
     turbine         = ROSCO_turbine.Turbine
     turbine         = turbine.load(os.path.join(example_out_dir,'01_NREL5MW_saved.p'))
-    # controller      = ROSCO_controller.Controller(controller_params)
 
     # Load turbine data from OpenFAST and rotor performance text file
     cp_filename = os.path.join(tune_dir,path_params['rotor_performance_filename'])
@@ -101,8 +107,8 @@ def main():
     if False:
         plt.show()
     else:
-        plt.savefig(os.path.join(example_out_dir,'04_NREL5MW_SimpSim.png'))
+        plt.savefig(os.path.join(example_out_dir,'04_NREL5MW_SimpSim.png'), bbox_inches='tight')
 
-if __name__=='__main__':
+if __name__ == "__main__":
     main()
 
@@ -1,7 +1,7 @@
 """
 05_openfast_sim
 ---------------
-Load a turbine, tune a controller, run OpenFAST simulation 
+Load a turbine, tune a controller, and run an OpenFAST simulation.
 In this example:
 
 * Load a turbine from OpenFAST
@@ -10,15 +10,11 @@
 
 Note
 
-* you will need to have a compiled controller in ROSCO/build/ 
+* You must have a compiled controller in ROSCO/rosco/lib/
 """
 
-# Python Modules
-#import yaml
+
 import os
-#import numpy as np
-#import matplotlib.pyplot as plt
-# ROSCO toolbox modules 
 from rosco.toolbox import controller as ROSCO_controller
 from rosco.toolbox import turbine as ROSCO_turbine
 from rosco.toolbox.utilities import write_DISCON, run_openfast
@@ -56,7 +52,7 @@ def main():
     controller.tune_controller(turbine)
 
     # Write parameter input file
-    param_file = os.path.join(this_dir,'DISCON.IN')   # This must be named DISCON.IN to be seen by the compiled controller binary. 
+    param_file = os.path.join(this_dir,'DISCON.IN') 
     write_DISCON(turbine,controller,param_file=param_file, txt_filename=path_params['rotor_performance_filename'])
 
     # Run OpenFAST
@@ -71,4 +67,4 @@ def main():
     )
 
 if __name__ == "__main__":
-    main()
+    main()
@@ -1,15 +1,33 @@
 """
-06_peak_shavings
+06_peak_shaving
 ----------------
-Load saved turbine, tune controller, plot minimum pitch schedule
-In this example:
 
-* Load a yaml file
-* Load a turbine from openfast
-* Tune a controller
-* Plot minimum pitch schedule
+This example demonstrates the minimum pitch schedule of the NREL 5MW RWT.
+In the ROSCO controller, the minimum pitch is determined from a lookup table from the (estimated) wind speed to the limit.
+The ROSCO DISCON controller only has PS_Mode of 0 (disable) or 1 (enabled).
+
+When creating a DISCON using the ROSCO toolbox, a few more options are available.
+For PS_Mode = 1, the minimum pitch limit is calculated to limit the maximum thrust to a fraction of the un-limited maximum thrust, computed from the rotor's Ct table.
+The ``ps_percent`` input (to the tuning yaml) is the fraction of the allowed thrust to the maximum, un-limited thrust.
+For example, if the maximum thrust is 1e5 N, and we want to limite the maximum thrust to 8e4 N, ``ps_percent`` = 0.8.
+Note that "percent" is a bit of a misnomer.
+
+For PS_Mode = 2, the minimum pitch limit is calculated to maximize the Cp surface in below rated; this usually results in a non-zero pitch at low wind speeds.  
+For large rotors, sometimes a minimum rotor speed is enforced to avoid resonance between the rotor period and the tower natural frequency; this results in a non-constant TSR across the below-rated operating points.
+In this case, different pitch angles will be required to maximize Cp.
+
+For PS_Mode = 3, both the thrust limiting and the power maximizing tuning routines determine the minimum pitch limit.
+This example demonstrates PS_Mode = 3 as follows, compared to the steady state blade pitch operating points of the turbine.
+The ROSCO toolbox uses Cp and Ct tables to compute these inputs to the ROSCO controller.
+
+.. figure:: /source/figures/06_MinPitch.png
+   :align: center
+   :width: 70%
+
 """
 
+# Figure copy: cp ../Examples/examples_out/06_MinPitch.png source/figures/
+
 # Python modules
 import matplotlib.pyplot as plt 
 import os
 
@@ -1,14 +1,14 @@
 """
 07_openfast_outputs
 -------------------
-Plot some OpenFAST output data
-In this example:
+Demonstrate the ROSCO routines for reading OpenFAST I/O files.
+Nearly all the figures in the example documentation rely on a version of these scripts, which can also be used to load ROSCO *.dbg* files, including
 
-* Load openfast output data
-* Trim the time series
-* Plot some available channels
+ # .dbg files output basic ROSCO internal variables, like the inputs and outputs to the wind speed estimator
+ # .dbg2 files output all the ROSCO LocalVariables.  If the variable is an array, only the first entry is recorded.
+ # .dbg3 files output the avrSWAP array at each timestep that is transfered between ROSCO and the multi-physics solver
 
-Note: need to run openfast model in 'Test_Cases/5MW_Land_DLL_WTurb/' to plot
+Note: this example relies on the previous running of the OpenFAST model in 'Test_Cases/NREL-5MW/' to plot.
 """
 
 # Python Modules
-Original file line number
+Diff line change
 # Binaries
 *.dylib
 *.so
 -*.dll
 +*.dll.*
 *.bts
 # Other