Docs

README.md

@@ -1,3 +1,5 @@
+[![Python System Tests with Coverage](https://github.com/WISDEM/Ard/actions/workflows/python-tests-system.yml/badge.svg)](https://github.com/WISDEM/Ard/actions/workflows/python-tests-system.yml)
+[![Python Unit Tests with Coverage](https://github.com/WISDEM/Ard/actions/workflows/python-tests-unit.yml/badge.svg)](https://github.com/WISDEM/Ard/actions/workflows/python-tests-unit.yml)
 
 # Ard
 
@@ -14,6 +16,9 @@ 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.
 
+## Documentation
+Ard documentation is available at [https://wisdem.github.io/Ard/]()
+
 ## 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`. -->
@@ -67,9 +72,7 @@ For user information, in pre-release, we are using some co-developed changes to
 
 If the installation fails, please open a new issue [here](https://github.com/WISDEM/Ard/issues).
 
-### Optional installations
-
-#### OptiWindNet
+## OptiWindNet
 
 We currently have experimental support for [Mauricio Souza de Alancar's OptiWindNet package for collection system cable path-planning optimization](https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet).
 
@@ -104,6 +107,16 @@ This, then, allows us to attempt to accomplish the technical goals of `Ard`, to:
 2) target wholistic and complex system-level optimization objectives like LCOE and beyond-LCOE metrics
 3) naturally incorporate multi-fidelity analyses to efficiently integrate physics-resolving simulation
 
+## Building Documentation
+
+To build the documentation locally run the following from the top `Ard/` directory.
+
+```shell
+jupyter-book build docs/
+```
+
+You can then open `Ard/docs/_build/html/index.html` to view the docs.
+
 ---
 
 Released as open-source software by the National Renewable Energy Laboratory under NREL software record number SWR-25-18.

ard/layout/gridfarm.py

@@ -8,26 +8,31 @@ class GridFarmLayout(templates.LayoutTemplate):
     A simplified, uniform four-parameter parallelepiped grid farm layout class.
 
     This is a class to take a parameterized, structured grid farm defined by a
-    gridded parallelepiped with spacing variables defined to 1) orient the farm
-    with respect to North, 2) space the rows of turbines along this primary
-    vector, 3) space the columns of turbines along the perpendicular, and
-    4) skew the positioning along a parallel to the primary (orientation)
-    vector. The layout model is shown in a ASCII image below:
-
-                                      |-------| <- streamwise spacing
-      orient.         x ----- x ----- x ----- x ----- x -
-       angle         /       /       /       /       /  | <- spanwise spacing
-        |           x ----- x ----- x ----- x ----- x   -      (perpendicular
-        v          /       /       /       /       /            w.r.t. primary)
-       -------    x ----- x ----- x ----- x ----- x    ----- primary vector
-            '    /       /       /       /       /             (rotated from
-        '       x ----- x ----- x ----- x ----- x               north CW by
-    '          /       /       /       /       /                orientation
-     NORTH    x ----- x ----- x ----- x ----- x                 angle)
-                     /|
-                    / |
-                   /  | <- skew angle
-
+    gridded parallelepiped with spacing variables defined to: 
+    1) orient the farm with respect to North, 
+    2) space the rows of turbines along this primary vector, 
+    3) space the columns of turbines along the perpendicular, and 
+    4) skew the positioning along a parallel to the primary (orientation) vector. 
+
+    The layout model is shown in a ASCII image below:
+
+    ::
+
+    |                                          |-------| <- streamwise spacing
+    |          orient.         x ----- x ----- x ----- x ----- x -
+    |           angle         /       /       /       /       /  | <- spanwise spacing
+    |            |           x ----- x ----- x ----- x ----- x   -      (perpendicular
+    |            v          /       /       /       /       /            w.r.t. primary)
+    |           -------    x ----- x ----- x ----- x ----- x    ----- primary vector
+    |                '    /       /       /       /       /             (rotated from
+    |            '       x ----- x ----- x ----- x ----- x               north CW by
+    |        '          /       /       /       /       /                orientation
+    |        NORTH    x ----- x ----- x ----- x ----- x                 angle)
+    |                        /|
+    |                       / |
+    |                      /  | <- skew angle
+
+
     Options
     -------
     modeling_options : dict

docs/_toc.yml

@@ -3,7 +3,24 @@
 
 format: jb-book
 root: intro
-chapters:
-- file: utils
-- file: LCOE_analysis
-- file: reference
+parts:
+  # introductory material
+  - caption: Getting Started
+    chapters:
+    - file: installation
+  # Tutorials
+  - caption: Tutorials
+    chapters:
+    - file: LCOE_analysis
+  # How-to Guides
+  - caption: How-to Guides
+    chapters:
+    - file: multi_fidelity_aep
+  # Reference Material
+  - caption: Reference
+    chapters:
+    - file: api_reference
+  # Explanations
+  - caption: Explanation
+    chapters:
+    - file: structure

docs/installation.md

@@ -0,0 +1,48 @@
+# Installation instructions
+`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 git@github.com:WISDEM/Ard.git
+```
+Once downloaded, you can enter the `Ard` root directory using
+```shell
+cd Ard
+```
+
+At this point, although not strictly required, we recommend creating a dedicated conda environment with `pip`, `python=3.12`, and `mamba` in it:
+```shell
+conda create --name ard-env
+conda activate ard-env
+conda install python=3.12 pip mamba -y
+```
+
+From here, installation can be handled by `pip`.
+
+For a basic and static installation, type:
+```shell
+pip install .
+```
+
+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]`).
+
+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.
+
+```shell
+mamba install wisdem=3.18.1 -y
+pip install -e .[dev,docs]
+```
+
+To test the installation, from the `Ard` folder run unit and regression tests:
+```shell
+source test/run_local_test_unit.sh
+source test/run_local_test_system.sh
+```
+
+For user information, in pre-release, we are using some co-developed changes to the `FLORIS` library.
+
+If the installation fails, please open a new issue [here](https://github.com/WISDEM/Ard/issues).

docs/intro.md

@@ -1,5 +1,5 @@
 
-# Ard
+# Introduction
 
 **Dig in to wind farm design.**
 
@@ -14,36 +14,14 @@ 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 git@github.com: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]`).
-
-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.
-
-For user information, in pre-release, we are using some co-developed changes to the `FLORIS` library.
+## Documentation
+The documentation organized as follows: 
+- **Getting Started**: helpful information to get you started using Ard, including installation instructions
+- **Tutorials**: example problems with solutions
+- **How-to Guides**: instructions on solving particular problems and using specific features of Ard
+- **Reference**: dry, but helpfully useful, reference material including the API reference manual
+- **Explanation**: discursive content on the whys, hows, and the wherefores of Ard for those that are interested
+
 
 ## Current capabilities
 

docs/multi_fidelity_aep.md

@@ -0,0 +1,7 @@
+# Multi-fidelity AEP
+
+Ard is capable of running multiple AEP models in an intelligent way to get increased accuracy (from a mid- to high-fidelity model) and reasonable speed (from a low-fidelity model) at the same time.
+
+## Setting up a multi-fidelity analysis
+
+## interpreting the results

ard/README.md → docs/structure.md

@@ -1,5 +1,5 @@
 
-# Component types
+# OpenMDAO Component types
 
 The design intention of `Ard` is to offer a principled, modular, extensible wind farm layout optimization tool.
 
@@ -50,5 +50,23 @@ The default `cost` component set are the WISDEM tools given in `ard/cost/windse_
 
 **tl;dr:** `cost` components map from machines and their production of energy to money inputs and outputs
 
+# Explanation of Utilities (`utils`)
+
+The `utils` sub-module of Ard contains the many generic capabilities needed for effective wind farm design and optimization in order to facilitate maximum code reuse. However, utils includes only generalized functions and methods and excludes most code that is technology-specific (see IO as an exception). As the capabilities in `utils` expand, some of them could eventually be broken off into a separate package. The utils are divided into the following categories:
+
+## Core
+The capabilities housed in `core.py` are generic and short enough that having a discipline-specific file is not warranted.
+
+## Geometry
+The capabilities housed in `geometry.py` are generic geometry-related code. They calculate distances, define shapes, and generally simplify working with geometric tasks in a continuously differentiable way in Ard.
+
+## IO
+The capabilities in `io.py` provide for loading and saving information and may be technology specific.
+
+## Mathematics
+The capabilities housed in `mathematics.py` are pure mathematical functions generally formulated to be continuously differentiable. These functions are useful in a range of applications within Ard and design optimization generally.
+
+## Test Utils
+The capabilities housed in `test_utils.py` are specifically for use in testing and not in other parts of Ard.
 
 <!-- FIN! -->

examples/LCOE_stack/LCOE_analysis.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# LCOE Stack Demo\n",
+    "# Introductory Tutorial: Estimating and Minimizing LCOE\n",
     "\n",
     "In this demo analysis, we will analyze the `Ard` layout-to-LCOE stack for land-based analysis.\n",
     "First, `Ard` must be installed, and the test case in `test/system/LCOE_stack` relative to the `Ard` root directory.\n",