Merge pull request #116 from NREL/develop

Hercules v1.1

.github/workflows/check-working-examples.yaml

@@ -0,0 +1,52 @@
+name: Check Examples APIs
+
+on: [push, pull_request]
+
+jobs:
+
+  examples-check:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+        os: [ubuntu-latest] #, macos-latest, windows-latest]
+      fail-fast: False
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[develop]"
+        pip install git+https://github.com/NREL/electrolyzer.git
+        pip install https://github.com/NREL/SEAS/blob/main/SEAS.tar.gz?raw=true
+        pip install git+https://github.com/NREL/floris.git@v4
+    - name: Run example 06_amr_wind_standin_and_battery
+      # Run all examples and test that they finish successfully. Do not evaluate the results.
+      # Copy the examples to a new directory outside of the repo to ensure that there is no
+      # reliance on the repo directory structure.
+      run: |
+
+        #mkdir -p temp1/temp2/temp3
+        #cp -rv example_case_folders/06_amr_wind_standin_and_battery/ temp1/temp2/temp3/.
+        # cd temp1/temp2/temp3/06_amr_wind_standin_and_battery/
+        cd example_case_folders/06_amr_wind_standin_and_battery/
+
+        error_found=0  # 0 is false
+        error_results="Error in example:"
+
+        # Try running the bash script
+        if ! bash batch_script.sh; then
+          error_results="${error_results}"$'\n'" - run_example.sh"
+          error_found=1
+        fi
+
+        if [[ ! $error_found ]]; then
+          echo "${error_results}"
+        fi
+
+        exit $error_found

.github/workflows/continuous-integration-workflow.yaml

@@ -10,7 +10,7 @@ jobs:
       fail-fast: False
       matrix:
         python-version: ["3.9", "3.10", "3.11"]
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, macos-latest]
 
     steps:
     - uses: actions/checkout@v3
@@ -27,7 +27,7 @@ jobs:
 #    - uses: pre-commit/[email protected]
     - name: Run ruff
       run: |
-        ruff .
+        ruff check .
 #        ruff format
     - name: Run tests and collect coverage
       run: |

.github/workflows/deploy-pages.yaml

@@ -23,6 +23,16 @@ jobs:
     - name: Install dependencies
       run: |
         pip install -e ".[docs]"
+    
+    - name: Make copies of example docs
+      run: |
+        mkdir -vp docs/examples
+        cp -v example_case_folders/05_floris_wind_standin_and_electrolyzer/README.md docs/examples/05_floris_wind_standin_and_electrolyzer.md
+        cp -v example_case_folders/06_amr_wind_standin_and_battery/README.md docs/examples/06_amr_wind_standin_and_battery.md
+        cp -v example_case_folders/07_floris_standin_and_solar_pysam/README.md docs/examples/07_floris_standin_and_solar_pysam.md
+        cp -v example_case_folders/08_floris_only/README.md docs/examples/08_floris_only.md
+        cp -v example_case_folders/09_amr_wind_openfast/README.md docs/examples/09_amr_wind_openfast.md
+        ls -l docs/examples
 
     # Build the book
     - name: Build the book

.gitignore

@@ -34,12 +34,17 @@ hercules/local_amr_wind_demo/sample_copy.nc
 
 #Ignore csv files
 *.csv
+!tests/test_inputs/*.csv
+!example_case_folders/10_heterogeneous_wind/floris_standin_data.csv
+!example_case_folders/10_heterogeneous_wind/wind_power_reference_data.csv
 
 # Some output files to ignore
 t_00*
 logdummy
-loghercules
-logstandin
+loghelics
+loghercules*
+logstandin*
+logfloris*
 *echo
 *out-example.json
 

README.md

@@ -1,7 +1,7 @@
 # README
 
 # hercules
-Hercules, based on the acronym "Hybrid Energy and Control Using Large Eddy Simulations", is an open-source tool for wind-based hybrid plant simulation in real time. Hercules is based around high fidelity wind farm flow simulations through AMR-Wind, co-simulated with a hybrid plant that includes solar, storage, and generation. The entire hybrid plant can be controlled using the Wind Hybrid Open Controller (WHOC).
+Hercules, based on the acronym "Hybrid Energy and Control Using Large Eddy Simulations", is an open-source tool for wind-based hybrid plant simulation in real time. Hercules is based around high fidelity wind farm flow simulations through AMR-Wind, co-simulated with a hybrid plant that includes solar, storage, and generation. The entire hybrid plant can be controlled using the [Wind Hybrid Open Controller (WHOC)](https://github.com/nrel/wind-hybrid-open-controller).
 
 # Documentation
 

docs/_config.yml

@@ -4,7 +4,7 @@
 title: HERCULES
 author: National Renewable Energy Laboratory
 logo: herc.png
-copyright: '2023'
+copyright: '2024'
 only_build_toc_files: false
 
 # Force re-execution of notebooks on each build.
@@ -25,7 +25,7 @@ bibtex_bibfiles:
 repository:
   url: https://github.com/NREL/hercules
   path_to_book: docs
-  branch: main
+  branch: develop
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
@@ -36,37 +36,4 @@ html:
   google_analytics_id: G-3V1BDK8KEJ
 
 
-# Sphinx for API doc generation
-sphinx:
-  extra_extensions:
-  - 'sphinx.ext.autodoc'
-  - 'sphinx.ext.autosummary'
-  - 'sphinx.ext.viewcode'
-  - 'sphinx_autodoc_typehints'
-  - 'sphinxcontrib.autoyaml'
-  - 'sphinx.ext.napoleon'       # Formats google and numpy docstring styles
-  - 'sphinxcontrib.mermaid'
-  config:
-    html_theme: sphinx_book_theme
-    templates_path:
-    - '_templates'
-    language: 'python'
-    autoyaml_level: 3
-    autosummary_generate: true
 
-    # Autodoc config reference
-    # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
-    autodoc_default_options:
-      members: true
-      member-order: bysource
-      undoc-members: true
-      private-members: true
-      # special-members: true
-      # inherited-members
-      # show-inheritance
-      # ignore-module-all
-      # imported-members: true
-      # exclude-members
-      # class-doc-from
-      # no-value
-    autodoc_typehints: both

docs/_toc.yml

@@ -7,10 +7,30 @@ parts:
   - caption: Installation
     chapters:
     - file: install_instructions
-    - file: install_old
+    - file: install_local
     - file: install_on_kestrel
     - file: install_spack
   - caption: Usage
     chapters:
-    - file: examples
     - file: order_of_op
+  - caption: Technologies
+    chapters:
+    - file: wind
+    - file: battery
+    - file: solar_pv
+  - caption: Examples
+    chapters:
+    - file: examples_overview
+    - file: examples/05_floris_wind_standin_and_electrolyzer
+    - file: examples/06_amr_wind_standin_and_battery
+    - file: examples/07_floris_standin_and_solar_pysam
+    - file: examples/08_floris_only
+    - file: examples/09_amr_wind_openfast
+
+
+
+
+
+
+
+

docs/battery.md

@@ -0,0 +1,53 @@
+# Battery
+
+There are two battery models currently implemented in Hercules: `SimpleBattery` and `LIB`. Both interact with Hercules through a simple wrapper class: `Battery`.
+
+### Parameters
+
+Battery parameters are defined in the hercules input yaml file used to initialize `emulator`.
+
+- `py_sim_type`: `"SimpleBattery"` or `"LIB"`
+- `energy_capacity`: [kWh]
+- `charge_rate`: [kW]
+- `max_SOC`: between 0 and 1
+- `min_SOC`: between 0 and 1
+- `initial_conditions`
+  - `SOC`: between `min_SOC` and `max_SOC`
+
+
+Once initialized, the battery is only interacted with using the `step` method.
+
+### Inputs
+Inputs are passed to `step()` as a dict named `inputs`, which must have the following fields:
+
+```
+{py_sims:{inputs:{battery_signal: ____,
+                 available_power: ____
+                 }}}
+```
+
+### Outputs
+Outputs are returned as a dict containing the following values
+- `power` The charging/discharging power of the battery
+- `reject` The amount of charging/discharging requested of the battery that it could not fulfill. Can be positive or negative.
+- `soc` The battery state of charge
+
+
+## `SimpleBattery`
+
+`SimpleBattery` is defined by $E_t = \sum_{k=0}^t P_k \Delta t$, where $E_t$ is the energy stored and $P_t$ is the charging/discharging power at time $t$. Both $E$ and $P$ are constrained by upper and lower limits.
+
+$\underline{E} \leq E \leq \overline{E}$
+
+$\underline{P} \leq P \leq \overline{P}$
+
+
+## `LIB`
+
+`LIB` models a lithium ion battery based on the lithium ion cell model presented in [1.]. The main difference between `LIB` and `SimpleBattery` is that `LIB` includes diffusion transients and losses both of which are modeled as an equivalent circuit model following the approach in [1.].
+
+
+
+### References
+
+1. M.-K. Tran et al., “A comprehensive equivalent circuit model for lithium-ion batteries, incorporating the effects of state of health, state of charge, and temperature on model parameters,” Journal of Energy Storage, vol. 43, p. 103252, Nov. 2021, doi: 10.1016/j.est.2021.103252.

docs/examples_overview.md

@@ -0,0 +1,4 @@
+# Examples Overview
+
+Hercules includes several examples to demonstrate usage for a number of key configurations.
+

docs/install_instructions.md

@@ -2,8 +2,8 @@
 
 Still a work in progress but currently there are 3 sets of installation instructions
 
-[Installing on kestrel](install_on_kestrel)
+[Local installation instructions](install_local)
 
-[Old installation instructions](install_old)
+[Installing on Kestrel](install_on_kestrel)
 
 [Install via spack](install_spack)