environment_tutorial.md

Environment module

In this tutorial you can learn how to:

• Manage the simulation options
• Initialize the simulation
• Add objects to the environment

Manage the simulation options

There are 40 simulation options that can be changed from the scripts. Please refer to NeuroMechFly/simulation/bullet_simulation.py to check each of the options. Here we list the ones used in our scripts to manage the environment:

• headless: The GUI is not shown if True. This speeds up the simulation.
• model: Global path to the sdf file with the desired model description.
• pose: Global path to the yaml file with the desired initial pose.
• results_path: Global path where the results will be stored.
• model_offset: Model's base offset [x, y, z] (in meters) when the simulation starts.
• run_time: Total time of the simulation in seconds.
• time_step: Time step of the simulation in seconds.
• base_link: Link defined as the starting point of the kinematic chain.
• ground_contacts: List of link names from which ground reactions forces will be obtained.
• self_collisions: List of link names from which self-collision forces will be obtained.
• draw_collisions: If True, links in contact with the ground or experiencing self-collisions (if defined in the self-collision variable) are painted green.
• record: If True a video from the simulation is recorded. This variable is accesible from our script's flags. headless variable should be False.
• save_frames: If True an image for each time step of the simulation will be stored in the folder specified in the results_path variable.
• camera_distance: Distance (in millimeters) from the rendering camera to the model's base link.
• track: If True the camera will follow the model as it moves in the environment.
• moviename: Name of the recorded video with the global path. If record is True.
• moviespeed: Speed for the recorded video, 1 corresponds to real time. If record is True.
• slow_down: If True the simulation is paused sleep_time seconds after each time step.
• sleep_time: Sleep time when slow_down is True.
• rot_cam: If True the camera rotates around the model as in our Kinematic Replay videos.
• behavior: Specifies which behavior we are simulating (walking, grooming, or None) for selecting the treadmill position, if ball_info is False, and the rot_cam sequence.
• ground: Specifies what will be considered the ground during the simulation (ball or floor).
• ground_friction_coef: Specifies the lateral friction coefficient for the ground specified in ground.
• ball_info: If True a file named treadmill_info__* will be read to obtain the treadmill's position and size.
• ball_mass: Specifies the mass of the treadmill. If None the mass is calculated based on its size and the density of polyurethane foam.
• solver_iterations: Specifies the number of iterations used by the phisics engine solver during each time step. Default value is 1000, if you decrease it the simulation will run faster but the solver could not converge to a feasible solution.

You can refer to any of the scripts in the scripts/kinematic_replay folder to have an example of how to use them.

Initializing the simulation

When the simulation is initialized, you can set other parameters besides the simulation options explained above. For example, as shown in the snippet below, we can (i) set the controller gains (kp and kv) if we are using PyBullet's PD controller, (ii) specify the position of joints that should remain fixed during the simulation, and (iii) define the paths where data can be found. We use this kind of initialization for the Kinematic Replay scripts. You can find examples of usage in scripts/kinematic_replay/. If you want to add other variables during initialization you need to modify the class DrosophilaSimulation found in any script in the folder NeuroMechFly/experiments.

animal = kinematic_replay.DrosophilaSimulation(
        container,
        sim_options,
        kp=0.4, kv=0.9,
        angles_path=angles_path,
        velocity_path=velocity_path,
        starting_time=starting_time,
        fixed_positions=fixed_positions
    )

Adding objects to the environment

Please refer to the PyBullet documentation for a complete guide on how to include objects in your simulation. We include objects in the simulation in three ways. The NeuroMechFly model is imported from a sdf file which contains the model's description (see the biomechanics tutorial). External perturbations shown in Video 10 from our related publication were added from a urdf file. This is another format supported by PyBullet that is used to describe objects (you can find this example in the file NeuroMechFly/experiments/kinematic_replay/kinematic_replay_no_support.py). Finally, we included the spherical treadmill in the simulation using the createMultiBody built-in function from PyBullet. You can refer to NeuroMechFly/simulation/bullet_simulation.py to see an example of how we use this function.