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 tensors across multiple pipeline runs. (Compiled Warp kernels are cached by Warp itself, per module, on disk.) 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 tensors across pipeline runs.
Use this to avoid repeated GPU startup and recomputation 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 the session tensor cache between independent runs. 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.
close(flush=True)
¶
Clear the in-memory tensor cache. 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): ...