Update v2.9.0 documentation (#303)

* Finalize v2.9.0 documentation

* Add ruamel.yaml as a requirement in pyproject.toml

* Re-add wisdem in pyproject.toml

* Revise docs slightly

* Add developer documentation

* Fix small typo with documentation

---------

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

.readthedocs.yaml

@@ -9,10 +9,10 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
-    # nodejs: "18"
-    # rust: "1.64"
-    # golang: "1.19"
+    python: "mambaforge-22.9"
+
+conda:
+  environment: environment.yml
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

docs/conf.py

@@ -52,6 +52,7 @@ def __getattr__(cls, name):
     "sphinx.ext.intersphinx",
     "sphinx.ext.graphviz",
     "sphinx.ext.autosectionlabel",
+    "sphinx_rtd_theme",
     # "sphinxcontrib.bibtex",
 ]
 
@@ -84,7 +85,7 @@ def __getattr__(cls, name):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/index.rst

@@ -3,54 +3,39 @@ ROSCO Documentation
 :Version: |release|
 :Date: |today|
 
-NREL's Reference OpenSource Controller (ROSCO) tool-set for wind turbine applications designed to ease controller implementation for the wind turbine researcher. The purpose of these documents is to provide information for the use of the tool-set. 
+NREL's "Reference Open Source Controller" (ROSCO) is a reference controller framework that facilitates design and implementation of wind turbine and wind farm controllers for fixed and floating offshore wind turbines.
 
-:numref:`fig-RT` shows the general workflow for the ROSCO tool-chain. with OpenFAST
+ROSCO frameworks includes a large set of available controllers and advanced functionalities that can be combined in a modular fashion based on the intended application and can be easily adapted to a wide variety wind turbines.
+For example, ROSCO can be used to design turbine yaw controller along with an individual blade pitch controller with floating platform feedback for an offshore turbine while simulating a pitch actuator fault and running a user-defined torque controller.
 
-.. _fig-RT:
-.. figure:: /source/figures/ROSCO_toolbox.svg
-   :align: center
-   :width: 80%
+ROSCO provides a single framework for designing controllers for onshore and offshore turbines of varying sizes.
+It can be used to run representative dynamic simulations using OpenFAST.
+This helps researchers perform 'apples-to-apples' comparison of controller capabilities across turbines.
+Control engineers can also design their own controllers and compare them with reference controller design using ROSCO for existing and new turbines.
+ROSCO has been used to provide reference controllers for many recent reference turbines including the `IEA 3.4-MW <https://github.com/IEAWindTask37/IEA-3.4-130-RWT>`_ , `IEA 10-MW <https://github.com/IEAWindTask37/IEA-10.0-198-RWT>`_ , `IEA 15-MW <https://github.com/IEAWindTask37/IEA-15-240-RWT>`_ and the upcoming `IEA 22-MW <https://github.com/IEAWindTask37/IEA-22-280-RWT>`_ turbines.
 
-   ROSCO toolchain general workflow
+The ROSCO framework also includes a python based toolbox that primarily enables tuning the controllers.
+The tuning process is extemely simple where only a tuning parameters need to be provided.
+It is not necessary to run aeroelastic simulations or provide linearized state-space models to tune the controller to tune the controllers.
+The toolbox has other capabilities like simple 1-DOF turbine simulations for quick controller capability verifications, linear model analysis, and parsing of input and output files.
 
+Source code for ROSCO toolset can be found in this `github repository <https://github.com/NREL/ROSCO>`_ and it can be installed following the instructions provided in :ref:`install`.
 
-**ROSCO Toolbox**
-The python-based toolbox primarily used for tuning the controller and writing the DISCON.IN. 
+**Documentation Directory**
 
-* Generic tuning of NREL's ROSCO controller
-* Simple 1-DOF turbine simulations for quick controller capability verifications
-* Parsing of OpenFAST input and output files
-* Linear model analysis capability
-
-**ROSCO Controller**
-The controller implementation itself. This is compiled to :code:`libdiscon.*` file, reads the DISCON.IN file, and interfaces with OpenFAST using the Bladed-style interface. 
-
-* Fortran based
-* Follows Bladed-style control interface
-* Modular
-
-Standard Use
-------------
-
-For the standard use case in OpenFAST (or similar), ROSCO will need to be compiled. This is made possible via the instructions found in :ref:`install`. Once the controller is compiled, the turbine model needs to point to the compiled binary. In OpenFAST, this is ensured by changing the :code:`DLL_FileName` parameter in the ServoDyn input file. 
-
-Additionally, an additional input file is needed for the ROSCO controller. Though the controller only needs to be compiled once, each individual turbine/controller tuning requires an input file. This input file is generically dubbed "DISCON.IN''. In OpenFAST, the :code:`DLL_InFile` parameter should be set to point to the desired input file. The ROSCO toolbox is used to automatically generate the input file. These instructions are provided in the instructions for :ref:`standard_use`.
-
-Technical Documentation
------------------------
-A publication highlighting much of the theory behind the controller tuning and implementation methods can be found at:
-https://wes.copernicus.org/preprints/wes-2021-19/
-
-Survey
-------
-Please help us better understand the ROSCO user-base and how we can improve ROSCO through this brief survey:
-
-.. raw:: html
-
-   <iframe width="640px" height= "480px" src= "https://forms.office.com/Pages/ResponsePage.aspx?id=fp3yoM0oVE-EQniFrufAgGWnC45k8q5Kl90RBkHijqBUN0JTNzBJT1QwMjIzNDhCWDlDTUZPWDdMWC4u&embed=true" frameborder= "0" marginwidth= "0" marginheight= "0" style= "border: none; max-width:100%; max-height:100vh" allowfullscreen webkitallowfullscreen mozallowfullscreen msallowfullscreen> </iframe>
+.. toctree::
+   :maxdepth: 3
+   :numbered:
 
-
+   source/standard_use.rst
+   source/install.rst
+   source/examples.rst
+   source/rosco.rst
+   source/rosco_toolbox.rst
+   source/api_change.rst
+   source/toolbox_input.rst
+   source/how_to_contribute_code.rst
+   source/ROSCO_instructions_for_Bladed.rst
 
 License
 -------
@@ -67,15 +52,3 @@ distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-
-.. toctree::
-   :maxdepth: 3
-   :numbered:
-
-   source/install.rst
-   source/standard_use.rst
-   source/rosco_toolbox.rst
-   source/rosco.rst
-   source/api_change.rst
-   source/toolbox_input.rst
-   source/ROSCO_instructions_for_Bladed.rst

docs/requirements.txt

@@ -1,4 +1,4 @@
 # File: docs/requirements.txt
 
 sphinx>4.0.0
-furo
+sphinx_rtd_theme

docs/source/api_change.rst

@@ -42,7 +42,7 @@ Thus, be sure to implement each in order so that subsequent line numbers are cor
 
 *  Each turbine is assigned a `ZMQ_ID` by the controller, which is tracked by a farm-level controller
 
-**Tower resonance avoidance
+**Tower resonance avoidance**
 
 *  When `TRA_Mode` is 1, change the torque control generator speed setpoint to avoid TRA_ExclSpeed +/- TRA_ExclBand.
 *  The set point is changed at a slow rate `TRA_RateLimit` to avoid generator power spikes.  `VS_RefSpd`/100 is recommended.
@@ -89,7 +89,7 @@ Line    Input Name                 Example Value
 161     Ind_Azimuth               0           ! Ind_Azimuth   - The column in OL_Filename that contains the desired azimuth position in rad (used if OL_Mode = 2)
 162     RP_Gains                  0.0000 0.0000 0.0000 0.0000     ! RP_Gains - PID gains and Tf of derivative for rotor position control (used if OL_Mode = 2)
 186     ZMQ_ID                    0     ! ZMQ_ID - Integer identifier of turbine
-====== =================          ======================================================================================================================================================================================================
+====== =======================    ===============================================================================================================================================================================================================================================================
 
 ====== =================    ======================================================================================================================================================================================================
 Changed in ROSCO develop

docs/source/examples.rst

@@ -0,0 +1,100 @@
+
+.. toctree::
+
+.. _examplepage:
+
+ROSCO Examples
+==============
+Methods for reading turbine models, generating the control parameters of a :code:`DISCON.IN`: file, and running aeroelastic simulations to test controllers
+Reading Turbine Models
+----------------------
+Control parameters depend on the turbine model.
+The rosco.toolbox uses OpenFAST inputs and an additional :code:`.yaml` formatted file to set up a :code:`turbine` object in python.
+Several OpenFAST inputs are located in `Test_Cases/ <https://github.com/NREL/ROSCO/tree/main/Test_Cases>`_.
+The controller tuning :code:`.yaml` are located in `Tune_Cases/ <https://github.com/NREL/ROSCO/tree/main/Tune_Cases>`_.
+A detailed description of the ROSCO control inputs and tuning :code:`.yaml` are provided in :ref:`discon_in` and :ref:`rt_tuning_yaml`, respectively.
+
+* :code:`01_turbine_model.py` loads an OpenFAST turbine model and displays a summary of its information
+
+ROSCO requires the power and thrust coefficients for tuning control inputs and running the extended Kalman filter wind speed estimator.
+
+* :code:`02_ccblade.py` runs cc-blade, a blade element momentum solver from WISDEM, to generate a :math:`C_p` surface.
+
+The :code:`Cp_Cq_Ct.txt` (or similar) file contains the rotor performance tables that are necessary to run the ROSCO controller. 
+This file can be located wherever you desire, just be sure to point to it properly with the :code:`PerfFileName` parameter in :code:`DISCON.IN`.
+
+
+Tuning Controllers and Generating DISCON.IN
+-------------------------------------------
+The ROSCO :code:`turbine` object, which contains turbine information required for controller tuning, along with control parameters in the tuning yaml and the :math:`C_p` surface are used to generate control parameters and :code:`DISCON.IN` files.
+To tune the PI gains of the torque control, set :code:`omega_vs` and :code:`zeta_vs` in the yaml.
+Similarly, set :code:`omega_pc` and :code:`zeta_pc` to tune the PI pitch controller; gain scheduling is automatically handled using turbine information.
+Generally :code:`omega_*` increases the responsiveness of the controller, reducing generator speed variations, but an also increases loading on the turbine.
+:code:`zeta_*` changes the damping of the controller and is generally less important of a tuning parameter, but could also help with loading.
+The default parameters in `Tune_Cases/ <https://github.com/NREL/ROSCO/tree/main/Tune_Cases>`_ are known to work well with the turbines in this repository.
+
+* :code:`03_tune_controller.py` loads a turbine and tunes the PI control gains
+* :code:`04_simple_sim.py` tunes a controller and runs a simple simualtion (not using OpenFAST)
+* :code:`05_openfast_sim.py` loads a turbine, tunes a controller, and runs an OpenFAST simulation
+
+Each of these examples generates a :code:`DISCON.IN` file, which is an input to libdiscon.*.
+When running the controller in OpenFAST, :code:`DISCON.IN` must be appropriately named using the :code:`DLL_FileName` parameter in ServoDyn. 
+
+OpenFAST can be installed from `source <https://github.com/OpenFAST/openfast>`_ or in a conda environment using:
+
+.. code-block:: bash
+
+  conda install -c conda-forge openfast
+
+ROSCO can implement peak shaving (or thrust clipping) by changing the minimum pitch angle based on the estimated wind speed:
+
+* :code:`06_peak_shaving.py` loads a turbine and tunes a controller with peak shaving.
+
+By setting the :code:`ps_percent` value in the tuning yaml, the minimum pitch versus wind speed table changes and is updated in the :code:`DISCON.IN` file.
+
+ROSCO also contains a method for distributed aerodynamic control (e.g., via trailing edge flaps):
+
+* :code:`09_distributed_aero.py` tunes a controller for distributed aerodynamic control
+
+The ROSCO toolbox also contains methods for working with OpenFAST linear models
+* :code:`10_linear_params.py` exports a file of the parameters used for the simplified linear models used to tune ROSCO
+* :code:`11_robust_tuning.py` shows how linear models generated using OpenFAST can be used to tune controllers with robust stability properties. 
+* :code:`12_tune_ipc.py` shows the tuning procedure for IPC
+
+Running OpenFAST Simulations
+----------------------------
+
+To run an aeroelastic simulation with ROSCO, the ROSCO input (:code:`DISCON.IN`) must point to a properly formatted :code:`Cp_Cq_Ct.txt` file using the :code:`PerfFileName` parameter.
+If called from OpenFAST, the main OpenFAST input points to the ServoDyn input, which points to the :code:`DISCON.IN` file and the :code:`libdiscon.*` dynamic library.
+
+For example in `Test_Cases/NREL-5MW`:
+
+* :code:`NREL-5MW.fst` has :code:`"NRELOffshrBsline5MW_Onshore_ServoDyn.dat"`  as the :code:`ServoFile` input
+* :code:`NRELOffshrBsline5MW_Onshore_ServoDyn.dat` has :code:`"../../ROSCO/build/libdiscon.dylib"` as the :code:`DLL_FileName` input and :code:`"DISCON.IN"` as the :code:`DLL_InFile` input.
+  Note that these file paths are relative to the path of the main fast input (:code:`NREL-5MW.fst`)
+* :code:`DISCON.IN` has :code:`"Cp_Ct_Cq.NREL5MW.txt"` as the :code:`PerfFileName` input
+
+The rosco.toolbox has methods for running OpenFAST (and other) binary executables using system calls, as well as post-processing tools in `ofTools/ <https://github.com/NREL/ROSCO/tree/main/rosco.toolbox/ofTools>`_.
+
+Several example scripts are set up to quickly simulate ROSCO with OpenFAST:
+
+* :code:`05_openfast_sim.py` loads a turbine, tunes a controller, and runs an OpenFAST simulation
+* :code:`07_openfast_outputs.py` loads the OpenFAST output files and plots the results
+* :code:`08_run_turbsim.py` runs TurbSim, for generating turbulent wind inputs
+* :code:`14_open_loop_control.py` runs an OpenFAST simulation with ROSCO providing open loop control inputs
+
+
+Testing ROSCO
+-------------
+
+The rosco.toolbox also contains tools for testing ROSCO in IEC design load cases (DLCs), located in `ROSCO_testing/ <https://github.com/NREL/ROSCO/tree/main/ROSCO_testing>`_.
+The script :code:`run_Testing.py` allows the user to set up their own set of tests.
+By setting :code:`testtype`, the user can run a variety of tests:
+
+* :code:`lite`, which runs DLC 1.1 simulations at 5 wind speed from cut-in to cut-out, in 330 second simulations
+* :code:`heavy`, which runs DLC 1.3 from cut-in to cut-out in 2 m/s steps and 2 seeds for each, in 630 seconds, as well as DLC 1.4 simulations
+* :code:`binary-comp`, where the user can compare :code:`libdiscon.*` dynamic libraries (compiled ROSCO source code), with either a lite or heavy set of simulations
+* :code:`discon-comp`, where the user can compare :code:`DISCON.IN` controller tunings (and the complied ROSCO source is constant)
+
+Setting the :code:`turbine2test` allows the user to test either the IEA-15MW with the UMaine floating semisubmersible or the NREL-5MW reference onshore turbine.
+