Motions

Wall boundary particles can be moved during a simulation with a prescribed motion. Depending on the type of the imposed motion, different values must be defined.

Background

The principal concept is to define a motion for a specific phase and apply this motion within a given time-frame. Similar to the phases, different motions are defined consecutively. Using this approach it is possible to combine different motions for one and the same phase at different times. Thus, it is possible to realize more complex motions with a combination of existing motion types. However, if a special motion is required it is worth it to contact the nanoFluidX support. It might be easier/faster to improve the available motion types for special customer requests.

Before proceeding with the glossary of related commands for the motion setup, there is an important disclaimer that has to be made. Given the current structure of nanoFluidX, there are clear rules regarding which motions can be combined, executed in sequence or modified upon restart.

Motion combinations that are well-behaved and accounted for:
  • A - impose_vel+impose_vel (allowed for all)
  • C - rotate_axis+rotate_axis (allowed if only different in time and freq, other differences may cause unknown behavior)
  • D - planetary+planetary (allowed if only different in time and freq)
  • E - conrod+conrod (allowed if only different in time and freq)
  • F - position_file+position_file (not allowed)
  • G - trn_osc+trn_osc (allowed if only different in time and freq)
  • H - passive_rigid_body+passive_rigid_body (not allowed)
  • K - C+A (allowed)
  • L - D+A (allowed)
  • M - E+A (not allowed, unknown behavior)
  • N - C+D or D+C (not allowed, unknown behavior)
  • O - A+C (allowed, A is discarded)
  • P - A+D (allowed, A is discarded)
  • Q - F+Others or Others+F (not allowed, A+F/F+A may behave correctly though)
  • R - G+Others or Others+G (not allowed, unknown behavior)
  • S - H+Others or Others+H (not allowed)
Restart/continue (recon) clarifications:
  • Motions should not be removed from a restart/continue
  • Motions may be added to the restart/continue
  • If a motion has to have a transition at the restart time, one may modify the ending of the first motion and add the second one from the start of the restart/continue time.
Example for restart/continue, clean run:
motion1{ROTATE_AXIS; start 0; end 10}
Example for restart/continue from 5, add a second motion:
motion1{ROTATE_AXIS; start 0; end 5}
motion2{ROTATE_AXIS; start 5; end 10}

Commands

motions
{
       motion
       {
           phase_motion                    1
           motion_type                     IMPOSE_VEL 
           impose_vel                      "0. 0. 1."
           tstart_prescribe                0.
           tend_prescribe                  2.
           t_damping                       0.5
       }
       motion
       {
           phase_motion                    2
           motion_type                     ROTATE
           freq_unit                       RPM			
           rot_freq                        "50. 0. 0."
           rot_freq_init                   "0. 0. 0."
           rot_cntr                        "0. 0. 0."
           tstart_prescribe                0.
           tend_prescribe                  3.
           t_damping                       0.5
           max_dist                        0.1
       }
       motion
       {   
           phase_motion                    2
           motion_type                     ROTATE_AXIS
           freq_unit                       Hz			 
           rot_axis                        "1. 0. 0."
           rot_axis_freq                   50.0
           rot_axis_freq_init              0.0
           rot_cntr                        "0. 0. 0."
           tstart_prescribe		   0.
           tend_prescribe                  3.
           t_damping                       0.5
           max_dist                        0.1
       }
       motion
       {
           phase_motion                    1
           motion_type                     POSITION_FILE
           positionFile                    motionfile.txt
           rot_cntr                        "0. 0. 0."		
           isOrientation                   false
           tstart_prescribe                0.
           tend_prescribe                  1.
       }
       motion
       {
           phase_motion                    3
           motion_type                     PLANETARY    
           freq_unit                       Rad/s			               
           orbit_cntr                      "0.0 0.0 0.0"
           orbit_radius                    0.06
           year_rotationVec		   "1.0 0.0 0.0"
           year_frequency                  1.73
           year_frequency_init             0.0
           day_rotationVec                 "1.0 0.0 0.0"
           day_frequency                   6.11
           day_frequency_init              0.0
           initial_centerOfDayRotation     "0.58 0.22 0.34"
           tstart_prescribe		   0.0
           tend_prescribe                  1.0
           max_dist                        0.1
       }
       motion
       {
           phase_motion                    3
           motion_type                     OSCILLATE
           freq_unit                       Hz
           oscill_ampl                     "0.0 0.07 0.0"
           oscill_freq_init                "0.0 0.0 0.0"
           oscill_freq                     "0.0 50.0 0.0"
           oscill_phaseshift               "0.0 90.0 0.0"
           tstart_prescribe                0.0
           tend_prescribe                  0.0
           t_damping                       0.0
       }
       motion
       {
           motion_type                      CONROD
           phase_piston                     5               
           phase_conrod                     7
           freq_unit                        Rad/min		  
           crankshaft_rot_freq              -100.0
           crankshaft_rot_freq_init         0.0
           crankshaft_axis                  "0.0 1.0 0.0"
           crankshaft_cntr                  "1.15 0.11 0.6"
           crankshaft_normal                "0.2 0.0 -0.9"
           crankshaft_phaseshift            0.0
           crankshaft_rad                   0.12
           conrod_length                    0.15
           piston_offset                    0.01
           tstart_prescribe                 0.0
           tend_prescribe                   1.0 
           t_damping                        0.1
       }
       motion
       {
           phase_motion                     1
           motion_type                      PASSIVE_RIGID_BODY       
           freq_unit                        Rad/s                    
           init_CoM                         "1.0 1.0 1.0"            
           mom_inert_diag                   "1.0 1.0 1.0"            
           mom_inert_offdiag                "0.0 1.0 0.0"            
           body_mass                        10                       
           init_vel                         "0.0 0.0 1.0"            
           init_angvel                      "0.0 0.0 0.5"            
           mom_principal_ax_x_i             "1.0 0.0 0.0"            
           mom_principal_ax_y_i             "0.0 1.0 0.0"            
           mom_principal_ax_z_i             "0.0 0.0 1.0"            
           prbcon_ax_x_i                    "1.0 0.0 0.0"            
           prbcon_ax_y_i                    "1.0 0.0 0.0"            
           prbcon_ax_z_i                    "1.0 0.0 0.0"            
           prbcon_linlck_c                  "1.0 1.0 0.0"            
           prbcon_anglck_c                  "1.0 1.0 1.0"            
           prbcon_linspr_k_c                "5.0 0.0 0.0"            
           prbcon_linspr_p_c                "0.0 0.0 0.0"            
           prbcon_angspr_k_c                "0.0 0.0 8.0"
           prbcon_lindmp_c_c                "0.0 0.0 0.0"
           prbcon_angdmp_c_c                "0.0 0.0 0.0"            
           prbcon_angspr_p_c                "0.0 0.0 0.0"            
           prbcon_linlim_pls_c              "2.0 0.0 -3.0"           
           prbcon_linlim_mns_c              "1.0 0.0 -2.0"           
           prbcon_anglim_pls_c              "2.0 0.0 -3.0"           
           prbcon_anglim_mns_c              "1.0 0.0 -2.0"           
           prbcon_pt_i                      "0.0 0.0 0.0"            
           prbcon_ax_hinge_c                "0.0 1.0 0.0"
           prbcon_cnstfrc_c                 "3.0 -1.0 0.0"
           prbcon_cnsttrq_c                 "1.0 5.0 -2.0"            
           prbcon_linvel_ctoi               true
           prbcon_linvel_a_c                "1.0 0.0 0.0"
           prbcon_linvel_f_c                "prb_tlvs.txt"
           prbcon_angvel_ctoi               true
           prbcon_angvel_a_c                "1.0 0.0 0.0"
           prbcon_angvel_f_c                "prb_alvs.txt"
       }
       motion
       {
           motion_type                      DOUBLE_ROLLER_1DOF
           dr1dof_bod_phs                   "1 2 3"
           dr1dof_frw_phs                   "4 5 6 7"
           dr1dof_bck_phs                   "8 9"
           dr1dof_drvr_frwbck               reardrive
           dr1dof_bod_cgpnt                 "5.0 1.0 2.0"
           dr1dof_frw_axpnt                 "0.0 1.0 2.0"
           dr1dof_bck_axpnt                 "0.0 2.0 3.0"
           dr1dof_whl_rd                    5.0
           dr1dof_vel_init                  0.0
           dr1dof_vel                       0.0
           dr1dof_time_start                0.0
           dr1dof_time_rampup               0.0
           dr1dof_time_rampdn               0.0
           dr1dof_time_end                  0.0
           dr1dof_rd_pth_ply                2.0
           dr1dof_rd_pth_file               somefile.someextension
           dr1dof_tvs_file                  /path/to/tvsfile.txt
           
       }
       motion
       {
           motion_type             DOUBLE_ROLLER_3DOF
           dr3dof_bod_phs          "1 2 3"           
           dr3dof_frw_phs          "4 5 6 7"         
           dr3dof_bck_phs          "8 9"             
           dr3dof_drvr_frwbck      reardrive         
           dr3dof_bod_cgpnt        "5.0 1.0 2.0"     
           dr3dof_bod_ms           730               
           dr3dof_bod_iyy          2460              
           dr3dof_frw_ms           46                
           dr3dof_bck_ms           46                
           dr3dof_frw_ks           17500             
           dr3dof_bck_ks           17500             
           dr3dof_frw_cs           1000              
           dr3dof_bck_cs           1000              
           dr3dof_frw_axpnt        "0.0 1.0 2.0"     
           dr3dof_bck_axpnt        "0.0 2.0 3.0"     
           dr3dof_whl_rd           5.0               
           dr3dof_bod_eqlb         "0.0 0.0"                                       
           dr3dof_bod_reffrm       false             
           dr3dof_ptch_mod         false             
           dr3dof_bod_z_1dofcon    "0 0.04 -0.04"                                  
           dr3dof_bod_a_1dofcon    "0 0.001 -0.001"                                 
           dr3dof_fld_react_freq   1                 
           dr3dof_vel_init         0.0               
           dr3dof_vel              0.0               
           dr3dof_tvs_file         tvs_file.txt      
           dr3dof_time_start       0.0               
           dr3dof_time_rampup      0.0               
           dr3dof_time_rampdn      0.0               
           dr3dof_time_end         0.0               
           dr3dof_rd_pth_ply       2.0               
           dr3dof_rd_pth_file      rd_pth_file.txt   

        }

        ...

}

Definitions

Important: ROTATE and ROTATE_AXIS motion types have the same function, albeit slightly different definitions. In ROTATE_AXIS the rotational frequency is separated from the rotational axis definition, while in ROTATE the axis vector definition is multiplied by the frequency scalar. Both functions can be used. You can choose which one is more convenient.
Command Contents SI Unit Example
phase_motion The following motion is applied to this phase number
Options
  • The phase number must not exceed the number of defined phases. Counting starts with 1.
Note: The type of these phases needs to be MOVINGWALL or WALL. The WALL phase types can only be assigned IMPOSE_VEL and ROTATE_AXIS motion types, in which case the velocities on these WALL phases will be set as a velocity boundary condition, in accordance with the specified motion.
motion_type The type of the imposed motion
Options
  • IMPOSE_VEL
  • ROTATE
  • ROTATE_AXIS
  • POSITION_FILE
  • PLANETARY
  • OSCILLATE
  • CONROD
  • Passive_RIGID_BODY
  • DOUBLE_ROLLER_1DOF
freq_unit Defines which unit will be used to specify rotational frequencies for this motion
Options
  • Hz
  • RPM
  • Rad/s
  • Rad/min

Default = Hz (same as rotations per second) except for PASSIVE_RIGID_BODY (Rad/s).

impose_vel For motion_type = IMPOSE_VEL. This is the imposed velocity of the moving wall particles defined as a vector in X, Y and directions.

Default = “0. 0. 0”

tstart_prescribe / tend_prescribe Within the time-frame tstart_prescribe and tend_prescribe, the velocity of the moving wall particles is set to impose_vel.
Note: tend_prescribe should be greater than or equal to tstart_prescribe.

Default = 0.0

t_damping In SPH, impulsively started motions always cause pressure oscillations since in a weakly-compressible method disturbances can only travel at the numerical speed of sound. To alleviate this effect it is possible to slowly increase the imposed motion starting at tstart_prescribe for an interval of t_damping.
Tip: For example:
  • Before tstart_damping: No imposed motion
  • tstart_ presribe < current time < tstart_prescribe + t_damping: smoothly increase impose_vel to the specified value
  • tstart_prescribe + t_damping < current time < tend_prescribe: the full impose_vel is applied
  • tend_prescribe < current time: no change of the motion, that is, current status is maintained.
Default = 0.0
Note: t_damping will be renamed to t_ramping in the future, as it describes better the effect it has in the simulation. The exact version wherein this switch will take place is unknown, but will be appropriately announced via Release Notes.
rot_freq For motion_type= ROTATE. Rotational frequency vector [rot/s] specified as a vector with x, y, and z-axis components.

Default = “0. 0. 0”

rot_freq_init For motion_type= ROTATE. This case is a restart and you can specify initial frequency of rotation. With this command you can start from, for example, 1000 RPM to an arbitrary RPM.

Default = “0. 0. 0”

rot_cntr For motion_type= ROTATE and ROTATE_AXIS. Center-of-rotation for the rotational motion.
Note: For a body that is rotating around its axis of symmetry such as a gear, the center of rotation needs to lie anywhere along the specified direction of the rotation vector. For example, on the axis of the gear.

Default = “0. 0. 0”

rot_axis For motion_type= ROTATE_AXIS. Defines the axis of rotation of a body.

Default = “0. 0. 0”

rot_axis_freq For motion_type= ROTATE_AXIS. Defines the frequency of rotation of the body.

Default = “0. 0. 0.” or 0.0 (depending on the motion type)

rot_axis_freq_init For motion_type= ROTATE_AXIS. In case it is a restart, you can specify initial frequency of rotation. This allows you to start from 1000 RPM to an arbitrary RPM, for example.

Default = 0.0

positionFile The name of the file that contains the prescribed motion information
Note: For more information, refer to the POSITION_FILE section.
Related Commands
  • Motion: POSITION_FILE
rot_cntr If this command is defined in the configuration file, it will use this point as the center of rotation and it will move it as specified by the position text file.
Attention: If this command is not specified, the code will rotate the body around the calculated center of mass.
Related Commands
  • Motion: POSITION_FILE
isOrientation Options
  • true - If it is set to true, the code looks for an 8-column format, which defines cosine values of the axis vector and the orientation scalar (in radians).
  • false (Default) - If this switch is set to false, the code looks for a 7-column format input, reading the rotational velocity vectors.
Related Commands
  • Motion: POSITION_FILE
orbit_cntr Defines the planetary carrier center location. It is sufficient that it lies on the year rotation axis, since the year rotation axis is specified separately.
orbit_radius Distance between the orbit_cntr and the planet gear center (initial_centerOfDayRotation).
year_rotationVec Axis of year rotation. Can be defined as an arbitrary vector (it will be normalized automatically).
year_frequency Frequency of the year rotation [rot/s]
year_frequency_init In case it is a restart, you can specify initial year frequency of rotation. This allows you to start from 1000 RPM to an arbitrary RPM, for example.

Default = “0. 0. 0.” or 0.0 (depending on the motion type)

day_rotationVec Axis of day rotation. Can be defined as an arbitrary vector (it will be normalized automatically).
day_frequency Frequency of the day rotation [rot/s]
day_frequency_init In case it is a restart you can specify initial day frequency of rotation. This allows you to start from 1000 RPM to an arbitrary RPM, for example.

Default = “0. 0. 0.” or 0.0 (depending on the motion type)

initial_centerOfDayRotation Initial coordinates of the planetary gear for which the motion is defined.
Oscillatory motion is based on a cosine trigonometric function and it is defined by three parameters: oscillation amplitude, frequency and initial phase shift. It is only translatory oscillating motion, for example, piston motion, not rotational, for example, wiper motion.
Command Contents SI Unit Example
oscill_ampl Amplitude of the oscillatory motion [m]
oscill_freq_init Initial frequency of the oscillating motion. When the case is a restart, you can specify initial frequency of oscillation. For example, you can start from 1000 Hz and go to an arbitrary oscillation frequency.
oscill_freq Frequency of the oscillating motion
oscill_phaseshift Initial phase shift along the cosine function, for example, which defines the initial piston position. [deg]

CONROD Commands

The commands below are related to the CONROD type of motion. Given that the motion is rather complex, refer to the CONROD section for more information.
Command Contents SI Unit Example
phase_piston Defines which piston phase belongs to a particular conrod
Note: CONROD motion is the only motion that defines the motion for two phases at a time – the piston and the conrod phase.
phase_conrod Defines which conrod phase belongs to a particular piston
Note: CONROD motion is the only motion that defines the motion for two phases at a time – the piston and the conrod phase.
crankshaft_rot_freq Rotational frequency of the crankshaft (needed for proper conrod/piston motion definition)
Note: The actual crankshaft motion is defined separately by ROTATE or ROTATE_AXIS.
[rot/s]
crankshaft_rot_freq_init Initial rotational frequency of the crankshaft in case of a restart [rot/s]
crankshaft_axis Defines the axis of the crankshaft (necessary for proper conrod/piston motion definition)
crankshaft_cntr Point belonging to the crankshaft axis (lying on the crankshaft axis)
crankshaft_normal Cylinder-parallel vector in a direction pointing closer to the crankshaft axis unit vector. In other words, this is a vector parallel to the piston's line of movement and pointing in the direction of piston movement when moving away from TDC.
Tip: Be aware of the sign, try the opposite direction if it is not working.
crankshaft_phaseshift Defines the initial angular position (phaseshift) of the particular conrod/piston pair with respect to the crankshaft_normal direction.

The reference point for this angle is when the crankshaft is parallel to the cylinder and the piston is closer to TDC.

The sign is with respect to crankshaft axis.

[deg]
crankshaft_rad Defines the radius of the crankshaft; the distance between the crankshaft axis and the conrod-crankshaft connection center. [m]
conrod_length Defines the length of the conrod; the distance between the conrod-crankshaft and conrod-piston connections. [m]
piston_offset Positive or negative offset in the direction of crankshaft_axis x crankshaft_normal (cross product). [m]
max_dist Provides a maximum radius of the geometry with the center of the circle being on the rotation axis. In combination with the other motion definitions, this helps calculate the reference velocity.

This value is automatically exported by the SimLab pre-processor.

Tip: It is recommended that you specify ref_vel explicitly and avoid using the fall back option of automatic ref_vel calculation.
[m]

PASSIVE_RIGID_BODY Commands

The options below pertain only to the PASSIVE_RIGID_BODY motion. Use these options to add linear and torsional spring forces to the rigid body, as well as linear and angular constraints on the motion, which enables a number of new applications. For more information, refer to the PASSIVE_RIGID_BODY section.
Note: There are no rigid-rigid body interactions or rigid-wall interactions in nanoFluidX, therefore collisions and impacts among multiple bodies is not possible.
Command Contents SI Unit Example
body_mass If the MOVINGWALL phase is a passive rigid body, you need to prescribe the mass of the body, as the discretized geometry based on particles that may not reflect the real geometry.

For example, you can create just the hull of a ship and assign specific masses to the body, as if the geometry was a full ship.

Note: This option recalculates the density of each particle, and the rho_0 of this phase is ignored.
init_CoM Initial location of the center of mass
Related Commands
  • fluidCoupledMotion
  • Motion:PASSIVE_RIGID_BODY
init_vel Initial linear velocity of the rigid body
Note: This is a vector value.
[m/s]
init_angvel Initial angular velocity of the rigid body
Note: This is a vector value.
[rad/s]
mom_inert_diag Diagonal components of the moment of inertia around the global X, Y and Z axes.
Tip: For more information, refer to the PASSIVE_RIGID_BODY section).
The corresponding values refer to XX, YY and ZZ components.
[kg*m2]
mom_inert_offdiag Off-diagonal components of the moment of inertia around the global X, Y and Z axes.
Tip: For more information, refer to the PASSIVE_RIGID_BODY section).
The corresponding values refer to XY, XZ and YZ components.
[kg*m2]
Important: For the following commands, if the inertial reference frame does not align with the global axes, for example, if the moment of inertia needs to be defined around the principal axes of the body, then additional information must be supplied to define the principal axes. To do this you must define any two unit vectors of the principal axes and a third vector is calculated by the code. The coordinates must be specified with respect to the global axes.
mom_principal_ax_x_i Unit vector in the X-direction of the principal axis. This is a vector value, for example “1.0 0 0” implies the principal axis is aligned with the global X-axis in this case.
mom_principal_ax_y_i Unit vector in the Y-direction of the principal axis. This is a vector value, for example “0.0 1.0 0” implies the principal axis is aligned with the global Y-axis in this case.
mom_principal_ax_z_i Unit vector in the Z-direction of the principal axis. This is a vector value, for example “0 0 1.0” implies the principal axis is aligned with the global Z-axis in this case.
Important: With the above rigid body related commands, you can simulate a freely moving rigid body that is interacting with the fluid. However, additional options are available to constrain motion and add linear or torsional springs with the following commands. Unless another coordinate system is defined for the constraints (constraint reference frame), the code assumes constraint alignment with the global axes. If this is not the case, if some of the constraints are under angles, then the constraint reference frame must be defined by specifying any two unit vectors. The coordinates must be specified with respect to the global axes.
prbcon_ax_x_i Unit vector in the X-direction of the constraint axis. This is a vector value, for example “1.0 0 0” implies the X-axis of the constraint frame is aligned with the global X-axis in this case.
prbcon_ax_y_i Unit vector in the Y-direction of the constraint axis. This is a vector value, for example “0.0 1.0 0” implies the Y-axis of the constraint frame is aligned with the global Y-axis in this case.
prbcon_ax_z_i Unit vector in the Z-direction of the constraint axis. This is a vector value, for example “0 0 1.0” implies the Z-axis of the constraint frame is aligned with the global Z-axis in this case.
Important: Once the constraint reference frame has been defined, you can proceed to defining the constraints themselves. If you want to lock linear or angular degrees-of-freedom you can use the following.
prbcon_linlck_c This is a vector value that defines which of the linear motions will be locked.
Options
  • 1.0 to lock
  • 0 to unlock
Tip: For example, “1.0 0 0” locks the linear motion in the X-direction of the constraint frame.
prbcon_anglck_c This is a vector value that defines which of the angular motions will be locked.
Options
  • 1.0 to lock
  • 0 to unlock
Tip: For example, “1.0 0 0” locks the angular motion around the X-direction of the constraint frame.
Important: Define linear and torsional springs using the following commands.
prbcon_linspr_k_c Linear spring stiffness coefficient. This is a vector value. [N/m]
prbcon_linspr_p_c Pre-deformation distance with respect to the initial (equilibrium) position. This is a vector value. [m]
prbcon_angspr_k_c Torsional spring stiffness coefficient. This is a vector value. [Nm/rad]
prbcon_angspr_p_c Pre-deformation angle with respect to the initial (equilibrium) position. This is a vector value. [rad]
prbcon_lindmp_c_c Linear damping coefficients along the corresponding constraint axis. Inactive when pinned. [Ns/m]
prbcon_angdmp_c_c Torsional damping coefficients around the corresponding constraint axis. [Nms/rad]
Important: It is often necessary to set the limits of motion, such that the constrained body would not go beyond a certain distance or beyond a certain angle value. Set limits with the following commands.
prbcon_linlim_pls_c Allowed upper limit coordinate of the linear motion with respect to the init_CoM. This is a vector value (to specify all three directions in the constraint reference frame). [m]
prbcon_linlim_mns_c Allowed lower limit coordinate of the linear motion with respect to the init_CoM. This is a vector value (to specify all three directions in the constraint reference frame). [m]
prbcon_anglim_pls_c Allowed upper limit angle of the rotational motion with respect to the initial position. This is a vector value (to specify all three directions in the constraint reference frame). [rad]
prbcon_anglim_mns_c Allowed lower limit angle of the rotational motion with respect to the initial position. This is a vector value (to specify all three directions in the constraint reference frame). [rad]
Important: A special case of limited motion is a hinge whose center of rotation is not the center of mass (axis of rotation does not pass through the center of mass). In this situation the axis of rotation needs to be specified, which can be done by translating the constraint reference frame to a new position and by modifying the rotational lock command.
prbcon_pt_i Specified by the new origin of the constraint frame and defined in the global coordinate system. This is a vector value.
prbcon_ax_hinge_c Since the rotations are now moved away from the center of mass, new rotational constraints must be set in place. This is a vector value that defines which of the angular motions will be locked.
Options
  • 0.0 to lock
  • 1 to unlock
Tip: For example, “1.0 0 0” unlocks only the angular motion around the x direction of the constraint frame. By setting all three values to zero, one enables a spherical joint behavior.
CAUTION: Overrides the prbcon_anglck_c command.
prbcon_cnstfrc_c A constant force applied in constraint frame.
Note: Inactive if the motion is pinned in the given direction.
[N]
prbcon_cnsttrq_c A constant torque applied in constraint frame around a X, Y and Z axes.
Note: Inactive if the motion is pinned in the given rotation.
[Nm]
prbcon_linvel_ctoi Set this command to true to keep constraint frame stationary, set to false to rotate constraint frame with body frame.
Note: Applies only to the prbcon_linvel constraint.
prbcon_linvel_a_c Set any element to a positive number to activate the preset time dependent linear velocity for that constraint axis. [m/s]
prbcon_linvel_f_c Name of a 4-column file (t,u,v,w) for preset time dependent linear velocity applied in constraint frame.
Note: Inactive for all pinned motion directions.
[m/s]
prbcon_angvel_ctoi Options
  • Set this command to true to keep constraint frame stationary
  • Set this command to false to rotate constraint frame with body frame
Note: Applies only to prbcon_angvel constraint.
prbcon_angvel_a_c Set any element to a positive number to activate the preset time dependent linear velocity for that constraint axis. [Rad/s]
prbcon_angvel_f_c Name of a 4-column file ( t , ω x , ω y , ω z MathType@MTEF@5@5@+= feaahqart1ev3aqatCvAUfeBSjuyZL2yd9gzLbvyNv2CaerbuLwBLn hiov2DGi1BTfMBaeXatLxBI9gBaerbd9wDYLwzYbItLDharqqtubsr 4rNCHbGeaGqiVCI8FfYJH8YrFfeuY=Hhbbf9v8qqaqFr0xc9pk0xbb a9q8WqFfeaY=biLkVcLq=JHqpepeea0=as0Fb9pgeaYRXxe9vr0=vr 0=vqpWqaaeaabiGaciaacaqabeaadaqaaqaaaOqaaabaaaaaaaaape GaamiDaiaacYcacqaHjpWDpaWaaSbaaSqaa8qacaWG4baapaqabaGc peGaaiilaiabeM8a39aadaWgaaWcbaWdbiaadMhaa8aabeaak8qaca GGSaGaeqyYdC3damaaBaaaleaapeGaamOEaaWdaeqaaaaa@42B5@ ) for preset time dependent linear velocity applied in constraint frame.
Note: Inactive for all pinned motion directions.
[Rad/s]

DOUBLE_ROLLER_1DOF Commands

Command Contents SI Unit Example
dr1dof_bod_phs List of phases associated with the body in form of a vector (space separated and under quotation marks).
dr1dof_frw_phs List of phases associated with the front wheels (space separated and under quotation marks).
dr1dof_bck_phs List of phases associated with the rear wheels (space separated and under quotation marks).
dr1dof_drvr_frwbck Optional command that specifies if the vehicle is rear drive or front drive
Options
  • reardrive (Default)
  • frontdrive
dr1dof_bod_cgpnt Optional command that defines a reference point on the vehicle body which would later be used for post-processing. This does not have any impact on the motion definition.

Default = "0.0 0.0 0.0"

[m]
dr1dof_frw_axpnt A reference point on the line passing through the front wheel axle and parallel to Y-axis [m]
dr1dof_bck_axpnt A reference point on the line passing through the rear wheel axle and parallel to Y-axis [m]
dr1dof_whl_rd Defines the wheel radius. It must be a positive number [m]
dr1dof_vel_init Initial velocity of the center of the driving wheel
Note: This command is optional.

Default = 0.0

[m/s]
dr1dof_vel Determines the velocity of the vehicle. Set this command to false to rotate constraint frame with body frame. [Rad/s]
dr1dof_time_start Starting time of the motion
Note: This command is optional.

Default = 0.0

dr1dof_time_rampup Ramp-up duration of the motion (after which the vehicle reaches desired velocity).
Note: This command is optional.

Default = 0.0

dr1dof_time_rampdn Ramp down duration of the motion (after which the vehicle comes to a halt).
Note: This command is optional.

Default = 0.0

dr1dof_time_end Ending time of the motion
Note: This command is optional.

Default = End time of the simulation

dr1dof_rd_pth_ply Arc length coefficient (arc length is equal to dr1dof_rd_pth_ply*dx). The arc is used to connect any two lines in the path definition.
Note: This command is optional.

Default = 2.0

dr1dof_rd_pth_file Relative or absolute path to the file containing the two-column (X Z) piecewise linear road path (the road path Z must be a function of road path X, that is, X values must be strictly increasing). The vehicle will follow the specified road.
dr1dof_tvs_file Relative or absolute path to the file containing time-velocity series (.tvs) data. The .tvs file has a two column space delimited format with the first column specifying time values in a strictly increasing order, while the second column specifies the driving wheel axis signed velocity magnitude along the road. It is possible to specify any positive or negative value as well as zero in any order in the second column of the .tvs file.
Note:
  • Depending on the road profile, the traveled distance may need to be considered when mapping time to position along the path. When defined, the .tvs file takes precedence over dr1dof_vel_init, dr1dof_vel, dr1dof_time_rampupand/or dr1dof_time_rampdn.
  • The relative path is preferred over absolute path due to portability.
Important additional notes regarding the 1DoF double roller motion can be found below:
  • Only two axles are supported.
  • All wheels must have the same radius.
  • The wheels always follow the road.
  • This motion is not stackable (no ability to super-pose double roller motion with any other motion).
  • The wheel rotation axes must be parallel to Y-axis.
  • Only constant driver wheel axis velocity is supported.
  • Initial position of driver and driven wheels must be within the first line segment.
  • Two consecutive road segments may not have the same normal (there has to be an angle between two segments).
This means only X-positive motion is supported and dr1dof_vel must be positive and larger than dr1dof_vel_init. The road path is defined through a file according to following conditions:
  • Road path is a two column file of the X Z form.
  • Road path must contain at least one line segment (two X Z pairs).
  • Road path X-coordinates must be strictly increasing.

DOUBLE_ROLLER_3DOF Commands

Command Contents SI Unit Example
dr3dof_bod_phs Phase or list of phases that follow the body motion. If more than one phase was specified, the list should be enclosed in quotation marks, start with a number and end with a number. The list separator is space.
Tip: For example, "1 10 2 6 5".

No default (Multi element integer)

dr3dof_frw_phs Phase or list of phases that follow the front wheel motion. If more than one phase was specified, the list should be enclosed in quotation marks, start with a number and end with a number. The list separator is space.
Tip: For example, "4 7".

No default (Multi element integer)

dr3dof_bck_phs Phase or list of phases that follow the rear wheel motion. If more than one phase was specified, the list should be enclosed in quotation marks, start with a number and end with a number. The list separator is space.
Tip: For example, "8".

No default (Multi element integer)

dr3dof_drvr_frwbck Options
  • Set to reardrive for rear wheel drive
  • Set to frontdrive for front wheel drive motion

Default = reardrive (Predefined)

dr3dof_bod_cgpnt Center of mass of the body phases and reference point used for calculating moments on the body phases. This is the internal center of rotation though apparent center of rotation may be different.

Default = "0.0, 0.0, 0.0" (Three element float)

dr3dof_bod_ms Total mass of the body phases

No default (Float)

dr3dof_bod_iyy Mass moment of inertial of combined body phases about Y

No default (Float)

dr3dof_frw_ms Combined front wheel mass. Only used when dr3dof_ptch_mod is active and ignored otherwise.

Default = 0.0 (Float)

dr3dof_bck_ms Combined rear wheel mass. Only used when dr3dof_ptch_mod is active and ignored otherwise.

Default = 0.0 (Float)

dr3dof_frw_ks Effective front wheel spring constant. A positive value is recommended.

No default (Float)

dr3dof_bck_ks Effective rear wheel spring constant. A positive value is recommended.

No default (Float)

dr3dof_frw_cs Effective front wheel damping coefficient. A positive value is recommended.

No default (Float)

dr3dof_bck_cs Effective rear wheel damping coefficient. A positive value is recommended.

No default (Float)

dr3dof_frw_axpnt Coordinates of a point passing through the front axis of the motion. This point is used as a reference point for calculating moments on the front wheel phases.

No default (Three element float)

dr3dof_bck_axpnt Coordinates of a point passing through the rear axis of the motion. This point is used as a reference point for calculating moments on the rear wheel phases.

No default (Three element float)

dr3dof_whl_rd Wheel radius. Must be a positive number.

No default (Float)

dr3dof_bod_eqlb Adjustment of position and angle of the body by "Z ANG" in case the initial configuration is not in equilibrium. This adjustment does not introduce perturbation. The body is translated by Z [m] in the Z-direction and is rotated by ANG [deg] about the driver axis.

Default = "0.0 0.0" (Two element float)

dr3dof_bod_reffrm Options
  • Set to true to apply the motion in body frame or false to apply the motion in inertial frame.
  • When set to false, the motion is suitable for sliding frame while when set to true, the motion can be used in temporal frame.

Default - false (Boolean)

dr3dof_ptch_mod Options
  • Set to true to activate pitch modulation due to acceleration and deceleration.

Default - false (Boolean)

dr3dof_bod_z_1dofcon Constrain body Z-position by equivalent 1DoF motion in meters.

In combination with dr3dof_bod_a_1dofcon, it has a similar effect to limiting stretch/compression of the suspension.

Set the first element to a positive number to activate, for example, "1 X Y". Or set to a non-positive number to deactivate, for example, "0 X Y".

Once active, the second element is the allowed positive deviation and the third element is the allowed negative deviation. The body is not allowed beyond the deviation range. For example, when set to "1 0.02 -0.05", the body may go 0.02 m further up and 0.05 m further down compared to equivalent 1DoF motion in Z-direction. A positive number for the second element and a negative number for the third element is recommended, but is not necessary.

Default = "0.0 0.0 0.0" (Three element float)

dr3dof_bod_a_1dofcon Constrain body the Y-angle by equivalent 1DoF motion in degrees.

In combination with dr3dof_bod_z_1dofcon, it has a similar effect to limiting stretch/ compression of the suspension.

Set the first element to a positive number to activate, for example, "1 X Y". Or set to a non-positive number to deactivate, for example, "0 X Y".

Once active, the second element is the allowed positive deviation and the third element is the allowed negative deviation. The body is not allowed beyond the deviation range. For example, when set to "1 5 -2", the body may deviate by 5 degrees in positive Y (clockwise) and 2 degrees in negative Y (counter clockwise) direction from equivalent 1DoF motion. A positive number for the third element is recommended, but is not necessary.

Default = "0.0 0.0 0.0" (Three element float)

dr3dof_fld_react_freq Frequency of sampling fluid force and torque on the body phases. The force and torque will remain constant in between sampling points. Set to a non-positive value to deactivate.

Default = 0 (Integer)

dr3dof_tvs_file Relative or absolute path to the file containing time-velocity series data. When defined, takes precedence over dr3dof_vel_init, dr3dof_vel, dr3dof_time_rampup and/ or dr3dof_time_rampdn.
Note: Relative path is preferred over absolute path due to portability.

(String)

dr3dof_vel_init Initial signed velocity magnitude of the driving wheel axis along the road. Ignored when dr3dof_tvs_file is present.

Default = 0.0 (Float)

dr3dof_vel Signed velocity magnitude of the driving wheel axis along the road.
Note: Ignored when dr3dof_tvs_file is present.

Default = 0.0 (Float)

dr3dof_time_rampup Time duration to ramp from dr3dof_vel_init to dr3dof_vel. The ramp starts at dr3dof_time_start and ends at dr3dof_time_start + dr3dof_time_rampup.
Note: Ignored when dr3dof_tvs_file is present.

Default = 0.0 (Float)

dr3dof_time_start Start time of the motion

Default = 0.0 (Float)

dr3dof_time_end End time of the motion

Default = t_end (Float)

dr3dof_time_rampdn Time duration to ramp from dr3dof_vel to dr3dof_vel_init. The ramp starts at dr3dof_time_end - dr3dof_time_rampdn and ends at dr3dof_time_end. Ignored when dr3dof_tvs_file is present.

Default = 0.0 (Float)

dr3dof_rd_pth_ply A coefficient to determine the arc length as dr3dof_rd_pth_ply*dx. An approximate arc length is then used to construct a circular piece to connect the road pieces with a topside angle of more than 180 degrees after elevation.

Default = 2.0 (Float)

dr3dof_rd_pth_file Relative or absolute path to a file containing the two-column (X Z) piecewise linear road path. The road path Z must be a function of road path X, for example, X-values must be strictly increasing.

No default (String)