Clean up gitignore and consolidate examples documentation

.gitignore

@@ -1,78 +1,114 @@
-# Gitignore file
+# =============================================================================
+# Python
+# =============================================================================
 *.pyc
-*.log
-*.egg-info
-data.db
+__pycache__/
+*.egg-info/
 *.python-version
-*.DS_Store
-*.conda
-*.sqlite
-slices
 
-# macOS files
+# =============================================================================
+# macOS
+# =============================================================================
 .DS_Store
+__MACOSX/
 
-# ide settings and files
-.idea
-.vscode
+# =============================================================================
+# IDE/Editor Settings
+# =============================================================================
+.idea/
+.vscode/
+.cursor/rules/
 
-# Some c++ stuff
-a.out
-*.plist
-test_client.dSYM
+# =============================================================================
+# Jupyter Notebooks
+# =============================================================================
 *checkpoint.ipynb
-hercules/sampling00000.nc
-hercules/front_end.db
-hercules/control_center.db
-hercules/test_client_cpp/test_client
-hercules/df_flow.p
-hercules/flow_data.p
-
-t_*.txt
-hercules/sample_copy.nc
-hercules/t_0*
-hercules/local_amr_wind_demo/sample_copy.nc
+*.nbconvert.ipynb
+.ipynb_checkpoints/
 
-#Ignore csv files
+# =============================================================================
+# Data Files (large/generated)
+# =============================================================================
+# CSV files (except test inputs)
 *.csv
 !tests/test_inputs/*.csv
-!example_case_folders/00_wind_farm_only/inputs/floris_standin_data.csv
-!example_case_folders/00_wind_farm_only/inputs/wind_power_reference_data.csv
 
-# h5 files
+# Binary data formats
 *.h5
 *.hdf5
+*.feather
+*.ftr
+*.parquet
 
-# Larger wind input file
-wind_resource_rex
+# Pickle files (generated input data)
+*.p
+*.pkl
 
-# Wind input pickle files
-wind_input.p
+# Large wind resource data
+wind_resource_rex/
 
-# Solar input pickle files
-solar_input.p
+# =============================================================================
+# Hercules Simulation Outputs
+# =============================================================================
+# Output directories contain generated results
+outputs/
 
-# Intermediate notebook files
-*.nbconvert.ipynb
-*.ipynb_checkpoints
+# Log files (generated during simulation)
+*.log
 
-# Some output files to ignore
+# H_dict echo files (simulation state dumps)
+*.echo
+
+# =============================================================================
+# Documentation Build Artifacts
+# =============================================================================
+docs/_build/
+
+# =============================================================================
+# Testing/CI Artifacts
+# =============================================================================
+.pytest_cache/
+.ruff_cache/
+
+# =============================================================================
+# LEGACY HERCULES - May remove in future cleanup
+# =============================================================================
+# Old example folder path (renamed to examples/)
+!example_case_folders/00_wind_farm_only/inputs/floris_standin_data.csv
+!example_case_folders/00_wind_farm_only/inputs/wind_power_reference_data.csv
+
+# C++ build artifacts (from old AMR-Wind integration)
+a.out
+*.plist
+test_client.dSYM
+hercules/test_client_cpp/test_client
+
+# NetCDF files (from old AMR-Wind demos)
+hercules/sampling00000.nc
+hercules/sample_copy.nc
+hercules/local_amr_wind_demo/sample_copy.nc
+
+# Database files (from old front-end/control center)
+data.db
+*.sqlite
+*.conda
+hercules/front_end.db
+hercules/control_center.db
+
+# Old data/flow pickle files
+hercules/df_flow.p
+hercules/flow_data.p
+
+# AMR-Wind time step outputs
+t_*.txt
+hercules/t_0*
 t_00*
+slices
+
+# Old log file patterns (now covered by *.log)
 logdummy
 loghelics
 loghercules*
 logstandin*
 logfloris*
-*echo
 *out-example.json
-
-.vscode/*
-
-# Doc builds
-docs/_build
-docs/examples
-
-.cursor/rules/
-*.feather
-*.ftr
-*.parquet

docs/_toc.yml

@@ -36,8 +36,9 @@ parts:
     - file: examples_overview
     - file: examples/00_wind_farm_only
     - file: examples/01_wind_farm_dof1_model
-    - file: examples/02_wind_farm_realistic_inflow
+    - file: examples/02a_wind_farm_realistic_inflow
     - file: examples/02b_wind_farm_realistic_inflow_precom_floris
+    - file: examples/02c_wind_farm_realistic_inflow_direct
     - file: examples/03_wind_and_solar
     - file: examples/04_wind_and_storage
     - file: examples/05_wind_and_storage_with_lmp

examples/00_wind_farm_only/README.md → docs/examples/00_wind_farm_only.md

@@ -18,7 +18,7 @@ python hercules_runscript.py
 
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

examples/01_wind_farm_dof1_model/README.md → docs/examples/01_wind_farm_dof1_model.md

@@ -15,9 +15,10 @@ To run the example, execute the following command in the terminal:
 ```bash
 python hercules_runscript.py
 ```
+
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

examples/02a_wind_farm_realistic_inflow/README.md → docs/examples/02a_wind_farm_realistic_inflow.md

@@ -1,24 +1,24 @@
-# Example 02: Wind Farm Realistic Inflow
+# Example 02a: Wind Farm Realistic Inflow
 
 ## Description
 
-In this case uses a large set of synthetic wind data.
+This example uses a large set of synthetic wind data.
 
 ## Setup
 
 No manual setup is required. The example automatically generates the necessary input files (large-scale wind data, FLORIS configuration, and turbine model) in the centralized `examples/inputs/` folder when first run.
 
-
 ## Running
 
 To run the example, execute the following command in the terminal:
 
 ```bash
 python hercules_runscript.py
 ```
+
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

docs/examples/02b_wind_farm_realistic_inflow_precom_floris.md

@@ -0,0 +1,38 @@
+# Example 02b: Wind Farm Realistic Inflow (Precomputed FLORIS)
+
+## Description
+
+This example is identical to `02a_wind_farm_realistic_inflow` with the exception that the `precomputed` wake method is used to speed up the simulation. The configuration sets `wake_method: precomputed` in the `wind_farm` component. This example automatically generates the necessary input files in the centralized `examples/inputs/` folder when first run.
+
+Note the caveats to using this method from the docs:
+
+
+> In contrast to `wake_method: dynamic`, this method pre-computes the FLORIS wake
+    deficits for all possible wind speeds and power setpoints. This is done by running for
+    all wind speeds and wind directions (but not over all power setpoints).  This is valid
+    for cases where the wind farm is operating in the following ways:
+        - all turbines operating normally (maximum power)
+        - all turbines off
+        - following a wind-farm wide derating level
+
+    It is in practice conservative with respect to the wake deficits, but it is more efficient
+    than running FLORIS for each condition at each time step.  In cases where turbines are:
+        - partially derated below the curtailment level
+        - some, but not all, turbines are off
+    this is not an appropriate model and the more general `wake_method: dynamic` should be used.
+
+## Running
+
+To run the example, execute the following command in the terminal:
+
+```bash
+python hercules_runscript.py
+```
+
+## Outputs
+
+To plot the outputs, run the following command in the terminal:
+
+```bash
+python plot_outputs.py
+```

examples/02c_wind_farm_realistic_inflow_direct/README.md → docs/examples/02c_wind_farm_realistic_inflow_direct.md

@@ -4,7 +4,7 @@
 
 This example demonstrates the `"no_added_wakes"` wake method, which assumes that wake effects are already included in the input wind data and performs no additional wake modeling. 
 
-In this example, the `WindFarm` component type uses `wake_method="no_added_wakes"`, which means:
+In this example, the `WindFarm` component uses `wake_method: no_added_wakes`, which means:
 - No FLORIS calculations are performed during the simulation (only at initialization to read turbine properties)
 - `wind_speeds_withwakes` equals `wind_speeds_background` at all times
 - Wake deficits are always zero
@@ -22,10 +22,8 @@ python hercules_runscript.py
 
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py
 ```
-
-

examples/03_wind_and_solar/README.md → docs/examples/03_wind_and_solar.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-In this setup, wind and solar are combined in a hybrid plant.  For demonstration, the plant has a fixed interconnect limit of 3000 kW, which is much below the combined capacity of the wind and solar farms.  A simple controller limits the solar power to keep the total power below the interconnect limit.
+In this setup, wind and solar are simulated together in a hybrid plant. A simple controller can be used to curtail the solar power to keep the total power below the interconnect limit.
 
 ## Setup
 
@@ -15,9 +15,10 @@ To run the example, execute the following command in the terminal:
 ```bash
 python hercules_runscript.py
 ```
+
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

examples/04_wind_and_storage/README.md → docs/examples/04_wind_and_storage.md

@@ -2,23 +2,23 @@
 
 ## Description
 
-Example of a wind and storage hybrid plant where the storage is constrained to charge only using power produced by the wind farm.  
+Example of a wind and storage hybrid plant where the storage is constrained to charge only using power produced by the wind farm.
 
 ## Setup
 
 No manual setup is required. The example automatically generates the necessary input files (wind data, FLORIS configuration, and turbine model) in the centralized `examples/inputs/` folder when first run.
 
-
 ## Running
 
 To run the example, execute the following command in the terminal:
 
 ```bash
 python hercules_runscript.py
 ```
+
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

examples/05_wind_and_storage_with_lmp/README.md → docs/examples/05_wind_and_storage_with_lmp.md

@@ -28,7 +28,7 @@ The simulation runs for 4 hours with the following characteristics:
 
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py

examples/06_wind_and_hydrogen/README.md → docs/examples/06_wind_and_hydrogen.md

@@ -2,24 +2,24 @@
 
 ## Description
 
-Example of a wind and hydrogen hybrid plant where power that the wind farm produces goes directly to hydrogen electrolysis 
+Example of a wind and hydrogen hybrid plant where power that the wind farm produces goes directly to hydrogen electrolysis. The hydrogen output is then controlled by controlling the wind farm power to follow a hydrogen production reference signal.
 
 ## Setup
 
 No manual setup is required. The example automatically generates the necessary input files (wind data, FLORIS configuration, and turbine model) in the centralized `examples/inputs/` folder when first run.
 
-
 ## Running
 
 To run the example, execute the following command in the terminal:
 
 ```bash
 python hercules_runscript.py
 ```
+
 ## Outputs
 
-To plot the outputs run the following command in the terminal:
+To plot the outputs, run the following command in the terminal:
 
 ```bash
 python plot_outputs.py
-```
+```