Python SDK /fastsim.app

fastsim.app

2 classes

Primary entry point for loading configuration, building the scene, and running the simulation loop. FastSim wraps the full lifecycle: init → setup → reset → step/start → close.

FastSim StepContext
class

FastSim

18 methods
fastsim.app.FastSim

Main application class that orchestrates config loading, simulation initialization, scene setup, and the step loop.

Instantiate with an optional config path, call setup_all_before_loop() for one-shot initialization, then drive the loop manually with step() or let start() / start_with_task() manage it. Use add_step_callback() to hook into each tick.

__init__constructor
def __init__(self, config_path: str | None = None)

Create a FastSim instance, optionally loading config immediately.

Parameters
NameTypeDefaultDescription
config_pathoptstr|NoneNonePath to a YAML/JSON config file. If omitted, config must be loaded later via load_config().
load_configmethod
def load_config(self, config_path: str) → None

Load (or reload) the config from a file path.

Parameters
NameTypeDefaultDescription
config_pathstr—Absolute or relative path to a YAML/JSON configuration file.
Returns
None — Mutates internal ConfigManager state.
initialize_simulationmethod
def initialize_simulation(self) → None

Initialize the UniSim backend (e.g. Isaac Lab). Must be called before scene setup.

Returns
None
setup_all_before_loopmethod
def setup_all_before_loop(self) → None

One-shot initialization: initialize backend → enable extensions → build scene → reset.

Recommended way to prepare the simulation before entering a step loop. Equivalent to calling initialize_simulation(), enabling extensions, setting up the scene, and reset() in order.

Returns
None
Call this before any step() or start() invocation.
Extensions must be configured in the config file before this call.
resetmethod
def reset(self) → None

Reset all scene entities to their initial state.

Returns
None
stepmethod
def step(self) → None

Run one simulation tick: pre_step → UniSim.step → post_step → step callbacks.

Returns
None
Use this for fine-grained manual control of the loop.
pre_stepmethod
def pre_step(self) → None

Hook executed at the start of each tick, before the backend step.

Returns
None
post_stepmethod
def post_step(self) → None

Hook executed at the end of each tick, after the backend step.

Returns
None
is_runningmethod
def is_running(self) → bool

Return True while the simulation has not been terminated.

Returns
bool — False after request_terminate() has been called and processed.
request_terminatemethod
def request_terminate(self) → None

Signal the simulation loop to stop at the end of the current tick.

Returns
None
start_simulation_loopmethod
def start_simulation_loop(self) → None

Block and run the simulation loop until is_running() returns False.

Returns
None
add_step_callbackmethod
def add_step_callback(self, callback: Callable) → None

Register a callable invoked with a StepContext at the end of every tick.

Parameters
NameTypeDefaultDescription
callbackCallable—Function accepting a StepContext (step: int, dt: float).
Returns
None
add_terminate_callbackmethod
def add_terminate_callback(self, callback: Callable) → None

Register a callable invoked once when the simulation terminates.

Parameters
NameTypeDefaultDescription
callbackCallable—Function accepting a StepContext.
Returns
None
add_controller_threadmethod
def add_controller_thread(self, thread_func: Callable, thread_name: str, daemon: bool, terminate_sim_on_exit: bool) → threading.Thread

Register a controller function to be run in a dedicated thread.

Parameters
NameTypeDefaultDescription
thread_funcCallable—Target function for the thread.
thread_namestr—Human-readable name for the thread.
daemonbool—Whether the thread is a daemon thread.
terminate_sim_on_exitbool—If True, the simulation will be terminated when this thread exits.
Returns
threading.Thread — The created Thread object (not yet started).
start_controller_threadsmethod
def start_controller_threads(self) → None

Start all threads registered via add_controller_thread().

Returns
None
startmethod
def start(self) → None

Start controller threads and run the simulation loop until termination.

Returns
None
start_with_taskmethod
def start_with_task(self, stop_sim_on_task_end: bool = True) → None

Run the configured task in a controller thread and optionally stop when it ends.

Parameters
NameTypeDefaultDescription
stop_sim_on_task_endoptboolTrueIf True, request_terminate() is called automatically when the task finishes.
Returns
None
closemethod
def close(self, show_time_consumption: bool = False) → None

Shut down the simulation and release backend resources.

Parameters
NameTypeDefaultDescription
show_time_consumptionoptboolFalseIf True, print a summary of time spent in each simulation phase.
Returns
None
class

StepContext

2 methods
fastsim.app.StepContext

Dataclass passed to step and terminate callbacks carrying per-tick metadata.

stepproperty
@property def step(self) → int

The current simulation step index (0-based integer).

Returns
int
dtproperty
@property def dt(self) → float

The physics timestep duration in seconds.

Returns
float