hyperverse 0.0.1__py3-none-any.whl

hyperdrone/examples/visual_inertial_localization.py

@@ -0,0 +1,159 @@
+"""The visual-inertial localization benchmark from Python. The task flies a waypoint route
+through a scene at IMU rate with its built-in autopilot and streams what an estimator
+gets — a camera frame every `frame_stride` steps, an IMU sample after every step — next to
+the ground truth to score it. The estimator slot below holds IMU dead reckoning (the C++
+demo's blind baseline): swap in your own and compare the absolute trajectory error.
+
+  python -m hyperdrone.examples.visual_inertial_localization
+  python -m hyperdrone.examples.visual_inertial_localization --instances 4 --width 320 --height 240 --video vio.mp4
+"""
+import argparse
+import time
+
+import numpy as np
+
+from hyperdrone.env import EnvConfig, MultiEnvironment
+from hyperdrone.examples.data import procthor_scene_path
+
+parser = argparse.ArgumentParser()
+parser.add_argument("-m", "--model", default=None, help="GLB scene (default: the ProcTHOR test scene)")
+parser.add_argument("--instances", type=int, default=2)
+parser.add_argument("--width", type=int, default=160)
+parser.add_argument("--height", type=int, default=120)
+parser.add_argument("--steps", type=int, default=None, help="IMU steps to fly (default: the episode length)")
+parser.add_argument("--seed", type=int, default=0)
+parser.add_argument("--video", default=None, help="record the onboard frames to this path (mp4)")
+arguments = parser.parse_args()
+
+GRAVITY = np.array([0.0, 0.0, -9.81])
+
+env = MultiEnvironment(
+    [arguments.model or procthor_scene_path()],
+    config=EnvConfig(instances=arguments.instances, cam_width=arguments.width, cam_height=arguments.height,
+                     shading="high", preset="x500_fpv_imu", task="visual_inertial_localization"),
+    seed=arguments.seed,
+)
+steps = arguments.steps or env.episode_step_limit
+print(f"{env.config} imu_rate={1 / env.dt:.0f}Hz frame_rate={1 / (env.dt * env.frame_stride):.0f}Hz")
+
+
+def block(vector, layout, name):
+    offset, size = layout.blocks[name]
+    return vector[:, offset:offset + size]
+
+
+def quaternion_multiply(a, b):
+    w = a[:, 0] * b[:, 0] - a[:, 1] * b[:, 1] - a[:, 2] * b[:, 2] - a[:, 3] * b[:, 3]
+    x = a[:, 0] * b[:, 1] + a[:, 1] * b[:, 0] + a[:, 2] * b[:, 3] - a[:, 3] * b[:, 2]
+    y = a[:, 0] * b[:, 2] - a[:, 1] * b[:, 3] + a[:, 2] * b[:, 0] + a[:, 3] * b[:, 1]
+    z = a[:, 0] * b[:, 3] + a[:, 1] * b[:, 2] - a[:, 2] * b[:, 1] + a[:, 3] * b[:, 0]
+    return np.stack([w, x, y, z], axis=1)
+
+
+def rotation_matrix(quaternion):
+    w, x, y, z = quaternion.T
+    return np.stack([
+        1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y),
+        2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x),
+        2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y),
+    ], axis=1).reshape(-1, 3, 3)
+
+
+class DeadReckoning:
+    """IMU-only estimator in the episode frame: identity pose and zero velocity at t=0 (the
+    protocol hands the estimator no ground truth), gyro-integrated attitude, accelerometer
+    integrated twice — the C++ baseline in tasks/visual_inertial_localization/baseline.h."""
+
+    def __init__(self, count, dt):
+        self.dt = dt
+        self.position = np.zeros((count, 3))
+        self.orientation = np.tile([1.0, 0.0, 0.0, 0.0], (count, 1))
+        self.velocity = np.zeros((count, 3))
+
+    def step(self, accelerometer, gyroscope):
+        rate = np.concatenate([np.zeros((len(gyroscope), 1)), gyroscope], axis=1)
+        self.orientation += 0.5 * quaternion_multiply(self.orientation, rate) * self.dt
+        self.orientation /= np.linalg.norm(self.orientation, axis=1, keepdims=True)
+        acceleration = np.einsum("nij,nj->ni", rotation_matrix(self.orientation), accelerometer) + GRAVITY
+        velocity_next = self.velocity + acceleration * self.dt
+        self.position += (self.velocity + velocity_next) * self.dt / 2
+        self.velocity = velocity_next
+
+
+class TrajectoryMetrics:
+    """Absolute trajectory error and rotation error of poses expressed relative to the
+    episode start, plus the ground-truth distance traveled (metrics.h)."""
+
+    def __init__(self, count):
+        self.count = 0
+        self.position_squared_error = np.zeros(count)
+        self.rotation_error_sum = np.zeros(count)
+        self.rotation_error_max = np.zeros(count)
+        self.distance_traveled = np.zeros(count)
+        self.previous_position = None
+
+    def accumulate(self, truth_position, truth_rotation, estimate_position, estimate_rotation):
+        self.position_squared_error += np.sum((estimate_position - truth_position) ** 2, axis=1)
+        cosine = (np.einsum("nij,nij->n", truth_rotation, estimate_rotation) - 1) / 2
+        rotation_error = np.arccos(np.clip(cosine, -1.0, 1.0))
+        self.rotation_error_sum += rotation_error
+        self.rotation_error_max = np.maximum(self.rotation_error_max, rotation_error)
+        if self.previous_position is not None:
+            self.distance_traveled += np.linalg.norm(truth_position - self.previous_position, axis=1)
+        self.previous_position = truth_position.copy()
+        self.count += 1
+
+    def ate(self):
+        return np.sqrt(self.position_squared_error / self.count)
+
+
+layout = env.observation_layout_privileged
+layout_imu = env.observation_layout_imu
+
+video_writer = None
+if arguments.video:
+    import imageio
+
+    video_writer = imageio.get_writer(arguments.video, fps=round(1 / (env.dt * env.frame_stride)))
+
+reset_mask = np.ones(env.total_instances, dtype=bool)
+no_reset = np.zeros(env.total_instances, dtype=bool)
+env.reset(reset_mask)
+state = env.observe_privileged()
+origin_position = block(state, layout, "position").copy()
+origin_rotation = block(state, layout, "orientation_rotation_matrix").reshape(-1, 3, 3).copy()
+estimator = DeadReckoning(env.total_instances, env.dt)
+metrics = TrajectoryMetrics(env.total_instances)
+frames_rendered = 0
+
+start = time.perf_counter()
+for step in range(steps):
+    env.render(reset_mask)
+    reset_mask = no_reset
+    if step % env.frame_stride == 0:
+        frames = env.frames()  # (instances, height, width, 3) in [0, 1]: the estimator's camera input
+        frames_rendered += 1
+        if video_writer is not None:
+            video_writer.append_data((np.clip(np.concatenate(list(frames), axis=0), 0, 1) * 255).astype(np.uint8))
+    env.step()  # the autopilot flies the route
+    imu = env.observe_imu()  # the estimator's IMU sample for this step
+    estimator.step(block(imu, layout_imu, "accelerometer"), block(imu, layout_imu, "gyroscope"))
+    state = env.observe_privileged()  # ground truth after the step, relative to the episode start below
+    relative_position = np.einsum("nji,nj->ni", origin_rotation, block(state, layout, "position") - origin_position)
+    relative_rotation = origin_rotation.transpose(0, 2, 1) @ block(state, layout, "orientation_rotation_matrix").reshape(-1, 3, 3)
+    metrics.accumulate(relative_position, relative_rotation, estimator.position, rotation_matrix(estimator.orientation))
+elapsed = time.perf_counter() - start
+
+if video_writer is not None:
+    video_writer.close()
+    print(f"saved {arguments.video}")
+print(f"{steps} IMU steps x {env.total_instances} instances, {frames_rendered} frames at {env.cam_width}x{env.cam_height} "
+      f"in {elapsed:.1f}s ({steps * env.total_instances / elapsed:.0f} steps/s)")
+for instance in range(env.total_instances):
+    print(f"instance {instance}: dead reckoning ATE {metrics.ate()[instance]:.3f} m | "
+          f"rot mean {metrics.rotation_error_sum[instance] / metrics.count:.4f} rad max {metrics.rotation_error_max[instance]:.4f} rad | "
+          f"drift {metrics.ate()[instance] / max(metrics.distance_traveled[instance], 1e-9):.4f} m/m | "
+          f"distance {metrics.distance_traveled[instance]:.2f} m")
+if env.terminated().any():
+    print("warning: at least one instance terminated during the episode")
+env.close()

hyperdrone/gym/__init__.py

@@ -0,0 +1,63 @@
+"""hyperdrone.gym — optional Gymnasium VectorEnv adapter over hyperdrone.env.
+
+A leaf module: the core packages never import gymnasium, and gym-side API churn stays
+isolated here. Requires the optional dependency: pip install "hyperdrone[gym]".
+"""
+import numpy as np
+
+try:
+    import gymnasium
+except ImportError as error:
+    raise ImportError("hyperdrone.gym needs gymnasium — pip install 'hyperdrone[gym]'") from error
+
+from ..env import EnvConfig, MultiEnvironment
+
+__all__ = ["VectorEnv"]
+
+
+class VectorEnv(gymnasium.vector.VectorEnv):
+    """Same-step autoreset vectorized environment over MultiEnvironment.
+
+    Instances that terminate or hit the step limit reset within the same step, so the
+    returned observation is the first of the new episode. No final_observation is surfaced;
+    the environment renders once per step. `truncations` flags time limits that are not
+    terminations. Seeding is fixed at construction (the C++ environment owns its RNG);
+    reset(seed=...) is rejected to keep determinism claims honest.
+    """
+
+    render_mode = None
+
+    def __init__(self, scenes, config=None, seed=0, **environment_arguments):
+        self._env = MultiEnvironment(scenes, config=config, seed=seed, **environment_arguments)
+        self.num_envs = self._env.total_instances
+        self.single_observation_space = gymnasium.spaces.Box(
+            0.0, 1.0, shape=(self._env.observation_dim,), dtype=np.float32
+        )
+        self.single_action_space = gymnasium.spaces.Box(
+            -1.0, 1.0, shape=(self._env.action_dim,), dtype=np.float32
+        )
+        self.observation_space = gymnasium.vector.utils.batch_space(self.single_observation_space, self.num_envs)
+        self.action_space = gymnasium.vector.utils.batch_space(self.single_action_space, self.num_envs)
+        self._steps = np.zeros(self.num_envs, dtype=np.int64)
+
+    def reset(self, *, seed=None, options=None):
+        if seed is not None:
+            raise ValueError("hyperdrone: the environment seed is fixed at construction — pass seed= to VectorEnv()")
+        self._env.reset()
+        self._steps[:] = 0
+        return self._env.observe(), {}
+
+    def step(self, actions):
+        self._env.step(np.asarray(actions, dtype=np.float32))
+        rewards = self._env.rewards()
+        terminations = self._env.terminated()
+        self._steps += 1
+        truncations = (self._env.episode_step_limit > 0) & (self._steps >= self._env.episode_step_limit) & ~terminations
+        reset_mask = terminations | truncations
+        if reset_mask.any():
+            self._env.reset(reset_mask)
+            self._steps[reset_mask] = 0
+        return self._env.observe(), rewards, terminations, truncations, {}
+
+    def close_extras(self, **kwargs):
+        self._env.close()

hyperdrone/jit/__init__.py

@@ -0,0 +1,129 @@
+"""hyperdrone.jit — shared compile-and-cache infrastructure.
+
+A *component* is a native code unit under hyperdrone/_native/<name>/: an optional nanobind
+core module built once per build tree, plus JIT artifacts compiled per configuration:
+Python extension modules or shared libraries with a C ABI.
+
+Configs implement the JitConfig protocol: defines() -> {NAME: value} compile definitions,
+canonical() -> stable human-readable string of the configuration, key() -> its short hash,
+which names the artifact. Config files land as configs/<key>.txt inside the
+build tree, one NAME=VALUE line each; the shared hyperdrone_jit.cmake turns each file into
+a MODULE target named <component>_<key>.
+
+Build trees live at <cache>/<component>-<variant>-<tag> (one per component and variant so
+switching variants never invalidates another's cache); all configure/build steps run under
+a per-tree file lock so concurrent processes cannot race one CMake tree.
+"""
+import hashlib
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+
+from . import _build
+from ._workspace import BuildError, build_dir, cache_root, native_root, source_root, workspace_tag
+
+__all__ = [
+    "BuildError",
+    "Component",
+    "build_dir",
+    "cache_root",
+    "canonical_key",
+    "core",
+    "ensure",
+    "native_root",
+    "module",
+    "source_root",
+    "workspace_tag",
+]
+
+_core_modules = {}
+
+
+@dataclass(frozen=True)
+class Component:
+    name: str
+    variant: str
+    core_target: str = None
+    needs_cuda: bool = False
+    cmake_defines: tuple = field(default_factory=tuple)
+    source_dir: str = None  # default: hyperdrone/_native/<name>
+
+
+def canonical_key(canonical):
+    return hashlib.sha1(canonical.encode()).hexdigest()[:16]
+
+
+def _write_config_file(directory, config):
+    import os
+    config_dir = directory / "configs"
+    config_dir.mkdir(exist_ok=True)
+    config_file = config_dir / f"{config.key()}.txt"
+    if config_file.exists():
+        return False
+    lines = "".join(f"{name}={value}\n" for name, value in sorted(config.defines().items()))
+    # per-process staging name: concurrent writers of the same config must not race on one
+    # staging path; the final rename is atomic and idempotent (identical content)
+    staging = config_dir / f"{config.key()}.{os.getpid()}.tmp"
+    staging.write_text(lines)
+    staging.rename(config_file)
+    return True
+
+
+def ensure(component, config):
+    """Build (if necessary) and return the path of the JIT artifact for this config."""
+    directory = _build.ensure_configured(component)
+    fresh = _write_config_file(directory, config)
+    artifact = directory / "jit" / f"{component.name}_{config.key()}.so"
+    if fresh or not artifact.exists():
+        # the target only exists after the configs/ glob is re-run
+        _build.reconfigure(component)
+    _build.build_target(component, f"{component.name}_{config.key()}")
+    return artifact
+
+
+def core(component):
+    """Build (if necessary), load, and cache the component's nanobind core module.
+
+    Extension modules are identified by name process-wide, so one component core can only
+    be loaded for one variant per process (e.g. dynamics on cpu OR cuda, not both)."""
+    if component.core_target is None:
+        raise BuildError(f"hyperdrone: component {component.name} declares no core module")
+    cached = _core_modules.get(component.core_target)
+    if cached is not None:
+        variant, module = cached
+        if variant != component.variant:
+            raise BuildError(
+                f"hyperdrone: {component.core_target} is already loaded for variant "
+                f"'{variant}'; one process can use only one {component.name} variant"
+            )
+        return module
+    directory = build_dir(component)
+    if (directory / "CMakeCache.txt").exists() and not sorted(directory.glob(f"{component.core_target}*.so")):
+        # a core target added since this workspace was configured exists only after a reconfigure
+        _build.reconfigure(component)
+    directory = _build.build_target(component, component.core_target)
+    matches = sorted(directory.glob(f"{component.core_target}*.so"))
+    if not matches:
+        raise BuildError(f"hyperdrone: {component.core_target} module not found in {directory}")
+    extension = _load_extension(component.core_target, matches[0])
+    _core_modules[component.core_target] = (component.variant, extension)
+    return extension
+
+
+def _load_extension(name, path):
+    cached = sys.modules.get(name)
+    if cached is not None:
+        return cached
+    specification = importlib.util.spec_from_file_location(name, path)
+    extension = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(extension)
+    sys.modules[name] = extension
+    return extension
+
+
+def module(component, config):
+    """Build and import a configuration's Python extension, after its shared core."""
+    if component.core_target is not None:
+        core(component)
+    artifact = ensure(component, config)
+    return _load_extension(f"hyperdrone_{component.name}_{component.variant}_{config.key()}", artifact)

hyperdrone/jit/_build.py

@@ -0,0 +1,113 @@
+import os
+import subprocess
+from pathlib import Path
+
+from ._lock import FileLock
+from ._patches import seed_dependencies
+from ._toolchain import environment
+from ._workspace import BuildError, build_dir, dependencies_root, native_root, source_root
+
+BUILD_JOBS = os.environ.get("HYPERDRONE_BUILD_JOBS", "5")
+
+
+def lock(component):
+    directory = build_dir(component)
+    return FileLock(directory.parent / f"{directory.name}.lock")
+
+
+def run(arguments, env):
+    process = subprocess.run(
+        [str(argument) for argument in arguments],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, env=env,
+    )
+    if process.returncode != 0:
+        tail = "\n".join(process.stdout.splitlines()[-60:])
+        raise BuildError(
+            f"hyperdrone: command failed: {' '.join(str(argument) for argument in arguments)}\n{tail}"
+        )
+    return process.stdout
+
+
+def source_dir(component):
+    if component.source_dir is not None:
+        from pathlib import Path
+        return Path(component.source_dir)
+    return native_root() / component.name
+
+
+def fetchcontent_base(directory):
+    return (dependencies_root() / directory.name).resolve()
+
+
+def configured_fetchcontent_base(directory):
+    cache_file = directory / "CMakeCache.txt"
+    if not cache_file.exists():
+        return None
+    prefix = "FETCHCONTENT_BASE_DIR:"
+    for line in cache_file.read_text().splitlines():
+        if line.startswith(prefix):
+            return Path(line.split("=", 1)[1]).resolve()
+    return None
+
+
+def configure(component, directory):
+    import sys
+    seeded = seed_dependencies(directory.name)
+    arguments = [
+        "cmake",
+        "-S", source_dir(component),
+        "-B", directory,
+        "-DCMAKE_BUILD_TYPE=Release",
+        f"-DRLTOOLS_ROOT={source_root()}",
+        f"-DHYPERDRONE_VARIANT={component.variant.upper()}",
+        f"-DHYPERDRONE_NATIVE_ROOT={native_root()}",
+        f"-DPython_EXECUTABLE={sys.executable}",
+        # fully qualified: the rl_tools root CMakeLists cannot append the build-dir
+        # basename to an externally-passed value (non-FORCE cache set)
+        f"-DFETCHCONTENT_BASE_DIR={fetchcontent_base(directory)}",
+    ]
+    for fetch_name, path in sorted(seeded.items()):
+        arguments.append(f"-DFETCHCONTENT_SOURCE_DIR_{fetch_name}={path}")
+    for name, value in component.cmake_defines:
+        arguments.append(f"-D{name}={value}")
+    if os.environ.get("HYPERDRONE_OFFLINE"):
+        arguments.append("-DRL_TOOLS_OFFLINE_BUILD=ON")
+    run(arguments, environment(component))
+
+
+def ensure_configured(component):
+    directory = build_dir(component)
+    expected_fetchcontent_base = fetchcontent_base(directory)
+    if configured_fetchcontent_base(directory) == expected_fetchcontent_base:
+        return directory
+    with lock(component):
+        if configured_fetchcontent_base(directory) != expected_fetchcontent_base:
+            fresh = not (directory / "CMakeCache.txt").exists()
+            directory.mkdir(parents=True, exist_ok=True)
+            try:
+                configure(component, directory)
+            except BaseException:
+                # a failed configure must not leave a tree that looks configured; the
+                # FetchContent state lives in .dependencies/ and survives for the retry
+                if fresh:
+                    import shutil
+                    shutil.rmtree(directory, ignore_errors=True)
+                raise
+    return directory
+
+
+def build_target(component, target):
+    directory = ensure_configured(component)
+    if os.environ.get("HYPERDRONE_SKIP_BUILD"):
+        return directory
+    with lock(component):
+        run(["cmake", "--build", directory, "--target", target, "-j", BUILD_JOBS],
+            environment(component))
+    return directory
+
+
+def reconfigure(component):
+    directory = ensure_configured(component)
+    with lock(component):
+        run(["cmake", directory], environment(component))
+    return directory

hyperdrone/jit/_lock.py

@@ -0,0 +1,23 @@
+"""Advisory file lock serializing configure/build on one build tree across processes
+(vectorized RL workloads routinely spawn many workers that would otherwise race the same
+CMake tree). POSIX flock; a Windows port replaces this module with an msvcrt equivalent."""
+import fcntl
+import os
+
+
+class FileLock:
+    def __init__(self, path):
+        self._path = path
+        self._handle = None
+
+    def __enter__(self):
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._handle = os.open(self._path, os.O_CREAT | os.O_RDWR, 0o644)
+        fcntl.flock(self._handle, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *exception):
+        fcntl.flock(self._handle, fcntl.LOCK_UN)
+        os.close(self._handle)
+        self._handle = None
+        return False

hyperdrone/jit/_patches.py

@@ -0,0 +1,99 @@
+"""Reuse dependencies from sibling JIT build caches.
+
+Git sources use FETCHCONTENT_SOURCE_DIR overrides, with patch scripts applied explicitly.
+Assimp reuses downloaded archives so CMake verifies URL_HASH before extracting them.
+"""
+import re
+import shutil
+import subprocess
+
+from ._workspace import source_root
+
+# FetchContent name -> source directory basename
+SEEDED_SOURCES = {
+    "OWL": "owl-src",
+    "STB": "stb-src",
+    "NLOHMANN_JSON": "nlohmann_json-src",
+}
+
+# FetchContent name -> cmake file declaring its GIT_TAG; seeds are validated against the
+# declared pin so a repin upstream can never be shadowed by a stale seeded checkout
+PINNED_SOURCES = {
+    "OWL": "cmake/optional/optix.cmake",
+}
+
+
+def declared_pin(fetch_name):
+    relative = PINNED_SOURCES.get(fetch_name)
+    if relative is None:
+        return None
+    declaration = source_root() / relative
+    if not declaration.exists():
+        return None
+    match = re.search(
+        r"FetchContent_Declare\(\s*" + fetch_name + r"\b.*?GIT_TAG\s+([0-9a-fA-F]{7,40})",
+        declaration.read_text(), re.IGNORECASE | re.DOTALL,
+    )
+    return match.group(1) if match else None
+
+
+def checkout_head(tree):
+    result = subprocess.run(
+        ["git", "-C", str(tree), "rev-parse", "HEAD"], capture_output=True, text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def matches_pin(tree, pin):
+    return pin is None or checkout_head(tree) == pin
+
+# cmake -P scripts under <source_root>/cmake/patches, applied to the named FetchContent
+# source dir; each script is idempotent and documents its upstream-removal condition.
+# (Empty since the OWL PinnedHostMem fix landed upstream with the 978a6664 repin.)
+PATCH_SCRIPTS = {}
+
+
+def apply_patch_scripts(seeded):
+    for fetch_name, (script_name, root_variable) in PATCH_SCRIPTS.items():
+        tree = seeded.get(fetch_name)
+        script = source_root() / "cmake" / "patches" / script_name
+        if tree is not None and script.exists():
+            subprocess.run(
+                ["cmake", f"-D{root_variable}={tree}", "-P", str(script)],
+                check=True, capture_output=True,
+            )
+
+
+def seed_dependencies(build_dir_name):
+    """Copy FetchContent sources from a populated sibling; returns {FETCH_NAME: path} for
+    every seeded (or already present) source directory."""
+    from ._workspace import dependencies_root
+    dependency_root = dependencies_root()
+    target_base = dependency_root / build_dir_name
+    donors = sorted(
+        candidate for candidate in dependency_root.glob("*")
+        if candidate.is_dir() and candidate.name != build_dir_name
+    ) if dependency_root.is_dir() else []
+    seeded = {}
+    for donor in donors:
+        for archive in (donor / "assimp-download").glob("*.tar.gz"):
+            target = target_base / "assimp-download" / archive.name
+            if not target.exists():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(archive, target)
+    for fetch_name, source_name in SEEDED_SOURCES.items():
+        pin = declared_pin(fetch_name)
+        target = target_base / source_name
+        if target.exists() and not matches_pin(target, pin):
+            shutil.rmtree(target)
+        if not target.exists():
+            for donor in donors:
+                source = donor / source_name
+                if source.is_dir() and matches_pin(source, pin):
+                    target_base.mkdir(parents=True, exist_ok=True)
+                    shutil.copytree(source, target, symlinks=True)
+                    break
+        if target.is_dir():
+            seeded[fetch_name] = target
+    apply_patch_scripts(seeded)
+    return seeded

hyperdrone/jit/_toolchain.py

@@ -0,0 +1,17 @@
+import os
+import shutil
+from pathlib import Path
+
+
+def cuda_available():
+    return Path("/usr/local/cuda/bin/nvcc").exists() or shutil.which("nvcc") is not None
+
+
+def environment(component):
+    env = os.environ.copy()
+    if component.needs_cuda and "CUDACXX" not in env and "CMAKE_CUDA_COMPILER" not in env:
+        for candidate in ("/usr/local/cuda/bin/nvcc", shutil.which("nvcc")):
+            if candidate and Path(candidate).exists():
+                env["CUDACXX"] = str(candidate)
+                break
+    return env

hyperdrone/jit/_workspace.py

@@ -0,0 +1,68 @@
+import hashlib
+import os
+import sysconfig
+from pathlib import Path
+
+
+class BuildError(RuntimeError):
+    pass
+
+
+def cache_root():
+    env = os.environ.get("HYPERDRONE_CACHE_DIR")
+    if env:
+        return Path(env)
+    return Path.home() / ".cache" / "hyperdrone"
+
+
+def package_root():
+    return Path(__file__).resolve().parents[1]
+
+
+def native_root():
+    return package_root() / "_native"
+
+
+def source_root():
+    """rl-tools source root: env override, enclosing repository checkout, vendored tree."""
+    env = os.environ.get("HYPERDRONE_RLTOOLS_ROOT")
+    if env:
+        root = Path(env).resolve()
+        if not (root / "include" / "rl_tools").is_dir():
+            raise BuildError(
+                f"hyperdrone: HYPERDRONE_RLTOOLS_ROOT={root} is not an rl-tools source root "
+                "(include/rl_tools missing)"
+            )
+        return root
+    candidate = package_root()
+    for _ in range(8):
+        if (candidate / "include" / "rl_tools").is_dir():
+            return candidate
+        candidate = candidate.parent
+    vendored = package_root() / "_vendor" / "rl-tools"
+    if (vendored / "include" / "rl_tools").is_dir():
+        return vendored
+    raise BuildError(
+        "hyperdrone: rl-tools sources not found (no enclosing repository checkout and no "
+        "vendored tree; set HYPERDRONE_RLTOOLS_ROOT to an rl-tools source root)"
+    )
+
+
+def dependencies_root():
+    """FetchContent sources and build state live under the configured cache root.
+
+    Source checkouts and installed packages may be read-only; neither should accumulate
+    generated files. Keeping dependencies beside the component build trees also makes
+    HYPERDRONE_CACHE_DIR a complete, relocatable build cache.
+    """
+    return cache_root() / ".dependencies"
+
+
+def workspace_tag():
+    from .. import __version__
+    fingerprint = f"{source_root()}|{sysconfig.get_config_var('SOABI')}|{__version__}"
+    return hashlib.sha1(fingerprint.encode()).hexdigest()[:8]
+
+
+def build_dir(component):
+    return cache_root() / f"{component.name}-{component.variant}-{workspace_tag()}"