novaphy.utils

Engine-wide infrastructure: thread-local profiling, device descriptors, CUDA stream / graph-capture hooks, version / build-feature detection, and scaffold helpers. These symbols live at the top level of novaphy; they are grouped here to mirror newton.utils.

Profiling

PerformanceMonitor is NovaPhy's primary profiling entry point. It is thread-local: outside a with monitor.scoped(): context every C++ phase scope returns without recording a timestamp, so solver public APIs stay free of profiling parameters. Inside the block it captures aggregate per-phase timings and (optionally) emits a Chrome / Perfetto trace.

import novaphy

monitor = novaphy.PerformanceMonitor()
monitor.enabled = True
monitor.trace_enabled = True

for _ in range(120):
    with monitor.scoped():
        solver.step(state, state, control, contacts, dt)

for stat in monitor.phase_stats():
    print(stat.name, stat.avg_ms)
monitor.write_trace_json("trace.json")

Mirrors Newton's EventTracer / event_scope pattern; instantiate one PerformanceMonitor per worker thread when running parallel rollouts.

Devices

Device and DeviceType describe a compute device (CPU or CUDA ordinal). Most users never need to construct one explicitly — ModelBuilder.finalize() defaults to Device.cpu(). Pass an explicit Device.cuda(ordinal=N) only when targeting a specific GPU for fluid CUDA backends or when interleaving multi-GPU work.

Version and Feature Detection

Use these checks at startup to decide which solvers / backends to construct:

import novaphy

print(novaphy.version())
print("IPC enabled      :", novaphy.has_ipc())
print("MuJoCo CUDA      :", novaphy.has_mujoco_cuda())
print("Featherstone CUDA:", novaphy.has_featherstone_cuda())
print("SPH CUDA         :", novaphy.has_sph_cuda())
print("VBD CUDA         :", novaphy.has_vbd_cuda())
print("VBD DLAN         :", novaphy.has_vbd_dlan())

SolverIPC and IPCConfig are None when IPC is not built — always combine with has_ipc() before constructing.

CUDA Stream and Graph Capture

NovaPhy keeps CUDA capture orchestration outside solver APIs. Install a thread-local stream when integrating with a framework-owned stream, or wrap a warm, allocation-free stepping loop in CudaGraphCapture:

capture = novaphy.CudaGraphCapture(device_ordinal=0)

with capture:
    solver.step(state, state, control, contacts, dt)

capture.launch()
capture.synchronize()

CudaGraphCapture is a driver-level helper. Allocate model, state, contacts, and solver scratch before capture; the captured body must not resize buffers or perform host-side setup.

Scaffold Helpers

is_scaffold(obj) and scaffold_reason(obj) let downstream tooling (parity tests, telemetry, Isaac Lab adapters) detect constructed placeholder solver instances at runtime and skip / report them gracefully:

mpm = novaphy.solvers.SolverMPM(model)
if novaphy.is_scaffold(mpm):
    print(novaphy.scaffold_reason(mpm))
    # → "SolverMPM.step raises until Material Point Method kernels land."

Currently registered scaffold: SolverMPM. Real backends, including SolverLBM, return False from is_scaffold(). Pass an instance; the current helpers do not identify the unconstructed class objects.

Profiling

Class	Description
PerformanceMetric	Single named metric value captured per frame.
PerformanceMonitor	Thread-local profiling context with Chrome / Perfetto trace export.
PerformancePhaseStat	Aggregate per-phase statistics.

Devices

Class	Description
Device	Device descriptor (CPU / CUDA, ordinal).
DeviceType	Device type enumeration.
DeviceArray concrete classes	Concrete device-buffer wrappers exposed by runtime objects.

CUDA Runtime

Class / Function	Description
CudaGraphCapture	Driver-level CUDA graph capture helper.
set_current_cuda_stream()	Install an opaque CUDA stream pointer for this thread.
current_cuda_stream()	Return the current thread-local CUDA stream pointer.
clear_current_cuda_stream()	Clear the thread-local CUDA stream override.
synchronize_current_cuda_stream()	Synchronize the current stream, or the device fallback.
current_cuda_stream_is_capturing()	Report whether the current stream is under CUDA capture.

Version and Feature Detection

Function	Description
has_featherstone_cuda()	Whether the Featherstone CUDA backend is available.
has_ipc()	Whether the package was built with IPC / libuipc.
has_mujoco_cuda()	Whether the native SolverMuJoCo CUDA backend is available.
has_sph_cuda()	Whether the SPH CUDA backend is available.
has_vbd_cuda()	Whether the SolverVBD CUDA backend is available.
has_vbd_dlan()	Whether the SolverVBD Denglin DLAN backend is available.
version()	Engine version string.

Scaffold Helpers

Function	Description
is_scaffold()	Returns whether an object instance is a scaffold placeholder.
scaffold_reason()	Returns an instance's scaffold reason string (or None).

Compatibility Notes

Newton's newton.utils includes mesh authoring (MeshAdjacency, remesh_mesh, solidify_mesh, validate_triangle_mesh, validate_tet_mesh), graph utilities (color_graph, plot_graph), texture helpers, asset downloading, and ONNX inference (OnnxModule). None of these are provided by NovaPhy.