v1.0.0 Release

.github/workflows/CI_FAD.yml

@@ -0,0 +1,72 @@
+name: CI_FAD
+
+# Run CI on push commits and pull requests on main branches and dev
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main, dev ]
+  # Allow manual triggering of the workflow
+  workflow_dispatch:
+
+# Workflow jobs for comprehensive testing
+jobs:
+  # Comprehensive integration tests
+  build_conda:
+    name: Conda Build (${{ matrix.os }}) - Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash -el {0}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macOS-latest", "windows-latest"]
+        python-version: ["3.11"]
+
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          # Use mamba for faster package resolution
+          #mamba-version: "*"
+          miniforge-version: "latest"
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+          environment-file: fad-env.yaml
+          activate-environment: fad-env
+          auto-activate-base: false
+          channels: conda-forge
+          channel-priority: true
+          #use-mamba: true          
+
+      - name: Install additional dependencies
+        run: |
+          conda install -y pytest meson ninja nlopt
+          pip install scipy==1.11.2   # specific SciPy version needed for current LineDesign test results
+          conda info
+
+      - name: Install FAD-Toolset package
+        run: |
+          pip install -e .
+
+      - name: Update MoorPy to dev version
+        run: |
+          pip uninstall -y moorpy  # need to uninstall the old version to install the current dev branch
+          pip install git+https://github.com/NREL/MoorPy@dev
+
+      - name: Run example driver
+        run: |
+          cd examples
+          python example_driver.py false
+
+      - name: Run comprehensive tests
+        run: |
+          cd tests
+          pytest .
+

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, The NLR Floating Array Design Team
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -5,23 +5,23 @@ modeling and designing arrays of floating offshore structures. It was
 originally designed for floating wind systems but has applicability
 for many offshore applications.
 
-A core part of the FAD Toolset is the Floating Array Model (FAModel),
+A core part of the FAD Toolset is the floating array model,
 which serves as a high-level library for efficiently
-modeling a floating wind array. It combines site condition information and a 
+modeling a floating array, such as a floating wind array. It combines site condition information and a 
 description of the floating array design, and contains functions for evaluating
 the array's behavior considering the site conditions. For example, it combines
-information about site soil conditions and an array's anchor characteristics to
-estimate the holding capacity of each anchor.
+information about site soil conditions, mooring line loads, and an array's anchor characteristics to
+estimate the holding capacity of each anchor. 
 
 The library works in conjunction with the tools RAFT, MoorPy, and FLORIS to model floating
-wind turbines, mooring systems, and array wakes respectively.
+platforms, wind turbines, mooring systems, power cables, and array wakes respectively.
 
 Layered on top of the floating array model is a set of design tools that can
 be used for algorithmically adjusting or optimizing parts of the a floating
 array. Specific tools existing for mooring lines, shared mooring systems, 
 dynamic power cables, static power cable routing, and overall array layout.
 These capabilities work with the design representation and evaluation functions
-in FAModel, and they can be applied by users in various combinations to suit
+in the floating array model, and they can be applied by users in various combinations to suit
 different purposes. 
 
 In addition to standalone uses of the FAD Toolset, a coupling has been made with
@@ -36,50 +36,72 @@ and designs.
 
 See example use cases in our [examples](./examples/README.md) folder.
 
-## Pre-installation Requirements
-The FAD Toolset is built entirely in Python. It is recommended that users 
-familiarize themselves with basic Python commands before use. 
 For working with the library, it is important to understand the floating array 
-model structure, which is described more [here](./famodel/README.md).
+model structure, which is described more [here](./fad/README.md).
 
 
 ## Installation
-To install the FAD Toolset itself, first clone this FAD-Toolset repository.
 
-The dependencies required by FAD depend on how it is used. To install all
-possible required dependencies, you can create a 
-new python virtual environment based on the included yaml listing the required 
-dependencies.
+FAD-Toolset is built entirely in Python. It is recommended that users familiarize themselves with Python and install Python onto their machine through Anaconda or Miniconda distributions.
 
-In the terminal (Anaconda Powershell Prompt), clone this repository to a 
-directory of your choice, navigate into the main folder of the repository, and 
-run the following command:
+The following describes the steps to set up a python virtual environment, install FAD-Toolset, and all install required dependencies into the environment.
 
-    conda env create -f famodel-env.yaml
+First, in a terminal such as the Anaconda Powershell Prompt, clone the GitHub repository to access the files. Navigate to a directory of your choice to download the repository and then navigate into the FAD-Toolset folder.
 
-This command will install all the dependencies required to run FAD.
-Activate your virtual environment before using FAD with ```conda activate famodel-env```
+```
+(base) YOUR_PATH> git clone https://github.com/FloatingArrayDesign/FAD-Toolset.git
+(base) YOUR_PATH> cd FAD-Toolset
+```
 
-To install the FAD Toolset package in your environment, enter the 
-following in the command line from the FAD-Toolset directory.
+Next, create a new python virtual environment with an environment name of your choice. We will use 'fad-env' as an example.
 
-For development use:
+```
+(base) YOUR_PATH\FAD-Toolset> conda env create -n fad-env -f fad-env.yaml
+(base) YOUR_PATH\FAD-Toolset> conda activate fad-env     # run `conda deactivate` to deactivate
+(fad-env) YOUR_PATH\FAD-Toolset>
+```
 
-run ```python setup.py develop``` or ```pip install -e .``` from the command 
-line in the main FAD-Toolset directory.
+Within the new python virtual environment, we can install FAD-Toolset. 
 
-For non-development use:
+Use ```pip``` to install the contents of this folder. Ensure you are still within the root directory of FAD-Toolset.
 
-run ```python setup.py``` or ```pip install .``` from the command line in 
-the main FAD-Toolset directory.
+```
+(fad-env) YOUR_PATH\FAD-Toolset> pip install -e .
+```
 
-You can test the installation by running ```pytest``` from the main FAD-Toolset directory.
+This command tells `pip` to look at the `pyproject.toml` file to install the FAD-Toolset program into the current virtual environment, along with all the dependencies listed in the `pyproject.toml` file. There is overlap between the python packages listed in the `pyproject.toml` and the `fad-env.yaml` file since the installation can be done by either or both of the package installation managers, `conda` and `pip`. Specific versions of packages like scipy are listed in the `pyproject.toml` file to ensure they get installed properly. The `-e` option allows users to make local changes to their FAD-Toolset files and have those changes be reflected in the FAD-Toolset installation.
+
+Lastly, we can test the installation by running `pytest` from the main FAD-Toolset directory.
+
+```
+(fad-env) YOUR_PATH\FAD-Toolset> pytest
+```
 
 <!-- FAD requires MoorPy and we currently install it separately. If you don't already have it,
 you can install MoorPy with ```git clone https://github.com/NREL/MoorPy.git```
 then navigate to the MoorPy folder and install with ```pip install .```.
 Make sure your virtual enviroment is activated before installing MoorPy. -->
 
+For future changes to dependencies like MoorPy or RAFT, as long as those changes come through a new release of the software and an updated version is listed on PyPI, users should manually re-install the dependencies in their virtual environment to gather those new changes (i.e., `pip install moorpy`).
+
+FAD-Toolset is also pip installable and can be installed using `pip install fad-toolset`. The main source code folder in the repo is named `fad`, which is how classes and functions will be imported (i.e., `import fad.Project as Project` or `from fad.anchors.anchor import Anchor`).
+
+
+
+### Installation/Dependency Issues
+
+Some of the toolset's functionality requires RAFT, which in turn requires
+CCBlade, which recently can only be installed as part of WISDEM. Some issues
+can occur from the associated dependencies, but some have quick fixes:
+
+- Getting a readline error when breakpoint() is called?  Check if the 
+  pyreadline3 package is installed in the conda environment. If so, try
+  removing it.
+
+- Wanting to use both WEIS and FAD Toolset in the same environment, but
+  getting errors related to "smt" when installing WEIS? Try commenting out
+  the smt requirement in environment.yml and pyproject.toml.
+
 
 ## Subpackages
 
@@ -93,24 +115,33 @@ collection of subpackages for specific functions. The current subpackages are:
 
 Please navigate into the subfolders above for additional information.
 
+
 ## Getting Started
+
 The easiest way to create a FAD project is to provide the array 
 information in an ontology yaml file. FAD has been designed
 to work with a specific ontology yaml setup, which is described 
-in detail in the [Ontology ReadMe](./famodel/ontology/README.md).
+in detail in the [Ontology ReadMe](./fad/ontology/README.md).
+
+For examples of ontologies and driver files of common use cases, 
+we recommend starting with the numbered examples in the examples folder.
+The [visualization examples](./examples/01_Visualization/) are a good place
+to start. Run the .py files and inspect the .yaml files with the same name 
+to see what information is required for different uses and how they are conveyed
+in the ontology.
 
-The [example driver file](./famodel/example_driver.py) creates a FAD Project 
+To see an example with all use cases, the [example driver file](./examples/example_driver.py) creates a FAD Project 
 object from a pre-set ontology file and shows the syntax and outputs of 
 various capabilities. For guidance on creating your own ontology yaml file, 
-it is recommended to read through the [Ontology ReadMe](./famodel/ontology/README.md), 
+it is recommended to read through the [Ontology ReadMe](./fad/ontology/README.md), 
 then either adapt one of the ontology samples or fill in the ontology template. 
 
-The [core model readme](./famodel/README.md) describes the Project class structure, 
+The [core model readme](./fad/README.md) describes the Project class structure, 
 as well as the properties and methods of each component class. 
 
 There are some limited helper functions to automatically fill in sections 
 of a yaml from a MoorPy system or a list of platform locations. 
-See [helpers](./famodel/helpers.py) for the full list of yaml writing capabilities. 
+See [helpers](./fad/helpers.py) for the full list of yaml writing capabilities. 
 
 
 ## Authors

examples/01_Visualization/01_2D-visual_turbine_locations.py

@@ -5,11 +5,13 @@
                           site condition information, etc.)
 """
 
-from famodel import Project
+from fad import Project
 import matplotlib.pyplot as plt
+import os
 
 # define name of ontology input file
-input_file = '01_2D-visual_turbine_locations.yaml'
+dir = os.path.dirname(os.path.realpath(__file__))
+input_file = os.path.join(dir,'01_2D-visual_turbine_locations.yaml')
 
 # initialize Project class with input file, we don't need RAFT for this so mark False
 project = Project(file=input_file,raft=False)

examples/01_Visualization/01_2D-visual_turbine_locations.yaml

@@ -1,9 +1,22 @@
 
 # ----- Array-level inputs -----
 
-# Wind turbine array layout
+# platform array layout
 array:
     keys : [ID, topsideID, platformID, mooringID,   x_location,     y_location,   heading_adjust]
+    # ID: unique identifier for that platform/turbine system (can be anything you want)
+    # topside ID: index in list of topsides, which includes wind turbines (indices starting at 1. 0 means there is no topside). 
+    #             In this case, we have no topside design defined, so all are 0.
+    # platform ID: index in list of platforms, which includes FOWT platforms, substation platforms, etc. 
+    #              (indices starting at 1, 0 means there is no platform). In this case, we only have 1 platform design defined, so all are 1.
+    # mooringID: string/id of mooring system to apply to this platform if using mooring_system. 
+    #            If there is no mooring or you want to define the mooring lines individually (i.e. through array_mooring table),
+    #            then set mooringID=0, which means there is no mooring system and we've instead individually defined the mooring lines in the array_mooring table.
+    #            In this case, we have no mooring system defined, so all are 0.
+    # x_location: x coord of platform location 
+    # y_location: y coord of platform location
+    # z_location: z coord of platform location. For FOWTs generally is 0
+    # heading_adjust: rotation of platform relative to its 0 position defined for that platformID
     data : #    ID#        ID#        ID#          [m]             [m]           [deg]
         -  [fowt0,     0,         1,           0,          -1600,         -1600,          0   ]
         -  [fowt1,     0,         1,           0,          0,             -1600,          0     ]  
@@ -16,4 +29,4 @@ array:
         -  [fowt8,     0,         1,         0,          1600,           1600,            0   ] 
 
 platform:
-  type         :  FOWT
+  type         :  FOWT # type of platform, can be FOWT, substation, WEC, or other

examples/01_Visualization/02_visual_moorings.py

@@ -7,11 +7,13 @@
                                        site condition information, etc.)
 """
 
-from famodel import Project
+from fad import Project
 import matplotlib.pyplot as plt
+import os
 
 # define name of ontology input file
-input_file = '02_visual_moorings.yaml'
+dir = os.path.dirname(os.path.realpath(__file__))
+input_file = os.path.join(dir,'02_visual_moorings.yaml')
 
 # initialize Project class with input file, we don't need RAFT for this so mark False
 project = Project(file=input_file,raft=False)