Merge remote-tracking branch 'origin/main' into IOandM_development

Author: RyanDavies19

.github/workflows/CI_FAModel.yml

@@ -0,0 +1,62 @@
+name: CI_FAModel
+
+# We run CI on push commits and pull requests on all branches
+on: [push, pull_request]
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+    build_conda:
+        name: Conda Build (${{ matrix.os }}) - ${{ matrix.python-version }}
+        runs-on: ${{ matrix.os }}
+        defaults:
+            run:
+                shell: bash -el {0}
+                
+        strategy:
+            fail-fast: false #true
+            matrix:
+                os: ["ubuntu-latest", "macOS-latest", "windows-latest"]
+                python-version: ["3.11", "3.12"]
+
+
+        steps:
+            - name: checkout repository
+              uses: actions/checkout@v4
+
+            - uses: conda-incubator/setup-miniconda@v3
+              # https://github.com/marketplace/actions/setup-miniconda
+              with:
+                  # To use mamba, uncomment here, comment out the miniforge line
+                  #mamba-version: "*"
+                  miniforge-version: "latest"
+                  auto-update-conda: true
+                  python-version: ${{ matrix.python-version }}
+                  environment-file: famodel-env.yaml
+                  activate-environment: test
+                  auto-activate-base: false
+                  channels: conda-forge
+                  channel-priority: true          
+
+            - name: Extras
+              run: |
+                  conda install -y pytest meson ninja nlopt
+                  conda info
+
+            - name: Conda Install famodel
+              run: |
+                  pip install -e .
+
+            - name: Overwrite MoorPy
+              run: |
+                  pip install git+https://github.com/NREL/MoorPy@dev
+
+            - name: Example run
+              run: |
+                  cd examples
+                  python example_driver.py false
+
+            - name: Test run
+              run: |
+                  cd tests
+                  pytest .
+

README.md

@@ -7,8 +7,8 @@ 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.
 
-The library works in conjunction with the tools RAFT and MoorPy to model floating
-wind turbines and mooring systems, respectively.
+The library works in conjunction with the tools RAFT, MoorPy, and FLORIS to model floating
+wind turbines, mooring systems, and array wakes respectively.
 
 In addition to the code, this repository defines a 
 [Floating Array Ontology](https://github.com/FloatingArrayDesign/FAModel/tree/main/famodel/ontology), 
@@ -19,6 +19,13 @@ of the Humboldt lease area is shown below.
 
 ![Humboldt](famodel/seabed/images/slopeview4.PNG)
 
+See example use cases in our [examples](https://github.com/FloatingArrayDesign/FAModel/tree/main/examples/README.md) folder.
+
+## Pre-installation Requirements
+The FAModel package is built entirely in Python. It is recommended that users familiarize themselves with basic Python commands before use.
+It is important to understand the general structure of FAModel and how to access models and stored information. Please see the model structure 
+document (./famodel/README.md).
+
 
 ## Installation
 To install FAModel itself, first clone the FAModel repository.
@@ -58,7 +65,7 @@ Make sure your virtual enviroment is activated before installing MoorPy.
 ## Subpackages
 
 The library has a core Project class for organizing information, classes for each component of an array and an evolving
-collection of subpackages for specific functions. The two current subpackages are:
+collection of subpackages for specific functions. The current subpackages are:
 
 - anchors: contains modules for anchor capacity calculations, in addition to the anchor class
 - failures: contains modules for failure modeling with graph theory, and allows for enactment of a failure mode in integrated FAModel tools such as MoorPy and RAFT.

environment_droplet.yml

@@ -0,0 +1,20 @@
+"""
+Simple driver file to create a 2d plot of an platform locations in an array.
+The input file only contains the bare minimum information to build a 2d plot 
+of the turbine locations (no moorings, cables, anchors, platform design, turbines, 
+                          site condition information, etc.)
+"""
+
+from famodel import Project
+import matplotlib.pyplot as plt
+
+# define name of ontology input file
+input_file = '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)
+
+# plot
+project.plot2d()
+
+plt.show()

examples/01_Visualization/01_2D-visual_turbine_locations.py

@@ -0,0 +1,19 @@
+
+# ----- Array-level inputs -----
+
+# Wind turbine array layout
+array:
+    keys : [ID, topsideID, platformID, mooringID,   x_location,     y_location,   heading_adjust]
+    data : #    ID#        ID#        ID#          [m]             [m]           [deg]
+        -  [fowt0,     0,         1,           0,          -1600,         -1600,          0   ]
+        -  [fowt1,     0,         1,           0,          0,             -1600,          0     ]  
+        -  [fowt2,     0,         1,           0,          1600,           -1600,          0   ]
+        -  [fowt3,     0,         1,         0,          -1600,          0,            0   ]
+        -  [fowt4,     0,         1,         0,          0,              0,            0   ]
+        -  [fowt5,     0,         1,         0,          1600,              0,            0   ]
+        -  [fowt6,     0,         1,        0,          -1600,           1600,            0   ]
+        -  [fowt7,     0,         1,         0,          0,              1600,            0   ]
+        -  [fowt8,     0,         1,         0,          1600,           1600,            0   ] 
+
+platform:
+  type         :  FOWT

examples/01_Visualization/01_2D-visual_turbine_locations.yaml

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""
+Simple driver file to create a 2d plot of an platform locations with
+mooring lines in an array.
+The input file only contains the bare minimum information to build a 2d plot 
+of the turbine locations and moorings (no cables, platform design, turbines, 
+                                       site condition information, etc.)
+"""
+
+from famodel import Project
+import matplotlib.pyplot as plt
+
+# define name of ontology input file
+input_file = '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)
+
+# plot
+project.plot2d()
+
+# to moorings plot in 3d, we'll need to add depth and create a moorpy model of the system
+project.depth = 200 # depth added because we did not include the site conditions section of the yaml
+project.getMoorPyArray()
+project.plot3d()
+
+plt.show()
+

examples/01_Visualization/02_visual_moorings.py

@@ -0,0 +1,65 @@
+
+# ----- Array-level inputs -----
+
+# Wind turbine array layout
+array:
+    keys : [ID, topsideID, platformID, mooringID,   x_location,     y_location,   heading_adjust]
+    data : #    ID#        ID#        ID#          [m]             [m]           [deg]
+        -  [fowt0,     0,         1,           ms1,          -1600,         -1600,          180   ]
+        -  [fowt1,     0,         1,           ms1,          0,             -1600,          0     ]  
+        -  [fowt2,     0,         1,           ms1,          1600,           -1600,            0   ]
+        -  [fowt3,     0,         1,           ms1,          -1600,          0,            0   ]
+        -  [fowt4,     0,         1,           ms1,          0,              0,            45   ]
+        -  [fowt5,     0,         1,           ms1,          1600,              0,            0   ]
+        -  [fowt6,     0,         1,           ms1,          -1600,           1600,            0   ]
+        -  [fowt7,     0,         1,           ms1,          0,              1600,            0   ]
+        -  [fowt8,     0,         1,           ms1,          1600,           1600,            0   ] 
+
+platform:
+  type         :  FOWT
+  rFair        :  58
+  zFair        :  -14
+
+
+
+# ----- Mooring system -----
+
+# Mooring system descriptions (each for an individual FOWT with no sharing)
+mooring_systems:
+ 
+    ms1:
+        name: 2-line semi-taut polyester mooring system with a third line shared
+        
+        keys: [MooringConfigID,  heading, anchorType, lengthAdjust] 
+        data:
+          - [  semitaut-poly_1,  150 ,    drag-embedment1,   0 ]
+          - [  semitaut-poly_1,  270 ,    drag-embedment1,   0 ]
+          - [  semitaut-poly_1,  30 ,     drag-embedment1,   0 ]
+
+
+# Mooring line configurations
+mooring_line_configs:
+
+    semitaut-poly_1:  # mooring line configuration identifier, matches MooringConfigID
+    
+        name: Semitaut polyester configuration 1  # descriptive name
+        
+        span: 642 # 2D x-y distance from fairlead to anchor
+        
+        sections:                 #in order from anchor to fairlead
+          - mooringFamily: chain      # ID of a mooring line section type
+            d_nom: .1549              # nominal diameter of material [m]
+            length: 497.7            # [m] usntretched length of line section
+          - mooringFamily: polyester        # ID of a mooring line section type
+            d_nom: .182              # nominal diameter of material [m]
+            length: 199.8           # [m] length (unstretched)
+
+
+
+# Anchor type properties
+anchor_types:
+
+    drag-embedment1:
+        type   :  DEA   # type of anchor (drag-embedment anchor)
+
+

examples/01_Visualization/02_visual_moorings.yaml

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+Simple driver file to create a 2d plot of an platform locations with
+mooring lines in an array.
+The input file only contains the bare minimum information to build a 2d plot 
+of the turbine locations and moorings (no cables, platform design, turbines, 
+                                       site condition information, etc.)
+"""
+
+from famodel import Project
+import matplotlib.pyplot as plt
+
+# define name of ontology input file
+input_file = '03_visual_cables.yaml'
+
+# initialize Project class with input file, we don't need RAFT for this so mark False
+project = Project(file=input_file,raft=False)
+
+# plot
+project.plot2d()
+
+# to plot cables in 3d, we'll need to add depth and create a moorpy model of the system
+project.depth = 200 # depth added because we did not include the site conditions section of the yaml
+project.getMoorPyArray()
+project.plot3d()
+
+plt.show()

examples/01_Visualization/03_visual_cables.py

@@ -0,0 +1,68 @@
+
+# ----- Array-level inputs -----
+
+# Wind turbine array layout
+array:
+    keys : [ID, topsideID, platformID, mooringID,   x_location,     y_location,   heading_adjust]
+    data : #    ID#        ID#        ID#          [m]             [m]           [deg]
+        -  [fowt0,     0,         1,           0,          -1600,         -1600,          0   ]
+        -  [fowt1,     0,         1,           0,          0,             -1600,          0     ]
+        -  [fowt2,     0,         1,           0,          1600,           -1600,          0   ]
+        -  [fowt3,     0,         1,         0,          -1600,          0,            0   ]
+        -  [fowt4,     0,         1,         0,          0,              0,            0   ]
+        -  [fowt5,     0,         1,         0,          1600,              0,            0   ]
+        -  [fowt6,     0,         1,        0,          -1600,           1600,            0   ]
+        -  [fowt7,     0,         1,         0,          0,              1600,            0   ]
+        -  [fowt8,     0,         1,         0,          1600,           1600,            0   ] 
+
+platform:
+  type         :  FOWT
+
+# Array cables 
+array_cables:   
+    keys:  [ AttachA,  AttachB,  DynCableA, DynCableB, headingA, headingB, cableType]
+    data:
+      - [ fowt0, fowt1, suspended_1, None, 90, 270, None] # suspended cable, so only one dynamic cable configuration, no static cable
+      - [ fowt1, fowt2, lazy_wave1,  lazy_wave1, 90, 270, static_cable_66]
+
+# Dynamic and cable configurations
+dynamic_cable_configs:
+# contains the subsections that make up each section of the subsea cable (i.e., what sections make up the lazywave cable in array_cable_1)              
+    lazy_wave1:
+        name: Lazy wave configuration 1 (simpler approach)
+        voltage: 66 # [kV]
+        span : 195    # [m] horizontal distance to end of dynamic cable from attachment point
+        A: 300  # cable conductor area [mm^2]
+        cable_type: dynamic_cable_66       # ID of a cable section type from famodel/cables/cableProps_default.yaml. Cable props loaded automatically from this!
+        length: 353.505                   # [m] length (unstretched) 
+        rJTube : 5 # [m] radial distance from center of platform that J-tube is located
+       
+        sections: 
+          - type: Buoyancy_750m # name of buoy type from famodel/cables/cableProps_default.yaml - buoy design info read in automatically from this!
+            L_mid: 200 # [m] from platform connection
+            N_modules: 6
+            spacing: 11.23 # [m]
+            V: 1 # [m^3]
+
+        
+    suspended_1:
+        name: Dynamic suspended cable configuration 1 
+        voltage: 33 # [kV]
+        span: 1512    # [m]
+        cable_type: dynamic_cable_66        # ID of a cable section type from famodel/cables/cableProps_default.yaml. Cable props loaded automatically from this!
+        A: 300 # cable conductor area [mm^2]
+        length: 1550                   # [m] length (unstretched)
+        rJTube : 58 # [m] radial distance from center of platform that J-tube is located
+            
+        sections:            
+          - type: Buoyancy_750m 
+            L_mid: 510 # [m] from end A
+            N_modules: 6
+            spacing: 18 # [m]
+            V: 2 # [m^3]
+            
+          - type: Buoyancy_750m 
+            L_mid: 1040 # [m] from end A
+            N_modules: 6
+            spacing: 18 # [m]
+            V: 2 # [m^3]

examples/01_Visualization/03_visual_cables.yaml

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""
+Simple driver file to create a 2d plot of bathymetry.
+The input file only contains the bare minimum information to build a 2d and 3d plot 
+of the bathymetry (no platforms, moorings, cables, platform design, turbines, 
+                                       site condition information, etc.)
+"""
+
+from famodel import Project
+import matplotlib.pyplot as plt
+
+# define name of ontology input file
+input_file = '04_visual_bathymetry.yaml'
+
+# initialize Project class with input file, we don't need RAFT for this so mark False
+project = Project(file=input_file,raft=False)
+
+# plot
+project.plot2d()
+
+project.plot3d()
+
+plt.show()