hyperverse 0.0.1__py3-none-any.whl

hyperdrone/__init__.py

@@ -0,0 +1,31 @@
+"""hyperdrone — drone simulation stack for RLtools.
+
+Subpackages:
+  hyperdrone.render   — raytracing renderer (self-contained, no drone dynamics)
+  hyperdrone.dynamics — L2F multirotor simulator (vectorized, stateful Sim; pure dynamics)
+  hyperdrone.env      — the RL environment: the C++ MultiEnvironment behind the batch verbs
+  hyperdrone.gym      — optional Gymnasium VectorEnv adapter (pip install "hyperdrone[gym]")
+  hyperdrone.jit      — shared compile-and-cache infrastructure
+  hyperdrone.cuda     — CUDA staging helpers (DLPack tensor sets)
+
+The three domain packages are independent: render and dynamics couple only through a
+DLPack tensor of camera bases; env owns no Python-side semantics — it drives the C++
+environment. Native components are JIT-compiled per set of compile-time constants and
+cached under ~/.cache/hyperdrone (override with HYPERDRONE_CACHE_DIR). Importing
+hyperdrone (or any subpackage) is cheap; the first build happens on first use.
+"""
+import importlib
+
+__version__ = "0.1.5"
+
+_SUBPACKAGES = ("render", "dynamics", "env", "gym", "jit", "cuda")
+
+
+def __getattr__(name):
+    if name in _SUBPACKAGES:
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module 'hyperdrone' has no attribute {name}")
+
+
+def __dir__():
+    return sorted(list(globals()) + list(_SUBPACKAGES))

hyperdrone/_native/cmake/hyperdrone_jit.cmake

@@ -0,0 +1,65 @@
+# Shared JIT machinery: one MODULE target per configs/<key>.txt file in the build tree.
+# Each file holds NAME=VALUE compile definitions written by hyperdrone.jit; the target is
+# named <COMPONENT>_<key> and its artifact lands in <build>/jit/<COMPONENT>_<key>.so.
+#
+# A component may define, before calling this function:
+#   function(hyperdrone_component_libraries DEFINES OUT_LIBRARIES)
+# to map a config's definition list to extra link libraries (set ${OUT_LIBRARIES} in
+# PARENT_SCOPE); used e.g. by render to pick the backend device-program library.
+#
+# Components with Python modules call hyperdrone_jit_find_nanobind() first; a macro so the
+# variables nanobind's config sets stay in the caller's scope for nanobind_add_module.
+macro(hyperdrone_jit_find_nanobind)
+    find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+    execute_process(
+        COMMAND ${Python_EXECUTABLE} -m nanobind --cmake_dir
+        OUTPUT_VARIABLE nanobind_DIR
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        COMMAND_ERROR_IS_FATAL ANY
+    )
+    find_package(nanobind CONFIG REQUIRED)
+endmacro()
+
+function(hyperdrone_jit_add_configs)
+    cmake_parse_arguments(ARG "PYTHON_MODULE" "COMPONENT" "SOURCES;LINK" ${ARGN})
+    set(config_dir ${CMAKE_BINARY_DIR}/configs)
+    file(MAKE_DIRECTORY ${config_dir})
+    file(GLOB config_files ${config_dir}/*.txt)
+    foreach(config_file IN LISTS config_files)
+        set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${config_file})
+        get_filename_component(config_key ${config_file} NAME_WE)
+        file(STRINGS ${config_file} config_defines)
+        set(target ${ARG_COMPONENT}_${config_key})
+        if(ARG_PYTHON_MODULE)
+            # NOMINSIZE: the simulation and renderer must not be built at nanobind's default -Os
+            nanobind_add_module(${target} NOMINSIZE ${ARG_SOURCES})
+            string(TOLOWER "${HYPERDRONE_VARIANT}" module_variant)
+            target_compile_definitions(${target} PRIVATE HYPERDRONE_MODULE_NAME=hyperdrone_${ARG_COMPONENT}_${module_variant}_${config_key})
+            set_target_properties(${target} PROPERTIES SUFFIX ".so")
+        else()
+            add_library(${target} MODULE ${ARG_SOURCES})
+        endif()
+        target_include_directories(${target} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/../common)
+        target_compile_definitions(${target} PRIVATE ${config_defines})
+        set(extra_libraries "")
+        if(COMMAND hyperdrone_component_libraries)
+            hyperdrone_component_libraries("${config_defines}" extra_libraries)
+        endif()
+        target_link_libraries(${target} PRIVATE ${ARG_LINK} ${extra_libraries})
+        set_target_properties(${target} PROPERTIES
+            LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/jit
+            PREFIX ""
+        )
+    endforeach()
+endfunction()
+
+# Reads NAME=VALUE from a definitions list into <PREFIX>_<NAME> variables in the caller's
+# scope (helper for hyperdrone_component_libraries implementations).
+function(hyperdrone_jit_parse_defines DEFINES PREFIX)
+    foreach(define IN LISTS DEFINES)
+        string(REGEX MATCH "^([A-Za-z0-9_]+)=(.*)$" _match "${define}")
+        if(_match)
+            set(${PREFIX}_${CMAKE_MATCH_1} "${CMAKE_MATCH_2}" PARENT_SCOPE)
+        endif()
+    endforeach()
+endfunction()

hyperdrone/_native/common/bindings.h

@@ -0,0 +1,39 @@
+#pragma once
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+
+#include <array>
+#include <cstring>
+#include <stdexcept>
+
+namespace hyperdrone {
+    namespace nb = nanobind;
+
+    using Vec3 = std::array<float, 3>;
+    using Vec4 = std::array<float, 4>;
+    using FloatArray = nb::ndarray<const float, nb::c_contig, nb::device::cpu>;
+    using Transform = nb::ndarray<const float, nb::c_contig, nb::device::cpu>;
+
+    inline void extract_transform(const Transform& transform, float out[12]){
+        if(transform.ndim() == 1 && transform.shape(0) == 12){
+            std::memcpy(out, transform.data(), 12 * sizeof(float));
+        }
+        else if(transform.ndim() == 2 && transform.shape(0) == 3 && transform.shape(1) == 4){
+            std::memcpy(out, transform.data(), 12 * sizeof(float));
+        }
+        else {
+            throw std::invalid_argument("hyperdrone: transform must have shape (12,) or (3, 4)");
+        }
+    }
+
+    inline nb::ndarray<nb::numpy, float> make_owned_array(const float* values, std::initializer_list<size_t> shape){
+        size_t count = 1;
+        for(size_t dim : shape){
+            count *= dim;
+        }
+        float* buffer = new float[count];
+        std::memcpy(buffer, values, count * sizeof(float));
+        nb::capsule owner(buffer, [](void* pointer) noexcept { delete[] (float*)pointer; });
+        return nb::ndarray<nb::numpy, float>(buffer, shape, owner);
+    }
+}

hyperdrone/_native/common/cuda_staging.h

@@ -0,0 +1,75 @@
+#pragma once
+// GPU staging buffer for device-resident inputs: uploads a host float32 array once; slices
+// along axis 0 are handed out as DLPack CUDA views (e.g. one pre-sampled camera set per
+// slice). Registered by every CUDA-capable component core so hyperdrone.cuda can resolve a
+// provider from whichever domain package is in use.
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/vector.h>
+#include <cuda_runtime.h>
+
+#include <stdexcept>
+#include <vector>
+
+namespace hyperdrone {
+    struct CudaBuffer {
+        void* pointer = nullptr;
+        std::vector<size_t> shape;
+
+        explicit CudaBuffer(nanobind::ndarray<const float, nanobind::c_contig, nanobind::device::cpu> source){
+            shape.assign(source.shape_ptr(), source.shape_ptr() + source.ndim());
+            const size_t bytes = source.size() * sizeof(float);
+            if(cudaMalloc(&pointer, bytes) != cudaSuccess){
+                throw std::runtime_error("hyperdrone: cudaMalloc failed");
+            }
+            if(cudaMemcpy(pointer, source.data(), bytes, cudaMemcpyHostToDevice) != cudaSuccess){
+                cudaFree(pointer);
+                pointer = nullptr;
+                throw std::runtime_error("hyperdrone: upload to CUDA device memory failed");
+            }
+        }
+        ~CudaBuffer(){
+            if(pointer != nullptr){
+                cudaFree(pointer);
+            }
+        }
+        CudaBuffer(const CudaBuffer&) = delete;
+        CudaBuffer& operator=(const CudaBuffer&) = delete;
+
+        size_t slice_elements() const {
+            size_t count = 1;
+            for(size_t dimension = 1; dimension < shape.size(); dimension++){
+                count *= shape[dimension];
+            }
+            return count;
+        }
+        const float* slice_pointer(size_t index) const {
+            if(shape.empty() || index >= shape[0]){
+                throw std::out_of_range("hyperdrone: CudaBuffer slice index out of range");
+            }
+            return (const float*)pointer + index * slice_elements();
+        }
+    };
+
+    // the render and dynamics cores share this type: whichever module registers it second
+    // re-exports the existing binding instead of registering a duplicate
+    inline void register_cuda_staging(nanobind::module_& m){
+        namespace nb = nanobind;
+        if(nb::handle registered = nb::type<CudaBuffer>(); registered.is_valid()){
+            m.attr("CudaBuffer") = registered;
+            return;
+        }
+        nb::class_<CudaBuffer>(m, "CudaBuffer")
+            .def(nb::init<nb::ndarray<const float, nb::c_contig, nb::device::cpu>>(), nb::arg("source"))
+            .def_prop_ro("shape", [](const CudaBuffer& buffer){ return buffer.shape; })
+            .def("slice_dlpack", [](CudaBuffer& buffer, size_t index){
+                std::vector<size_t> slice_shape(buffer.shape.begin() + 1, buffer.shape.end());
+                return nb::ndarray<>((void*)buffer.slice_pointer(index), slice_shape.size(), slice_shape.data(),
+                                     nb::find(&buffer), nullptr, nb::dtype<float>(), nb::device::cuda::value, 0);
+            }, nb::arg("index"))
+            .def("dlpack", [](CudaBuffer& buffer){
+                return nb::ndarray<>(buffer.pointer, buffer.shape.size(), buffer.shape.data(),
+                                     nb::find(&buffer), nullptr, nb::dtype<float>(), nb::device::cuda::value, 0);
+            });
+    }
+}

hyperdrone/_native/common/jit_host.h

@@ -0,0 +1,69 @@
+#pragma once
+// Host side of the JIT ABI seam: dlopen a per-config artifact, resolve its
+// hyperdrone_<component>_* symbols, validate iface version and canonical config string,
+// and manage instance lifetime. Libraries stay loaded for the process lifetime so repeated
+// construction is cheap and CUDA/driver teardown ordering stays trivial.
+#include <dlfcn.h>
+#include <map>
+#include <stdexcept>
+#include <string>
+
+namespace hyperdrone {
+    template <typename IFACE>
+    struct JitLibrary {
+        IFACE* (*create)();
+        void (*destroy)(IFACE*);
+        const char* (*config_string)();
+        int (*iface_version)();
+    };
+
+    template <typename IFACE>
+    JitLibrary<IFACE>& get_jit_library(const std::string& path, const std::string& symbol_prefix, int expected_iface_version){
+        static std::map<std::string, JitLibrary<IFACE>> libraries;
+        auto existing = libraries.find(path);
+        if(existing != libraries.end()){
+            return existing->second;
+        }
+        void* handle = dlopen(path.c_str(), RTLD_NOW | RTLD_LOCAL);
+        if(handle == nullptr){
+            throw std::runtime_error("hyperdrone: failed to load JIT library: " + std::string(dlerror()));
+        }
+        JitLibrary<IFACE> library;
+        library.create = (IFACE* (*)())dlsym(handle, (symbol_prefix + "_create").c_str());
+        library.destroy = (void (*)(IFACE*))dlsym(handle, (symbol_prefix + "_destroy").c_str());
+        library.config_string = (const char* (*)())dlsym(handle, (symbol_prefix + "_config_string").c_str());
+        library.iface_version = (int (*)())dlsym(handle, (symbol_prefix + "_iface_version").c_str());
+        if(library.create == nullptr || library.destroy == nullptr || library.config_string == nullptr || library.iface_version == nullptr){
+            throw std::runtime_error("hyperdrone: JIT library is missing the " + symbol_prefix + "_{create,destroy,config_string,iface_version} symbols: " + path);
+        }
+        if(library.iface_version() != expected_iface_version){
+            throw std::runtime_error("hyperdrone: JIT library was built against iface version "
+                + std::to_string(library.iface_version()) + " but the core module expects "
+                + std::to_string(expected_iface_version) + " (stale cache): " + path);
+        }
+        return libraries.emplace(path, library).first->second;
+    }
+
+    template <typename IFACE>
+    struct JitInstance {
+        IFACE* instance = nullptr;
+        void (*destroy)(IFACE*) = nullptr;
+
+        JitInstance(const std::string& path, const std::string& symbol_prefix, int expected_iface_version, const std::string& expected_config){
+            JitLibrary<IFACE>& library = get_jit_library<IFACE>(path, symbol_prefix, expected_iface_version);
+            const std::string actual_config = library.config_string();
+            if(actual_config != expected_config){
+                throw std::runtime_error("hyperdrone: JIT library config mismatch (expected \"" + expected_config + "\", library reports \"" + actual_config + "\"): " + path);
+            }
+            destroy = library.destroy;
+            instance = library.create();
+        }
+        ~JitInstance(){
+            if(instance != nullptr){
+                destroy(instance);
+            }
+        }
+        JitInstance(const JitInstance&) = delete;
+        JitInstance& operator=(const JitInstance&) = delete;
+    };
+}

hyperdrone/_native/common/models.h

@@ -0,0 +1,24 @@
+#pragma once
+#include <rl_tools/rl/environments/l2f/parameters/registry.h>
+
+#include <string>
+
+namespace hyperdrone {
+    // runtime lookup of the l2f dynamics registry by the names in hyperdrone.dynamics.MODELS
+    template <typename PARAMETERS_SPEC, typename DYNAMICS>
+    bool model_by_name(const std::string& name, DYNAMICS& out){
+        namespace pd = rl_tools::rl::environments::l2f::parameters::dynamics;
+        if(name == "crazyflie"){ out = pd::registry<pd::REGISTRY::crazyflie, PARAMETERS_SPEC>; return true; }
+        if(name == "crazyflie_openmv"){ out = pd::registry<pd::REGISTRY::crazyflie_openmv, PARAMETERS_SPEC>; return true; }
+        if(name == "mrs"){ out = pd::registry<pd::REGISTRY::mrs, PARAMETERS_SPEC>; return true; }
+        if(name == "x500"){ out = pd::registry<pd::REGISTRY::x500, PARAMETERS_SPEC>; return true; }
+        if(name == "x500_real"){ out = pd::registry<pd::REGISTRY::x500_real, PARAMETERS_SPEC>; return true; }
+        if(name == "x500_sim"){ out = pd::registry<pd::REGISTRY::x500_sim, PARAMETERS_SPEC>; return true; }
+        if(name == "arpl"){ out = pd::registry<pd::REGISTRY::arpl, PARAMETERS_SPEC>; return true; }
+        if(name == "fs_base"){ out = pd::registry<pd::REGISTRY::fs_base, PARAMETERS_SPEC>; return true; }
+        if(name == "flightmare"){ out = pd::registry<pd::REGISTRY::flightmare, PARAMETERS_SPEC>; return true; }
+        if(name == "soft"){ out = pd::registry<pd::REGISTRY::soft, PARAMETERS_SPEC>; return true; }
+        if(name == "soft_rigid"){ out = pd::registry<pd::REGISTRY::soft_rigid, PARAMETERS_SPEC>; return true; }
+        return false;
+    }
+}

hyperdrone/_native/dynamics/CMakeLists.txt

@@ -0,0 +1,61 @@
+cmake_minimum_required(VERSION 3.24)
+project(hyperdrone_dynamics LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+set(RLTOOLS_ROOT "" CACHE PATH "Path to the rl-tools source root")
+set(HYPERDRONE_VARIANT "CPU" CACHE STRING "Dynamics device (CPU|CUDA)")
+
+if(NOT RLTOOLS_ROOT)
+    message(FATAL_ERROR "RLTOOLS_ROOT must point to the rl-tools source root")
+endif()
+
+set(RL_TOOLS_DISABLE_TARGETS ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_DISABLE_TESTS ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_DISABLE_GIT_DIFF ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_RL_ENVIRONMENTS_DISABLE_MUJOCO ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_RENDERING_DISABLE_RAYTRACING ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_WARNINGS_AS_ERRORS OFF CACHE BOOL "" FORCE)
+
+if(HYPERDRONE_VARIANT STREQUAL "CUDA")
+    enable_language(CUDA)
+    set(CMAKE_CUDA_STANDARD 17)
+    set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+    if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+        set(CMAKE_CUDA_ARCHITECTURES native)
+    endif()
+endif()
+
+add_subdirectory(${RLTOOLS_ROOT} rl_tools EXCLUDE_FROM_ALL)
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/hyperdrone_jit.cmake)
+hyperdrone_jit_find_nanobind()
+
+nanobind_add_module(hyperdrone_dynamics_core host.cpp)
+target_include_directories(hyperdrone_dynamics_core PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../common)
+target_link_libraries(hyperdrone_dynamics_core PRIVATE RLtools::RLtools ${CMAKE_DL_LIBS})
+set_target_properties(hyperdrone_dynamics_core PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+set(HYPERDRONE_DYNAMICS_EXTRA_LINK "")
+if(HYPERDRONE_VARIANT STREQUAL "CUDA")
+    find_package(CUDAToolkit REQUIRED)
+    target_compile_definitions(hyperdrone_dynamics_core PRIVATE HYPERDRONE_DYNAMICS_CUDA=1)
+    target_link_libraries(hyperdrone_dynamics_core PRIVATE CUDA::cudart)
+    add_compile_definitions(HYPERDRONE_DYNAMICS_CUDA=1)
+    set_source_files_properties(impl.cpp PROPERTIES LANGUAGE CUDA)
+else()
+    # per-drone parallelism on the CPU variant; drones are independent, so this stays
+    # deterministic for a fixed seed
+    find_package(OpenMP QUIET)
+    if(OpenMP_CXX_FOUND)
+        set(HYPERDRONE_DYNAMICS_EXTRA_LINK OpenMP::OpenMP_CXX)
+    endif()
+endif()
+
+hyperdrone_jit_add_configs(
+    COMPONENT dynamics
+    SOURCES impl.cpp
+    LINK RLtools::RLtools ${HYPERDRONE_DYNAMICS_EXTRA_LINK}
+)

hyperdrone/_native/dynamics/host.cpp

@@ -0,0 +1,193 @@
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/optional.h>
+#include <nanobind/stl/string.h>
+
+#include <rl_tools/operations/cpu.h>
+#include <rl_tools/rl/environments/l2f/operations_cpu.h>
+
+#include "iface.h"
+#include "jit_host.h"
+#include "models.h"
+
+#include <cstring>
+#include <optional>
+#include <stdexcept>
+#include <string>
+
+#if defined(HYPERDRONE_DYNAMICS_CUDA)
+#include "cuda_staging.h"
+#include <cuda_runtime.h>
+#endif
+
+namespace nb = nanobind;
+namespace hdd = hyperdrone::dynamics;
+
+struct JitSim {
+    hyperdrone::JitInstance<hdd::Sim> instance;
+
+    JitSim(const std::string& path, const std::string& expected_config)
+        : instance(path, "hyperdrone_dynamics", HYPERDRONE_DYNAMICS_IFACE_VERSION, expected_config) {}
+
+    hdd::Sim* operator->() const { return instance.instance; }
+
+    size_t component_dim(int component) const {
+        if(component < 0 || component > 4){
+            throw std::invalid_argument("hyperdrone: unknown state component");
+        }
+        return component == 4 ? instance.instance->config().action_dim
+                              : (size_t)hdd::state_component_dims[component];
+    }
+
+    void copy_out(const float* source, float* destination, size_t count) const {
+#if defined(HYPERDRONE_DYNAMICS_CUDA)
+        instance.instance->synchronize();
+        cudaMemcpy(destination, source, count * sizeof(float), cudaMemcpyDeviceToHost);
+#else
+        std::memcpy(destination, source, count * sizeof(float));
+#endif
+    }
+};
+
+using HostFloatArray = nb::ndarray<const float, nb::c_contig, nb::device::cpu>;
+
+NB_MODULE(hyperdrone_dynamics_core, m){
+    m.doc() = "hyperdrone dynamics core: JIT loader for the vectorized L2F multirotor simulator";
+
+    m.def("model_json", [](const std::string& name) -> std::optional<std::string> {
+        using DEVICE = rl_tools::devices::DefaultCPU;
+        using SPEC = rl_tools::rl::environments::l2f::Specification<float, typename DEVICE::index_t>;
+        using ENVIRONMENT = rl_tools::rl::environments::Multirotor<SPEC>;
+        typename ENVIRONMENT::Parameters::Dynamics dynamics;
+        if(!hyperdrone::model_by_name<SPEC>(name, dynamics)){
+            return std::nullopt;
+        }
+        DEVICE device;
+        ENVIRONMENT environment;
+        return rl_tools::json(device, environment, dynamics);
+    }, nb::arg("name"), "The l2f dynamics of a registry model as JSON (the schema of MultiEnvironment.parameters['dynamics']['dynamics']); None for an unknown name.");
+
+    auto jit_sim_class = nb::class_<JitSim>(m, "JitSim");
+    jit_sim_class
+        .def(nb::init<const std::string&, const std::string&>(), nb::arg("library_path"), nb::arg("expected_config"))
+        .def_prop_ro("num_drones", [](const JitSim& jit){ return jit->config().num_drones; })
+        .def_prop_ro("action_dim", [](const JitSim& jit){ return jit->config().action_dim; })
+        .def_prop_ro("observation_dim", [](const JitSim& jit){ return jit->config().observation_dim; })
+        .def_prop_ro("domain_randomization", [](const JitSim& jit){ return jit->config().domain_randomization; })
+        .def_prop_ro("device_name", [](const JitSim& jit){ return std::string(jit->device_name()); })
+        .def_prop_ro("buffer_device_type", [](const JitSim& jit){ return jit->buffer_device_type(); })
+        .def_prop_ro("stream", [](const JitSim& jit){ return (uintptr_t)jit->stream(); })
+        .def("synchronize", [](JitSim& jit){
+            nb::gil_scoped_release release;
+            jit->synchronize();
+        })
+        .def("set_model", [](JitSim& jit, const std::string& name){ return jit->set_model(name.c_str()); }, nb::arg("name"))
+        .def("set_dt", [](JitSim& jit, float dt){ jit->set_dt(dt); }, nb::arg("dt"))
+        .def_prop_ro("dt", [](const JitSim& jit){ return jit->dt(); })
+        .def("reset", [](JitSim& jit, uint64_t seed, bool sample_parameters, bool sample_states){
+            nb::gil_scoped_release release;
+            jit->reset(seed, sample_parameters, sample_states);
+        }, nb::arg("seed"), nb::arg("sample_parameters"), nb::arg("sample_states"))
+        .def("step", [](JitSim& jit, HostFloatArray actions){
+            const hdd::Config config = jit->config();
+            if(actions.ndim() != 2 || actions.shape(0) != config.num_drones || actions.shape(1) != config.action_dim){
+                throw std::invalid_argument("hyperdrone: actions must have shape (num_drones, action_dim) and dtype float32");
+            }
+            nb::gil_scoped_release release;
+            jit->step(actions.data(), 1, 0);
+        }, nb::arg("actions"))
+        .def("state_dlpack", [](JitSim& jit, int component){
+            const hdd::Config config = jit->config();
+            const size_t dim = jit.component_dim(component);
+            return nb::ndarray<>((void*)jit->state_buffer(component), {config.num_drones, dim}, nb::find(&jit), {},
+                                 nb::dtype<float>(), jit->buffer_device_type(), 0);
+        }, nb::arg("component"))
+        .def("read_state", [](JitSim& jit, int component, nb::ndarray<float, nb::c_contig, nb::device::cpu> out){
+            const hdd::Config config = jit->config();
+            const size_t dim = jit.component_dim(component);
+            if(out.size() != config.num_drones * dim){
+                throw std::invalid_argument("hyperdrone: output array has the wrong size for this state component");
+            }
+            nb::gil_scoped_release release;
+            jit.copy_out(jit->state_buffer(component), out.data(), config.num_drones * dim);
+        }, nb::arg("component"), nb::arg("out"))
+        .def("set_state", [](JitSim& jit, int component, HostFloatArray values){
+            const hdd::Config config = jit->config();
+            const size_t dim = jit.component_dim(component);
+            if(values.ndim() != 2 || values.shape(0) != config.num_drones || values.shape(1) != dim){
+                throw std::invalid_argument("hyperdrone: state component values must have shape (num_drones, dim) and dtype float32");
+            }
+            nb::gil_scoped_release release;
+            jit->set_state_component(component, values.data());
+        }, nb::arg("component"), nb::arg("values"))
+        .def("update_observations", [](JitSim& jit){
+            nb::gil_scoped_release release;
+            jit->update_observations();
+        })
+        .def("observations_dlpack", [](JitSim& jit){
+            const hdd::Config config = jit->config();
+            return nb::ndarray<>((void*)jit->observation_buffer(), {config.num_drones, config.observation_dim}, nb::find(&jit), {},
+                                 nb::dtype<float>(), jit->buffer_device_type(), 0);
+        })
+        .def("read_observations", [](JitSim& jit, nb::ndarray<float, nb::c_contig, nb::device::cpu> out){
+            const hdd::Config config = jit->config();
+            if(out.size() != (size_t)config.num_drones * config.observation_dim){
+                throw std::invalid_argument("hyperdrone: observations output must have num_drones * observation_dim elements");
+            }
+            nb::gil_scoped_release release;
+            jit.copy_out(jit->observation_buffer(), out.data(), (size_t)config.num_drones * config.observation_dim);
+        }, nb::arg("out"))
+        .def("update_camera_bases", [](JitSim& jit, HostFloatArray mount, float fov, float aspect){
+            if(mount.size() != 12){
+                throw std::invalid_argument("hyperdrone: mount transform must have 12 elements (3x4 row-major)");
+            }
+            nb::gil_scoped_release release;
+            jit->update_camera_bases(mount.data(), fov, aspect);
+        }, nb::arg("mount"), nb::arg("fov"), nb::arg("aspect"))
+        .def("camera_bases_dlpack", [](JitSim& jit){
+            const hdd::Config config = jit->config();
+            return nb::ndarray<>((void*)jit->camera_bases_buffer(), {config.num_drones, (size_t)12}, nb::find(&jit), {},
+                                 nb::dtype<float>(), jit->buffer_device_type(), 0);
+        })
+        .def("read_camera_bases", [](JitSim& jit, nb::ndarray<float, nb::c_contig, nb::device::cpu> out){
+            const hdd::Config config = jit->config();
+            if(out.size() != (size_t)config.num_drones * 12){
+                throw std::invalid_argument("hyperdrone: camera bases output must have num_drones * 12 elements");
+            }
+            nb::gil_scoped_release release;
+            jit.copy_out(jit->camera_bases_buffer(), out.data(), (size_t)config.num_drones * 12);
+        }, nb::arg("out"))
+        .def("read_parameter", [](JitSim& jit, const std::string& name, nb::ndarray<float, nb::c_contig, nb::device::cpu> out){
+            if(out.size() != jit->config().num_drones){
+                throw std::invalid_argument("hyperdrone: parameter output must have num_drones elements");
+            }
+            if(!jit->read_parameter(name.c_str(), out.data())){
+                throw std::invalid_argument("hyperdrone: unknown parameter " + name);
+            }
+        }, nb::arg("name"), nb::arg("out"))
+        .def("write_parameter", [](JitSim& jit, const std::string& name, HostFloatArray values){
+            if(values.size() != jit->config().num_drones){
+                throw std::invalid_argument("hyperdrone: parameter values must have num_drones elements");
+            }
+            if(!jit->write_parameter(name.c_str(), values.data())){
+                throw std::invalid_argument("hyperdrone: unknown parameter " + name);
+            }
+        }, nb::arg("name"), nb::arg("values"));
+
+#if defined(HYPERDRONE_DYNAMICS_CUDA)
+    m.attr("HAS_CUDA") = true;
+
+    hyperdrone::register_cuda_staging(m);
+
+    jit_sim_class
+        .def("step_device", [](JitSim& jit, nb::ndarray<const float, nb::c_contig, nb::device::cuda> actions, uintptr_t stream){
+            const hdd::Config config = jit->config();
+            if(actions.ndim() != 2 || actions.shape(0) != config.num_drones || actions.shape(1) != config.action_dim){
+                throw std::invalid_argument("hyperdrone: actions must have shape (num_drones, action_dim) and dtype float32");
+            }
+            jit->step(actions.data(), 2, stream);
+        }, nb::arg("actions"), nb::arg("stream") = 0);
+#else
+    m.attr("HAS_CUDA") = false;
+#endif
+}

hyperdrone/_native/dynamics/iface.h

@@ -0,0 +1,76 @@
+#pragma once
+#include <cstdint>
+
+// ABI boundary between the hyperdrone dynamics core module and the JIT-compiled simulator
+// libraries. Buffer exchange uses raw float pointers sized by config(); state is published
+// after every mutation as SoA component buffers (device-resident on the CUDA variant) so
+// consumers get stable zero-copy views. Bump HYPERDRONE_DYNAMICS_IFACE_VERSION on any
+// change to this file.
+#define HYPERDRONE_DYNAMICS_IFACE_VERSION 4
+
+namespace hyperdrone::dynamics {
+    struct Config {
+        uint32_t num_drones;
+        uint32_t action_dim;
+        uint32_t observation_dim;
+        bool domain_randomization;
+    };
+
+    // SoA state component buffers, each (num_drones, dim) float32
+    enum class StateComponent : int {
+        POSITION = 0,         // 3
+        ORIENTATION = 1,      // 4, quaternion wxyz
+        LINEAR_VELOCITY = 2,  // 3
+        ANGULAR_VELOCITY = 3, // 3
+        RPM = 4               // action_dim
+    };
+    inline constexpr int state_component_dims[5] = {3, 4, 3, 3, 4};
+
+    class Sim {
+    public:
+        virtual ~Sim() = default;
+        virtual Config config() const = 0;
+        virtual const char* device_name() const = 0;    // "cpu" | "cuda"
+        virtual int buffer_device_type() const = 0;     // DLPack: 1 = kDLCPU, 2 = kDLCUDA
+        virtual unsigned long long stream() const = 0;  // cudaStream_t handle (0 on cpu)
+        virtual void synchronize() = 0;
+
+        virtual bool set_model(const char* name) = 0;   // registry preset, all drones
+        virtual void set_dt(float dt) = 0;
+        virtual float dt() const = 0;
+
+        // deterministic given seed: default parameters (+ optional domain-randomization
+        // sampling) and sampled initial states. All sampling runs on the host with the
+        // rl_tools CPU engine so cpu and cuda variants reset to identical states.
+        virtual void reset(unsigned long long seed, bool sample_parameters, bool sample_states) = 0;
+
+        // actions (num_drones, action_dim) float32, normalized [-1, 1];
+        // actions_device_type: 1 = host pointer, 2 = CUDA device pointer
+        virtual void step(const float* actions, int actions_device_type, unsigned long long producer_stream) = 0;
+
+        virtual const float* state_buffer(int component) const = 0;
+        virtual void set_state_component(int component, const float* values_host) = 0;
+
+        virtual void update_observations() = 0;
+        virtual const float* observation_buffer() const = 0;
+
+        // packed camera ray-gen bases (num_drones, 12): pos, dir_00, dir_du, dir_dv in the
+        // renderer's layout. mount is a (3, 4) body-frame transform: rotation columns map
+        // camera axes (FLU: +X forward) into the body frame, translation is the offset.
+        // fov is in degrees, like every user-facing FOV.
+        virtual void update_camera_bases(const float mount[12], float fov_degrees, float aspect) = 0;
+        virtual const float* camera_bases_buffer() const = 0;
+
+        // per-drone runtime physical parameters (host pointers, num_drones scalars each;
+        // parameters are host-authoritative). False for unknown names.
+        virtual bool read_parameter(const char* name, float* dst) = 0;
+        virtual bool write_parameter(const char* name, const float* values) = 0;
+    };
+}
+
+extern "C" {
+    hyperdrone::dynamics::Sim* hyperdrone_dynamics_create();
+    void hyperdrone_dynamics_destroy(hyperdrone::dynamics::Sim* sim);
+    const char* hyperdrone_dynamics_config_string();
+    int hyperdrone_dynamics_iface_version();
+}