Docs (#368)

* Update .readthedocs.yaml

* Docs: Fix small bug in docs that caused errors with links

* Start using automatic documentation for examples (#371)

* Added autodocumentation template for all examples

* Add a note about building docs

* Fix global variables in Example 17a and 17b

* Try numpy<2.0

---------

Co-authored-by: AbhineetGupta <abhineet.gupta@nrel.gov>

Examples/01_turbine_model.py

@@ -1,16 +1,16 @@
-'''
------------ 01_turbine_model --------------
-Load and save a turbine model
--------------------------------------
-In this example:
-- Read .yaml input file
-- Load an openfast turbine model
-- Read text file with rotor performance properties
-- Print some basic turbine properties
-- Save the turbine as a picklle
+"""
+01_turbine_model
+----------------
+Load and save a turbine model.
+
+* Read .yaml input file
+* Load an openfast turbine model
+* Read text file with rotor performance properties
+* Print some basic turbine properties
+* Save the turbine as a picklle
 
 Note: Uses the NREL 5MW included in the Test Cases and is a part of the OpenFAST distribution
-'''
+"""
 
 # Python Modules
 import os
@@ -19,44 +19,48 @@
 from rosco.toolbox.inputs.validation import load_rosco_yaml
 import matplotlib.pyplot as plt
 
+def main():
+    # Load yaml file
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    tune_dir =  os.path.join(this_dir,'Tune_Cases')
+    parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
+    inps = load_rosco_yaml(parameter_filename)
+    path_params         = inps['path_params']
+    turbine_params      = inps['turbine_params']
+
+    # Load turbine data from openfast model
+    turbine = ROSCO_turbine.Turbine(turbine_params)
 
-# Load yaml file
-this_dir = os.path.dirname(os.path.abspath(__file__))
-tune_dir =  os.path.join(this_dir,'Tune_Cases')
-parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
-inps = load_rosco_yaml(parameter_filename)
-path_params         = inps['path_params']
-turbine_params      = inps['turbine_params']
+    turbine.load_from_fast(
+        path_params['FAST_InputFile'],
+        os.path.join(tune_dir,path_params['FAST_directory']),
+        rot_source='txt',txt_filename=os.path.join(tune_dir,path_params['rotor_performance_filename'])
+        )
 
-# Load turbine data from openfast model
-turbine = ROSCO_turbine.Turbine(turbine_params)
+    # Print some basic turbine info
+    print(turbine)
 
-turbine.load_from_fast(
-    path_params['FAST_InputFile'],
-    os.path.join(tune_dir,path_params['FAST_directory']),
-    rot_source='txt',txt_filename=os.path.join(tune_dir,path_params['rotor_performance_filename'])
-    )
+    # Save the turbine model
+    example_out_dir = os.path.join(this_dir,'examples_out')
+    if not os.path.isdir(example_out_dir):
+        os.makedirs(example_out_dir)
 
-# Print some basic turbine info
-print(turbine)
+    turbine.save(os.path.join(example_out_dir,'01_NREL5MW_saved.p'))
 
-# Save the turbine model
-example_out_dir = os.path.join(this_dir,'examples_out')
-if not os.path.isdir(example_out_dir):
-  os.makedirs(example_out_dir)
+    # Now load the turbine and plot the Cp surface
 
-turbine.save(os.path.join(example_out_dir,'01_NREL5MW_saved.p'))
+    # Load quick from python pickle
+    turbine = turbine.load(os.path.join(example_out_dir,'01_NREL5MW_saved.p'))
 
-# Now load the turbine and plot the Cp surface
+    # plot rotor performance 
+    print('Plotting Cp data')
+    turbine.Cp.plot_performance()
 
-# Load quick from python pickle
-turbine = turbine.load(os.path.join(example_out_dir,'01_NREL5MW_saved.p'))
+    if False:
+        plt.show()
+    else:
+        plt.savefig(os.path.join(example_out_dir,'01_NREL5MW_Cp.png'))
 
-# plot rotor performance 
-print('Plotting Cp data')
-turbine.Cp.plot_performance()
 
-if False:
-  plt.show()
-else:
-  plt.savefig(os.path.join(example_out_dir,'01_NREL5MW_Cp.png'))
+if __name__=='__main__':
+  main()

Examples/02_ccblade.py

@@ -1,46 +1,53 @@
-'''
------------ 02_ccblade --------------
-Run CCblade, save a rotor performance text file
--------------------------------------
-
+"""
+02_ccblade
+-------------- 
+Run CCblade, save a rotor performance text file.
 In this example:
-- Read .yaml input file
-- Load an openfast turbine model
-- Run ccblade to get rotor performance properties
-- Write a text file with rotor performance properties
-'''
+
+* Read .yaml input file
+* Load an openfast turbine model
+* Run ccblade to get rotor performance properties
+* Write a text file with rotor performance properties
+"""
+
 # Python modules
 import os 
 # ROSCO toolbox modules 
 from rosco.toolbox import turbine as ROSCO_turbine
 from rosco.toolbox.utilities import write_rotor_performance
 from rosco.toolbox.inputs.validation import load_rosco_yaml
-# Initialize parameter dictionaries
-turbine_params = {}
-control_params = {}
-
-this_dir = os.path.dirname(os.path.abspath(__file__))
-example_out_dir = os.path.join(this_dir,'examples_out')
-if not os.path.isdir(example_out_dir):
-  os.makedirs(example_out_dir)
-
-# Load yaml file
-this_dir = os.path.dirname(os.path.abspath(__file__))
-tune_dir =  os.path.join(this_dir,'Tune_Cases')
-parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
-inps = load_rosco_yaml(parameter_filename)
-path_params         = inps['path_params']
-turbine_params      = inps['turbine_params']
-controller_params   = inps['controller_params']
-
-# Load turbine data from openfast model
-turbine = ROSCO_turbine.Turbine(turbine_params)
-turbine.load_from_fast(
-    path_params['FAST_InputFile'],
-    os.path.join(tune_dir,path_params['FAST_directory']),
-    rot_source='cc-blade',
-    txt_filename=None)
-
-# Write rotor performance text file
-txt_filename = os.path.join(example_out_dir,'02_Cp_Ct_Cq.Ex03.txt')
-write_rotor_performance(turbine,txt_filename=txt_filename)
+
+def main():
+    # Initialize parameter dictionaries
+    turbine_params = {}
+    control_params = {}
+
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    example_out_dir = os.path.join(this_dir,'examples_out')
+    if not os.path.isdir(example_out_dir):
+        os.makedirs(example_out_dir)
+
+    # Load yaml file
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    tune_dir =  os.path.join(this_dir,'Tune_Cases')
+    parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
+    inps = load_rosco_yaml(parameter_filename)
+    path_params         = inps['path_params']
+    turbine_params      = inps['turbine_params']
+    controller_params   = inps['controller_params']
+
+    # Load turbine data from openfast model
+    turbine = ROSCO_turbine.Turbine(turbine_params)
+    turbine.load_from_fast(
+        path_params['FAST_InputFile'],
+        os.path.join(tune_dir,path_params['FAST_directory']),
+        rot_source='cc-blade',
+        txt_filename=None)
+
+    # Write rotor performance text file
+    txt_filename = os.path.join(example_out_dir,'02_Cp_Ct_Cq.Ex03.txt')
+    write_rotor_performance(turbine,txt_filename=txt_filename)
+
+if __name__ == "__main__":
+    main()
+

Examples/03_tune_controller.py

@@ -1,15 +1,16 @@
-'''
------------ 03_tune_controller --------------
+"""
+03_tune_controller
+------------------ 
 Load a turbine model and tune the controller
--------------------------------------
-
 In this example:
-  - Read a .yaml file
-  - Load a turbine model from OpenFAST
-  - Tune a controller
-  - Write a controller input file
-  - Plot gain schedule
-'''
+
+* Read a .yaml file
+* Load a turbine model from OpenFAST
+* Tune a controller
+* Write a controller input file
+* Plot gain schedule
+"""
+
 # Python modules
 import matplotlib.pyplot as plt 
 import os 
@@ -19,62 +20,65 @@
 from rosco.toolbox.utilities import write_DISCON
 from rosco.toolbox.inputs.validation import load_rosco_yaml
 
+def main():
+    # Load yaml file 
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    tune_dir =  os.path.join(this_dir,'Tune_Cases')
+    parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
+    inps = load_rosco_yaml(parameter_filename)
+    path_params         = inps['path_params']
+    turbine_params      = inps['turbine_params']
+    controller_params   = inps['controller_params']
 
-# Load yaml file 
-this_dir = os.path.dirname(os.path.abspath(__file__))
-tune_dir =  os.path.join(this_dir,'Tune_Cases')
-parameter_filename = os.path.join(tune_dir,'NREL5MW.yaml')
-inps = load_rosco_yaml(parameter_filename)
-path_params         = inps['path_params']
-turbine_params      = inps['turbine_params']
-controller_params   = inps['controller_params']
+    # Instantiate turbine, controller, and file processing classes
+    turbine         = ROSCO_turbine.Turbine(turbine_params)
+    controller      = ROSCO_controller.Controller(controller_params)
 
-# Instantiate turbine, controller, and file processing classes
-turbine         = ROSCO_turbine.Turbine(turbine_params)
-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'])
+    turbine.load_from_fast(
+        path_params['FAST_InputFile'],
+        os.path.join(tune_dir,path_params['FAST_directory']),
+        rot_source='txt',txt_filename= cp_filename
+        )
 
-# Load turbine data from OpenFAST and rotor performance text file
-cp_filename = os.path.join(tune_dir,path_params['rotor_performance_filename'])
-turbine.load_from_fast(
-    path_params['FAST_InputFile'],
-    os.path.join(tune_dir,path_params['FAST_directory']),
-    rot_source='txt',txt_filename= cp_filename
-    )
+    # Tune controller 
+    controller.tune_controller(turbine)
 
-# Tune controller 
-controller.tune_controller(turbine)
+    # Write parameter input file
+    param_file = os.path.join(this_dir,'DISCON.IN')
+    write_DISCON(turbine,controller,
+    param_file=param_file, 
+    txt_filename=cp_filename
+    )
 
-# Write parameter input file
-param_file = os.path.join(this_dir,'DISCON.IN')
-write_DISCON(turbine,controller,
-param_file=param_file, 
-txt_filename=cp_filename
-)
+    # Plot gain schedule
+    fig, ax = plt.subplots(2,2,constrained_layout=True,sharex=True)
+    ax = ax.flatten()
+    ax[0].plot(controller.v[len(controller.v_below_rated)+1:], controller.omega_pc_U)
+    ax[0].set_ylabel('omega_pc')
 
-# Plot gain schedule
-fig, ax = plt.subplots(2,2,constrained_layout=True,sharex=True)
-ax = ax.flatten()
-ax[0].plot(controller.v[len(controller.v_below_rated)+1:], controller.omega_pc_U)
-ax[0].set_ylabel('omega_pc')
+    ax[1].plot(controller.v[len(controller.v_below_rated)+1:], controller.zeta_pc_U)
+    ax[1].set_ylabel('zeta_pc')
 
-ax[1].plot(controller.v[len(controller.v_below_rated)+1:], controller.zeta_pc_U)
-ax[1].set_ylabel('zeta_pc')
+    ax[2].plot(controller.v[len(controller.v_below_rated)+1:], controller.pc_gain_schedule.Kp)
+    ax[2].set_xlabel('Wind Speed')
+    ax[2].set_ylabel('Proportional Gain')
 
-ax[2].plot(controller.v[len(controller.v_below_rated)+1:], controller.pc_gain_schedule.Kp)
-ax[2].set_xlabel('Wind Speed')
-ax[2].set_ylabel('Proportional Gain')
+    ax[3].plot(controller.v[len(controller.v_below_rated)+1:], controller.pc_gain_schedule.Ki)
+    ax[3].set_xlabel('Wind Speed')
+    ax[3].set_ylabel('Integral Gain')
 
-ax[3].plot(controller.v[len(controller.v_below_rated)+1:], controller.pc_gain_schedule.Ki)
-ax[3].set_xlabel('Wind Speed')
-ax[3].set_ylabel('Integral Gain')
+    plt.suptitle('Pitch Controller Gains')
 
-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)
 
-example_out_dir = os.path.join(this_dir,'examples_out')
-if not os.path.isdir(example_out_dir):
-  os.makedirs(example_out_dir)
+    if False:
+        plt.show()
+    else:
+        plt.savefig(os.path.join(example_out_dir,'03_GainSched.png'))
 
-if False:
-  plt.show()
-else:
-  plt.savefig(os.path.join(example_out_dir,'03_GainSched.png'))
+if __name__ == "__main__":
+    main()