Revise documentation

docs/source/rosco.rst

@@ -9,7 +9,7 @@ Here, we give an overview of the structure of the ROSCO controller and how the c
 -----
 
 File Structure
----------------
+--------------
 The primary functions of the ROSCO toolbox are separated into several files. They include the following:
 
     * :code:`DISCON.f90` is the primary driver function. 
@@ -19,12 +19,15 @@ The primary functions of the ROSCO toolbox are separated into several files. The
     * :code:`Controllers.f90` contains the primary controller algorithms (e.g. blade pitch control)
     * :code:`ControllerBlocks.f90` contains additional control features that are not necessarily primary controllers (e.g. wind speed estimator)
     * :code:`Filters.f90` contains the various filter implementations.
+    * :code:`Functions.f90` contains various functions used in the controller.
 
 .. _discon_in: 
 
 The DISCON.IN file
 ------------------------------
-A standard file structure is used as an input to the ROSCO controller. This is, generically, dubbed the DISCON.IN file, though it can be renamed (In OpenFAST_, this file is pointed to by :code:`DLL_InFile` in the ServoDyn file. Examples of the DISCON.IN file are found in each of the Test Cases in the ROSCO toolbox, and in the :code:`parameter_files` folder of ROSCO. 
+A standard file structure is used as an input to the ROSCO controller. 
+This is, generically, dubbed the DISCON.IN file, though it can be renamed (In OpenFAST_, this file is pointed to by :code:`DLL_InFile` in the ServoDyn file. 
+Examples of the DISCON.IN file are found in each of the Test Cases in the ROSCO toolbox, and in the :code:`parameter_files` folder of ROSCO. 
 
 .. list-table:: DISCON.IN 
   :header-rows: 1
@@ -74,7 +77,7 @@ A standard file structure is used as an input to the ROSCO controller. This is,
   * -
     - :code:`PS_Mode`
     - Int
-    - Pitch saturation mode. 0: no pitch saturation, 1: implement pitch saturation}
+    - Pitch saturation mode. 0: no pitch saturation, 1: implement pitch saturation
   * -
     - :code:`SD_Mode`
     - Int 

docs/source/rosco_toolbox.rst

@@ -25,7 +25,7 @@ The source code for the ROSCO toolbox generic tuning implementations lives here.
 
 *Examples*
 ..........
-A number of examples are included to showcase the numerous capabilities of the ROSCO toolbox
+A number of examples are included to showcase the numerous capabilities of the ROSCO toolbox; they are described in the :ref:`standard_use`.
 
 *Matlab_Toolbox*
 ................
@@ -37,7 +37,7 @@ Testing scripts for the ROSCO toolbox are held here and showcased with :code:`ru
 
 *Test_Cases*
 ............
-Example OpenFAST models consistent with OpenFAST's master branch are provided here for simple testing and simulation cases.
+Example OpenFAST models consistent with the latest release of OpenFAST are provided here for simple testing and simulation cases.
 
 *Tune_Cases*
 ............
@@ -113,7 +113,7 @@ A yaml_ formatted input file is used for the standard ROSCO toolbox tuning proce
     - :code:`bld_edgewise_freq`
     - Yes
     - Float
-    - Blade edgewise first natural frequency [rad/s]. 
+    - Blade edgewise first natural frequency [rad/s].  Set this even if you are using stiff blades. It becomes the generator speed LPF bandwidth.
   * - 
     - :code:`TSR_operational`
     - No

docs/source/standard_use.rst

@@ -11,14 +11,15 @@ A set of `example scripts <https://github.com/NREL/ROSCO_toolbox/tree/main/Examp
 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:`ROSCO_turbine` object in python.
+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_toolbox/tree/main/Test_Cases>`_.
-The controller tuning .yaml are located in `Tune_Cases/ <https://github.com/NREL/ROSCO_toolbox/tree/main/Tune_Cases>`_; a detailed description of these parameters is located here. **TODO: add link**
+The controller tuning :code:`.yaml` are located in `Tune_Cases/ <https://github.com/NREL/ROSCO_toolbox/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:`example_01.py` loads an OpenFAST turbine model and displays a summary of its information
-* :code:`example_02.py` plots the C_p surface of a turbine
+* :code:`example_02.py` plots the :math:`C_p` surface of a turbine
 
-ROSCO requires the power and thrust coefficients for tuning control parameters and running the extended Kalman filter wind speed estimator.
+ROSCO requires the power and thrust coefficients for tuning control inputs and running the extended Kalman filter wind speed estimator.
 
 * :code:`example_03.py` runs cc-blade, a blade element momentum solver from WISDEM, to generate a :math:`C_p` surface.
 
@@ -28,27 +29,31 @@ This file can be located wherever you desire, just be sure to point to it proper
 
 Tuning Controllers and Generating DISCON.IN
 -------------------------------------------
-The ROSCO_turbine object, which contains turbine information required for controller tuning, along with control parameters in the tuning yaml and the Cp surface are used to generate control parameters and DISCON.IN files.
+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 increase loading on the turbine.
+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_toolbox/tree/main/Tune_Cases>`_ are known to work well with the turbines in this repository.
 
 * :code:`example_04.py` loads a turbine and tunes the PI control gains
 * :code:`example_05.py` tunes a controller and runs a simple simualtion (not using OpenFAST)
-* :code:`example_06.py` loads a turbine, tunes a controller, and runs an OpenFAST simulations
+* :code:`example_06.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::
+
+  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:`example_07.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):
+ROSCO also contains a method for distributed aerodynamic control (e.g., via trailing edge flaps):
 
 * :code:`example_10.py` tunes a controller for distributed aerodynamic control
 
@@ -69,14 +74,10 @@ If called from OpenFAST, the main OpenFAST input points to the ServoDyn input, w
 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 "../../ROSCO/build/libdiscon.dylib" as the :code:`DLL_FileName` input and :code:`"DISCON.IN"` as the :code:`DLL_InFile` 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
 
-OpenFAST can be installed from `source <https://github.com/OpenFAST/openfast>`_ or from conda using::
-
-  conda install -c conda-forge openfast
-
 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_toolbox/tree/develop/ROSCO_toolbox/ofTools>`_.
 For more extensive post-processing tools, please see pCrunch (link).