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

**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: ** 200 g/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:** 0.5 N/m

**Acceptable range:** Any value greater than 0.

**Settings**

Alpha Threshold

This is a setting used to control the threshold of when alpha values are used or discarded within the OSG scene. This is a not something you should typically be messing with. If you have some parts that have transparency and they are showing rings around their edges then you can adjust this and see if it fixes your problem, otherwise I would leave this alone.

**Default value:** 0.2 ^{}

**Acceptable range:** A value between 0 and 1.

AutoGenerate Random Numbers

If this is true then the random number generator will be automatically seeded with a value generated from the current time when the simulation starts. If it is false then the Manual Random Seed property will be shown so you can specify a seed you want to use for every run of the simulation.

**Default value:** True

**Acceptable range:** True/False.

Manual Random Seed

If AutoGenerate Random Numbers is set to false then this property is shown. It allows you to enter a seed that you would like to use for every run of the simulation.

**Default value:** 12345

**Acceptable range:** Any value greater than 0.

Background Color

Allows you to set the color of the simulation background.

**Default value:** Blue

**Acceptable range:** Any valid color.

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^{2}

**Acceptable range:** Any value.

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:** 0.5 ms

**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

Selected Vertex Radius

The radius of the sphere used to show the selected vertex while in receptive field mode.

**Default value:** 5 mm

**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_{0} 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_{0}. 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.

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.

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.

Alpha Threshold

This is a setting used to control the threshold of when alpha values are used or discarded within the OSG scene. This is a not something you should typically be messing with. If you have some parts that have transparency and they are showing rings around their edges then you can adjust this and see if it fixes your problem, otherwise I would leave this alone.

AutoGenerate Random Numbers

If this is true then the random number generator will be automatically seeded with a value generated from the current time when the simulation starts. If it is false then the Manual Random Seed property will be shown so you can specify a seed you want to use for every run of the simulation.

Manual Random Seed

If AutoGenerate Random Numbers is set to false then this property is shown. It allows you to enter a seed that you would like to use for every run of the simulation.

Background Color

Allows you to set the color of the simulation background.

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.

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.

**Acceptable range:** Any value greater than 0.

Simulate Hydrodynamics

If this property is true then hydrodynamics are simulated. If this value is false then no hydrodynamics are simulated. This value will be set to true automatically when you add a fluid plane to the simulation.

**Default value: **False

**Acceptable range:** True/False

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.

Mass Units

This is the mass units for this simulation.

Selected Vertex Radius

The radius of the sphere used to show the selected vertex while in receptive field mode.

**Acceptable range:** Any value greater than 0.

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

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.

Angular Damping

The damping value of the spring used in angular collisions within the simulator.

Angular Kinetic Loss

The amount of kinetic loss for angular collisions within the simulator.

Linear Compliance

The compliance value of the spring used in linear collisions within the simulator.

Linear Damping

The damping value of the spring used in linear collisions within the simulator.

Linear Kinetic Loss

The amount of kinetic loss for linear collisions within the simulator.

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.