RAFT model update, documentation improvements, fairlead warning

lsirkis · lsirkis · commit 277bdd947c27 · 2025-12-10T11:38:05.000-07:00
-- updated RAFT development to allow creation of raft input dictionary based on project state rather than just input yaml
	- you can use helpers.createRAFTDict() to create a RAFT dictionary input based on project's current state, then call project.getRAFT() to make the raft model
	- this process is shown in examples/03_Frequency_Domain_Analysis_RAFT/02_FOWT
	- fixes small bug if getRAFT is called multiple times, to ensure the platform heading is not reversed
-- documentation imporvements to examples in examples/02_Mooring_Analysis_MoorPy and examples/08_Design_Adjustment/01_Fairleads.yaml
-- added exception when loading in a yaml if multiple moorings attached to 1 fairlead. This is a common mistake in yamls, so this exception explains the error and hwo to fix
diff --git a/examples/01_Visualization/02_visual_moorings.yaml b/examples/01_Visualization/02_visual_moorings.yaml
@@ -70,10 +70,10 @@ mooring_line_configs:
         sections:                 #in order from anchor to fairlead
           - mooringFamily: chain      # ID of a mooring line section material type 
                                       # (alternatively could define mooring material properties in a mooring_line_properties section and use type: <mooring prop id> instead of mooringFamily and d_nom))
-            d_nom: .1549              # nominal diameter of material [m] (not required if using type: <mooring prop id> instead of mooringFamily)
+            d_nom: .1549              # nominal diameter of material [m] (used to scale the material properties of the line correctly) (not required if using type: <mooring prop id> instead of mooringFamily)
             length: 497.7            # [m] usntretched length of line section
           - mooringFamily: polyester        # ID of a mooring line section material type
-            d_nom: .182              # nominal diameter of material [m]
+            d_nom: .182              # nominal diameter of material [m] (used to scale the material properties of the line correctly) (not required if using type: <mooring prop id> instead of mooringFamily)
             length: 199.8           # [m] length (unstretched)
 
 
diff --git a/examples/02_Mooring_Analysis_MoorPy/01_moorings.yaml b/examples/02_Mooring_Analysis_MoorPy/01_moorings.yaml
@@ -9,19 +9,12 @@ 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     ]    # 2 array, shared moorings
-        # -  [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   ] 
+        -  [fowt0,     0,         1,           ms1,          -1600,         -1600,          0   ]
 
 platform:
-  type         :  FOWT
-  rFair        :  58
-  zFair        :  -14
+  type         :  FOWT # designates a floating offshore wind turbine platform. other types can be WEC (wave energy converter), substation, etc
+  rFair        :  58 # fairlead radius from platform center [m]
+  zFair        :  -14 # fairlead depth from platform center [m]
 
 
 
@@ -34,7 +27,15 @@ mooring_systems:
         name: 2-line semi-taut polyester mooring system with a third line shared
         
         keys: [MooringConfigID,  heading, anchorType, lengthAdjust] 
+        # MooringConfigID: references a key from mooring_line_configs section.
+        #                  In this case, we have a mooring line configuration defined below called 'semitaut-poly_1'. Each mooring line in this system (ms1) uses that configuration.                  
+        # heading: compass heading, relative to 0 deg platform heading
+        #          In this case, we have a mooring line at 150 deg (Southeast if platform heading is 0), 
+        #          a line at 270 deg (due West if platform heading is 0), and a line at 30 deg (Northeast if platform heading is 0).
+        # anchorType: references a key from anchor_types section. In this case, we have a drag-embedment anchor type defined below called 'drag-embedment1'. 
+        #             Each mooring line in this system (ms1) uses that anchor type.
         data:
+          # the order of lines here corresponds to the order they are added to the project mooringList, and affects their name. The first line will have name fowt0a, second fowt0b, etc.
           - [  semitaut-poly_1,  150 ,    drag-embedment1,   0 ]
           - [  semitaut-poly_1,  270 ,    drag-embedment1,   0 ]
           - [  semitaut-poly_1,  30 ,     drag-embedment1,   0 ]
@@ -50,11 +51,11 @@ mooring_line_configs:
         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]
+          - mooringFamily: chain      # ID of a mooring line material
+            d_nom: .1549              # nominal diameter of material [m] (used to scale the material properties of the line correctly)
             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]
+          - mooringFamily: polyester        # ID of a mooring line material
+            d_nom: .182              # nominal diameter of material [m] (used to scale the material properties of the line correctly)
             length: 199.8           # [m] length (unstretched)
 
 
diff --git a/examples/02_Mooring_Analysis_MoorPy/02_moorings_cables.yaml b/examples/02_Mooring_Analysis_MoorPy/02_moorings_cables.yaml
@@ -11,12 +11,6 @@ array:
         -  [fowt0,     0,         1,           ms1,          -1600,         -1600,          0    ]
         -  [fowt1,     0,         1,           ms1,          0,             -1600,          180  ]    # 2 array, shared moorings
         -  [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
@@ -42,7 +36,7 @@ mooring_systems:
 
 # Mooring line configurations
 mooring_line_configs:
-
+    # see 01_moorings.yaml in this folder or 01_Visualization/02_visual_moorings.yaml for explanation of each entry
     semitaut-poly_1:  # mooring line configuration identifier, matches MooringConfigID
     
         name: Semitaut polyester configuration 1  # descriptive name
@@ -76,22 +70,22 @@ array_cables:
 
 # 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)              
+# contains the subsections that make up each section of the subsea dynamic cable (i.e., what sections make up the lazywave cable in array_cable_1)              
     lazy_wave1:
-        name: Lazy wave configuration 1 (simpler approach)
+        name: Lazy wave configuration 1
         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!
+        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
+        rJTube : 5 # [m] radial distance from center of platform that J-tube is located, can be used instead of a J-tube designation in the platform description
        
         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]
+            L_mid: 200 # [m] length of cable from platform connection to midpoint of buoyancy section
+            N_modules: 6 # number of buoyancy modules
+            spacing: 11.23 # [m] spacing between buoyancy modules
+            V: 1 # [m^3] volume of each buoyancy module, used to scale buoyancy module properties
 
         
     suspended_1:
diff --git a/examples/02_Mooring_Analysis_MoorPy/03_platform-hydrostatics.yaml b/examples/02_Mooring_Analysis_MoorPy/03_platform-hydrostatics.yaml
@@ -11,22 +11,16 @@ array:
         -  [fowt0,     0,         1,           ms1,          -1600,         -1600,          0    ]
         -  [fowt1,     0,         1,           ms1,          0,             -1600,          180  ]    # 2 array, shared moorings
         -  [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
-  hydrostatics :  {m: 19911423.956678286,
-                   rCG: [ 1.49820657e-15,  1.49820657e-15, -2.54122031e+00],
-                   v: 19480.104108645974,
-                   rM: [2.24104273e-15, 1.49402849e-15, 1.19971829e+01],
-                   AWP: 446.69520543229874}
+  hydrostatics :  {m: 19911423.956678286, # mass centered at CG [kg]
+                   rCG: [ 1.49820657e-15,  1.49820657e-15, -2.54122031e+00], # center of gravity [m]
+                   v: 19480.104108645974, # volume [m^3]
+                   rM: [2.24104273e-15, 1.49402849e-15, 1.19971829e+01], # coordinates or height of metacenter relative to body reference frame [m]
+                   AWP: 446.69520543229874} # waterplane area [m^2]
 
 
 
@@ -74,53 +68,3 @@ anchor_types:
     drag-embedment1:
         type   :  DEA   # type of anchor (drag-embedment anchor)
 
-
-# Array cables 
-array_cables:   
-    keys:  [ AttachA,  AttachB,  DynCableA, DynCableB, headingA, headingB, cableType]
-    data:
-      - [ fowt0, fowt1, suspended_1, None, 90, 90, None] # suspended cable, so only one dynamic cable configuration, no static cable
-      - [ fowt1, fowt2, lazy_wave1,  lazy_wave1, 240, 300, 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: 1500                   # [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]
-
diff --git a/examples/03_Frequency_Domain_Analysis_RAFT/02_FOWT.py b/examples/03_Frequency_Domain_Analysis_RAFT/02_FOWT.py
@@ -8,15 +8,29 @@
 from famodel import Project
 import matplotlib.pyplot as plt
 import os
+from famodel.helpers import createRAFTDict
 
 # define name of ontology input file
 dir = os.path.dirname(os.path.realpath(__file__))
 input_file = os.path.join(dir,'02_FOWT.yaml')
 
-# initialize Project class with input file, we don't need RAFT for this so mark False
+# initialize Project class with input file
 project = Project(file=input_file,raft=True)
 
-# pull out RAFT object, this will only have a raft platform (no turbine), because we didn't specify a RAFT turbine definition in the ontology file
+project.plot3d(plot_fowt=True) # plot the system
+
+# - - - Let's adjust the heading of one platform, and then re-create the raft model - - - 
+project.platformList['fowt0'].setPosition(project.platformList['fowt0'].r, heading=180, degrees=True) # rotate platform 180 degrees
+
+project.getMoorPyArray() # re-create the moorpy array
+
+rd = createRAFTDict(project) # create new raft input dictionary that will account for the heading change
+
+project.getRAFT(rd) # create new RAFT model
+
+project.plot3d(plot_fowt=True) # plot updated system
+
+# pull out RAFT object
 raft_model = project.array # store short cut to raft model 
 
 # - - - Let's try running a case - - - 
diff --git a/examples/08_Design_Adjustment/01_Fairleads.yaml b/examples/08_Design_Adjustment/01_Fairleads.yaml
@@ -17,10 +17,12 @@ array:
 
 platform:
   type         :  FOWT
-  fairleads    : # list of fairlead coordinates for the platform relative to platform coordinate and 0-degree heading
+  fairleads    : # list of fairlead coordinates for the platform relative to 0-degree heading
                 - name     : fairlead1
                   r_rel    : [58, 0, -14]
-                  headings : [30, 150, 270]
+                  headings : [30, 150, 270] # corresponds to 1,2, and 3 indices for fairlead entry in mooring_systems table below
+                  # if a platform is at 0 degree heading and placed at [0,0,0] location, the fairleads would be at [29, 50.23, -14], [29, -50.23, -14], and [-58, 0, -14] respectively
+                  # if a platform is at 45 degree heading and placed at [0, 0, 0]
 
 
 
@@ -35,9 +37,9 @@ mooring_systems:
         
         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]
+          - [  semitaut-poly_1,  135 ,    drag-embedment1, 2] # fairlead index from platform fairleads list above, corresponds to fairlead attachment at 150 deg, but then mooring line extends outward at 135 deg
+          - [  semitaut-poly_1,  270 ,    drag-embedment1, 3] # corresponds to fairlead attachment at 270 deg heading for mooring line extending outward at 270 deg
+          - [  semitaut-poly_1,  45 ,     drag-embedment1, 1] # corresponds to fairlead attachment at 30 deg heading for mooring line extending outward at 45 deg
 
 
 # Mooring line configurations
diff --git a/examples/checkyaml.yaml b/examples/checkyaml.yaml
diff --git a/famodel/helpers.py b/famodel/helpers.py
diff --git a/famodel/project.py b/famodel/project.py
