Merge branch 'f/docs' of https://github.com/NREL/ROSCO_toolbox into f…

…/docs

docs/source/standard_use.rst

@@ -2,16 +2,102 @@
 
 .. _standard_use:
 
-Standard Uses
-=================
-TODO: This needs a lot of expansion
-
-Tuning a Controller
---------------------
-
-.. _generate_discon:
-Generating DISCON.IN
---------------------
-IF you would like to run the generic tuning process for ROSCO, examples are shown in the :code:`Tune_Cases` folder. When you run your own version of :code:`tune_ROSCO.py`, you will have two files that are necessary to run the controller. 
-1. `DISCON.IN` (or similar) - the input file to `libdiscon.*`. When running the controller in OpenFAST, `DISCON.IN` must be appropriately pointed to by the `DLL_FileName` parameter in ServoDyn. 
-2. `Cp_Cq_Ct.txt` (or similar) - This file contains rotor performance tables that are necessary to run the wind speed estimators in ROSCO. This can live wherever you desire, just be sure to point to it properly with the `PerfFileName` parameter in `DISCON.IN`.
+Standard ROSCO Workflow
+=======================
+This page outlines methods for reading turbine models, generating the control parameters of a :code:`DISCON.IN`: file, and running aeroelastic simulations to test controllers.
+A set of `example scripts <https://github.com/NREL/ROSCO_toolbox/tree/main/Examples>`_ demonstrate the functionality of ROSCO_toolbox and ROSCO controller.
+
+
+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.
+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**
+
+* :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
+
+ROSCO requires the power and thrust coefficients for tuning control parameters 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.
+
+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_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.
+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.
+: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
+
+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. 
+
+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):
+
+* :code:`example_10.py` tunes a controller for distributed aerodynamic control
+
+.. This was incorported into the above
+.. .. _generate_discon:
+.. Generating DISCON.IN
+.. --------------------
+.. IF you would like to run the generic tuning process for ROSCO, examples are shown in the :code:`Tune_Cases` folder. When you run your own version of :code:`tune_ROSCO.py`, you will have two files that are necessary to run the controller. 
+.. 1. `DISCON.IN` (or similar) - the input file to `libdiscon.*`. When running the controller in OpenFAST, `DISCON.IN` must be appropriately pointed to by the `DLL_FileName` parameter in ServoDyn. 
+.. 2. `Cp_Cq_Ct.txt` (or similar) - This file contains rotor performance tables that are necessary to run the wind speed estimators in ROSCO. This can live wherever you desire, just be sure to point to it properly with the `PerfFileName` parameter in `DISCON.IN`.
+
+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 "../../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).
+
+Several example scripts are set up to quickly simulate ROSCO with OpenFAST:
+
+* :code:`example_06.py` loads a turbine, tunes a controller, and runs an OpenFAST simulation
+* :code:`example_08.py` loads the OpenFAST output files and plots the results
+* :code:`example_09.py` runs TurbSim, for generating turbulent wind 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_toolbox/tree/develop/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.
+