Tutorials: Setup

Launching and stopping a simulation

The simulation can be launched using two different modes, as pictured below.

The simulation can be launched using a SimulationManager object:

from qibullet import SimulationManager

if __name__ == "__main__":
    simulation_manager = SimulationManager()
    client_id = simulation_manager.launchSimulation(gui=True)

    # Your code here...

This code snippet will launch a simulated instance, and will spawn an OpenGL rendering window. The gui parameter allows the user to choose whether to display a graphical interface or not (GUI or DIRECT mode). You can theoretically launch an unlimited amount of simulated instance in headless - without a GUI - mode (the limit is set by the computing power available), but only one at a time with a GUI.

from qibullet import SimulationManager

if __name__ == "__main__":
    simulation_manager = SimulationManager()
    client_gui = simulation_manager.launchSimulation(gui=True)
    client_direct_0 = simulation_manager.launchSimulation(gui=False)
    client_direct_1 = simulation_manager.launchSimulation(gui=False)
    ###
    client_direct_n = simulation_manager.launchSimulation(gui=False)

    # Your code here...

In this snippet, we launch a simulation instance in GUI mode, and n instances in DIRECT mode: the launchSimulation method will return the id of the created instance. Please note that the n created instances will run in the same process and won't be parallelized.

Since qibullet 1.4.0 the shared_memory_server (experimental) feature allows you to parallelize the motion servers of your headless simulation instances, using the SHARED_MEMORY_SERVER pybullet mode (see the pybullet documentation for more details). This feature allows you to handle multiple instances much more efficiently.

The above graph describes a simple comparison between the headless modes when handling multiple instances. Be aware that this feature is computationally expensive, always create strictly less instances than you number of CPU cores. The following snippet describes how to create two instances in that mode:

simulation_manager = SimulationManager()
client_a = simulation_manager.launchSimulation(gui=False, use_shared_memory=True)
client_b = simulation_manager.launchSimulation(gui=False, use_shared_memory=True)

# Your code here...

simulation_manager.stopSimulation(client_a)
simulation_manager.stopSimulation(client_b)

The SimulationManager object can also be used to reset or stop a simulated instance:

simulation_manager = SimulationManager()
client_id = simulation_manager.launchSimulation(gui=True)
simulation_manager.resetSimulation(client_id)
simulation_manager.stopSimulation(client_id)

# Your code here...

The methods can be called independently, resetSimulation will remove all of the simulated objects in an instance but leave the instance running, while stopSimulation will stop the instance.

By default, a simulated instance will have a gravity of -9.81m/s^2 on the world's Z axis. Calling the getGravity method of SimulationManager (getting the gravity of a simulated instance) on a default simulated instance will henceforth return [0.0, 0.0, -9.81]. The gravity of said simulated instance can be updated with the setGravity method of SimulationManager:

client_id = simulation_manager.launchSimulation(gui=True)

# Simulating things on the moon in the client_id instance
simulation_manager.setGravity(client_id, [0.0, 0.0, -1.62])

# Get the gravity of the client_id instance
gravity = simulation_manager.getGravity(client_id)

Spawning a virtual robot in the simulation

A virtual robot can be spawned using the simulation manager:

from qibullet import SimulationManager
from qibullet import RomeoVirtual
from qibullet import PepperVirtual
from qibullet import NaoVirtual

if __name__ == "__main__":
    simulation_manager = SimulationManager()
    client_id = simulation_manager.launchSimulation(gui=True)
    pepper = simulation_manager.spawnPepper(
        client_id,
        spawn_ground_plane=True)

    nao = simulation_manager.spawnNao(
        client_id,
        translation=[0, 2, 0],
        quaternion=[0, 0, 0, 1])

    romeo = simulation_manager.spawnRomeo(
        client_id,
        spawn_ground_plane=False)

    # Your code here...

In this snippet:

• A virtual Pepper will be spawned in the client_id instance, at the origin of the simulation world frame with no rotation on its base. A ground will also be spawned at the same time.
• A virtual NAO will be spawned in the client_id instance, at the position [0, 2, 0] in the simulation world frame with no rotation.
• A virtual Romeo will be spawned in the client_id instance, at the origin of the simulation world frame with no rotation.

By default, the translation and quaternion parameters are respectively set to [0, 0, 0] and [0, 0, 0, 1]. The spawn_ground_plane parameter is set to False by default.

A virtual robot can also be spawned using the PepperVirtual, NaoVirtual or RomeoVirtual class directly, but the virtual environment needs to be launched first:

pepper = PepperVirtual()
nao = NaoVirtual()

pepper.loadRobot(
    translation=[0, 0, 0],
    quaternion=[0, 0, 0, 1],
    physicsClientId=client_id)

nao.loadRobot(
    translation=[0, 2, 0],
    physicsClientId=client_id)

# Your code here...

Removing a virtual robot from the simulation

A spawned virtual robot can be removed from a simulated instance using the simulation manager:

from qibullet import SimulationManager
from qibullet import NaoVirtual

if __name__ == "__main__":
    simulation_manager = SimulationManager()
    client_id = simulation_manager.launchSimulation(gui=True)
    nao = simulation_manager.spawnNao(
        client_id,
        spawn_ground_plane=True)

    # Your code here...

    simulation_manager.removeNao(nao)

In this snippet:

• A virtual NAO will be spawned in the client_id instance along with a ground plane.
• The spawned NAO will be removed from the instance.

The NAO, Pepper and Romeo robots can be removed from a simulated instance by respectively using the methods removeNao, removePepper and removeRomeo

Manual vs Auto stepping

By default, when a simulation is launched with the simulation manager, simulation stepping is done automatically (in GUI or DIRECT mode). If one wants to manually step the simulation, the auto_step parameter should be set to False when launching the simulation. The simulation then needs to be stepped manually, using the stepSimulation method of the simulation manager.

from qibullet import SimulationManager


if __name__ == "__main__":
    simulation_manager = SimulationManager()
    client_id = simulation_manager.launchSimulation(gui=True, auto_step=False)

    try:
        while True:
            # Your code here...
            simulation_manager.stepSimulation(client)

    except KeyboardInterrupt:
        pass

    simulation_manager.stopSimulation(client)

In this snippet:

• A simulation (with a GUI and manual stepping) is spawned.
• A loop contains some user code, and the stepSimulation method, stepping the simulation.
• The simulation is stopped.

Documentation

For a more complete overview of the qiBullet API, please see the API documentation.