PTO Extension Feature (WEC-Sim#1198)

* Add Extension feature to ptoClass * Added PTO Extension Documentation * WECCCOMP Extension Image Upload * Updated mask and prismatic joint block for wecsim pto library * Added Changes to PTO file and reverted to 2020b * Revert WEC-Sim Library to older version * PTO Extension Applications Documentation * Delete WECSim_Lib_PTOs.slx * Updated pto.rst file * Updated Rotational PTO * Updates to Rotational PTO and version control * save main library file to R2020b * add parameter validation for pto.extension * spherical pto - add pto.extension, fix rigid transforms * docs revision 1 * update units called out in ptoclass * update extension units, mask code in pto library * add extension feature to relevant constraints * doc update 2 * fix extension direction in rotational joints * update units and mask initialization --------- Co-authored-by: akeeste <[email protected]>
akeeste · Mar 27, 2024 · 1c2e8dd · 1c2e8dd
1 parent 0ffa77a
commit 1c2e8dd
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 1 deletion.
diff --git a/docs/_include/pto.rst b/docs/_include/pto.rst
@@ -86,6 +86,72 @@ recommended that hard-stops are implemented in a similar fashion using an
 Actuation Force/Torque PTO block in which the actuation force is specified in a 
 custom MATLAB Function block. 
 
+.. _pto-pto-extension:
+
+Setting PTO or Constraint Extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The PTO and Constraint classes have an Extension value that
+can be specified to define the initial displacement of 
+the PTO or constraint at the beginning of the simulation, allowing the user to set the 
+ideal position for maximum wave capture and energy generation. This documentation
+will use the PTO as an example, but the proces is applicable to both translational, 
+rotational, or spherical PTOs and constraints. 
+Whereas the initial displacement feature only defines this updated position for the PTO,
+the PTO Extension feature propagates the change in position to all bodies and joints
+on the Follower side of the PTO block. This allows for an accurate reflection of the 
+initial locations of each component without having to calculate and individually
+define each initial displacement or rotation. To set the extension of a PTO, the 
+following parameter must be specified in ``wecSimInputFile.m``::
+
+	pto(i).extension.PositionTargetSpecify = '1'
+
+to enable the joint's target position value to be defined. The specifics of the 
+extension are described in turn by::
+
+	pto(i).extension.PositionTargetValue
+	pto(i).extension.PositionTargetPriority
+
+``PositionTargetValue`` defines the extension magnitude and ``PositionTargetPriority``
+specifies Simulink's priority in setting the initial target value in regards
+to other constraints and PTOs. The priority is automatically set to "High" when 
+the extension is initialized but can be adjusted to "Low" if required by Simulink.
+
+The figure below shows the PTO extension feature on the WECCCOMP model at 0.1 m.
+The left image is at equilibrium (:code:`pto(i).extension.PositionTargetSpecify=0`),
+and the right image set as
+:code:`pto(i).extension.PositionTargetSpecify=1` with the WEC body moving in 
+accordance with the set PTO Extension value.
+
+.. figure:: /_static/images/WECCCOMP_PTO_Extension.png
+   :align: center
+   :width: 500pt
+
+   ..
+
+   WECCCOMP Model PTO Extension
+
+While this method generally fits most WEC models, there are specific 
+designs such as the RM3 that may have a larger DOF and are dependent on
+the particular block orientation in the simulink model in terms of which 
+body blocks will move in response to a PTO initial extension. These specific 
+cases require extra setup on the users end if looking to define a 
+different body's motion than the one automatically established. For the RM3
+model, a set PTO Extension value results in movement in the float body.
+However, if the user would like the movement to be within the spar instead,
+extra steps are required. To view examples of how to set the PTO Extension
+for both the float as well as the spar view the RM3 PTO Extension examples
+on the `WEC-Sim Applications repository 
+<https://github.com/WEC-Sim/WEC-Sim_Applications>`_ .
+
+For the spherical PTO which can rotate about three axes, 
+``pto(i).extension.PositionTargetValue`` must be a 1x3 array that specifying
+three consecutive rotations about the Base frame's axes in the X-Y-Z convention.
+
+.. Note:: 
+   The PTO extension is not valid for PTO already actuated by user-defined motion
+   (Translational PTO Actuation Motion, Rotational PTO Actuation Motion).
+
 .. _pto-pto-sim:
 
 PTO-Sim

diff --git a/docs/_static/images/WECCCOMP_PTO_Extension.png b/docs/_static/images/WECCCOMP_PTO_Extension.png
diff --git a/docs/user/applications.rst b/docs/user/applications.rst
@@ -130,6 +130,12 @@ Examples of WEC-Sim models using PTO-Sim are included for the :ref:`RM3 <user-tu
 geometry and :ref:`OSWEC <user-tutorials-oswec>`
 geometry.
 
+RM3 PTO Extension
+^^^^^^^^^^^^^^^^^
+
+Examples on using the :ref:`PTO Extension <pto-pto-extension>` advanced feature to set-up an initial displacement of the :ref:`RM3 <user-tutorials-rm3>` easily.
+This geometry is a special case with a large DOF in which different WEC bodies can be identified as the PTO mechanism with a cooresponding position change when setting the PTO Initial Displacement. 
+
 Visualization Markers
 ^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/source/lib/WEC-Sim/WECSim_Lib.slx b/source/lib/WEC-Sim/WECSim_Lib.slx
diff --git a/source/lib/WEC-Sim/WECSim_Lib_Constraints.slx b/source/lib/WEC-Sim/WECSim_Lib_Constraints.slx
diff --git a/source/lib/WEC-Sim/WECSim_Lib_PTOs.slx b/source/lib/WEC-Sim/WECSim_Lib_PTOs.slx
diff --git a/source/objects/constraintClass.m b/source/objects/constraintClass.m
@@ -42,6 +42,10 @@
           'lowerLimitTransitionRegionWidth',    1e-4)                       % (`float`) Define lower limit transition region, over which spring and damping values ramp up to full values. Increase for stability. m or deg. ``Default = 1e-4``                                                                                    
         initial (1,1) struct                    = struct(...                % 
             'displacement',                     [0 0 0])                    % (`structure`) Defines the initial displacement of the constraint. ``displacement`` (`3x1 float vector`) is defined as the initial displacement of the constraint [m] in the following format [x y z], Default = [``0 0 0``].
+        extension (1,1) struct                      = struct(...            % (`structure`) Defines the constraint extension
+            'PositionTargetSpecify',                0,...                   % (`float`) Initialize constraint extension. `` '0' or '1' `` Default = '0'.
+            'PositionTargetValue',                  0,...                   % (`float`) Define extension value, in m or deg.
+            'PositionTargetPriority',               'High')                 % (`string`) Specify priority level for extension. `` 'High' or 'Low' `` Default = ``High``.
         location (1,3) {mustBeNumeric}          = [999 999 999]             % (`1x3 float vector`) Constraint location [m]. Defined in the following format [x y z]. Default = ``[999 999 999]``.        
         name (1,:) {mustBeText}                 = 'NOT DEFINED'             % (`string`) Specifies the constraint name. For constraints this is defined by the user, Default = ``NOT DEFINED``.
         orientation (1,1) struct                = struct(...                % (`structure`) Defines the orientation axis of the constraint.
@@ -108,6 +112,10 @@ function checkInputs(obj)
                 assert(isequal(size(obj.orientation.rotationMatrix)==[3,3],[1,1]),'Input constraint.orientation.rotationMatrix should be 3x3')
                 mustBeNumeric(obj.orientation.rotationMatrix)
             end
+            % Extension
+            mustBeMember(obj.extension.PositionTargetSpecify,[0,1])
+            mustBeNumeric(obj.extension.PositionTargetValue)
+            mustBeMember(obj.extension.PositionTargetPriority,{'High','Low'})
         end
 
         function obj = checkLoc(obj,action)

diff --git a/source/objects/ptoClass.m b/source/objects/ptoClass.m
@@ -44,13 +44,17 @@
             'lowerLimitTransitionRegionWidth',      1e-4)                   % (`float`) Define lower limit transition region, over which spring and damping values ramp up to full values. Increase for stability. m or deg. ``Default = 1e-4``    
         initial (1,1) struct                        = struct(...            % (`structure`) Defines the PTO initial displacement
             'displacement',                         [0 0 0])                % (`structure`) Defines the initial displacement of the pto. ``displacement`` (`3x1 float vector`) is defined as the initial displacement of the pto [m] in the following format [x y z], Default = [``0 0 0``].
+        extension (1,1) struct                      = struct(...            % (`structure`) Defines the PTO extension
+            'PositionTargetSpecify',                0,...                   % (`float`) Initialize PTO extension. `` '0' or '1' `` Default = '0'.
+            'PositionTargetValue',                  0,...                   % (`float`) Define extension value, in m or deg.
+            'PositionTargetPriority',               'High')                 % (`string`) Specify priority level for extension. `` 'High' or 'Low' `` Default = ``High``.
         location (1,3) {mustBeNumeric}              = [999 999 999]         % (`3x1 float vector`) PTO location [m]. Defined in the following format [x y z]. Default = ``[999 999 999]``.
         name (1,:) {mustBeText}                     = 'NOT DEFINED'         % (`string`) Specifies the pto name. For ptos this is defined by the user, Default = ``NOT DEFINED``. 
         orientation (1,1) struct                    = struct(...            % (`structure`) Defines the PTO orientation
             'z',                                    [0, 0, 1], ...          % 
             'y',                                    [0, 1, 0], ...          % 
             'x',                                    [], ...                 % 
-            'rotationMatrix',                       [])                     % (`structure`) Defines the orientation axis of the pto. ``z`` (`1x3 float vector`) defines the direciton of the Z-coordinate of the pto, Default = [``0 0 1``]. ``y`` (`1x3 float vector`) defines the direciton of the Y-coordinate of the pto, Default = [``0 1 0``]. ``x`` (`1x3 float vector`) internally calculated vector defining the direction of the X-coordinate for the pto, Default = ``[]``. ``rotationMatrix`` (`3x3 float matrix`) internally calculated rotation matrix to go from standard coordinate orientation to the pto coordinate orientation, Default = ``[]``.
+            'rotationMatrix',                       [])                     % (`structure`) Defines the orientation axis of the pto. ``z`` (`1x3 float vector`) defines the direction of the Z-coordinate of the pto, Default = [``0 0 1``]. ``y`` (`1x3 float vector`) defines the direction of the Y-coordinate of the pto, Default = [``0 1 0``]. ``x`` (`1x3 float vector`) internally calculated vector defining the direction of the X-coordinate for the pto, Default = ``[]``. ``rotationMatrix`` (`3x3 float matrix`) internally calculated rotation matrix to go from standard coordinate orientation to the pto coordinate orientation, Default = ``[]``.
         pretension (1,1) {mustBeNumeric}            = 0                     % (`float`) Linear PTO pretension, N or N-m. Default = `0`.
         stiffness (1,:) {mustBeNonnegative}         = 0                     % (`float`) Linear PTO stiffness coefficient. Default = `0`.        
     end
@@ -112,6 +116,10 @@ function checkInputs(obj)
                 assert(isequal(size(obj.orientation.rotationMatrix)==[3,3],[1,1]),'Input pto.orientation.rotationMatrix should be 3x3')
                 mustBeNumeric(obj.orientation.rotationMatrix)
             end
+            % Extension
+            mustBeMember(obj.extension.PositionTargetSpecify,[0,1])
+            mustBeNumeric(obj.extension.PositionTargetValue)
+            mustBeMember(obj.extension.PositionTargetPriority,{'High','Low'})
         end
 
         function obj = checkLoc(obj,action)