# Contact

Model ElementContact defines a 3-D contact force between geometries on two rigid bodies.

Contact

## Description

Each body is characterized by a set of one or more geometries. Whenever any geometry on the first body penetrates any geometry on the second body, a contact normal and frictional force are generated. The normal force tends to repulse motion along the common normal at the contact point. The frictional force tends to oppose relative sliding velocity at the contact point. The contact force vanishes when the geometries no longer intersect.

## Attribute Summary

Name Property Modifiable by Command? Designable?
id Int ()
label Str () Yes
igeom Reference (Graphics, count=0)
jgeom Reference (Graphics, count=0)
iflip_geometry Reference (Graphics)
jflip_geometry Reference (Graphics)
type Enum ("NONE IMPACT POISSON VOLUME USER")
stiffness Double (0.0) Yes FD Only
exponent Double (1.5) Yes FD Only
damping Double (0.0) Yes FD Only
dmax Double (0.0) Yes FD Only
penalty Double (0.1) Yes FD Only
restitution_coefficient Double (0.0) Yes FD Only
coulomb_friction Enum ("ON OFF DYNAMICS_ONLY")
mu_static Double (0.0) Yes FD Only
mu_dynamic Double (0.0) Yes FD Only
stiction_transition_velocity Double (1E-3) Yes FD Only
friction_transition_velocity Double (1E-3) Yes FD Only
i_elastic_modulus Double (0.0) Yes FD Only
i_layer_depth Double (1.0) Yes FD Only
j_elastic_modulus Double (0.0)   FD Only
j_layer_depth Double (1)   FD Only
master_surface Enum ("AUTO I J IANDJ", default="AUTO") Yes
collision_engine Enum ("AUTO OPCODE PCM PARASOLID", default="AUTO") Yes
normal_routine Routine ()
friction_routine Routine ()
friction_function Function ()
normal_function Function ()
active Bool () Yes

## Usage

Contact supports four normal force models. You must select one of these and specify its parameters.
• type = "IMPACT"
• type = "VOLUME"
• type = "POISSON"
• type = "USER"

Contact also supports some optional parameters that are independent of the choice of the normal force. You may specify any combination of these.

Finally Contact supports two friction models.
• Coulomb friction
• Your own custom friction model
Specification of friction at the contact patch is optional. If you want to model friction at the contact patch, you may specify the parameters for one of these models. If you use neither, friction forces are NOT applied at the contact patch.
# Type = "IMPACT"
Contact (type="IMPACT", igeom=list, jgeom=list, stiffness=Double, exponent=Double, damping=Double, dmax=Double, optional_attributes)

# Type = "Volume"
Contact (type="VOLUME", igeom=list, jgeom=list, i_elastic_modulus=Double, i_layer_depth=Double, j_elastic_modulus=Double, j_layer_depth=Double, exponent=Double, damping=Double, optional_attributes)

# Type = "POISSON"
Contact (type="POISSON", igeom=list, jgeom=list, penalty=Double, normal_trans_vel=Double, restitution_coefficient=Double, optional_attributes)

# Type = "USER"
Contact (type="USER", igeom=list, jgeom=list, normal_routine=String or Python function pointer, normal_function=userString, optional_attributes)
Normal force type = "IMPACT"
Attributes
type
String "IMPACT"
Specifies that the IMPACT, normal force model is to be used for calculating the contact normal force.
A contact force is computed as a function of the penetration between the intersecting geometries defined for the contact. In other words, as the geometries intersect, a repulsive force is generated which is based on the type of contact selected. See Comments 3 for more information on the IMPACT model.
This attribute is optional. MotionSolve will automatically set type = "IMPACT" when type is not specified.
igeom
List of Graphics objects.
This is a list of the Graphics objects on the first body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute igeom is mandatory.
jgeom
List of Graphics objects.
This is a list of the Graphics objects on the second body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute jgeom is mandatory.
stiffness
Double
Specifies the stiffness parameter of the contact; this is the same parameter as found for the IMPACT function.
A large value for stiffness permits only a small penetration between the two contacting geometries; a small value permits a larger penetration.
Consider using a stiffness value that is as small as possible, but still captures accurate deformation, to improve solver performance. See Comment 6 for more information on how to select a value for stiffness.
The attribute stiffness is mandatory for type="IMPACT".
stiffness ≥ 0
damping
Double
Specifies the maximum damping coefficient that is to be used for generating a damping force. See Comment 3 for more details.
A value around 0.1% of the stiffness is a good value to use. A large value for damping will make the contact "sticky". Conversely, a small value for damping will tend to cause the contact to be "intermittent".
Also note that the damping force adds to the spring force during penetration, but subtracts from the spring force during separation.
The attribute damping is mandatory for type="IMPACT"
damping ≥ 0
exponent
Double
The exponent of the force deformation characteristic of the contact interface. For a stiffening spring characteristic, it must be greater than 1.0.
The attribute exponent is mandatory for type="IMPACT".
exponent ≥ 1.0
dmax
Double
Specifies the penetration at which full damping is applied. It must be a positive number.
Note dmax should be somewhat smaller than the maximum penetration that is expected. If dmax is too small, the damping force is turned on quite rapidly. Conversely, if dmax is too large, the full damping may never be turned on.
The attribute dmax is mandatory for type="IMPACT".
dmax > 0.0
Normal force type = "VOLUME"
type
String "VOLUME"
Specifies that the VOLUME normal force model is to be used for calculating the contact normal force.
A contact force is computed as a function of the penetration between the intersecting geometries defined for the contact. In other words, as the geometries intersect, a repulsive force is generated which is based on the type of contact selected. See Comments 2, 5 for more information on the VOLUME model.
igeom
List of Graphics objects.
This is a list of the Graphics objects on the first body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute igeom is mandatory.
jgeom
List of Graphics objects.
This is a list of the Graphics objects on the second body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute jgeom is mandatory.
i_elastic_modulus
Double
Specifies the elastic modulus (sometimes also called the P-wave modulus) for the geometries belonging to Body I for the Volume force model. The value of this elastic modulus can be derived from the Bulk and Shear Modulus of a material. See Comment 5 for an explanation on how this parameter is used to calculate the contact stiffness.
The attribute i_elastic_modulus is mandatory when type="VOLUME"
i_elastic_modulus > 0
i_layer_depth
Double
Specifies the size of the layer depth for the geometries belonging to body I. See Comment 5 for an explanation on how this parameter is used to calculate the contact stiffness.
The attribute i_layer_depth is mandatory when type="VOLUME".
i_layer_depth > 0
j_elastic_modulus
Double
Specifies the elastic modulus (sometimes also called the P-wave modulus) for the geometries belonging to Body J for the Volume force model. The value of this elastic modulus can be derived from the Bulk and Shear Modulus of a material. See Comment 5 for an explanation on how this parameter is used to calculate the contact stiffness.
The attribute j_elastic_modulus is mandatory when type="VOLUME".
j_elastic_modulus > 0
j_layer_depth
Double
Specifies the size of the layer depth for the geometries belonging to body I. See Comment 5 for an explanation on how this parameter is used to calculate the contact stiffness.
The attribute j_layer_depth is mandatory when type="VOLUME".
j_layer_depth > 0
EXPONENT
Double
The exponent of the force deformation characteristic of the contact interface. For a stiffening spring characteristic, it must be greater than 1.0.
The attribute exponent is mandatory for type="VOLUME".
exponent ≥ 1.0
damping
Double
Specifies the coefficient of damping used to calculate the damping force for the VOLUME force model.
The attribute damping is mandatory for type="VOLUME".
damping > 0
Normal force type = "POISSON"
type
String "POISSON"
Specifies that the POISSON, normal force model is to be used for calculating the contact normal force.
A contact force is computed as a function of the penetration between the intersecting geometries defined for the contact. In other words, as the geometries intersect, a repulsive force is generated which is based on the type of contact selected. See Comments 2,4 for more information on the POISSON model.
igeom
List of Graphics objects.
This is a list of the Graphics objects on the first body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute igeom is mandatory.
jgeom
List of Graphics objects.
This is a list of the Graphics objects on the second body to be considered for contact.
Note All the GRAPHICS entities must belong to the same body.
The attribute jgeom is mandatory.
penalty
Double
Specifies the stiffness parameter that is used to calculate the spring force.
A large value for penalty permits only a small penetration between the two contacting geometries; a small value permits a larger penetration. Consider using a penalty value that is as small as possible, but still captures realistic deformation, to improve solver performance.
The attribute penalty is mandatory when type="POISSON".
penalty > 0
restitution_coef
Double
Defines the coefficient of restitution (COR) between the geometries in contact. This is used in the computation of the contact force. See Comment 4 for more information on the use of restitution_coef in the POISSON model.
A value of zero specifies perfectly plastic contact meaning that the two bodies coalesce after contact.
A value of one specifies perfectly elastic contact. No energy is lost in the collision and the relative velocity of separation equals the relative velocity of approach.
COR = (relative speed after collision)/(relative speed before collision)
The attribute restitution_coef is mandatory when type="POISSON".
0 ≤ restitution_coef ≤ 1
normal_trans_vel
Double
Defines the velocity limit between the two bodies at which full damping is applied in the contact force.
The attribute normal_trans_vel is optional when type=" POISSON". When not specified, MotionSolve initializes it to 0.01.
normal_trans_vel > 0
Normal force type = "USER"
TYPE
String "USER"
Specifies that the USER, normal force model is to be used for calculating the contact normal force.
A contact force is computed as a function of the penetration between the intersecting geometries defined for the contact. In other words, as the geometries intersect, a repulsive force is generated which is based on the type of contact selected.
IGEOM
List of Graphics objects.
This is a list of the Graphics objects on the first body to be considered for contact.
Note: All the GRAPHICS entities must belong to the same body.
The attribute igeom is mandatory.
JGEOM
List of Graphics objects.
This is a list of the Graphics objects on the second body to be considered for contact.
Note All the GRAPHICS entities must belong to the same body.
The attribute jgeom is mandatory.
normal_function
String
Specifies the list of parameters that are passed from the data file to the user defined subroutine.
The normal_function attribute must be specified when type="USER".
normal_routine
String or a pointer to a Python function.
Specifies the path of the shared library containing the contact force calculation subroutine and the function within that library that is to be executed. The path and function name are to be separated by "::". MotionSolve uses this information to load the user subroutine in the library at run time.
The normal_routine attribute is optional when type="USER".
When normal_function is specified, but normal_routine is not, normal_routine defaults to "CNFSUB".
Other optional Parameters that can be used with all normal force models
id
Integer
Specifies the element identification number. This number must be unique among all the Contact objects in the model.
This attribute is optional. MotionSolve will automatically create an ID when one is not specified.
Range of values: id > 0.
label
String
Specifies the name of the Contact object.
This attribute is optional. When not specified, MotionSolve will create a label for you.
master_surface
String. Choose one from: "I", "J", "IANDJ", "AUTO"
Specifies which surface should be used as the master surface while calculating the penetration depth, point of contact, contact normal etc. You can choose from:
• I: The geometry specified for the first body is the master.
• J: The geometry specified for the second body is the master surface.
• IANDJ: Both the geometries for the first and second bodies are used as master surface alternatively and the result is summed up.
• AUTO: Let MotionSolve decide which geometry to use as the master surface.
The attribute master_surface is optional.
When not specified, master_surface = "AUTO". This is also the recommended option.
active
Bool
Select one from TRUE or FALSE.
• TRUE indicates that the element is active in the model and it affects the behavior of the system.
• FALSE indicates that the element is inactive in the model and it does not affect the behavior of the system. It is almost as if the entity was removed from the model, of course with the exception that can be turned "ON" when desirable.
The attribute active is optional. When not specified, active defaults to TRUE.

Optional friction force specification These can be used with all normal force models

There are two options: Using the built-in friction model or using your own custom friction model. You can only select one of the two.

Using the built-in friction model
coulomb_friction
String. Choose one from: "ON", "OFF", "DYNAMICONLY", "USERCFF"
Specifies the friction force model that will be used to compute the contact friction force.
• "ON" specifies that friction forces are to be calculated and applied at the contact location. MotionSolve uses the Coulomb model for friction force.
• "OFF" specifies that frictional forces are not calculated or applied at the contact location. Friction is turned off.
• "DYNAMICONLY" specifies that only the dynamic friction is active.
• "USERCFF" specifies that a user defined friction force model is to be used.
See Comment 7 for more details.
mu_static
Double
Defines the coefficient of static friction when the friction is in the static regime.
Used only when coulomb_friction is not "USERCFF".
MotionSolve uses a step function to transition between the static and dynamic friction regimes. See Comment 7 for more details.
mu_static ≥ 0
mu_staticmu_dynamic
mu_dynamic
Double
Defines the coefficient of dynamic friction when the friction is in the dynamic regime.
Used only when coulomb_friction is not "USERCFF".
MotionSolve uses a step function to transition between the static and dynamic friction regimes. See Comment 7 for more details.
mu_dynamic ≥ 0
stiction_transition_velocity
Double
Defines the slip velocity at which the static coefficient of friction, MU_STATIC, is applied. See Comment 7 for more details.
Used only when coulomb_friction is not "USERCFF".
stiction_transition_velocity > 0
friction_transition_velocity
Double
Defines the slip velocity at which the dynamic coefficient of friction, MU_DYNAMIC, is applied. See Comment 7 for more details.
Used only when coulomb_friction is not "USERCFF".
friction_transition_velocitystiction_transition_velocity > 0

Using your own custom friction model

friction_function
String
The list of parameters that are passed from the data file to the user defined subroutine. The user defined subroutine CFFSUB is used.
The attribute must be specified when coulomb_friction = "USERCFF".
friction_routine
String or a pointer to a Python function.
Specifies the path and name of the shared library containing the friction force calculation subroutine. MotionSolve uses this information to load the user subroutine in the library at run time.
The friction_routine attribute is optional. When not specified.

## Example

1. Create a Contact object with the properties shown below:
<Force_Contact
id                   = "2"
num_i_graphics       = "1"
i_graphics_id        = "93"
num_j_graphics       = "1"
j_graphics_id        = "73"
cnf_type             = "POISSON"
penalty              = "1E6"
restitution_coef     = "0.52"
cff_type             = "COULOMB_ON"
mu_static            = "0.08"
mu_dynamic           = "0.06"
stiction_trans_vel   = "0.005"
friction_trans_vel   = "0.01"
/>
Equivalent Python
contact1 = Contact (type="POISSON", igeom=[gra93], jgeom=[gra73], penalty=1E6,
restitution_coefficient=0.52, coulomb_friction="ON", mu_static=0.08,
mu_dynamic=0.06, stiction_transition_velocity=0.005,
friction_transition_velocity=0.01)