Add more input file comments

examples/inputs/gch.yaml

@@ -1,17 +1,17 @@
 
 ###
 # A name for this input file.
-# This is not currently used in FLORIS and is only for the user's reference.
+# This is not currently only for the user's reference.
 name: GCH
 
 ###
 # A description of the contents of this input file.
-# This is not currently used in FLORIS and is only for the user's reference.
+# This is not currently only for the user's reference.
 description: Three turbines using Gauss Curl Hybrid model
 
 ###
 # The earliest verion of FLORIS this input file supports.
-# This is not currently used in FLORIS and is only for the user's reference.
+# This is not currently only for the user's reference.
 floris_version: v3.0.0
 
 ###
@@ -34,6 +34,7 @@ logging:
   ###
   # Settings for logging to a file.
   file:
+
     ###
     # Can be "true" or "false".
     enable: false
@@ -43,44 +44,140 @@ logging:
     # Can be one of "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG".
     level: WARNING
 
+###
+# Configure the solver for the type of simulation.
 solver:
+
+  ###
+  # Select the solver type.
+  # Can be one of: "turbine_grid", "flow_field_grid", "flow_field_planar_grid".
   type: turbine_grid
+
+  ###
+  # Options for the turbine type selected above. See the solver documentation for available parameters.
   turbine_grid_points: 3
 
+###
+# Configure the turbine types and their placement within the wind farm.
 farm:
+
+  ###
+  # Coordinates for the turbine locations in the x-direction which is typically considered
+  # to be the streamwise direction (left, right) when the wind is out of the west.
+  # The order of the coordinates here corresponds to the index of the turbine in the primary
+  # data structures.
   layout_x:
   - 0.0
   - 630.0
   - 1260.0
+
+  ###
+  # Coordinates for the turbine locations in the y-direction which is typically considered
+  # to be the spanwise direction (up, down) when the wind is out of the west.
+  # The order of the coordinates here corresponds to the index of the turbine in the primary
+  # data structures.
   layout_y:
   - 0.0
   - 0.0
   - 0.0
+
+  ###
+  # Listing of turbine types for placement at the x and y coordinates given above.
+  # The list length must be 1 or the same as layout_x and layout_y. If it is a
+  # single value, all turbines are of the same type. Otherwise, the turbine type
+  # is mapped to the location at the same index in layout_x and layout_y.
+  # The types can be either a name included in the turbine_library or
+  # a full definition of a wind turbine directly.
   turbine_type:
   - nrel_5MW
 
+###
+# Configure the atmospheric conditions.
 flow_field:
+
+  ###
+  # Air density.
   air_density: 1.225
-  reference_wind_height: -1 # -1 is code for use the hub height
+
+  ###
+  # The height to consider the "center" of the vertical wind speed profile
+  # due to shear. With a shear exponent not 1, the wind speed at this height
+  # will be the value given in ``wind_speeds``. Above and below this height,
+  # the wind speed will change according to the shear profile; see
+  # :py:meth:`floris.simulation.flow_field.FlowField.initialize_velocity_field`.
+  # For farms consisting of one wind turbine type, use "reference_wind_height: -1"
+  # to use the hub height of the wind turbine definition. For multiple wind turbine
+  # types, the reference wind height must be given explicitly.
+  reference_wind_height: -1
+
+  ###
+  # The level of turbulence intensity level in the wind.
   turbulence_intensity: 0.06
+
+  ###
+  # The wind directions to include in the simulation.
+  # 0 is north and 270 is west.
   wind_directions:
   - 270.0
+
+  ###
+  # The exponent used to model the wind shear profile; see
+  # :py:meth:`floris.simulation.flow_field.FlowField.initialize_velocity_field`.
   wind_shear: 0.12
+
+  ###
+  # The wind speeds to include in the simulation.
   wind_speeds:
   - 8.0
+
+  ###
+  # The wind veer as a constant value for all points in the grid.
   wind_veer: 0.0
 
+###
+# Configure the wake model.
 wake:
+
+  ###
+  # Select the models to use for the simulation. 
+  # See :py:mod:`floris.simulation.wake` for a list
+  # of available models and their descriptions.
   model_strings:
+
+    ###
+    # Select the wake combination model.
     combination_model: sosfs
+
+    ###
+    # Select the wake deflection model.
     deflection_model: gauss
+
+    ###
+    # Select the wake turbulence model.
     turbulence_model: crespo_hernandez
+
+    ###
+    # Select the wake velocity deficit model.
     velocity_model: gauss
 
+  ###
+  # Can be "true" or "false".
   enable_secondary_steering: true
+
+  ###
+  # Can be "true" or "false".
   enable_yaw_added_recovery: true
+
+  ###
+  # Can be "true" or "false".
   enable_transverse_velocities: true
 
+  ###
+  # Configure the parameters for the wake deflection model
+  # selected above.
+  # Additional blocks can be provided for
+  # models that are not enabled, but the enabled model
+  # must have a corresponding parameter block.
   wake_deflection_parameters:
     gauss:
       ad: 0.0
@@ -95,6 +192,12 @@ wake:
       bd: 0.0
       kd: 0.05
 
+  ###
+  # Configure the parameters for the wake velocity deficit model
+  # selected above.
+  # Additional blocks can be provided for
+  # models that are not enabled, but the enabled model
+  # must have a corresponding parameter block.
   wake_velocity_parameters:
     cc:
       a_s: 0.179367259
@@ -113,6 +216,12 @@ wake:
     jensen:
       we: 0.05
 
+  ###
+  # Configure the parameters for the wake turbulence model
+  # selected above.
+  # Additional blocks can be provided for
+  # models that are not enabled, but the enabled model
+  # must have a corresponding parameter block.
   wake_turbulence_parameters:
     crespo_hernandez:
       initial: 0.1