FLORIS v3.4

.github/ISSUE_TEMPLATE/bug_report.md

@@ -17,6 +17,10 @@ This form is written in GitHub's Markdown format. For a reference on this type
 of syntax, see GitHub's documentation:
 https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 
+This template contains guidance for your submission within the < ! - -, - - > blocks.
+These are comments in HTML syntax and will not appear in the submission.
+Be sure to use the "Preview" feature on GitHub to ensure your submission is formatted as intended.
+
 When including code snippets, please paste the text itself and wrap the code block with
 ticks (see the other character on the tilde ~ key in a US keyboard) to format it as code.
 For example, Python code should be wrapped in ticks like this:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -16,6 +16,10 @@ This form is written in GitHub's Markdown format. For a reference on this type
 of syntax, see GitHub's documentation:
 https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 
+This template contains guidance for your submission within the < ! - -, - - > blocks.
+These are comments in HTML syntax and will not appear in the submission.
+Be sure to use the "Preview" feature on GitHub to ensure your submission is formatted as intended.
+
 When including code snippets, please paste the text itself and wrap the code block with
 ticks (see the other character on the tilde ~ key in a US keyboard) to format it as code.
 For example, Python code should be wrapped in ticks like this:

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,6 +14,10 @@ This form is written in GitHub's Markdown format. For a reference on this type
 of syntax, see GitHub's documentation:
 https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 
+This template contains guidance for your submission within the < ! - -, - - > blocks.
+These are comments in HTML syntax and will not appear in the submission.
+Be sure to use the "Preview" feature on GitHub to ensure your submission is formatted as intended.
+
 When including code snippets, please paste the text itself and wrap the code block with
 ticks (see the other character on the tilde ~ key in a US keyboard) to format it as code.
 For example, Python code should be wrapped in ticks like this:

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

@@ -8,7 +8,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.9]
+        python-version: ["3.10"]
         os: [ubuntu-latest] #, macos-latest, windows-latest]
       fail-fast: False
 
@@ -21,7 +21,6 @@ jobs:
     - name: Install project
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
         pip install -e .
         pip install nbconvert  # For converting Jupyter notebook to python script in the next step
     - name: Run examples

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

@@ -8,9 +8,11 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.9]
+        python-version: ["3.8", "3.9", "3.10"]
         os: [ubuntu-latest] #, macos-latest, windows-latest]
       fail-fast: False
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
     steps:
     - uses: actions/checkout@v3
@@ -38,8 +40,9 @@ jobs:
         pip install pytest-cov
         pytest --cov=./ --cov-report=xml tests/ --ignore tests/reg_tests --ignore tests/timing.py --ignore tests/profiling.py
     - name: Upload coverage to Codecov
+      if: ${{ env.CODECOV_TOKEN }}  # Don't attempt to upload if the codecov token is not configured
       uses: codecov/codecov-action@v3
       with:
-        token: ${{ secrets.CODECOV_TOKEN }}
+        token: ${{ env.CODECOV_TOKEN }}
         files: ./coverage.xml
         fail_ci_if_error: true

.github/workflows/deploy-pages.yaml

@@ -15,15 +15,14 @@ jobs:
     - uses: actions/checkout@v2
 
     # Install dependencies
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v2
+    - name: Set up Python
+      uses: actions/setup-python@v4
       with:
-        python-version: 3.8
+        python-version: "3.10"
 
     - name: Install dependencies
       run: |
-        pip install -r docs/requirements.txt
-        pip install -e .
+        pip install -e ".[docs]"
 
     # Build the book
     - name: Build the book

.github/workflows/quality-metrics-workflow.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.9]
+        python-version: ["3.10"]
         os: [ubuntu-latest]
       fail-fast: False
 

.gitignore

@@ -3,11 +3,13 @@
 __pycache__/
 .cache
 *.ipynb
+*.ipynb_checkpoints
 *.pyc
 *.egg-info
 dist
 build
 .pytest_cache
+.ruff_cache
 
 # pip meta data
 pip-wheel-metadata

.pre-commit-config.yaml

@@ -7,13 +7,11 @@ repos:
   - id: trailing-whitespace
   - id: end-of-file-fixer
   - id: check-executables-have-shebangs
-  - id: check-json
   - id: check-yaml
+    args: [--unsafe]
   - id: check-merge-conflict
   - id: check-symlinks
   - id: mixed-line-ending
-  # - id: pretty-format-json
-  #   args: [--autofix, --no-sort-keys]
 
 - repo: https://github.com/charliermarsh/ruff-pre-commit
   rev: v0.0.241

docs/_config.yml

@@ -4,8 +4,8 @@
 title: FLORIS
 author: National Renewable Energy Laboratory
 logo: gch.gif
-copyright: '2022'
-only_build_toc_files: true
+copyright: '2023'
+only_build_toc_files: false
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -23,7 +23,7 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/nrel/floris
+  url: https://github.com/NREL/floris
   path_to_book: docs
   branch: main
 
@@ -45,6 +45,7 @@ sphinx:
   - 'sphinx_autodoc_typehints'
   - 'sphinxcontrib.autoyaml'
   - 'sphinx.ext.napoleon'       # Formats google and numpy docstring styles
+  - 'sphinxcontrib.mermaid'
   config:
     html_theme: sphinx_book_theme
     templates_path:

docs/_toc.yml

@@ -12,15 +12,20 @@ parts:
   - caption: User Reference
     chapters:
     - file: floris_101
-    - file: input_reference
+    - file: floating_wind_turbine
+    - file: turbine_interaction
+    - file: input_reference_main
+    - file: input_reference_turbine
     - file: examples
 
   - caption: Theory and Background
     chapters:
-    - file: reference
+    - file: wake_models
+    - file: bibliography
 
   - caption: Developer Reference
     chapters:
     - file: dev_guide
+    - file: architecture
     - file: code_quality
     - file: api_docs

docs/api_docs.rst

@@ -17,4 +17,5 @@ more users will interface with the software.
    floris.simulation
    floris.tools
    floris.type_dec
+   floris.turbine_library
    floris.utilities

docs/architecture.md

@@ -0,0 +1,119 @@
+
+# Architecture and Design
+
+Two fundamental ideas define the design of the FLORIS software:
+
+- Modularity in wake model formulation
+    - Mathematical formulation should be straightforward to include
+    - Requisite solver and grid data structures should not conflict with other existing
+        wake models
+- Management of abstraction
+    - Low level code is opaque but well tested and exercised; it should be very computationally
+        efficient with low algorithmic complexity
+    - High level code should be expressive and clear even if it results in verbose or less
+        efficient code
+
+The FLORIS software consists of two primary high-level packages and a few other low level
+packages. The internal structure and hierarchy is described below.
+
+```{mermaid}
+classDiagram
+
+    class tools {
+        +FlorisInterface
+    }
+
+    class simulation {
+        +Floris
+    }
+
+    class logging_manager
+    class type_dec
+    class utilities
+
+    tools <-- logging_manager
+    simulation <-- logging_manager
+    tools <-- type_dec
+    simulation <-- type_dec
+    tools <-- utilities
+    simulation <-- utilities
+    tools <-- simulation
+```
+
+## floris.tools
+
+This is the user interface. Most operations at the user level will happen through `floris.tools`.
+This package contains a wide variety of functionality including but not limited to:
+
+- Initializing and driving a simulation with `tools.floris_interface`
+- Wake field visualization through `tools.visualization`
+- Yaw and layout optimization in `tools.optimization`
+- Parallelizing work load with `tools.parallel_computing_interface`
+
+## floris.simulation
+
+This is the core simulation package. This should primarily be used within `floris.simulation` and
+`floris.tools`, and user scripts generally won't interact directly with this package.
+
+```{mermaid}
+classDiagram
+
+    class Floris
+
+    class Farm
+
+    class FlowField {
+        array u
+        array v
+        array w
+    }
+
+    class Grid {
+        <<interface>>
+    }
+    class TurbineGrid
+    class FlowFieldPlanarGrid
+
+    class WakeModelManager {
+        <<interface>>
+    }
+    class WakeCombination {
+        dict parameters
+        function()
+    }
+    class WakeDeflection {
+        dict parameters
+        function()
+    }
+    class WakeTurbulence {
+        dict parameters
+        function()
+    }
+    class WakeVelocity {
+        dict parameters
+        function()
+    }
+
+    class Solver {
+        <<interface>>
+        dict parameters
+    }
+
+    Floris o-- Farm
+    Floris o-- FlowField
+    Floris o-- Grid
+    Floris o-- WakeModelManager
+    Floris *-- Solver
+    WakeModelManager o-- WakeCombination
+    WakeModelManager o-- WakeDeflection
+    WakeModelManager o-- WakeTurbulence
+    WakeModelManager o-- WakeVelocity
+
+    Grid <|-- TurbineGrid
+    Grid <|-- FlowFieldPlanarGrid
+
+    Solver --> Farm
+    Solver --> FlowField
+    Solver --> Grid
+    Solver --> WakeModelManager
+```

docs/bibliography.md

@@ -0,0 +1,6 @@
+
+# Bibliography
+
+```{bibliography}
+:style: unsrt
+```

docs/dev_guide.md

@@ -210,21 +210,20 @@ is located at `floris/.github/workflows/continuous-integration-workflow.yaml`.
 The online documentation is built with Jupyter Book which uses Sphinx
 as a framework. It is automatically built and hosted by GitHub, but it
 can also be compiled locally. Additional dependencies are required
-for the documentation, and they are listed in ``docs/requirements.txt``.
+for the documentation, and they are listed in the `EXTRAS` of `setup.py`.
 The commands to build the docs are given below. After successfully
 compiling, a file should be located at ``docs/_build/html/index.html``.
 This file can be opened in any browser.
 
 ```bash
-pip install -r docs/requirements.txt
+pip install -e .["docs"]
 jupyter-book build docs/
 
 # Lots of output to the terminal here...
 
 open docs/_build/html/index.html
 ```
 
-
 ## Deploying to pip
 
 Generally, only NREL developers will have appropriate permissions to deploy