embodichain.lab.sim.profiler

Lightweight hierarchical profiler shared by simulation and environments.

The profiler records sections below an explicit root section. A root entered while another root is active is transparent, allowing lower-level simulation instrumentation to compose with an environment’s profiling hierarchy without adding duplicate path components.

Classes:

Profiler	Hierarchical wall-time profiler.
ProfilerCfg	Configuration for hierarchical wall-time profiling.

class embodichain.lab.sim.profiler.Profiler

Bases: object

Hierarchical wall-time profiler.

Parameters:

• cfg (Optional[ProfilerCfg]) – Profiler configuration. None disables profiling entirely.

• device (device) – Device used for optional CUDA synchronization and NVTX ranges.

Note

One profiler tracks one synchronous call stack. Use it on the simulation thread that owns the associated simulation manager.

Attributes:

enabled

Whether profiling is active.

Methods:

report()	Log a profiling report table and optionally dump JSON.
section(name, *[, is_root])	Record wall time for a named section.

property enabled: bool

Whether profiling is active.

report()

Log a profiling report table and optionally dump JSON.

Return type:

Dict[str, object]

Returns:

Report data, or an empty dictionary when profiling is disabled.

section(name, *, is_root=False)

Record wall time for a named section.

Parameters:

• name (str) – Leaf section name. The full name is derived from the active section stack.

• is_root (bool) – Whether this section starts a top-level profiling sample. A nested root is transparent and its children remain attached to the active outer hierarchy.

Return type:

Iterator[None]

class embodichain.lab.sim.profiler.ProfilerCfg

Bases: object

Configuration for hierarchical wall-time profiling.

Attributes:

color_output	Color terminal report rows by logical module.
enable_time	Enable per-section wall-time statistics (mean/min/max/std).
nvtx	Push NVTX ranges for sections so they appear in Nsight Systems.
output_path	Optional JSON path written by Profiler.report().
sync_cuda	Synchronize CUDA at section boundaries for accurate GPU wall time.
warmup_steps	Number of top-level root sections to discard before recording.

color_output: bool

Color terminal report rows by logical module.

This only affects the logged table; JSON report data remains unchanged.

enable_time: bool

Enable per-section wall-time statistics (mean/min/max/std).

nvtx: bool

Push NVTX ranges for sections so they appear in Nsight Systems.

output_path: str | None

Optional JSON path written by Profiler.report().

sync_cuda: bool

Synchronize CUDA at section boundaries for accurate GPU wall time.

warmup_steps: int

Number of top-level root sections to discard before recording.