Skip to content

Commit c062919

Browse files
MartinOtterMartinOtter
committed
Documentation improved (and wrong links corrected)
1 parent 675dbed commit c062919

File tree

3 files changed

+109
-22
lines changed

3 files changed

+109
-22
lines changed

‎docs/src/man/CollisionHandling.md‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Modia3D supports collisions of objects that are defined with a contact material
55
and (a) have a convex geometry, or (b) can be approximated by a set of
66
convex geometries, or (c) have a concave geometry that is (automatically)
77
approximated by its convex hull. When contact occurs, the response
8-
is computed with elastic force/torque laws based on the
8+
is computed with elastic (nonlinear) force/torque laws based on the
99
penetration depth and the relative motion of the objects in contact.
1010
It is planned to optionally also support impulsive response calculation
1111
in the future.
@@ -20,9 +20,10 @@ in order that a simulation is successful:
2020
otherwise a variable step-size integrator will typically fail. The reason is that
2121
the penetration depth is computed from the difference of tolerance-controlled
2222
variables and the precision will be not sufficient if a higher tolerance will be
23-
used because the penetration depth is in the order of ``10^{-5} .. 10^{-6}~ m``.
23+
used because the penetration depth of hard contact materials
24+
is in the order of ``10^{-5} .. 10^{-6}~ m``.
2425
A relative tolerancie of ``10^{-5}`` might be used, if the heuristic
25-
elastic contact reduction factor ``k_{red} = 10^{4}`` (see below).
26+
elastic contact reduction factor is set to ``k_{red} = 10^{4}`` (see [Material constants](@ref) below).
2627

2728
- A reasonable reliable simulation requires that objects have only
2829
*point contact*, since otherwise the contact point can easily ``jump`` between
@@ -55,22 +56,23 @@ and relative angular velocities. This region is defined by the following constan
5556
the relative angular velocity (see below).
5657

5758
Finally, the heuristic factor ``k_{red}`` (default = 1.0) can be defined with keyword argument
58-
`elasticContactReductionFactor` in the `SceneOptions` constructor. The goals is the following:
59-
Applying the elastic response calculation on hard materials
60-
such as steel, typically results in penetration depths in the order of
61-
``10^{-5} .. 10^{-5} m``. A penetration depth is implicitly computed by the
62-
difference of the absolute positions of the objects in contact and
63-
these absolute positions are typically error-controlled variables of
64-
the integrator. This in turn means that typically at least a relative
65-
tolerance of ``10^{-8}`` needs to be used for the integration, in order that
66-
the penetration depth is computed with 2 or 3 significant digits.
67-
To improve simulation speed, factor ``k_{red}``
68-
reduces the stiffness of the contact and therefore enlarges the
69-
penetration depth. If ``k_{red}`` is for example set to ``10^{4}``, the penetration
70-
depth might be in the order of ``10^{-3} m`` and then a relative tolerance
71-
of ``10^{-5}`` might be sufficient. In many cases, the essential response
72-
characteristic is not changed (just the penetration depth is larger),
73-
but simulation speed is significantly improved.
59+
`elasticContactReductionFactor` in the [`Modia3D.SceneOptions`](@ref) constructor.
60+
The goal is the following:
61+
Applying the elastic response calculation on hard materials
62+
such as steel, typically results in penetration depths in the order of
63+
``10^{-5} .. 10^{-6} m``. A penetration depth is implicitly computed by the
64+
difference of the absolute positions of the objects in contact and
65+
these absolute positions are typically error-controlled variables of
66+
the integrator. This in turn means that typically at least a relative
67+
tolerance of ``10^{-8}`` needs to be used for the integration, in order that
68+
the penetration depth is computed with 2 or 3 significant digits.
69+
To improve simulation speed, factor ``k_{red}``
70+
reduces the stiffness of the contact and therefore enlarges the
71+
penetration depth. If ``k_{red}`` is for example set to ``10^{4}``, the penetration
72+
depth might be in the order of ``10^{-3} m`` and then a relative tolerance
73+
of ``10^{-5}`` might be sufficient. In many cases, the essential response
74+
characteristic is not changed (just the penetration depth is larger),
75+
but simulation speed is significantly improved.
7476

7577

7678
## Response calculation
@@ -188,7 +190,7 @@ friction force and contact torque have a similar characteristic)
188190
There are several proposal to compute the damping coefficient as a function
189191
of the coefficient of restitution ``cor`` and the
190192
velocity when contact starts ``\dot{\delta}^-``.
191-
For a comparision of the different formulations see [^1].
193+
For a comparision of the different formulations see [^1], [^3].
192194

193195
Whenever the coefficient of restitution ``cor > 0``, then an object 2 jumping on an object 1 will
194196
mathematically never come to rest, although this is unphysical. To fix this, the value of a

‎src/Composition/scene.jl‎

Lines changed: 86 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,11 @@ include(joinpath(Modia3D.path, "src", "contactDetection", "ContactDetectionMPR",
127127

128128
#-------------------------------------- Gravity field ----------------------------------
129129

130+
"""
131+
gravityField = NoGravityField()
132+
133+
Generate an instance of type `NoGravityField` that defines no gravity.
134+
"""
130135
struct NoGravityField <: Modia3D.AbstractGravityField
131136
gvec::SVector{3,Float64} # [m/s^2] Vector of gravity acceleration
132137
NoGravityField() = new(SVector{3,Float64}(0.0, 0.0, 0.0))
@@ -169,7 +174,7 @@ const EarthRadius = 6.3781e6 # [m] Radius of earth (https://en.wik
169174

170175

171176
"""
172-
PointGravityField(mass), PointGravityField(;mue=G*EarthMass)
177+
PointGravityField([mass|;mue=G*EarthMass])
173178
174179
Return a PointGravityField struct with the gravity field constant mue (mue = G*mass).
175180
@@ -202,6 +207,86 @@ gravityAcceleration(grav::PointGravityField, r_abs::AbstractVector) = -(grav.mue
202207

203208
#-------------------------------------- Global Scene Options -------------------------------
204209

210+
"""
211+
sceneOptions = Modia3D.SceneOptions(;kwargs...)
212+
213+
Define global options for a simulation of the scene with keyword arguments:
214+
215+
| Keyword arguments | defaults |
216+
|:------------------------------|:----------------------------------------|
217+
| enableContactDetection | true |
218+
| elasticContactReductionFactor | 1.0 |
219+
| gravityField | [`Modia3D.UniformGravityField`](@ref)() |
220+
| enableVisualization | true |
221+
| visualizeGravity | true |
222+
| visualizeFrames | false |
223+
| visualizeConvexHulls | true |
224+
| visualizeContactPoints | false |
225+
| visualizeSupportPoints | false |
226+
| nominalLength | 1.0 |
227+
| defaultFrameLength | 0.2*nominalLength |
228+
| defaultJointLength | nominalLength/10 |
229+
| defaultJointWidth | nominalLength/20 |
230+
| defaultForceLength | nominalLength/10 |
231+
| defaultForceWidth | nominalLength/20 |
232+
| defaultBodyDiameter | nominalLength/9 |
233+
| defaultWidthFraction | 20 |
234+
| defaultArrowDiameter | nominalLength/40 |
235+
| `defaultN_to_m` | 1000 |
236+
| `defaultNm_to_m` | 1000 |
237+
| useOptimizedStructure | true |
238+
| defaultContactSphereDiameter | 0.1 |
239+
| contactDetection | ContactDetectionMPR_handler() |
240+
241+
242+
# Optional keyword arguments
243+
244+
- `enableContactDetection::Bool`: = true, if contact detection is enabled
245+
- `elasticContactReductionFactor::Float64`: used_contact_compliance = contact_compliance * elasticContactReductionFactor (> 0).
246+
- `gravityField::Modia3D.AbstractGravityField`: Type of gravity field, such as:
247+
[`Modia3D.NoGravityField`](@ref),
248+
[`Modia3D.UniformGravityField`](@ref),
249+
[`Modia3D.PointGravityField`](@ref).
250+
- `enableVisualization::Bool`: = true, if animation is enabled
251+
- `visualizeGravity::Bool`: = true, if gravity field shall be visualized (acceleration vector or field center)
252+
- `visualizeFrames::Bool`: = true, if all frames shall be visualized
253+
- `visualizeConvexHulls::Bool`: = true, if convex hulls (used for contact detection) shall be visualized
254+
- `visualizeContactPoints::Bool`: = true, if contact points shall be visualized
255+
- `visualizeSupportPoints::Bool` = true, if support points shall be visualized
256+
- `nominalLength::Float64`: [m] Nominal length of 3D system
257+
- `defaultFrameLength::Float64`: [m] Default for frame length if visualizeFrames = true (but not world frame)
258+
- `defaultJointLength::Float64`: [m] Default for the fixed length of a shape representing a joint
259+
- `defaultJointWidth::Float64`: [m] Default for the fixed width of a shape representing a joint
260+
- `defaultForceLength::Float64`: [m] Default for the fixed length of a shape representing a force (e.g., damper)
261+
- `defaultForceWidth::Float64`: [m] Default for the fixed width of a shape representing a force (e.g., spring, bushing)
262+
- `defaultBodyDiameter::Float64`: [m] Default for diameter of sphere representing the center of mass of a body
263+
- `defaultWidthFraction::Float64`: Default for shape width as a fraction of shape length
264+
- `defaultArrowDiameter::Float64`: [m] Default for arrow diameter (e.g., of forces, torques, sensors)
265+
- `defaultN_to_m::Float64`: [N/m] Default scaling of force arrows (length = force/defaultN_to_m)
266+
- `defaultNm_to_m::Float64`: [N.m/m] Default scaling of torque arrows (length = torque/defaultNm_to_m)
267+
- `useOptimizedStructure::Bool`: = true, if the optimized structure (with super objects, and common inertia) is used
268+
- `defaultContactSphereDiameter::Float64`: [m] Diameter of sphere used for contact point visualization
269+
- `contactDetection::Modia3D.AbstractContactDetection`: Handler used for contact detection
270+
(for example to determine the smallest distance between two objects).
271+
272+
273+
# Example
274+
275+
For all the details see "Modia3D/examples/dynamics/Simulate_Pendulum.jl":
276+
277+
```julia
278+
279+
@assembly Pendulum(;Lx = 1.0) begin
280+
...
281+
end
282+
283+
pendulum = Pendulum(Lx=1.6, sceneOptions=
284+
Modia3D.SceneOptions(visualizeFrames=true, defaultFrameLength=0.3))
285+
model = Modia3D.SimulationModel( pendulum )
286+
result = ModiaMath.simulate!(model, stopTime=4.5)
287+
```
288+
289+
"""
205290
struct SceneOptions
206291
useOptimizedStructure::Bool # = true, if the optimized structure (with super objects, and common inertia) is used
207292

‎src/Solids/contactPairMaterials.jl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ end
114114
"""
115115
contactPairMaterialPalette
116116
117-
Dictionary of contact pair material data, see [`Modia3D.ContactPairMaterial`](@ref)
117+
Dictionary of contact pair material data, see [`Modia3D.ElasticContactPairMaterial`](@ref)
118118
"""
119119
contactPairMaterialPalette = readContactPairMaterialFromJSON( joinpath(Modia3D.path, "palettes", "contactPairMaterials.json") )
120120

0 commit comments

Comments
 (0)