Dev

README.md

@@ -1,6 +1,12 @@
-# FAModel
+# Floating Array Design Toolset
 
-The FAModel (or Floating Array Model) package serves as a high-level library for
+The Floating Array Design (FAD) Toolset is a collection of tools for
+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),
+which serves as a high-level library for efficiently
 modeling 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
@@ -10,27 +16,37 @@ 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.
 
-In addition to the code, this repository defines a 
-[Floating Array Ontology](https://github.com/FloatingArrayDesign/FAModel/tree/main/famodel/ontology), 
-which provides a standardized description format for floating wind farms. 
+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
+different purposes. 
 
-An example of use of these tools to model three mooring lines over the bathymetry 
-of the Humboldt lease area is shown below.
+In addition to standalone uses of the FAD Toolset, a coupling has been made with
+[Ard](https://github.com/WISDEM/Ard), a sophisticated and flexible wind farm
+optimization tool. This coupling allows Ard to use certain mooring system
+capabilities from FAD to perform layout optimization of floating wind farms
+with Ard's more advanced layout optimization capabilities.
 
-![Humboldt](famodel/seabed/images/slopeview4.PNG)
+The FAD Toolset works with the [IEA Wind Task 49 Ontology](https://github.com/IEAWindTask49/Ontology),
+which provides a standardized format for describing floating wind farm sites
+and designs. 
 
-See example use cases in our [examples](https://github.com/FloatingArrayDesign/FAModel/tree/main/examples/README.md) folder.
+See example use cases in our [examples](./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).
+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).
 
 
 ## Installation
-To install FAModel itself, first clone the FAModel repository.
+To install the FAD Toolset itself, first clone this FAD-Toolset repository.
 
-The dependencies required by FAModel depend on how it is used. To install all
+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.
@@ -41,24 +57,25 @@ run the following command:
 
     conda env create -f famodel-env.yaml
 
-This command will install all the dependencies required to run FAModel.
-Activate your virtual environment before using FAModel with ```conda activate famodel-env```
+This command will install all the dependencies required to run FAD.
+Activate your virtual environment before using FAD with ```conda activate famodel-env```
 
-To install the FAModel package in your environment, enter the 
-following in the command line from the FAModel directory.
+To install the FAD Toolset package in your environment, enter the 
+following in the command line from the FAD-Toolset directory.
 
 For development use:
 
-run ```python setup.py develop``` or ```pip install -e .``` from the command line in the main FAModel directory.
+run ```python setup.py develop``` or ```pip install -e .``` from the command 
+line in the main FAD-Toolset directory.
 
 For non-development use:
 
-run ```python setup.py``` or ```pip install .``` from the command line in the main FAModel directory.
+run ```python setup.py``` or ```pip install .``` from the command line in 
+the main FAD-Toolset directory.
 
-** At this time, FAModel requires the latest MoorPy development branch version to be used. **
-Therefore, you must install MoorPy with ```git clone https://github.com/NREL/MoorPy.git```
-then navigate to the MoorPy folder and checkout the development branch with ```git checkout dev```
-Finally, install this version into your environment with ```pip install -e .```.
+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.
 
 
@@ -68,19 +85,30 @@ The library has a core Project class for organizing information, classes for eac
 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.
+- failures: contains modules for failure modeling with graph theory, and allows for enactment of a failure mode.
 - seabed: contains modules for seabed bathymetry and boundary information
+- design: contains various tools for performing design steps.
 
 Please navigate into the subfolders above for additional information.
 
 ## Getting Started
-The easiest way to create an FAModel project is to provide the array information in an ontology yaml file. FAModel has been designed to work with a specific ontology yaml setup, which is described in detail in the [Ontology ReadMe](./famodel/ontology/README.md).
-
-The [example driver file](./famodel/example_driver.py) creates an FAModel project 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), then either adapt one of the ontology samples or fill in the ontology template. 
-
-The [FAModel core readme](./famodel/README.md) describes the FAModel class structure, as well as the properties and methods of each component class. 
-
-There are some limited helper functions to auntomatically fill in sections of a yaml from a moorpy system or a list of platform locations. See [FAModel helpers](./famodel/helpers.py) for the full list of yaml writing capabilities. Many of these are a work in progress.
+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).
+
+The [example driver file](./famodel/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), 
+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, 
+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. 
 
 
 ## Authors

examples/01_Visualization/02_visual_moorings.yaml

@@ -30,11 +30,11 @@ mooring_systems:
     ms1:
         name: 2-line semi-taut polyester mooring system with a third line shared
 
-        keys: [MooringConfigID,  heading, anchorType, lengthAdjust] 
+        keys: [MooringConfigID,  heading, anchorType] 
         data:
-          - [  semitaut-poly_1,  150 ,    drag-embedment1,   0 ]
-          - [  semitaut-poly_1,  270 ,    drag-embedment1,   0 ]
-          - [  semitaut-poly_1,  30 ,     drag-embedment1,   0 ]
+          - [  semitaut-poly_1,  150 ,    drag-embedment1]
+          - [  semitaut-poly_1,  270 ,    drag-embedment1]
+          - [  semitaut-poly_1,  30 ,     drag-embedment1]
 
 
 # Mooring line configurations

examples/01_Visualization/03_visual_cables.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """
 Simple driver file to create a 2d plot of an platform locations with
-mooring lines in an array.
+cables 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, 
+of the turbine locations and cables (no moorings, platform design, turbines, 
                                        site condition information, etc.)
 """
 

examples/01_Visualization/03_visual_cables.yaml

@@ -35,7 +35,6 @@ dynamic_cable_configs:
         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!
@@ -51,8 +50,7 @@ dynamic_cable_configs:
         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
+        length: 1650                   # [m] length (unstretched)
 
         sections:            
           - type: Buoyancy_750m 

examples/08_Design_Adjustment/01_Fairleads.yaml

@@ -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,           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
+  fairleads    : # list of fairlead coordinates for the platform relative to platform coordinate and 0-degree heading
+                - name     : fairlead1
+                  r_rel    : [58, 0, -14]
+                  headings : [30, 150, 270]
+
+
+
+
+# ----- 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, fairlead] 
+        data:
+          - [  semitaut-poly_1,  135 ,    drag-embedment1, 2]
+          - [  semitaut-poly_1,  270 ,    drag-embedment1, 3]
+          - [  semitaut-poly_1,  45 ,     drag-embedment1, 1]
+
+
+# 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/08_Design_Adjustment/02_Jtubes.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+Simple driver file to create a 2d plot of an platform locations with
+cables in an array using Jtubes to define platform connection location.
+The input file only contains the bare minimum information to build a 2d plot 
+of the turbine locations and cables connected to Jtubes (no moorings, 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_Jtubes.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/08_Design_Adjustment/02_Jtubes.yaml

@@ -0,0 +1,71 @@
+
+# ----- 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
+  Jtubes       :
+                - name: Jtube1
+                  r   : 5
+                  z   : -20
+                  headings : [90, 210, 330] # headings in degrees for the Jtube (if multiple headings, the Jtube will be repeated for each heading)
+
+# Array cables 
+array_cables:   
+    keys:  [ AttachA,  AttachB,  DynCableA, DynCableB, headingA, headingB, JtubeA, JtubeB, cableType]
+    data:
+      - [ fowt0, fowt1, suspended_1, None, 90, 270, 1, 2, None] # suspended cable, so only one dynamic cable configuration, no static cable
+      - [ fowt1, fowt2, lazy_wave1,  lazy_wave1, 90, 270, 1, 3, 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) 
+
+        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: 1650                   # [m] length (unstretched)
+
+        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/08_Design_Adjustment/02_fairleads.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+"""
+Simple driver file to create an array showing moorings attached to fairelead objects.
+
+This allows you to connect moorings to platforms at a specific point and then run
+mooring headings independent of the heading of this connection point.
+The input file only contains the bare minimum information to build a 2d plot 
+of the turbine locations and moorings with fairleads (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 = '01_Fairleads.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()
+