# Simulator Documentation¶

The simulator class creates an instance of a simulation. You can send various objects and parameters using the send methods.

Example usage:

sim = pyrosim.Simulator()
sim.send_cylinder()

sim.start()

class pyrosim.Simulator(play_blind=False, play_paused=False, eval_time=100, dt=0.05, gravity=-1.0, window_size=(750, 500), xyz=[0.8317, -0.9817, 0.8], hpr=[121, -27.5, 0.0], use_textures=False, debug=False, capture=0)[source]

Python interface for ODE simulator

play_blind

bool, optional – If True the simulation runs without graphics (headless) else if False the simulation runs with graphics (the default is False)

play_paused

bool, optional – If True the simulation starts paused else if False the simulation starts running. With simulation window in focus use Ctrl-p to toggle pausing the simulation. (the default is False)

eval_time

int, optional – The number of discrete steps in the simulation (the default is 100)

dt

float, optional – The time in seconds between physics world steps. Larger dt values create more unstable physics. (the default is 0.05)

gravity

float, optional – The gravity in the system. Negative values implies normal downward force of gravity. (default is -1.0)

window_size

tuple or list of 2 ints, optional – The initial window size for the visualization. Irrelevant if blind=True. Default is (750, 500)

xyz

list of 3 floats – The xyz position of the camera (default is [0.8317,-0.9817,0.8000])

hpr

float, optional – The heading, pitch, and roll of the camera (default is [121,-27.5,0.0])

use_textures

bool, optional – Draw default ODE textures or not during simulation. (default is False)

debug

bool, optional – If True print out every string command sent through the pipe to the simulator (the default is False)

capture

bool, optional – If True captures frames of the simulation every capture timesteps. Meaningless if playing blind. (the default is False)

assign_collision(group_1, group_2)[source]

Create collision potential between group 1 and group 2

Parameters: group_1 (str) – The string handle of group 1 group_2 (str) – The string handle of group 2 True if successful bool
create_collision_matrix(collision_type='none')[source]

Create a predefined collision matrix

Parameters: collision_type (str, optional) – Creates a collision matrix specifying the type of collision between groups desired. There are 4 options ‘none’ - no collision ‘inter’ - collisions on only between different groups ‘intra’ - collisions on only within groups ‘all’ - both inter and intra group collisions True if successful bool
film_body(body_id, method='follow')[source]

Sets the camera to film a body

Camera has two modes: ‘follow’ moves the camera’s position based on where the body is moving and ‘track’ rotates the camera to look at the body

Parameters: body_id (int) – The id tag of the body to be filmed method (str, optional) – The way the camera should move to film the body. Either ‘follow’ or ‘track’ (default is ‘follow’) True if successful, False otherwise bool
get_data()[source]

Get all sensor data back as numpy matrix

get_group_id(group)[source]

Returns the id of the collision group

get_group_names()[source]

Returns a list containing the collision groups names

get_num_bodies()[source]

Returns the number of bodies

get_num_groups()[source]

Returns the number of collision groups

get_num_joints()[source]

Returns the number of joints

get_num_neurons()[source]

Returns the number of neurons

get_num_sensors()[source]

Returns the number of sensors

get_sensor_data(sensor_id, svi=0)[source]

Get the post simulation data from a specified sensor

Parameters: sensor_id (int) – the sensors id tag svi (int , optional) – The sensor value index. Certain sensors have multiple values (e.g. the position sensor) and the svi specifies which to access (e.g. for a position sensor, svi=0 corresponds to the x value of that sensor) Returns the list of sensor values over the simulation. list of float
make_movie(movie_name='')[source]

Takes captured image files and converts them into a movie

Uses ffmpeg to convert images. ffmpeg needs to be installed for this command to work. Takes images from ‘frame’ directory

Parameters: movie_name (string, optional) – The movies file name. Must include a proper extenison. If left blank, default is to make a time stamped file name: ‘%Y-%m-%d-%H-%M-%S_movie.mp4’ True if successful, False otherwise bool
remove_collision(group_1, group_2)[source]

Turn off collision potential between group 1 and 2 :param group_1: The string handle of group 1 :type group_1: str :param group_2: The string handle of group 2 :type group_2: str

Returns: True if successful bool
send_bias_neuron()[source]

Send bias neuron to simulator.

Bias neurons emit a constant value of 1.0

Returns: id tag of the neuron int
send_box(x=0, y=0, z=0, mass=1.0, r1=0, r2=0, r3=1, length=0.1, width=0.1, height=0.1, collision_group='default', r=1, g=1, b=1)[source]

Send box body to the simulator

Parameters: x (float, optional) – The x position coordinate of the center (default 0) y (float, optional) – The y position coordinate of the center (default 0) z (float, optional) – The z position coordinate of the center (default 0) mass (float, optional) – The mass of the body (default is 1.0) length (float, optional) – The length of the box width (float, optional) – The width of the box height (float, optional) – The height of the box collision_group (str or int, optional) – The collision group the body is assigned to. The collision group determines how the body collides with other bodies. The default group is labeled ‘default’. r (float, optional) – The amount of the color red in the body (r in [0,1]) g (float, optional) – The amount of the color green in the body (g in [0,1]) b (float, optional) – The amount of the color blue in the body (b in [0,1]) id tag of the box int
send_camera(xyz, hpr)[source]

Sends camera position to simulator in eulerian coordinates

Parameters: xyz (list of floats) – A length 3 list specifying the x,y,z position of the camera in simulation hpr (list of floats) – A length 3 list specifying the heading, pitch, and roll of the camera in degrees True if successful, False otherwise bool
send_cylinder(x=0, y=0, z=0, r1=0, r2=0, r3=1, length=1.0, radius=0.1, mass=1.0, collision_group='default', r=1, g=1, b=1, capped=True)[source]

Send cylinder body to the simulator

Parameters: x (float, optional) – The x position coordinate of the center (default is 0) y (float, optional) – The y position coordinate of the center (default is 0) z (float, optional) – The z position coordinate of the center (default is 0) mass (float, optional) – The mass of the body (default is 1.0) r1 (float, optional) – The orientation along the x axis. The vector [r1,r2,r3] specify the direction of the long axis of the cylinder. (default is 0) r2 (float, optional) – The orientation along the y axis. The vector [r1,r2,r3] specify the direction of the long axis of the cylinder. (default is 0) r3 (float, optional) – The orientation along the z axis. The vector [r1,r2,r3] specify the direction of the long axis of the cylinder. (default is 1) length (float, optional) – The length of long axis of the cylinder (default is 1.0) radius (float, optional) – The radius of the short axis of the cylinder (default is 0.1) r (float, optional) – collision_group (str or int, optional) – The collision group the body is assigned to. The collision group determines how the body collides with other bodies. The default group is labeled ‘default’. r – The amount of the color red in the body (r in [0,1]) g (float, optional) – The amount of the color green in the body (g in [0,1]) b (float, optional) – The amount of the color blue in the body (b in [0,1]) capped (bool, optional) – Use a hemisphere cap at the end of the cylinder or not. Collision detection in flat-ended cylinders usually takes more effort. The id tag of the cylinder int
send_developing_synapse(source_neuron_id=0, target_neuron_id=0, start_weight=0.0, end_weight=0.0, start_time=0.0, end_time=1.0)[source]

Sends a synapse to the simulator

Developing synapses are synapses which change over time. The synapse will interpolate between the start_weight and end_weight over the desired time range dictated by start_time and end_time. start_time and end_time are in [0,1] where 0 maps to time step 0 and 1 maps to the eval_time of the simulation. Setting start_time equal to end_time results in a discrete change from start_weight to end_weight in the synapse at the specified time step. If start_time >= end_time times are changed such that end_time = start_time.

Parameters: source_neuron_id (int, optional) – The id of the source neuron of the synapse target_neuron_id (int, optional) – The id of the target neuron of the synapse start_weight (float, optional) – The starting edge weight of the synapse end_weight (float, optional) – The ending edge weight of the synapse start_time (float, optional) – The starting time of development. start_time in [0,1] end_time (float, optional) – The ending time of development. end_time in [0,1] True if successful, False otherwise bool
send_external_force(body_id, x, y, z, time=0)[source]

Sends a directed force to a body at a specific time

Parameters: body_id (int) – The body to apply the force to x (float) – The amount of force in the x direction y (float) – The amount of force in the y direction z (float) – The amount of force in the z direction time (float, optional) – When the force should be applied. (default is 0) True if successful, False otherwise bool
send_fixed_joint(first_body_id, second_body_id)[source]

Fix two bodies (or a body and space) together

This is implemented by using a hinge joint and setting the hi and low stop parameter to 0. This is probably not the best way to do it…

Parameters: first_body_id (int) – The body id of the first body the joint is connected to. If set equal to -1, the joint is connected to a point in space second_body_id (int) – The body id of the second body the joint is connected to. If set equal to -1, the joint is connected to a point in space True if successful bool
send_function_neuron(function=<built-in function sin>)[source]

Send neuron to simulator which takes its value from the function

The function is mapped to the specific time in the simulation based on both the discrete evaluation time and the dt space between time steps. For example if evalTime=100 and dt=0.05 the function will be evaluated at [0,0.05,…,5]

Parameters: function (function, optional) – The function which defines the neuron value. Valid functions return a single float value over the time domain. The id tag of the neuron int
send_hidden_neuron(tau=1.0, alpha=1.0)[source]

Send a hidden neuron to the simulator

Hidden neurons are basic neurons which can have inputs and outputs. They ‘hidden’ between input neurons (sensors, bias, function) and output neurons (motors)

Parameters: tau (float, optional) – The ‘learning rate’ of the neuron. Increasing tau increases how much of value of the neuron at the current time step comes from external inputs vs. the value of the neuron at the previous time step. alpha – The ‘remembrance rate’ of the neuron. Usually 1 or 0. The id tag of the neuron int
send_hinge_joint(first_body_id, second_body_id, x=0, y=0, z=0, n1=0, n2=0, n3=1, lo=-0.7853981633974483, hi=0.7853981633974483, speed=1.0, torque=10.0, position_control=True)[source]

Send a hinge joint to the simulator

Hinge joints rotate around the axis specified by [n1,n2,n3]

Parameters: first_body_id (int) – The body id of the first body the joint is connected to. If set equal to -1, the joint is connected to a point in space second_body_id (int) – The body id of the second body the joint is connected to. If set equal to -1, the joint is connected to a point in space x (float, optional) – The x position coordinate of the joint (default is 0) y (float, optional) – The y position coordinate of the joint (default is 0) z (float, optional) – The z position coordinate of the joint (default is 0) n1 (float, optional) – The orientation along the x axis. The vector [n1,n2,n3] specifies the axis about which the joint rotates (default is 0) n2 (float, optional) – The orientation along the y axis. The vector [n1,n2,n3] specifies the axis about which the joint rotates (default is 0) n3 (float, optional) – The orientation along the z axis. The vector [n1,n2,n3] specifies the axis about which the joint rotates (default is 1) lo (float, optional) – The lower limit in radians of the joint (default is -pi/4) hi (float, optional) – The upper limit in radians of the joint (default is pi/4) speed (float, optional) – The speed of the motor of the joint (default is 1.0) torque (float, optional) – The maximum amount torque the motor in the joint can use (default is 10.0) position_control (bool, optional) – True means use position control. This means the motor neuron output is treated as a target angle for the joint to actuate to. False means the motor neuron output is treated as a target actuation rate. The id tag for the hinge joint int
send_is_seen_sensor(body_id)[source]

Attaches a sensor which detects when a body is being hit by a ray sensor

Parameters: body_id (int) – The body id to connect the sensor to The id tag of the sensor int
send_light_sensor(body_id)[source]

Attaches a light sensor to a body in simulation

Parameters: body_id (int, optional) – The body id of the body to connect the sensor to The id tag of the sensor int
send_light_source(body_id=0)[source]

Attaches light source to a body in simulation

Parameters: body_id (int, optional) – The body id of the body to attach the light to The id tag of the body the light source is attached to. int
send_motor_neuron(joint_id=0, tau=1.0, alpha=1.0, start_value=0.0)[source]

Send motor neurons to simulator

Motor neurons are neurons which connect to a specified joint and determine how the joint moves every time step of simulation

Warning

Sending a motor neuron to a joint whose starting position is not in the middle of the ‘hi’ & ‘lo’ cutoffs will most likely cause instabilities in the simulation. For example creating a joint with either ‘hi’ or ‘lo’ to 0 and attaching a motor neuron to this joint will cause the joint to break.

Parameters: joint_id (int, optional) – The joint id tag of the joint we want the neuron to connect to tau (float, optional) – The ‘learning rate’ of the neuron. Increasing tau increases how much of value of the neuron at the current time step comes from external inputs vs. the value of the neuron at the previous time step. (default 1) alpha (float, optional) – The ‘remembrance rate’ of the neuron. Usually 1 or 0. An alpha of 1 helps reduce jitter in positionally controlled joints. (default is 1) start_value (float, optional) – The starting value of the neuron. This value is specified to mitigate the problem of a joint starting not on its midpoint for positionally controlled joints. Set to +1 or greater for close to the ‘hi’ range and -1 or less for close to ‘lo’ range (default is 0.0) The id tag of the neuron int
send_position_sensor(body_id=0)[source]

Attaches a position sensor to a body in simulation

Parameters: body_id (int, optional) – The body id of the body to connect the sensor to The id tag of the sensor int
send_proprioceptive_sensor(joint_id=0)[source]

Attaches a proprioceptive sensor to a joint in simulation

Proprioceptive sensors returns the angle of the joint at each time step

Parameters: joint_id (int, optional) – The joint id of the joint to connect the sensor to The id tag of the sensor int
send_ray_sensor(body_id=0, x=0, y=0, z=0, r1=0, r2=0, r3=1, max_distance=10)[source]

Sends a ray sensor to the simulator connected to a body

Ray sensors return four values each time step, the distance and color (r,g,b).

Parameters: body_id (int, optional) – The body id of the associated body the ray sensor is connected to. When this body moves the ray sensor moves accordingly x (float, optional) – The x position of the sensor y (float, optional) – The y position of the sensor z (float, optional) – The z position of the sensor r1 (float, optional) – The x direction of the sensor. The array [r1,r2,r3] is the direction the ray sensor is pointing in the time step. r2 (float, optional) – The y direction of the sensor. The array [r1,r2,r3] is the direction the ray sensor is pointing in the time step. r3 (float, optional) – The z direction of the sensor. The array [r1,r2,r3] is the direction the ray sensor is pointing in the time step. max_distance (float, optional) – The maximum distance away the ray can sense in simulator units. (default is 10.0) The id tag of the sensor int
send_sensor_neuron(sensor_id=0, svi=0)[source]

Sends a sensor neuron to the simulator

Sensor neurons are input neurons which take the value of their associated sensor

Parameters: sensor_id (int, optional) – The associated sensor id for the neuron to draw values from. svi (int, optional) – The sensor value index is the offset index of the sensor. SVI is used for sensors which return a vector of values (position, ray sensors, etc.) The id tag of the neuron int
send_slider_joint(first_body_id, second_body_id, x=0, y=0, z=1, lo=-0.25, hi=0.25, speed=1.0, strength=10.0, position_control=True)[source]

Send a slider joint to the simulator

Slider joints push and pull two bodies along the axis defined by [x_dir,y_dir,z_dir]
Parameters: first_body_id (int) – The body id of the first body the joint is connected to. If set equal to -1, the joint is connected to a point in space second_body_id (int) – The body id of the second body the joint is connected to. If set equal to -1, the joint is connected to a point in space x (float, optional) – The orientation along the x axis. (default is 0) y (float, optional) – The orientation along the y axis. (default is 0) z (float, optional) – The orientation along the z axis. (default is 1) lo (float, optional) – The lower limit in simulator units of the joint (default is -1.0) hi (float, optional) – The upper limit in simulator units of the joint (default is 1.0) speed (float, optional) – The speed of the motor of the joint (default is 10.0) strength (float, optional) – The maximum amount of force the motor in the joint can use (default is 1.0) position_control (bool, optional) – True means use position control. This means the motor neuron output is treated as a position for the joint to actuate to. False means the motor neuron output is treated as a target actuation rate. The id tag for the hinge joint int
send_sphere(x=0, y=0, z=0, r1=0, r2=0, r3=1, radius=0.1, mass=1.0, collision_group='default', r=1, g=1, b=1)[source]

Sends a sphere to the simulator

Parameters: x (float, optional) – The x position of the center y (float, optional) – The y position of the center z (float, optional) – The z position of the center mass (float, optional) – The mass of the body (default is 1.0) radius (float, optional) – The radius of the sphere (default is 0.5) collision_group (str or int, optional) – The collision group the body is assigned to. The collision group determines how the body collides with other bodies. The default group is labeled ‘default’. r (float, optional) – The amount of the color red in the body (r in [0,1]) g (float, optional) – The amount of the color green in the body (g in [0,1]) b (float, optional) – The amount of the color blue in the body (b in [0,1]) The id tag of the sphere int
send_synapse(source_neuron_id=0, target_neuron_id=0, weight=0.0)[source]

Sends a synapse to the simulator

Synapses are the edge connections between neurons

Parameters: source_neuron_id (int, optional) – The id of the source neuron of the synapse target_neuron_id (int, optional) – The id of the target neuron of the synapse weight (float, optional) – The edge weight of the synapse True if successful, False otherwise bool
send_thruster(body_id, x=0, y=0, z=-1, lo=-10.0, hi=10.0)[source]

Send a thruster engine to the specified body

The thruster engine provides a linear force to the center of mass of the assigned body in the specified direction

body_id : int
The handle of the body the jet should be attached to
x : float, optional
The x value of the directional vector (default is 0)
y : float, optional
The y value of the directional vector (default is 0)
z : float, optional
The z value of the directional vector (default is 1)
lo : float, optional
The amount of force when the associated motor neuron is -1. Negative implies force in the opposit direction. (default is -10)
hi : float, optioal
The amount of force when the associated motor neuron is +1. (default is 10)
Returns: The id handle of the thruster int
send_touch_sensor(body_id=0)[source]

Send touch sensor to a body in the simulator

Parameters: body_id (int, optional) – The body id of the associated body The id tag of the sensor int
send_user_input_neuron(in_values)[source]

Send neuron to the simulator which takes user defined values

Parameters: in_values (list of floats or float, optional) – The user specified values for the neuron. If length of values < the number of time steps, the values are continually looped through until every time step has a corresponding value The id tag of the neuron. int
send_vestibular_sensor(body_id=0)[source]

Connects a vestibular sensor to a body

Vestibular sensors return a bodies orientation in space

Parameters: body_id (int, optional) – The body id of the associated body The id tag of the sensor int
start()[source]

Starts the simulation

wait_to_finish()[source]

Waits to for the simulation to finish and collects data

Returns: A matrix of the sensor values for each time step of the simulation numpy matrix
pyrosim.make_sure_path_exists(path)[source]

checks to se if path exists, if not creates path