hyperray 0.0.1__py3-none-any.whl

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,80 @@
+#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;
+        int device_ordinal = 0;
+        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");
+            }
+            cudaPointerAttributes attributes;
+            cudaPointerGetAttributes(&attributes, pointer);
+            device_ordinal = attributes.device;
+            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("device_id", [](const CudaBuffer& buffer){ return buffer.device_ordinal; })
+            .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, buffer.device_ordinal);
+            }, 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, buffer.device_ordinal);
+            });
+    }
+}

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/common/verbosity.h

@@ -0,0 +1,52 @@
+#pragma once
+#include <rl_tools/rl_tools.h>
+#include <rl_tools/devices/cpu.h>
+#include <rl_tools/logging/operations_cpu.h>
+
+#include <mutex>
+#include <stdexcept>
+
+namespace rl_tools::devices::logging {
+    struct Hyperdrone: CPU {};
+}
+
+namespace hyperdrone {
+    using CPUSpecification = rl_tools::devices::cpu::Specification<rl_tools::devices::math::CPU, rl_tools::devices::random::CPU, rl_tools::devices::logging::Hyperdrone>;
+
+    struct VerbosityState {
+        std::mutex mutex;
+        rl_tools::devices::logging::Verbosity level = rl_tools::devices::logging::Verbosity::info;
+    };
+
+    // Extensions have local symbol visibility: each owns a policy updated by Python.
+    inline VerbosityState& verbosity_state(){
+        static VerbosityState state;
+        return state;
+    }
+
+    inline rl_tools::devices::logging::CPU diagnostic_logger(){
+        auto& state = verbosity_state();
+        std::lock_guard<std::mutex> lock(state.mutex);
+        rl_tools::devices::logging::CPU logger;
+        logger.verbosity = state.level;
+        return logger;
+    }
+
+    inline void set_verbosity(int level){
+        using Verbosity = rl_tools::devices::logging::Verbosity;
+        if(level < (int)Verbosity::error || level > (int)Verbosity::debug){
+            throw std::invalid_argument("hyperdrone: verbosity level out of range");
+        }
+        auto& state = verbosity_state();
+        std::lock_guard<std::mutex> lock(state.mutex);
+        state.level = (Verbosity)level;
+    }
+}
+
+namespace rl_tools {
+    template <typename DEVICE, typename... ARGS>
+    void log(DEVICE& device, devices::logging::Hyperdrone& logger, devices::logging::Verbosity verbosity, const ARGS&... args){
+        auto snapshot = hyperdrone::diagnostic_logger();
+        log(device, snapshot, verbosity, args...);
+    }
+}

hyperdrone/_native/dynamics/CMakeLists.txt

@@ -0,0 +1,63 @@
+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")
+    # a normal variable before enable_language shadows the compiler default it caches, also in
+    # trees configured before; CUDAARCHS overrides
+    if(NOT DEFINED ENV{CUDAARCHS})
+        set(CMAKE_CUDA_ARCHITECTURES native)
+    endif()
+    enable_language(CUDA)
+    set(CMAKE_CUDA_STANDARD 17)
+    set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+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,188 @@
+#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>;
+using HostMask = nb::ndarray<const bool, 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("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("buffer_device_id", [](const JitSim& jit){ return jit->buffer_device_id(); })
+        .def("order_consumer", [](JitSim& jit, uintptr_t stream){ jit->order_consumer(stream); })
+        .def_prop_ro("stream", [](const JitSim& jit){ return (uintptr_t)jit->stream(); })
+        .def("synchronize", [](JitSim& jit){
+            nb::gil_scoped_release release;
+            jit->synchronize();
+        })
+        .def("parameters", [](JitSim& jit){ return jit->parameters_json(); })
+        .def("init", [](JitSim& jit, uint64_t seed, const std::string& parameters){ jit->init(seed, parameters); })
+        .def("reset", [](JitSim& jit, HostMask mask, bool sample_states){
+            if(mask.ndim() != 1 || mask.size() != jit->config().num_drones){
+                throw std::invalid_argument("hyperdrone: mask must have shape (num_drones,)");
+            }
+            nb::gil_scoped_release release;
+            jit->reset(mask.data(), sample_states);
+        }, nb::arg("mask"), nb::arg("sample_states"))
+        .def("instance_parameters", [](JitSim& jit){ return jit->instance_parameters_json(); })
+        .def("set_instance_parameters", [](JitSim& jit, HostMask mask, const std::string& parameters){
+            if(mask.ndim() != 1 || mask.size() != jit->config().num_drones){
+                throw std::invalid_argument("hyperdrone: mask must have shape (num_drones,)");
+            }
+            jit->set_instance_parameters(mask.data(), parameters);
+        })
+        .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(), jit->buffer_device_id());
+        }, 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(), jit->buffer_device_id());
+        })
+        .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(), jit->buffer_device_id());
+        })
+        .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"));
+
+#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,71 @@
+#pragma once
+#include <cstdint>
+#include <string>
+
+// 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 5
+
+namespace hyperdrone::dynamics {
+    struct Config {
+        uint32_t num_drones;
+        uint32_t action_dim;
+        uint32_t observation_dim;
+    };
+
+    // 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 int buffer_device_id() const = 0;
+        virtual void order_consumer(unsigned long long stream) = 0;
+        virtual std::string parameters_json() = 0;
+        virtual void init(unsigned long long seed, const std::string& parameters) = 0;
+        virtual void reset(const bool* mask, bool sample_states) = 0;
+        virtual std::string instance_parameters_json() = 0;
+        virtual void set_instance_parameters(const bool* mask, const std::string& parameters) = 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;
+
+    };
+}
+
+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();
+}