2. Run a simulation with PointMass

The identification tag for this tutorial is PDS-AAB. Input files for this tutorial are found in the folder named PDS-AAB in the provided tutorial input files.

2.1. Tutorial overview

This tutorial covers:

  • Setting up the environment with waves
  • Resolving follower properties in PST
  • Creating a PointMass DObject
  • Setting PointMass state (initial conditions: position and velocity)
  • Changing the simulation run time
  • Running the simulation

2.2. What is a DObject and a DObject State?

  • Create a new ProteusDS project by launching PST, selecting Save, and then selecting a location to save your input files to. Each new project should be created in a new folder.

In general ProteusDS refers to simulated entities (e.g. mooring lines, vessels, controllers) as DObjects (dynamic objects). Important types of DObjects in ProteusDS are: Cable, RigidBody, PointMass and Net. All the DObjects instances in a simulation are listed in the Project Explorer in PST.

DObjects have a state that evolves through simulation. It is required to specify the state at the start of a simulation (i.e. the initial condition).

For example, in this tutorial a PointMass DObject will be created. The PointMass state is defined by its position and velocity.

2.3. Global coordinate frame definition

The states of most DObjects are defined with respect to a global reference frame. The global reference frame follows the North-East-Down (NED) convention, where the X-Y plane is fixed at the mean water surface level. The positive Z direction indicates increasing depth. The principle axis directions can be seen in Fig. 2.1.

The state of some DObjects are defined in terms of their position and orientation relative to the global coordinate frame.

alternate text

Fig. 2.1 Global coordinate system.

2.4. Resolving follower properties in PST

Recall ProteusDS has several key input files that are used to define the simulation. The environment and simulation input files are accessible from the Project Explorer in PST.

  • Click on Environment in the Project Explorer.

Certain properties in ProteusDS are defined as master properties. When a master property is set to any value, there will be additional follower properties required to be initialized in the input file. $WaveType and $CurrentProfile are examples of master properties in the Environment input file. PST has the ability to automatically input all the required follower properties for a specific master property. The Property Description Panel in the PST window will specify whether a property is a master property. Master properties will display [master] to the right of the property name, as shown in yellow in Fig. 2.2.

alternate text

Fig. 2.2 PST window displaying master property - see yellow highlighted [master] in the property description.

To automatically insert all the required follower properties, right click on the master property in the input panel and select Resolve Follower Properties, or use the hotkey, Ctrl-R. The required follower properties will initialize with their default values.

  • Change the $CurrentProfile property to 1 and resolve follower properties. $CurrentSpeed and $CurrentHeading should initialize.
  • Revert the $CurrentProfile back to its default value (no current) by right clicking on the property and selecting Revert Property to Default Value. The property will change to $CurrentProfile 0.

When a master property is changed, the follower properties must either be added or removed. Right click on the $CurrentProfile property and select Resolve All Required Follower Properties. The follower properties are no longer required and they will automatically be commented out.

  • The property declarations shown below show how to set an Airy wave profile with 2.5 m wave height, 5 s period, and with a heading of 0 deg. Set these properties in the environment input file.
  • Next, add waves to the simulation by changing $WaveType to 1, and resolving the follower properties.

Note

  • $WaveHeight 2.5 is used to set the wave height to 2.5 m.
  • $WaveHeading 0 is used to set the wave heading to 0 deg (along the global reference frame X axis or North).
  • $WavePeriod 5 is used to set the wave period as 5 s.
  • $EnvironmentTransitionMode is used to control the ramping of environmental conditions. Current, wave, and wind may be ramped over a set duration from a calm or initial state, and started at a specific time.
  • Set $EnvironmentTransitionMode 0 to specify a single ramp duration for all environmental properties. Since waves are the only environmental condition activated, only waves will be ramped. Resolve follower properties by right clicking on the master property in the input panel and selecting Resolve All Required Follower Properties, or use the hotkey Ctrl-R.

Note

  • $RampDuration will be added to the list of properties.
  • $RampDuration specifies the time over which environmental effects are ramped up to specified values at the start of the simulation. This eliminates any large artificial discontinuities that may occur at the start of the simulation due sudden changes to the environment.
  • Specify $RampDuration 2.
  • Ensure the wave properties in your simulation look like the listing below:
$WaveType 1
$WaveHeading 0
$WavePeriod 5
$WaveHeight 2.5

2.5. Creating a PointMass

  • Now that the simulation environment has been configured with waves and current, create a new DObject by clicking DObject button or typing Ctrl-D within PST.
  • Select PointMass from the drop down menu and provide the DObject with a name.

The new PointMass DObject is created and its input file is added to the list of DObjects in the Project Explorer. The required properties are populated with default values. A PointMass uses a reference sphere of uniform density to compute mass, weight, buoyancy, and hydrodynamic loads. It has three degrees of freedom and moves in the global X, Y, and Z directions. The PointMass hydrodynamic loads are governed by a drag and added mass coefficients and the diameter specified.

  • Leave the PointMass properties at default settings.

2.6. Viewing the PointMass in the 3D Visualizer

When a new PointMass DObject is created, it is placed by default at the simulation origin (global coordinates (0,0,0)).

  • Navigate to the visualizer window by pressing F4. The camera is centered on the global reference frame initially but can be freely moved around the environment.
  • Click and hold down the right mouse button on the visualization window and move the mouse to pan the camera.
  • Use the scroll wheel to zoom in and out. Once zoomed in, the PointMass DObject can be seen.
  • To move the camera, use the W, A, S, and D keys on the keyboard.
  • To reset the camera view to be centered on the PointMass, go to the PST window and select the PointMass DObject from the DObject tree on the left side of the screen. Once the DObject is selected, click the target button on the top left of the visualizer window. The camera will move to center on the PointMass DObject. This functionality can be used to quickly navigate large simulations in the 3D window.
alternate text

Fig. 2.3 PointMass DObject seen in the visualizer window.

2.7. Setting point mass state (initial conditions)

The .dat file contains information about the state of a DObject at the start of a simulation; the state of a PointMass is its position and velocity relative to the global reference frame.

  • To define the state for the PointMass (i.e. its initial position and velocity), first click on the name of the PointMass in the Project Explorer, and then click the State button or press Ctrl-K.
  • The Define State window will appear that will allow you to choose the starting position and velocity of the PointMass.
  • Choose a location of (0,0,0) m in the global X,Y,Z frame and choose a velocity of (0,0,0) m/s. This will place the PointMass on the global origin with an initial velocity of 0 in all directions.
  • Click Generate to close the window and update the defined initial state of the PointMass. The data (.dat) file corresponding to the initial state of the PointMass in the simulation can be seen in the Data file tab of the PointMass input file. The format for the file can be seen below:
<state >
0.0 // X velocity (m/s)
0.0 // X position (m)
0.0 // Y velocity (m/s)
0.0 // Y position (m)
0.0 // Z velocity (m/s)
0.0 // Z position (m)
</state >

2.8. Setting the simulation run time

  • To adjust properties associated with the simulation execution select Simulation in the Project Explorer.

In the simulation input file, the simulation start time, end time, and simulation data interval output is defined.

  • Change the end time to 10 seconds by setting $EndTime 10. The simulation will now simulate 10 seconds.
  • Leave all other values at default settings.