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/examples/00_wind_farm_only.md

@@ -0,0 +1,25 @@
+# Example 00: Wind only
+
+## Description
+
+This example demonstrates a simple wind farm simulation using generated wind data. The simulation uses a small wind farm configuration with basic turbine control.
+
+## 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:
+
+```bash
+python plot_outputs.py
+```

docs/examples/01_wind_farm_dof1_model.md

@@ -0,0 +1,24 @@
+# Example 01: Wind Only: 1-DOF model
+
+## Description
+
+This example runs the 1-DOF long-duration wind simulation.
+
+## Pre setup
+
+Make sure to first generate the wind input file using generate_wind_history.ipynb
+
+## 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
+```

docs/examples/02_wind_farm_realistic_inflow.md

@@ -0,0 +1,25 @@
+# Example 02: Wind Farm Realistic Inflow
+
+## Description
+
+In this case 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:
+
+```bash
+python plot_outputs.py
+```

docs/examples/02b_wind_farm_realistic_inflow_precom_floris.md

@@ -0,0 +1,42 @@
+# Example 02b: Wind Farm Realistic Inflow (Precomputed FLORIS)
+
+## Description
+
+This example is identical to `02_wind_farm_realistic_inflow` with the exception that the `Wind_MesoToPowerPrecomFloris`
+class is used to speed up the simulation. This example automatically generates the necessary input files in the centralized `examples/inputs/` folder when first run.
+
+Note the caveats to using this class from the docs:
+
+
+> In contrast to the Wind_MesoToPower class, this class 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:
+        - all turbines operating normally
+        - 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.  In cases where turbines are:
+        - partially derated below the curtailment level
+        - not uniformly curtailed or     some turbines are off
+
+    This is not an appropriate model and the more general Wind_MesoToPower class 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
+```

docs/examples/03_wind_and_solar.md

@@ -0,0 +1,24 @@
+# Example 03: Wind and solar hybrid plant
+
+## 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.
+
+## Setup
+
+No manual setup is required. The example automatically generates the necessary input files (wind data, solar 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:
+
+```bash
+python plot_outputs.py
+```

docs/examples/04_wind_and_storage.md

@@ -0,0 +1,25 @@
+# Example 04: Wind and storage hybrid plant
+
+## Description
+
+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:
+
+```bash
+python plot_outputs.py
+```

docs/examples/05_wind_and_storage_with_lmp.md

@@ -0,0 +1,5 @@
+# Example 05: Wind and Storage with LMP-Based Control
+
+## Overview
+
+This example demonstrates a wind farm with battery storage using a controller that responds to Locational Marginal Pricing (LMP) signals. It also showcases the **selective external data logging** feature, where external data can be accessed by the controller but selectively logged to the output file.

docs/examples/06_wind_and_hydrogen.md

@@ -0,0 +1,49 @@
+# Example 06: Wind and Hydrogen
+
+## Description
+
+This example demonstrates a wind and hydrogen hybrid plant where power that the wind farm produces goes directly to hydrogen electrolysis. This configuration is useful for understanding how renewable energy can be directly converted to hydrogen for energy storage or industrial applications.
+
+## Key Features
+
+- Wind farm power generation
+- Electrolyzer plant for hydrogen production
+- Direct power flow from wind to electrolyzer
+- Hydrogen production tracking
+
+## 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 the Example
+
+To run the example, execute the following command in the terminal:
+
+```bash
+cd examples/06_wind_and_hydrogen/
+python hercules_runscript.py
+```
+
+## Visualizing Outputs
+
+To plot the outputs, run the following command:
+
+```bash
+python plot_outputs.py
+```
+
+## Expected Results
+
+The simulation will produce outputs showing:
+- Wind farm power generation over time
+- Hydrogen production rates
+- Electrolyzer stack status
+- Power consumption by the electrolyzer
+
+## Configuration
+
+The example uses:
+- Wind farm with FLORIS wake modeling
+- Electrolyzer plant with multiple stacks
+- Hydrogen reference signal for electrolyzer control (from `inputs/hydrogen_ref_signal.csv`)
+