novaphy.utils

Engine-wide infrastructure: thread-local profiling, device descriptors, 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 and zero-overhead outside the wrapped block: outside a with monitor.scoped(): context every C++ phase scope is a no-op, so solver public APIs stay free of profiling parameters and shipped binaries pay nothing when no scope is active. 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("SPH CUDA    :", novaphy.has_sph_cuda())

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

Scaffold Helpers

is_scaffold(obj) and scaffold_reason(obj) let downstream tooling (parity tests, telemetry, Isaac Lab adapters) detect placeholder solvers 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 scaffolds: SolverMPM, SolverLBM. Real backends return False from is_scaffold().

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.

Version and Feature Detection

Function	Description
has_ipc()	Whether the package was built with IPC / libuipc.
has_sph_cuda()	Whether the SPH CUDA backend is available.
version()	Engine version string.

Scaffold Helpers

Function	Description
is_scaffold()	Returns whether a symbol is a scaffold placeholder.
scaffold_reason()	Returns the 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.