Session¶
GPU context and Warp module lifecycle management. A CarverSession keeps the CUDA context alive across multiple pipeline calls, avoiding the ~2 s cold-start penalty on each invocation.
The Grasshopper plugin uses a long-lived session via the daemon; the Python API and CLI create sessions on demand. The session_cache decorator memoises expensive tensors (e.g., Tregenza patch directions) in the active session so they are computed once and reused across stages.
urbansolarcarver.session
¶
GPU/Warp session management for UrbanSolarCarver.
Provides CarverSession, a long-lived context manager that keeps a CUDA (or CPU) context alive and caches compiled Warp kernels and tensors across multiple pipeline runs. A weak-reference registry ensures at most one session per device index exists at any time.
Key public API: CarverSession -- context manager for device lifecycle and caching. session_cache -- decorator that memoises tensor results on the active session to avoid redundant GPU computation.
CarverSession(device=None)
¶
Bases: AbstractContextManager['CarverSession']
A long-lived GPU/Warp session that keeps the CUDA context alive and caches compiled Warp modules or tensors if desired.
Use this to avoid repeated GPU startup and JIT overhead across multiple runs.
device: - "auto" (default) to use CUDA if available, otherwise CPU - "cuda" or "cpu" to force a hardware target - a torch.device object
bump(flush=False)
¶
Invalidate session tensor cache between independent runs. Kernels are kept. Optionally free CUDA memory.
__enter__()
¶
Initialize CUDA context on first entry. No automatic warm-ups.
__exit__(exc_type, exc_value, traceback)
¶
Exit context; caches remain alive until explicit close().
from_config(cfg)
classmethod
¶
Construct a CarverSession using the device field in a user_config.
The device value in cfg may be "auto", "cuda" or "cpu".
get_tensor(key, factory)
¶
Cache or retrieve a tensor by key. The factory callable is invoked once per cache generation (bumped between pipeline runs). The result is moved to self.device automatically.
Args: key: Cache lookup identifier. factory: Zero-argument callable that produces the tensor.
Returns: Cached or freshly computed tensor on self.device.
get_kernel(key, factory)
¶
Cache or build a Warp kernel module, thread-safe via double-checked locking.
Args: key: Cache lookup identifier. factory: Zero-argument callable that returns a compiled Warp module.
Returns: Cached or freshly built Warp module.
close(flush=True)
¶
Clear all in-memory caches. If on CUDA and flush=True, empties torch's cache.
get_active_session(device=None)
¶
Fetch an existing CarverSession for the specified device, or None if none exists.
Returns: The CarverSession for the specified device, or None if no session is registered.
session_cache(key_template)
¶
Decorator that memoises a function's return value in the active CarverSession's tensor cache. The key_template is formatted with {args} and {kwargs} to produce a unique cache key per call signature. If no session is active, the function runs without caching.
Example::
@session_cache('tregenza_dirs')
def fetch_dirs(device): ...