Contact

Class Name

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)
iflex	Reference (FlexBody)
iflip_flex	Bool(False)
jgeom	Reference (Graphics, count=0)
jflex	Reference (FlexBody)
jflip_flex	Bool(False)
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
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.

Contact also 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)

Attributes

General: If body I is rigid, then you must define the attribute igeom and omit iflex. If body I is flexible, then iflex is mandatory, and the attribute igeom needs to be omitted. The same applies to body J.
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.
iflex: This argument specifies the ID of Flex_Body for the first body to be considered for contact.
jgeom: 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.
jflex: This argument specifies the ID of Flex_Body for the second body to be considered for contact.
type: String, choose between "IMPACT", "VOLUME", "POISSON", or "USER".; Specifies the normal force model 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.
This attribute is optional. MotionSolve automatically sets type = "IMPACT" when type is not specified.

Normal force type = "IMPACT"

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.; 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"

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.; 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.; 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.; 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"

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.; 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.
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".

Optional Parameters

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.

iflex_flip

Reverses the direction of the surface normal on flexible body I. This argument is optional. Choose from TRUE or FALSE.

The default is FALSE.

jflex_flip

Reverses the direction of the surface normal on flexible body J. This argument is optional. Choose from TRUE or FALSE.

The default is FALSE.

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.

Using the built-in friction model:

coulomb_friction

String. Choose one from: "ON", "OFF", "DYNAMICONLY", "USERCFF"

Specifies the friction force model that is 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.

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.

mu_static ≥ 0

mu_static ≥ mu_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.

mu_dynamic ≥ 0

stiction_transition_velocity

Double

Defines the slip velocity at which the static coefficient of friction, MU_STATIC, is applied.

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.

Used only when coulomb_friction is not "USERCFF".

friction_transition_velocity ≥ stiction_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

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)

Comments

See Properties for an explanation about what properties are, why they are used, and how you can extend these.
For a more detailed explanation about Contact, normal force types, and fiction types, see the Comments in the Force: Contact model statement.