Merge pull request #871 from NREL/develop

FLORIS v3.6

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

@@ -8,7 +8,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.9", "3.10", "3.11"]
         os: [ubuntu-latest] #, macos-latest, windows-latest]
       fail-fast: False
 
@@ -25,9 +25,14 @@ jobs:
         pip install nbconvert  # For converting Jupyter notebook to python script in the next step
     - name: Run examples
       # 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: |
 
-        cd examples/
+        mkdir -p temp1/temp2/temp3
+        cp -r examples/ temp1/temp2/temp3/.
+        cd temp1/temp2/temp3/examples/
+
         error_found=0  # 0 is false
         error_results="Error in example:"
 
@@ -48,27 +53,6 @@ jobs:
           fi
         done
 
-        # Run all Jupyter notebooks
-        for i in *.ipynb; do
-
-          # Convert this notebook to a Python script
-          if ! jupyter nbconvert --to script $i; then
-            # On conversion error, report and go to the next notebook
-            error_results="${error_results}"$'\n'" - Error converting ${i} to Python script"
-            continue
-          fi
-
-          # Get the basename of the notebook since the converted script will have the same basename
-          script_name=`basename $i .ipynb`
-
-          # Run the converted script
-          if ! python "${script_name}.py"; then
-            error_results="${error_results}"$'\n'" - ${i}"
-            error_found=1
-          fi
-
-        done
-
         if [[ $error_found ]]; then
           echo "${error_results}"
         fi

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

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

CONTRIBUTING.md

@@ -77,4 +77,4 @@ submit a new feature, let us know in
 
 We rely heavily on git and GitHub, so be sure to review the
 contributing guidelines in the
-[online documentation](https://floris.readthedocs.io/en/main/source/developers.html).
+[online documentation](https://nrel.github.io/floris/dev_guide.html).

README.md

@@ -3,7 +3,7 @@
 FLORIS is a controls-focused wind farm simulation software incorporating
 steady-state engineering wake models into a performance-focused Python
 framework. It has been in active development at NREL since 2013 and the latest
-release is [FLORIS v3.5](https://github.com/NREL/floris/releases/latest).
+release is [FLORIS v3.6](https://github.com/NREL/floris/releases/latest).
 Online documentation is available at https://nrel.github.io/floris.
 
 The software is in active development and engagement with the development team
@@ -71,7 +71,7 @@ and importing FLORIS:
         version
 
     VERSION
-        3.5
+        3.6
 
     FILE
         ~/floris/floris/__init__.py

docs/_config.yml

@@ -44,13 +44,13 @@ sphinx:
   - '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'
+    nb_execution_show_tb: true          # Shows the stack trace in stdout; its suppressed otherwise.
+    nb_execution_raise_on_error: true   # Stops the Sphinx build if there is an error in a notebook. See https://github.com/executablebooks/jupyter-book/issues/2011
+    suppress_warnings:
+    - etoc.toctree                      # autodoc output contains toctrees, so suppress this warning. See https://github.com/executablebooks/sphinx-external-toc/issues/36
     autoyaml_level: 3
     autosummary_generate: true
 
@@ -60,7 +60,7 @@ sphinx:
       members: true
       member-order: bysource
       undoc-members: true
-      private-members: true
+      private-members: false
       # special-members: true
       # inherited-members
       # show-inheritance
@@ -70,3 +70,4 @@ sphinx:
       # class-doc-from
       # no-value
     autodoc_typehints: both
+    mermaid_version: "10.8"

docs/_toc.yml

@@ -2,16 +2,16 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: intro
+root: index
 parts:
   - caption: Getting Started
     chapters:
-    # - file: intro
     - file: installation
 
   - caption: User Reference
     chapters:
-    - file: floris_101
+    - file: intro_concepts
+    - file: advanced_concepts
     - file: floating_wind_turbine
     - file: turbine_interaction
     - file: input_reference_main
@@ -21,6 +21,8 @@ parts:
   - caption: Theory and Background
     chapters:
     - file: wake_models
+      sections:
+      - file: empirical_gauss_model
     - file: bibliography
 
   - caption: Developer Reference

docs/api_docs.rst → docs/api_docs.md

@@ -1,16 +1,15 @@
-API Documentation
-=================
+# API Documentation
 
 FLORIS is divided into two primary packages.
-:py:mod:`floris.simulation` is the core code that models the wind turbines
-and wind farms. It is low-level code that generally is nto accessed
-by typical users. :py:mod:`floris.tools` is the set of analysis routines
+{py:mod}`floris.simulation` is the core code that models the wind turbines
+and wind farms. It is low-level code that generally is not accessed
+by typical users. {py:mod}`floris.tools` is the set of analysis routines
 that define, drive, and post process a simulation. This is where
 more users will interface with the software.
 
+```{eval-rst}
 .. autosummary::
    :toctree: _autosummary
-   :template: custom-module-template.rst
    :recursive:
 
    floris.logging_manager
@@ -19,3 +18,4 @@ more users will interface with the software.
    floris.type_dec
    floris.turbine_library
    floris.utilities
+```

docs/architecture.md

@@ -7,9 +7,10 @@ be violated, and ongoing work should strive to meet these ideas and expand on th
 as possible.
 
 - Modularity in wake model formulation:
-    - New mathematical formulation should be straightforward to incorporate.
-    - Requisite solver and grid data structures should not conflict with other existing
-        wake models.
+    - New mathematical formulation should be straightforward to incorporate by non-expert
+        software developers.
+    - Solver and grid data structures for one wake model should not conflict with the data
+        structures for other wake models.
 - Any new feature or work should not affect an existing feature:
     - Low level code should be reused as much as possible, but high level code should rarely
         be repurposed.
@@ -31,12 +32,12 @@ packages. The internal structure and hierarchy is described below.
 ```{mermaid}
 classDiagram
 
-    class tools {
-        +FlorisInterface
+    class simulation["floris.simulation"] {
+        +Floris
     }
 
-    class simulation {
-        +Floris
+    class tools["floris.tools"] {
+        +FlorisInterface
     }
 
     class logging_manager
@@ -45,9 +46,7 @@ classDiagram
 
     tools <-- logging_manager
     simulation <-- logging_manager
-    tools <-- type_dec
     simulation <-- type_dec
-    tools <-- utilities
     simulation <-- utilities
     tools <-- simulation
 ```
@@ -75,54 +74,61 @@ classDiagram
     class Farm
 
     class FlowField {
-        array u
-        array v
-        array w
+        u: NDArrayFloat
+        v: NDArrayFloat
+        w: NDArrayFloat
     }
 
     class Grid {
         <<interface>>
+        x: NDArrayFloat
+        y: NDArrayFloat
+        z: NDArrayFloat
     }
     class TurbineGrid
+    class TurbineCubatureGrid
     class FlowFieldPlanarGrid
+    class PointsGrid
 
     class WakeModelManager {
         <<interface>>
     }
     class WakeCombination {
-        dict parameters
+        parameters: dict
         function()
     }
     class WakeDeflection {
-        dict parameters
+        parameters: dict
         function()
     }
     class WakeTurbulence {
-        dict parameters
+        parameters: dict
         function()
     }
     class WakeVelocity {
-        dict parameters
+        parameters: dict
         function()
     }
 
     class Solver {
         <<interface>>
-        dict parameters
+        parameters: dict
     }
 
-    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
+    Floris *-- Farm
+    Floris *-- FlowField
+    Floris *-- Grid
+    Floris *-- WakeModelManager
+    Floris --> Solver
+    WakeModelManager *-- WakeCombination
+    WakeModelManager *-- WakeDeflection
+    WakeModelManager *-- WakeTurbulence
+    WakeModelManager *-- WakeVelocity
 
     Grid <|-- TurbineGrid
+    Grid <|-- TurbineCubatureGrid
     Grid <|-- FlowFieldPlanarGrid
+    Grid <|-- PointsGrid
 
     Solver --> Farm
     Solver --> FlowField