Search
Login
  • Register
AnimatLab AnimatLab Menu
  • Getting Started
  • Home
  • Community
    • Forum
    • Animat Warehouse
    • Wiki
    • Contributers
      • David Cofer
  • Download
    • AnimatLab 2.0
    • AnimatLab Windows SDK
    • AnimatLab Linux SDK
      • SDK on an NVIDIA Jetson TK1
    • AnimatLab 1.0
  • Store
  • Help
    • Documentation
      • Project Workspace
        • Environment
        • Organism
        • Structure
        • Simulation
        • Playback Speed
      • Neural Network Editor
        • Neural Simulation Plug-ins
        • Node Properties
        • Link Properties
        • Relabel
        • Relabel Selected
        • Select By Type
      • Biomechanical Editor
        • Biomechanical Body Parts
        • Food Sources
        • Joints
        • Receptive Fields
        • Material Types
        • Bullet Physics Engine
      • Robotics
        • Robot Interfaces
        • Robot IO Controllers
          • Dynamixel USB
          • Firmata
            • Arbotix Firmata
          • XBee Commander
          • Remote Control
        • Remote Controls
          • XBee Commander
          • AnimatSerial
      • Simulator
      • Data Tools
        • Line Chart
        • Scripted Simulation Window
      • Stimuli
        • Neural Stimuli
        • Mechanical Stimuli
        • General Stimuli
      • References
    • Tutorials
      • Using AnimatLab
        • AnimatLab Scripting
        • Biomechanical Editor
        • Line Charts
        • Neural Network Editor
        • Relabeling Items
        • User Interface V2
        • User Interface V1
      • Examples
        • Belly Flopper
        • Crayfish
        • Eating Frog
        • Hexapod Robot
        • Human Stretch Reflex
        • Limb Stiffness
        • Locust
        • Predator-Prey
        • Stretch Reflex
        • Touch Receptors
      • Body Parts
        • Hinge
        • Motorized Joints
        • Muscle
        • Spring
        • Stretch Receptor
        • Meshes
        • Constraint Relaxation
      • Data Tools
        • Line Charts
        • Scripted Simulation Window
      • Mechanical Tests
        • Balancing Forces
        • Pendulum
        • Springs
      • Neural Networks
        • Bistable Firing Rate Neuron
        • Classical Conditioning
        • Compartmental Model
        • Coordination
        • Endogenous Bursters
        • Electrical Synapses
        • Firing Rate Gated Synapse
        • Firing Rate Modulatory Synapse
        • Firing Rate Normal Synapse
        • Integrate And Fire Neurons
        • Lateral Inhibition
        • Long-Term Potentiation
        • Network Oscillators
        • Non-Spiking Chemical Synapses
        • Normal Firing Rate Neuron
        • Property Control
        • Random Firing Rate Neuron
        • Spiking Chemical Synapses
        • Voltage Dependent Synapses
      • Sensory Systems
        • Contact Sensors
        • Eating
        • Joint Angle
        • Odor Tracking
        • Touch Receptive Fields
      • Stimuli
        • Adding Current Stimuli
        • Enabler Stimulus
        • Force Stimulus
        • Motor Velocity
        • Position Clamp
        • Property Control
      • SDK
        • AnimatLab Scripting
        • Neural Module
        • Physics Module
        • Program Modules
        • SDK Basics
      • Robotics
        • Robot Arm Tutorials
          • Robot Arm Description
          • Robot Arm Simulation Setup
          • Robot Arm Control Part 1
          • Robot Arm Control Part 2
          • Robot Arm Position and Velocity Control
          • Robot Arm Joystick Control
        • PhantomX Hexapod Tutorials
          • PhantomX Hexapod Preview
    • SDK Help
HelpDocumentationProject WorkspaceEnvironment
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/s2
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

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

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

Acceptable range: Any value greater than 0.

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, v0 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 = v0. 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.
If you like AnimatLab and find it useful, then please donate in order to help support it. Thanks for your support!
  • Environment
    Allows the user to configure the environment of a virtual world of AnimatLab
  • Organism
    Describes biomechanical organsims in the biomechanical and neuromechanical simulations in AnimatLab
  • Structure
    Describes structures in the biomechanical and neuromechanical simulations in AnimatLab
  • Simulation
    Biomechanical and neural network simulations in AnimatLab.
  • Playback Speed
    Control the playback of biomechanical and neuromechanical simulations in AnimatLab



This project was supported by:


National Science Foundation

exploratory grant (GM065762)


Terms Of Use | Privacy Statement
Copyright 2011 by NeuroRobotic Technologies LLC
Open Source ASP.NET CMS by DNN