Add FOSWEC tutorial

.github/workflows/pr.yml

@@ -101,4 +101,4 @@ jobs:
       run: |
         git fetch --force --prune --tags
         git fetch --force --prune origin '+refs/heads/*:refs/remotes/origin/*'
-        python3 docs/build_docs.py --build production
+        python3 docs/build_docs.py --build debug

docs/source/conf.py

@@ -191,6 +191,11 @@ def _copy_examples() -> None:
         ignore=_all_but_nc,
         dirs_exist_ok=True,
     )
+    shutil.copytree(
+        os.path.join(project_root, 'examples/M4E_inputs'),
+        os.path.join(examples_dst, 'M4E_inputs'),
+        dirs_exist_ok=True,
+    )
 
 
 def _generate_theory_animations() -> None:

docs/source/tutorials.rst

@@ -13,13 +13,17 @@ The third part builds on the second to solve a design optimization problem, usin
 The second and third tutorials use the `AquaHarmonics`_ and `LUPA`_ WECs, respectively, and provide more robust optimization examples illustrating more complex cases of the WEC body, power take-off, applied forces, and constraints.
 These tutorials each have two parts, which are similar in structure to the second and third parts of Tutorial 1.
 
-    - :doc:`_examples/tutorial_2_AquaHarmonics`: Two part example with a realistic power take-off system and co-design study. You can find an extended version 
+    - :doc:`_examples/tutorial_2_AquaHarmonics`: Two part example with a realistic power take-off system and co-design study. You can find an extended version
     - :doc:`_examples/tutorial_3_LUPA`: Two part example with multiple bodies, multiple degrees of freedom, irregular waves, a mooring system, and realistic constraints.
 
 The fourth tutorial uses the `Pioneer WEC` model, which includes a unique pitch resonator PTO system. This tutorial illustrates how to use WecOptTool to implement and optimize control strategies for less common PTO archetypes.
 
     - :doc:`_examples/tutorial_4_Pioneer`: Example with custom PTO physics and modeling both hydrodynamic and non-hydrodynamic degrees of freedom.
 
+The fifth tutorial uses the `FOSWEC` model, which includes two flaps pitching relative to a floating platform. This tutorial illustrates how to use Multibody for Everybody to generate reduced-coordinate matrices and forces for WecOptTool.
+
+    - :doc:`_examples/tutorial_5_FOSWEC`: Example with multiple coupled bodies, code-to-code verification using a static solve, a multi-dof PTO representation, and a study of top-mounted ballast effects.
+
 .. toctree::
     :maxdepth: 3
     :hidden:
@@ -28,7 +32,7 @@ The fourth tutorial uses the `Pioneer WEC` model, which includes a unique pitch
     _examples/tutorial_2_AquaHarmonics
     _examples/tutorial_3_LUPA
     _examples/tutorial_4_Pioneer
-
+    _examples/tutorial_5_FOSWEC
 
 Simulating WEC Dynamics without optimization
 --------------------------------------------

examples/M4E_inputs/FOSWEC_M4E_inputs.py

@@ -0,0 +1,28 @@
+"""FOSWEC Multibody for Everybody input file.
+"""
+
+import numpy as np
+from multibody import JointSystem, normalize_prismatic
+
+# Set FOSWEC parameters
+platform_cg = [0, 0, -0.8]
+flap_center_distance_apart = 1.44
+flap_draft  = 0.59 
+cg_height_above_hinge = 0.17
+flap1_cg     = [-flap_center_distance_apart/2, 0, -flap_draft+cg_height_above_hinge] # from water surface/origin
+flap2_cg     = [flap_center_distance_apart/2, 0, -flap_draft+cg_height_above_hinge] # from water surface/origin
+flap_hinge_depth = 0.59
+
+# Define joints
+joints              = [[0, 1],[1, 2],[1, 3]] # Joint connectivity: [parent, child]
+types               = ['F', 'R', 'R']  # Joint types: 'R' for revolute, 'P' for prismatic, 'F' for floating
+parent_cg_to_joint  = [[0, platform_cg[2]],[flap1_cg[0],-platform_cg[2]-flap_hinge_depth],[flap2_cg[0],-platform_cg[2]-flap_hinge_depth]] # Vectors from parent's center-of-gravity (CG) to the joint location.
+joint_to_child_cg   = [[np.nan, np.nan],[0,flap_hinge_depth+flap1_cg[2]],[0,flap_hinge_depth+flap2_cg[2]]] # Vectors from the joint to the child's CG.
+prismatic_direction = [[np.nan, np.nan],[np.nan, np.nan],[np.nan, np.nan]] # For prismatic joints, the direction vector; for others, [nan, nan] is used.
+prismatic_direction = normalize_prismatic(prismatic_direction)
+
+# Create the JointSystem using the from_data class method and define initial conditions.
+joint_system        = JointSystem.from_data(joints, types, parent_cg_to_joint, joint_to_child_cg, prismatic_direction) # DO NOT MODIFY
+_, _, _, NDOF, _   = joint_system.coordinate_finder() # DO NOT MODIFY
+ic                  = np.zeros(2*sum(NDOF)) # Multiplied by 2 because is position and velocity
+ic[2]               = 0 * np.pi / 180  # Initial position of the first joint