Control Functions

Control Functions

These functions handle the asynchronous simulation control. The user can start the simulation, stop it and free memory, or pause it in order to issue get/set commands. The simulation MUST be paused in order for get/set commands to be issued.

void sim.start()

Starts the simulation, setting the global time of the simulation T to 0. Also initiates the OpenGL graphics rendering window and copies user-specified objects to GPU memory. As a performance consideration, it is best to create as many objects as possible before calling sim.start.

void sim.stop()

Stops the simulation permanently, freeing all allocated memory. No commands can be issued after sim.stop is called. This can also be run while the simulation is running, and can take an optional time parameter.

void sim.pause(double time)

Pauses the simulation at a given time, allowing the user to perform get and set operations. This is a blocking command on the CPU, and it should only be called when the user is ready to apply updates to the GPU and has no further computations to perform on the CPU.

Sample Code

sim.start(); // run indefinitely

while (True) {
    sim.pause(sim.time() + 1.0); // CPU hangs
    sim.getAll();
    sim.setSpringConstants(1000 * rand()); // set all spring constants to 1000
    sim.setAll();

    if (sim.time() > 20.0) {
        sim.stop();
        break;
    } else {
        sim.resume();
    }
}

void sim.resume()

Resumes the GPU thread, continuing the physics simulation.

double sim.time()

Returns the simulation global time.

Sample Code

sim.start();
// perform computations
sim.pause(1.0);
sim.set(...);
sim.resume();

void sim.wait(double t)

Pauses the user thread for T seconds in simulation time. Computation continues on the GPU. This is a blocking command on the CPU.

Sample Code

sim.start(); //start simulation
sim.wait(5.0); // pause user thread for 5 seconds

void sim.waitUntil(double T)

Pauses the user thread until simulation time T. This is a blocking command on the CPU.

Sample Code

sim.start(); // start simulation
sim.wait(2.0) // pause the user thread 2 seconds 
sim.waitUntil(5.0); //pause the user thread until t = 5 seconds

void sim.waitUntil(double T)

Pauses the user thread until simulation time T. This is a blocking command on the CPU.

void sim.setBreakpoint(double t)

Adds a breakpoint for time t, but does not block the CPU. The GPU will stop at time t with no callback or warning. It should be used in conjunction with sim.waitForEvent() to set non-blocking breakpoints. Be careful with this command, as modifying commands will produce errors if run while the simulation has not yet stopped.

void sim.waitForEvent()

Waits for the simulation to stop running (as the result of a breakpoint set by the user). This is a blocking command on the CPU.

Sample Code

sim.start(); //start simulation
sim.setBreakpoint(10.0);
sim.waitForEvent(); //pause user thread until next breakpoint, blocks CPU until time 10.0

bool sim.running()

Returns the simulation's running status. Returns false if sim.pause() or sim.stop() have been called.

Sample Code

sim.start(); //Simulations starts 
sim.running(); // returns true
sim.pause(1.0);
sim.running(); // returns false