Additional Parameters for Physical Materials

When using the AGX Dynamics plugin, the following physical material properties are available.

Sample

A sample demonstrating AGX Dynamics Plugin materials is available at: You can see how different parameter values affect the simulation behavior.

  • choreonoid/samples/AGXDynamics/agxMaterialSample.cnoid

Material Configuration Procedure

In AGXSimulator, friction coefficients and restitution coefficients between links can be adjusted using the following procedure:

  1. Define Material and ContactMaterial in a material file

  2. Set the Material defined in the material file in the body file

Material File

A material file is a list file that describes physical properties such as friction coefficients and restitution coefficients. This file can describe contact properties (ContactMaterial) for the same or different materials. By specifying the material name defined here in the body file, you can set materials for your models.

The material file is loaded by setting it in the world item properties. By default, choreonoid/share/default/materials.yaml is set and loaded automatically.

materials:
  -
    name: Ground
    roughness: 0.5
    viscosity: 0.0
  -
    name: agxMat5
    density: 1.0

contact_materials:
  -
    materials: [ Ground, agxMat5 ]
    youngs_modulus: 1.0e5
    restitution: 0.1
    spook_damping: 0.08
    friction: 0.416667
    surface_viscosity: 1.0e-8
    adhesion_force: 100
    adhesiv_overlap: 0.2
    friction_model: [ iterative, direct ]
    contact_reduction_mode: reduceGeometry
    contact_reduction_bin_resolution: 3

Material Parameter Descriptions

Bulk Material

Parameter

Default Value

Unit

Type

Description

density

1000

kg/m³

double

Density. Used for automatic calculation of link mass, inertia tensor, and center of mass.

youngs_modulus

4.0e8

Pa

double

Young’s modulus. Represents the stiffness of links (rigid bodies). Lower values make links more prone to interpenetration.

viscosity

0.5

-

double

Restitution viscosity. Pairs of restitution viscosity values determine the restitution coefficient.

spook_damping

0.075

s

double

Spook damping. Used to relax interpenetration between links (satisfying constraint conditions).

poissonRatio

0.3

-

double

Poisson’s ratio (deprecated since 2.27.0.0)

Surface Material

Parameter

Default Value

Unit

Type

Description

roughness

0.5

-

double

Surface roughness. Pairs of surface roughness values determine the friction coefficient.

surface_viscosity

5e-09

-

double

Surface viscosity. Viscosity acting in tangential directions. Pairs of surface viscosity values become the ContactMaterial’s surface_viscosity. Used to represent wetness like oil.

adhesion_force

0.0

N

double

Adhesion force. When shapes are in contact, adhesion force acts in the normal direction. Used for adhesive-like behavior.

adhesiv_overlap

0.0

m

double

Adhesion effective distance. Adhesion force becomes active when link penetration > effective distance.

Note

For materials with defined ContactMaterial, the ContactMaterial parameters are used. Surface material parameters from Material are not used.

Wire Material

Parameter

Default Value

Unit

Type

Description

wire_youngs_modulus_stretch

6e10

Pa

double

Tensile Young’s modulus

wire_spook_damping_stretch

0.075

s

double

Tensile spook damping

wire_youngs_modulus_bend

6e10

Pa

double

Bending Young’s modulus

wire_spook_damping_bend

0.075

s

double

Bending spook damping

ContactMaterial Parameter Descriptions

Parameter

Default Value

Unit

Type

Description

youngs_modulus

2.0e8

Pa

double

Young’s modulus

restitution

0.0

-

double

Restitution coefficient. 0: perfectly inelastic collision, 1: perfectly elastic collision

spook_damping

0.075

s

double

Spook damping

friction

0.5

-

double

Friction coefficient

secondary_friction

-1.0

-

double

Secondary direction friction coefficient. Enabled when secondary_friction>=0 and friction model is set to oriented_box, oriented_scaled_box, constant_normal_force_oriented_box, or oriented_iterative.

surface_viscosity

1.0e-8

-

double

Surface viscosity coefficient. Compliance for friction constraints.

secondary_surface_viscosity

-1.0

-

double

Secondary direction surface viscosity coefficient. Enabled when secondary_friction>=0 and friction model is set to oriented_box, oriented_scaled_box, constant_normal_force_oriented_box, or oriented_iterative.

adhesion_force

0.0

N

double

Adhesion force

adhesiv_overlap

0.0

m

double

Adhesion effective distance

friction_model

[ default, default ]

-
string
string
Friction model: default(iterative), iterative, box, scaled_box, oriented_box, oriented_scaled_box, constant_normal_force_oriented_box, oriented_iterative
Solver: default(split), split, direct, iterative, direct_and_iterative

contact_reduction_mode

default

-

string

Contact reduction mode: default(reduceGeometry), reduceGeometry, reduceALL, reduceNone

contact_reduction_bin_resolution

0

-

uint8_t

Contact reduction bin resolution. Uses AGXSimulator item parameter when 0.

primary_direction

[ 0, 0, 0 ]

Unit vector

Vec3

Primary direction vector when using orientedBox friction model

reference_body

-

-

string

Reference body name when using orientedBox friction model

reference_link

-

-

string

Reference link name when using orientedBox friction model

Note

AGX Dynamics does not distinguish between dynamic and static friction coefficients. In practice, the difference is only 10-20%, which is negligible in most situations.

Note

Additional friction models have been added since Choreonoid 1.7. The iterative and constant_normal_force_oriented_box models correspond to the cone and orientedBox models used up to version 1.7.

When ContactMaterial is Not Defined

Ideally, all material pair properties should be described in ContactMaterial, but this can be difficult. When ContactMaterial is not defined, parameter values are calculated according to the following formulas using parameters described in Material. Default values are applied when parameters are not set in Material either.

  • youngs_modulus = (m1.youngs_modulus * m2.youngs_modulus)/(m1.youngs_modulus + m2.youngs_modulus)

  • restitution = sqrt((1-m1.viscosity) * (1-m2.viscosity))

  • spook_damping = max(m1.spook_damping, m2.spook_damping)

  • friction = sqrt(m1.roughness * m2.roughness)

  • surface_viscosity = m1.surface_viscosity + m2.surface_viscosity

  • adhesion_force = m1.adhesion_force + m2.adhesion_force

Material Description in Body Files

This section explains how to describe materials in body files. Center of mass, mass, and inertia can be either directly specified or automatically calculated using density, selectable via massType. The default is mass.

massType: mass             # Direct specification
massType: density          # Automatic calculation using density

Materials can be selected from those defined in the material file or directly specified. The default is Default or default as defined in the material file.

material: Default          # Default material
material: Ground           # Material
material: useLinkInfo      # Direct specification

Below are description examples.

Note

Currently, calculation results for center of mass, mass, and inertia tensor using density are held internally in AGX Dynamics and cannot be retrieved or confirmed from Choreonoid links or GUI.

Traditional Notation

  • Traditional Choreonoid notation

  • Uses the described center_of_mass, mass, and inertia

  • Material becomes default except for density

  • ContactMaterial becomes default vs xxxxx

links:
  -
    name: box1
    center_of_mass: [ 0, 0, 0 ]
    mass: 1.0
    inertia: [
      0.02, 0,    0,
      0,    0.02, 0,
      0,    0,    0.02 ]