Environment

The environment contains all of the objects and properties to define your virtual environment. This includes a list of all organsms and structures, and the ground and water surfaces. It is also where you configure global properties like the magnitude of gravity.

Environment Properties

Hydrodynamics

Currently hydrodynamics is not fully functional. It has not been fully implemented or tested. If you wish to use it please be advised that the physics for has not been verified. Hydrodynamics currently simulates the following forces. It is currently implemented in the following way

Fluid Density
If hydrodynamics is turned on then this defines the density of the fluid in the environment. This is only used for items that are immersed in water. An object is in water if it located between the ground plane and the water plane.
Default value: 1 g/cm³
Acceptable range: Any value greater than 0.

Max Hyrdo Force
This is the maximum hydrodynamic force that can be applied to an object.
Default value:100 N
Acceptable range: Any value greater than 0.

Max Hyrdo Torque
This is the maximum hydrodynamic torque that can be applied to an object.
Default value:100 Nm
Acceptable range: Any value greater than 0.

Simulation Hydrodynamics
If this property is true then hydrodynamics are simulated. If this value is false then no hydrodynamics are simulated.
Default value: False
Acceptable range: True/False

Mouse Spring Settings

When a simulation is run the user can grab pieces in the simulation to try and manipulate them. When the user holds down the shift and control keys and clicks on a rigid body using the left mouse button a spring is attached to the rigid body from the point where the initial click occured to the end of the mouse pointer. By moving the pointer you can stretch the spring to apply forces to the rigid body at the selected point. These two properties control the springs behavior.

Mouse Spring Damping
This sets the damping of the spring. In other words, this controls how quickly the force is applied for a given change in length.
Default value:100 Kg/s
Acceptable range: Any value greater than 0.

Mouse Spring Stiffness
This sets the stiffness of the spring. This is how much force is to be applied for a given change in length. If you increase this value then your mouse spring can apply more force using smaller movements. However, you need to be careful here because if you apply forces that are too large you will rip the parts away from their joints and cause the simulation to become unstable.
Default value:300 N/m
Acceptable range: Any value greater than 0.

Settings

Gravity
This is the magnitude of gravity. It is applied along the Y axis. If you want your simulation to take place in a weightless environment then set this value to zero.
Default value:-9.8 m/s²
Acceptable range: Any value.

Max Surface Friction
The maximum force that friction can apply to objects in the environment. Currently you can not change the friction coefficients. We are working on this and plan to add this feature in future upgrades.
Default value:15 KN
Acceptable range: Any value greater than or equal 0.

Physics Time Step
This is the time step for the physics engine. This is one of the most important properties for producing a stable simulation. It is imperitave that you set this appropriately. If your simulation uses small distance or mass units or large forces then you will need to reduce the time step to allow it to run stably.
Default value:1 ms
Acceptable range: Any value greater than 0.

Units

Another important way of making sure you simulation remains stable is to use the correct mass and distance units. The magnitude of the units for for all of you rigid bodies should remain be 0.01 and 100 in order to remain stable. For example, lets say you are simulating a grasshopper. They are around 5-6 cm long and have parts as small as 0.1 cm or so. The weight for parts ranges from 2.3 grams to 1.5 milligrams. So in this case we would probably use centimeters for our distance units and decigrams for our weight units. If on the other hand we were simulating a mobile robot we might decide to use meters and decigrams. You want the biggest units that will meet your needs and keep you within the 0.01-100 range that was mentioned.

The reason for this is that if there is a wide variation in masses or sizes between objects in the simulation it can lead to instabilities that cause large forces to be applied which cause things to blow up spectacularly. You want the largest units you can get though because the lower the unit values you use the slower your simulation will run. This is because the forces and everything else have to be scaled up proportionally at the same time. AnimatLab uses abstract distance and mass units internally. When you tell it to use centimeters then 1 unit = 1 cm. In this case though gravity would be -980 cm/s. So now in 1 second a block that would have moved 1 unit in a second will move many units in that same time. To deal with this you must decrease the physics time step.

Distance Units
This is the distance units for this simulation.
Default value:Centimeters
Acceptable range: Kilometers, Centameters, Decameters, Meters, Decimeters, Centimeters, Millimeters

Mass Units
This is the mass units for this simulation.
Default value:Grams
Acceptable range: Kilograms, Centagrams, Decagrams, Grams, Decigrams, Centigrams, Milligrams

World Stability

Constraints in Animatlab are equivalent to very stiff, strongly damped, spring damper systems for the case position constraints, and highly dissipative viscous drags for velocity constraints. Stiffness and damping coefficients of these potentials and dissipation functions are adjustable by the user. The physics integrator was designed to handle very large stiffness and damping so constraints can be made almost perfectly rigid in most cases without having to worry much about stability. But this leaves a few parameters controlling the overall stability and efficiency of the solver for the user to adjust namely, compliance and damping rate of position constraints, and the kinetic loss of velocity constraints. We now explain what these parameters mean and how to adjust them to produce a stable and efficient simulation.

Mechanical compliance is the ability of an object to yield elastically when a force is applied to it. Numerically, a compliance is the inverse of a stiffness. So, with zero compliance, constraints do not yield at all, and they become increasingly elastic with increasing compliance.

Now, the problem with systems of noncompliant constraints is that they can be degenerate, i.e., redundant or over defined, and solving such systems is more difficult and therefore slower than solving for systems which are known or assumed to be non-degenerate. What’s a degenerate system? Think of a table with four leg on a perfectly planar floor. You know that you can remove a leg without the table tipping over so one of the contact constraint with the floor is redundant and so the system is degenerate. Degenerate systems are very common–especially in cases where you have stacks and piles of objects–and AnimatLab was designed to process these easily and seamlessly. That is why we add a small amount of constraint compliance by default since this makes the system non-degenerate. Compliance is both a guard against degeneracy and a modeling tool since it can be used to relax any given constraint equation to produce a desired effect. For instance, it is possible to turn a fixed distance constraint into a stable stiff spring. A chain of bodies linked with compliant locked prismatic joints can be used to model a stiff cable which has elongation, torsion and bending resistance.

Because of compliance and other reasons related to numerics, constraints are never exactly satisfied in a AnimatLab simulation, and the constraint violations oscillate near zero. These oscillation can be damped using a constraint damping parameter. Without any damping, it is possible that a significant amount of the energy of your system ends up in these oscillations which is not very good. If damping is critical for a given compliance, you will get an optimal compromise in stability. For damping to be critical, you need the damping ratio defined as

where

is the damping coefficient, c is the compliance, and m is the mass. This formula applies to a simple harmonic oscillator with one point mass.

However, constraints usually involves two bodies or more, and since these attached bodies might also be constrained to other objects in your simulation. Therefore, computing the exact oscillation frequency and damping ratio of a given constraint for a given compliance is not as trivial is might first appear. Indeed, this involves computing eigenvalues of large matrices, and it is configuration dependent. Therefore, computing critical damping coefficients is not done automatically by AnimatLab and the user has make reasonable estimate.

To help this analysis, it is important to realize that the product of the compliance and damping coefficient has units of time and therefore, this defines a time scale in your system. Similarly, the ratio of compliance over squared time step has units of inverse mass and therefore,

is a unit of mass (or inertial tensor) of your system.

Now, a damping ratio of 1 means that you have critical damping and this will prevent oscillations and force constraints to stabilize quickly. When the damping ratio is close to 0–it is always positive–the constraints are under-damped and you can get high frequency oscillations with high energy–even instabilities in some cases. When the damping ratio is much larger than one, the constraint is over-damped and this can prevent stabilization, i.e., constraints will no longer relax to a state where they are satisfied but will remain permanently violated.

A velocity constraint is the limit case of a very strong viscous drag force, i.e., a generalized force of the form

, where v is the current velocity, v₀ is a target velocity. and l > 0 is the kinetic loss, i.e., the inverse of a viscous drag. In the limit where l goes to 0 (the viscous drag going to infinity), the system will satisfy the constraint v = v₀. Just like in the case of position constraint, we force l > 0 to avoid dealing with degenerate cases. The kinetic loss is proportional to time it takes to ramp up to the target velocity. When l is large, the system is sluggish and when it is small, it is very prompt.

Angular and linear degrees of freedom are scaled differently and this is why the full set of parameters are defined using the following properties

Angular Compliance
The compliance value of the spring used in angular collisions within the simulator.
Default value:0.1 um/N
Acceptable range: Any value greater than 0.

Angular Damping
The damping value of the spring used in angular collisions within the simulator.
Default value:50 Kg/s
Acceptable range: Any value greater than 0.

Angular Kinetic Loss
The amount of kinetic loss for angular collisions within the simulator.
Default value:1 ug/s
Acceptable range: Any value greater than 0.

Linear Compliance
The compliance value of the spring used in linear collisions within the simulator.
Default value:0.1 um/N
Acceptable range: Any value greater than 0.

Linear Damping
The damping value of the spring used in linear collisions within the simulator.
Default value:200 Kg/s
Acceptable range: Any value greater than 0.

Linear Kinetic Loss
The amount of kinetic loss for linear collisions within the simulator.
Default value:1 ug/s
Acceptable range: Any value greater than 0.

By default, compliance and kinetic loss are all near 10E-12 in double precision and 10E-4 in single precision. The damping coefficients are 10E10. This is small enough to make constraints almost rigid but can cause problems if the masses in your systems are big enough.

To understand the relation between these parameters and your system, the thing to observe is that linear compliance has the units of the inverse a spring constant and for a linear variable, these are: squared time over mass. The perturbation added to the system matrix, which has units of inverse mass, is

where c is the compliance, and h is the time step. Now, if e is much smaller than the inverse of the biggest mass in your system, it is then very close to 0 and will therefore have practically no influence on the overall dynamics.

As soon as you have masses large enough such such that e is comparable to the inverse, your system will be more compliant. This might be the effect you are looking for. Decreasing compliance will work up to a point where your system matrix is found to be singular or nearly so. At that point, your simulations will slow down because the LCP solver has a harder time finding solutions, and eventually, the matrix factorizer will detect that your matrices are no longer positive definite and this causes a fatal error.

The choosing the damping coefficients is not automated yet and sometimes require attention. To produce critical damping on a linear mode, one must know the mass of that mode. To see this, consider the simple damped harmonic oscillator:

, where m is the mass, b the damping coefficient, and k the spring constant. This spring is critically damped when

, where

is the natural frequency of the spring. The problem here is that it’s not clear what is the mass attached to one constraint. For instance, if you have a chain fixed on the ceiling with several links of mass m, and a load of mass M, the mass on each constraint will be close to M when the chain is at rest, pointing downward, and closer to m when horizontal. So, you cannot tell how to fix critical damping for all cases.

If damping is too high, the constraints will not relax back to zero violation and if there is insufficient damping, you might find instability.