Merge pull request #31 from WISDEM/develop

Alpha release

.github/workflows/black.yml

@@ -0,0 +1,33 @@
+name: Format code with Black
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.12'  # Specify the Python version you want to use
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install black
+
+      - name: Run Black
+        run: |
+          black --check .  # This checks if the code is formatted correctly

.github/workflows/deploy-pages.yaml

@@ -0,0 +1,38 @@
+name: deploy-pages
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - docs/**
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    # Install dependencies
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install dependencies
+      run: |
+        pip install -e ".[docs]"
+
+    # Build the book
+    - name: Build the book
+      working-directory: ${{runner.workspace}}/Ard/docs/
+      run: |
+        jupyter-book build .
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.ARD_PAGES_TOKEN }}
+        publish_dir: ./docs/_build/html

.github/workflows/python-tests-system.yml

@@ -0,0 +1,46 @@
+name: Python System Tests with Coverage
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+
+    - name: Install Ard
+      run: |
+        pip install .[dev]
+
+    - name: Run system tests with coverage
+      run: |
+        pytest --cov=ard --cov-fail-under=50 test/system
+        # pytest --cov=ard --cov-fail-under=80 test/system
+
+    # - name: Upload coverage report
+    #   uses: codecov/codecov-action@v2
+    #   with:
+    #     file: ./coverage.xml
+    #     flags: unittests
+    #     name: codecov-umbrella
+

.github/workflows/python-tests-unit.yml

@@ -0,0 +1,45 @@
+name: Python Unit Tests with Coverage
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+
+    - name: Install Ard
+      run: |
+        pip install .[dev]
+
+    - name: Run unit tests with coverage
+      run: |
+        pytest --cov=ard --cov-fail-under=80 test/unit
+
+    # - name: Upload coverage report
+    #   uses: codecov/codecov-action@v2
+    #   with:
+    #     file: ./coverage.xml
+    #     flags: unittests
+    #     name: codecov-umbrella
+

.gitignore

@@ -1,5 +1,10 @@
 
-### WINDARD DEVELOPMENT IGNORES 
+### ARD DEVELOPMENT IGNORES 
+
+.vscode
+case_files/
+
+### MACOS DEFAULT IGNORES
 
 .DS_Store
 
@@ -77,6 +82,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+_autosummary/
 
 # PyBuilder
 .pybuilder/

COPYRIGHT

@@ -0,0 +1,14 @@
+
+Copyright (c) 2024-2025, Alliance for Sustainable Energy, LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file or any file found in this repository except in
+compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -1,40 +1,78 @@
-# windArd
 
-`windArd` is an optimization suite for multi-disciplinary optimization of wind farms.
+# Ard
 
-## Name
+**Dig into wind farm design.**
 
-`windArd` is not a typo in the middle of "windward".
-It is a portmanteau of "wind" and ["ard"](https://en.wikipedia.org/wiki/Ard_\(plough\)), which is a type of simple and lightweight plow used through the single-digit centuries to prepare a farm for planting.
+<!-- The (aspirationally) foolproof tool for preparing wind farm layouts. -->
 
-## Goals
+[An ard is a type of simple and lightweight plow](https://en.wikipedia.org/wiki/Ard_\(plough\)), used through the single-digit centuries to prepare a farm for planting.
+The intent of `Ard` is to be a modular, full-stack multi-disciplinary optimization tool for wind farms.
 
-The technical goals of `windArd` are to:
-1) allow optimization of wind farm layouts for specific wind resource profiles
-2) target wholistic, system-level optimization objectives
-3) incorporate multi-fidelity analyses to integrate physics-resolving simulation
+The problem with wind farms is that they are complicated, multi-disciplinary objects.
+They are aerodynamic machines, with complicated control systems, power electronic devices, social and political objects, and the core value (and cost) of complicated financial instruments.
+Moreover, the design of *one* of these aspects affects all the rest!
+
+`Ard` seeks to make plant-level design choices that can incorporate these different aspects _and their interactions_ to make wind energy projects more successful.
+
+## Installation instructions
+
+<!-- `Ard` can be installed locally from the source code with `pip` or through a package manager from PyPI with `pip` or conda-forge with `conda`. -->
+<!-- For Windows systems, `conda` is required due to constraints in the WISDEM installation system. -->
+<!-- For macOS and Linux, any option is available. -->
+`Ard` is currently in pre-release and is only available as a source-code installation.
+The source can be cloned from github using the following command in your preferred location:
+```shell
+git clone [email protected]:WISDEM/Ard.git
+```
+Once downloaded, you can enter the `Ard` root directory using
+```shell
+cd Ard
+```
+
+From here, installation can be handled by `pip`:
+```shell
+pip install .
+```
+will install Ard in its most basic and static configuration.
+For development (and really for everyone during pre-release), we recommend a full development installation:
+```shell
+pip install -e .[dev,docs]
+```
+which will install in "editable mode" (`-e`), such that changes made to the source will not require re-installation, and with additional optional packages for development and documentation (`[dev,docs]`).
 
-As a code, the goal of `windArd` is to be:
-1) modular: choose the parts you want, skip the ones you don't, build yourself the ones we don't have
-2) clean: fully documented, and adhering to best-practices for code development
-3) effective: fully tested and testable at the unit and system level, and built with a derivative-forward approach
+There can be some hardware-software mis-specification issues with WISDEM installation from `pip` for MacOS 12 and 13 on machines with Apple Silicon.
+In the event of issues, WISDEM can be installed manually or using `conda` without issues, then `pip` installation can proceed.
 
-These will not always be possible, but they are the goal.
+For user information, in pre-release, we are using some co-developed changes to the `FLORIS` library.
 
-## Prototype design problem
+## Current capabilities
 
-In the following figure, we have a prototype case for windArd:
+For the alpha pre-release of `Ard`, we have concentrated on optimization of wind plants, starting from a structured layout and optimizing to minimize the levelized cost of energy, or LCOE.
+This capability is demonstrated in `examples/LCOE_stack` and tested in an abridged form in `test/system/LCOE_stack/test_LCOE_stack.py`.
+In the alpha pre-release stage, the constituent subcomponents of these problems are known to work and fully tested; any capabilities not touched in the layout-to-LCOE stack should be treated as experimental.
 
-![`windArd` demonstration image](/assets/windard_xdsm/windard_xdsm.png)
+These cases start from a four parameter farm layout, compute landuse area, make FLORIS AEP estimates, compute turbine capital costs, balance-of-station (BOS), and operational costs using WISDEM components, and finally give summary estimates of plant finance figures.
+The components that achieve this can be assembled to either run a single top-down analysis run, or run an optimization.
+
+## Roadmap to future capabilities
+
+The future development of `Ard` is centered around two user cases:
+1) systems energy researchers who are focusing on one specific subdiscipline (e.g. layout strategies, social impacts, or aerodynamic modeling) but want to be able to easily keep track of how it impacts the entire value chain down to production, cost, and/or value of energy or even optimize with respect to it, and
+2) private industry researchers who are interested in how public-sector research results change when proprietary analysis tools are dropped in and coupled the other tools in a systems-level simulation.
+
+`Ard` is being developed as a modular tool to enable these types of research queries.
+This starts from our research goals, which are that `Ard` should be:
+1) principled: fully documented, and adhering to best-practices for code development
+1) modular and extensible: choose the parts you want, skip the ones you don't, build yourself the ones we don't have
+1) effective: fully tested and testable at the unit and system level, and built with a derivative-forward approach
+
+This, then, allows us to attempt to accomplish the technical goals of `Ard`, to:
+1) allow optimization of wind farm layouts for specific wind resource profiles
+1) target wholistic and complex system-level optimization objectives like LCOE and beyond-LCOE metrics
+1) naturally incorporate multi-fidelity analyses to efficiently integrate physics-resolving simulation
 
-This example shows the variable interactions for an LCOE minimization problem for a farm with a structured layout that can be parametrized by two spacing lengths and two angles.
-The problem is also set up to be constrained by the amount of area that is occupied by a wind farm, which can be calculated using the layout parameters.
+---
 
-The layout parameterization is controlled by an optimization loop which controls the layout design variables to minimize LCOE while satisfying a landuse constraint.
-These layout design variables are passed to a unit that determines the $(x,y)$ locations of the turbines for the parametrized layout, as well as to an area computation for the land use.
-The wind resource is passed in as a set of datapoints to a "de-multiplexer" ("demux") component which takes the single wind resource description and outputs the set of specific wind conditions that should be queried by aerodynamic solvers.
-The aerodynamic solvers result in an evaluation of the farm power for a given layout at the set of wind conditions to be queried.
-These powers, with the "weights" provided by the demux component allow the integration of AEP.
-Finally, the BOS costs can be calculated based on the layout variables, and along with input CapEx and OpEx costs, LCOE can be computed.
+Released as open-source software by the National Renewable Energy Laboratory under NREL software record number SWR-25-18.
 
-<!-- FIN -->
+Copyright &copy; 2024-2025, Alliance for Sustainable Energy, LLC.

ard/README.md

@@ -0,0 +1,45 @@
+
+# Component types
+
+The design intention of `Ard` is to offer a principled, modular, extensible wind farm layout optimization tool.
+
+In order to balance focus with the modularity and extensibility intended for the code, we will classify different types of components, and build "base `Ard`" with a set of default components.
+Each type of component will be defined below, and each type of component will have a template parent class which can be used to derive custom user-defined components to serve as drop in replacements in `Ard`.
+
+## Layout DV Components (`layout`)
+
+Wind farm layout optimization is a significantly challenging problem for global optimization, due to the existence of many local minima.
+One strategy for reducing the dimensionality of the design space is the use of layout models.
+`layout` components are for connecting some reduced layout variables to (`x_turbines`, `y_turbines`) variables that explicitly describe the layout of a farm for computing the farm aerodynamics.
+
+The default `layout` component is the grid farm layout defined in `ard/layout/gridfarm.py`, which parameterizes a structured parallelogram-shaped farm in terms of a primary axis, aligned with respect to North by an orientation angle coincident with compass rose angles, with rows spaced along this axis by a constant spacing measured in rotor diameters; and a secondary axis, skewed from orthagonal by a skew angle in the direction of compass angles, with rows spaced along this axis by a constant spacing.
+This results in four parameters, two nondimensional spacing values and two angles.
+
+**tl;dr:** `layout` components map from a simplified parameter set to Cartesian farm coordinates
+
+## Farm Aero Components (`farm_aero`)
+
+Fundamentally, `farm_aero` components will take in a set of farm layout design variables, in terms of `x_turbines` and `y_turbines` components of turbine locations, and potentially with some control command input, namely `yaw_turbines`.
+
+In addition to these design variables, the turbine definitions to be used and some (possibly comprehensive) set of wind conditions to be queried will also be provided to a given `farm_aero` component.
+
+The result of a `farm_aero` component will be a power or energy production quantity of interest.
+Typically, these will be a power output estimate for the set of provided conditions or annual energy production estimate for the farm given the wind resource.
+
+The default `farm_aero` component is [NREL's FLORIS tool](https://nrel.github.io/floris), which can be found at `ard/farm_aero/floris.py`.
+We wrap FLORIS to map from `x_turbines`, `y_turbines`, and `yaw_turbines` to turbine powers, turbine thrusts, farm power, and, optionally, farm AEP.
+
+**tl;dr:** `farm_aero` components map from a farm layouts and possibly control settings to some measure of farm power production
+
+## Economics and Finance Components (`cost`)
+
+The `cost` components are less formally structured than the components above, but generally take inputs that are consumable stocks or marketable products of a wind system.
+Meanwhile, they give as outputs some measure of the monetary trade value that the wind system can create.
+Complete details are provided in the components in the `ard/cost` folder.
+
+The default `cost` component set are the WISDEM tools given in `ard/cost/windse_wrap.py`, which include WISDEM's `LandBOSSE` module for BOS calculation and WISDEM's `PlantFinance` module for computation of LCOE.
+
+**tl;dr:** `cost` components map from machines and their production of energy to money inputs and outputs
+
+
+<!-- FIN! -->