diff --git a/.gitignore b/.gitignore index 65d20905..4c17b317 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/_toc.yml b/docs/_toc.yml index 993017ea..f0477e30 100644 --- a/docs/_toc.yml +++ b/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 diff --git a/examples/00_wind_farm_only/README.md b/docs/examples/00_wind_farm_only.md similarity index 90% rename from examples/00_wind_farm_only/README.md rename to docs/examples/00_wind_farm_only.md index c78df4a0..abfc3bc6 100644 --- a/examples/00_wind_farm_only/README.md +++ b/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 diff --git a/examples/01_wind_farm_dof1_model/README.md b/docs/examples/01_wind_farm_dof1_model.md similarity index 90% rename from examples/01_wind_farm_dof1_model/README.md rename to docs/examples/01_wind_farm_dof1_model.md index f2a3e55f..36fd5370 100644 --- a/examples/01_wind_farm_dof1_model/README.md +++ b/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 diff --git a/examples/02a_wind_farm_realistic_inflow/README.md b/docs/examples/02a_wind_farm_realistic_inflow.md similarity index 72% rename from examples/02a_wind_farm_realistic_inflow/README.md rename to docs/examples/02a_wind_farm_realistic_inflow.md index ad8bff56..5ef24dc7 100644 --- a/examples/02a_wind_farm_realistic_inflow/README.md +++ b/docs/examples/02a_wind_farm_realistic_inflow.md @@ -1,14 +1,13 @@ -# 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: @@ -16,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 diff --git a/docs/examples/02b_wind_farm_realistic_inflow_precom_floris.md b/docs/examples/02b_wind_farm_realistic_inflow_precom_floris.md new file mode 100644 index 00000000..3c42c271 --- /dev/null +++ b/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 +``` diff --git a/examples/02c_wind_farm_realistic_inflow_direct/README.md b/docs/examples/02c_wind_farm_realistic_inflow_direct.md similarity index 84% rename from examples/02c_wind_farm_realistic_inflow_direct/README.md rename to docs/examples/02c_wind_farm_realistic_inflow_direct.md index fda307b8..13229660 100644 --- a/examples/02c_wind_farm_realistic_inflow_direct/README.md +++ b/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 ``` - - diff --git a/examples/03_wind_and_solar/README.md b/docs/examples/03_wind_and_solar.md similarity index 55% rename from examples/03_wind_and_solar/README.md rename to docs/examples/03_wind_and_solar.md index 8fdddb3c..3742d91d 100644 --- a/examples/03_wind_and_solar/README.md +++ b/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 diff --git a/examples/04_wind_and_storage/README.md b/docs/examples/04_wind_and_storage.md similarity index 89% rename from examples/04_wind_and_storage/README.md rename to docs/examples/04_wind_and_storage.md index 5922a45f..0e99cbab 100644 --- a/examples/04_wind_and_storage/README.md +++ b/docs/examples/04_wind_and_storage.md @@ -2,13 +2,12 @@ ## 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: @@ -16,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 diff --git a/examples/05_wind_and_storage_with_lmp/README.md b/docs/examples/05_wind_and_storage_with_lmp.md similarity index 96% rename from examples/05_wind_and_storage_with_lmp/README.md rename to docs/examples/05_wind_and_storage_with_lmp.md index 2bf9fe85..fd91cef7 100644 --- a/examples/05_wind_and_storage_with_lmp/README.md +++ b/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 diff --git a/examples/06_wind_and_hydrogen/README.md b/docs/examples/06_wind_and_hydrogen.md similarity index 66% rename from examples/06_wind_and_hydrogen/README.md rename to docs/examples/06_wind_and_hydrogen.md index 7aca39b7..ed962fe4 100644 --- a/examples/06_wind_and_hydrogen/README.md +++ b/docs/examples/06_wind_and_hydrogen.md @@ -2,13 +2,12 @@ ## 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: @@ -16,10 +15,11 @@ 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 -``` \ No newline at end of file +``` diff --git a/examples/02b_wind_farm_realistic_inflow_precom_floris/README.md b/examples/02b_wind_farm_realistic_inflow_precom_floris/README.md deleted file mode 100644 index 20531969..00000000 --- a/examples/02b_wind_farm_realistic_inflow_precom_floris/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Example 02b: Wind Farm Realistic Inflow (Precomputed FLORIS) - -## Description - -This example is identical to `02_wind_farm_realistic_inflow` with the exception that the `precomputed` wake method of the `WindFarm` 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 `wake_method="dynamic"`, 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 `wake_method="dynamic"` version 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 -``` \ No newline at end of file diff --git a/examples/readme.txt b/examples/readme.txt new file mode 100644 index 00000000..3bc2aca8 --- /dev/null +++ b/examples/readme.txt @@ -0,0 +1,3 @@ +See https://natlabrockies.github.io/hercules/examples_overview.html for documentation describing +the Hercules examples. +