Simulator Items

As described in Basic Concepts, physics engines are provided as “simulator items” in Choreonoid, and you can perform simulations in the common framework regardless of which simulator item you use. This page describes the list of available simulator items and the properties common to the simulator items. For the “AIST simulator”, which is the standard simulator item of Choreonoid, its own properties are also explained on this page.

Available Simulator Items

Choreonoid provides the following simulator items corresponding to physics engines.

Simulator item	Physics engine	Availability	Description
AIST simulator	Built-in engine	Available by default	The standard simulator item of Choreonoid. See AIST Simulator for details.
PhysX simulator	PhysX	Available by default	Uses PhysX, an open-source physics engine developed by NVIDIA. The source code of the engine is bundled with Choreonoid and it is available with the default build. See PhysX Plugin for details.
MuJoCo simulator	MuJoCo	Available by default	Uses MuJoCo, an open-source physics engine developed by Google DeepMind. A prebuilt library of the engine is bundled with Choreonoid and it is available with the default build. See MuJoCo Plugin for details.
Bullet simulator	Bullet Physics	Bullet plugin	Uses Bullet, an open-source physics library. In an environment where Bullet is installed, the Bullet plugin is built by default and the simulator becomes available. See Bullet Plugin for details.
ODE simulator	Open Dynamics Engine	ODE plugin	Uses ODE, an open-source dynamics library. In an environment where ODE is installed, the ODE plugin is built by default and the simulator becomes available. See ODE Plugin for details.
AGX simulator	AGX Dynamics	AGX Dynamics plugin	Uses AGX Dynamics, a commercial physics engine developed by Algoryx in Sweden. An AGX Dynamics license is required to use it. See AGX Dynamics Plugin for details.

Any of these simulator items can be used by placing it as a child item of the world item following the procedure explained in Creating a Simulation Project. It is also possible to place multiple simulator items in the same project and switch which one to use for each simulation.

As for which simulator item to use, we recommend starting with the standard AIST simulator. Depending on the simulation target and purpose, other physics engines may be more suitable, so if you have problems with accuracy, stability, computation speed, etc., it is worth trying the other simulator items as well. Refer to the pages linked above for the characteristics of each engine.

Note

In addition to the above simulator items that perform physics computation, there are also Sub-simulator items that complement the simulation functionality. A representative one is the “GL vision simulator” that simulates vision sensors such as cameras and range sensors. It can be used in combination with any simulator item. See Vision Sensor Simulation for details.

Properties Common to Simulator Items

The following properties are defined in the base part of the simulator items and are commonly available in all simulator items.

Property	Default value	Meaning
Temporal resolution type	Timestep	Selects how to specify the temporal resolution of the simulation from “Timestep”, “Framerate”, and “Time bar”. When “Time bar” is selected, the frame rate set for the time bar is used.
Time step	0.001 [s]	The time corresponding to one simulation step. It is displayed when the temporal resolution type is “Timestep”. Smaller values improve the accuracy and stability of the simulation, but increase the computation time.
Frame rate	1000 [Hz]	The number of steps per second. It is displayed when the temporal resolution type is “Framerate”.
Realtime sync	On (Compensatory)	Whether to synchronize the progress of the simulation with real time. See Synchronization with Real Time for details.
Time range	Unlimited	Selects the time range of the simulation from “Unlimited”, “Specified time”, and “Time bar range”. See Setting Time Range for details.
Time length	300 [s]	The simulation time length when the time range is “Specified time”. It is also used as the length of the recording period when the recording mode is “tail”.
Active control period only	false	When set to true, the simulation runs only while controllers are actively performing control. That is, the simulation ends when all controllers finish their control.
Recording	tail	Selects how to record the simulation results from “full”, “tail”, and “off”. See Recording Simulation Results for details.
All link position recording	true	Records the positions and orientations of all links as simulation results. When false, only the root link position and the joint displacements are recorded, which reduces memory usage. In that case, the positions of the other links are reproduced by forward kinematics during playback.
Device state output	true	Also records the states of devices such as sensors and lights as simulation results. See Recording Device States for details.
Record collision data	false	Records the collision data detected during the simulation. The recorded collision data can be used during the playback of the results.
Controller Threads	true	Executes controller processing in threads separate from the physics computation.
Controller options	(empty string)	Optional text passed to the controllers. How the contents are interpreted depends on the implementation of each controller.
Block scene view edit mode	false	When set to true, the scene view cannot be switched to the edit mode during simulation. Enable this if you want to prevent accidental operations during simulation.

Note

In addition to the above, each simulator item defines its own properties. They are explained in the AIST simulator section of this page and on the documentation page of each simulator plugin.

AIST Simulator

The AIST simulator (AIST simulator item) is the standard simulator item of Choreonoid, which performs simulation with its own physics engine built into Choreonoid. The engine uses a method that rigorously handles link systems connected by joints (articulated robots) in the joint coordinate space (forward dynamics computation based on the Featherstone’s method), and can simulate articulated robots stably and accurately. Contact forces are computed with a constraint-based method, and contact behaviors including friction and restitution can be simulated.

In version 2.5.0, this engine has been significantly improved, especially in the computational performance (scalability) in scenes where many objects are in contact with each other. The main improvements are as follows:

• Speedup by improving the internal structure of the contact force computation (introduction of a sparse matrix structure, etc.)

• Introduction of the contact point reduction function (setting of the maximum number of contact points per link pair)

• Support for parallelized collision detection

• Introduction of the function to analytically detect collisions between primitive shapes (boxes, spheres, cylinders, etc.)

• Support for the restitution coefficient

• Enhancement of the extra joint functionality (see Setting Extra Joints )

The AIST simulator can be created from the main menu with “File” - “New” - “AISTSimulator”.

Properties of the AIST Simulator

In addition to the common properties, the following properties are available in the AIST simulator item.

Property	Default value	Meaning
Dynamics mode	Forward dynamics	With “Forward dynamics”, dynamics computation following the laws of physics is performed. With “Kinematics”, no physics computation is performed and kinematic motions that directly reflect the command values to the joints are reproduced.
Integration mode	Semi-implicit Euler	Selects the numerical integration method from “Semi-implicit Euler” and “Runge-Kutta”. The semi-implicit Euler method is usually sufficient.
Gravity	0 0 -9.80665	The gravitational acceleration vector [m/s^2].
Min friction coefficient	0.0	The lower bound of the friction coefficients used in the contact computation. Friction coefficients given by the material settings etc. are limited to this value or more.
Max friction coefficient	100.0	The upper bound of the friction coefficients used in the contact computation.
Contact culling distance	0.005 [m]	The distance threshold for culling close contact points. Contact points within this distance are aggregated, which reduces the computational cost.
Contact culling depth	0.05 [m]	The depth (penetration) threshold used for culling contact points.
Error criterion	0.001	The error criterion for the convergence test of the iterative solver in the contact force computation. When 0 is set, no convergence test is performed and the solver always iterates the maximum number of times.
Max iterations	10	The maximum number of iterations of the iterative solver in the contact force computation. Larger values may improve accuracy, but increase the computation time.
Collision detection threads	0	The number of threads for parallelizing the collision detection. When 0, no parallelization is performed. In scenes with many objects, parallelization can speed up the collision detection.
Primitive shape collision detection	Follow world item setting	The setting of the function to analytically detect collisions between primitive shapes such as boxes and spheres without converting them into meshes. Select from “Follow world item setting”, “Enabled”, and “Disabled”. With this function, contacts between primitive shapes can be processed faster and more accurately.
Max contact points	4	The upper limit of the number of contact points per link pair. When the detected contact points exceed this number, they are reduced to representative contact points. When 0 is set, no reduction is performed.
CC depth	0.00025 [m]	The target depth for correcting the penetration of contacts.
CC v-ratio	5.0	The coefficient related to the correction velocity for correcting the penetration of contacts.
Drive effort output	false	When set to true, the torque (or force for a prismatic joint) actually used for driving each joint in each simulation step is written back as the joint effort value. This allows controllers to refer to the drive torques and allows them to be checked in the recorded data.
Kinematic walking	false	A mode that kinematically reproduces biped walking motions by switching the support foot based on the ground contact state of the soles when the dynamics mode is “Kinematics”.
2D mode	false	Performs the simulation with the motions of the objects constrained in a 2D plane.
Old accel sensor mode	false	A backward compatibility mode that makes the output of the acceleration sensors the same as the old specification. Not used normally.

The parameters related to contacts (friction coefficients, restitution coefficients, etc.) can also be set for each model (material) with the mechanism of Contact Materials.

Note

The AIST simulator uses AISTCollisionDetector, the built-in collision detector of Choreonoid, for its collision detection. The “Collision detection threads” and “Primitive shape collision detection” properties above are the settings related to the behavior of this collision detector. For the world item settings related to collision detection, see also Collision Detection.