PyRXMesh 0.2.1rc0__tar.gz

pyrxmesh-0.2.1rc0/.clang-format

@@ -0,0 +1,42 @@
+---
+Language:        Cpp
+BasedOnStyle:  Chromium
+TabWidth: 4
+UseTab: Never
+
+AlignConsecutiveAssignments: true
+AllowShortFunctionsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: true
+AlignTrailingComments: true
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeTernaryOperators: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+Cpp11BracedListStyle: true
+IndentCaseLabels: true
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 2
+NamespaceIndentation: None 
+ObjCBlockIndentWidth: 2
+ColumnLimit:     80
+AlignConsecutiveDeclarations: true
+
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterClass: true
+  AfterControlStatement: false
+  AfterEnum: true
+  AfterFunction: true
+  AfterNamespace: false
+  AfterStruct: true
+  AfterUnion: true
+  AfterExternBlock: true
+  BeforeCatch: false
+  BeforeElse: false
+...

pyrxmesh-0.2.1rc0/.gitignore

@@ -0,0 +1,11 @@
+build/
+/dist/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.pyd
+*.so
+*.dylib
+RXMesh.log
+.polyscope.ini
+imgui.ini

pyrxmesh-0.2.1rc0/CMakeLists.txt

@@ -0,0 +1,186 @@
+cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
+
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+    set(CMAKE_CUDA_ARCHITECTURES native)
+endif()
+
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/pyproject.toml" PYRXMESH_PYPROJECT_TOML)
+string(REGEX MATCH
+    "\\[project\\][^[]*version[ \t]*=[ \t]*\"([^\"]+)\""
+    PYRXMESH_VERSION_MATCH
+    "${PYRXMESH_PYPROJECT_TOML}"
+)
+set(PYRXMESH_VERSION "${CMAKE_MATCH_1}")
+
+project(PyRXMesh LANGUAGES C CXX CUDA)
+# Increment when the compiled custom-plugin capsule/API contract changes incompatibly and old plugins will no longer work with the new PyRXMesh version. This is separate from the overall project version, which can be incremented for any change including compatible ones.
+set(PYRXMESH_PLUGIN_ABI_VERSION 2)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CUDA_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED TRUE)
+set(CMAKE_CUDA_STANDARD_REQUIRED TRUE)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+include(FetchContent)
+
+find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG QUIET)
+if(NOT pybind11_FOUND)
+    FetchContent_Declare(pybind11
+        GIT_REPOSITORY https://github.com/pybind/pybind11.git
+        GIT_TAG v2.13.6
+        GIT_SHALLOW TRUE
+    )
+    FetchContent_MakeAvailable(pybind11)
+endif()
+
+set(PYRXMESH_RXMESH_GIT_REPO "https://github.com/owensgroup/RXMesh.git" CACHE STRING "RXMesh Git repository URL")
+set(PYRXMESH_RXMESH_GIT_TAG "main" CACHE STRING "RXMesh Git tag, branch, or commit to build against")
+set(PYRXMESH_RXMESH_SOURCE_DIR "" CACHE PATH "Optional local RXMesh source checkout. If set, Git fetch is skipped.")
+set(PYRXMESH_USE_POLYSCOPE "ON" CACHE BOOL "Build RXMesh with Polyscope visualization support")
+set(PYRXMESH_BUILD_RXMESH_TESTS "OFF" CACHE BOOL "Build RXMesh tests when building PyRXMesh")
+set(PYRXMESH_BUILD_RXMESH_APPS "OFF" CACHE BOOL "Build RXMesh apps when building PyRXMesh")
+set(PYRXMESH_USE_DOUBLE "OFF" CACHE BOOL "Build RXMesh with double precision coordinate input")
+set(PYRXMESH_USE_CUDSS "OFF" CACHE BOOL "Build RXMesh with cuDSS support")
+set(PYRXMESH_USE_SUITESPARSE "OFF" CACHE BOOL "Build RXMesh with SuiteSparse support")
+set(PYRXMESH_INSTALL_PLUGIN_SDK "ON" CACHE BOOL "Install headers, libraries, and CMake files needed to build PyRXMesh plugins")
+
+
+string(REPLACE "\\" "/" PYRXMESH_RXMESH_SOURCE_DIR_TAG "${PYRXMESH_RXMESH_SOURCE_DIR}")
+set(PYRXMESH_CUDA_ARCHITECTURES_TAG "${CMAKE_CUDA_ARCHITECTURES}")
+string(REPLACE ";" "," PYRXMESH_CUDA_ARCHITECTURES_TAG "${PYRXMESH_CUDA_ARCHITECTURES_TAG}")
+
+# Captures build options that plugins must match to safely link against this PyRXMesh/RXMesh install. Used by plugins to check compatibility at runtime and refuse to load if incompatible, preventing hard-to-debug crashes due to ABI incompatibility.
+set(PYRXMESH_BUILD_CONFIG_TAG
+    "abi=${PYRXMESH_PLUGIN_ABI_VERSION},pyrxmesh=${PYRXMESH_VERSION},rxmesh_repo=${PYRXMESH_RXMESH_GIT_REPO},rxmesh_tag=${PYRXMESH_RXMESH_GIT_TAG},rxmesh_source=${PYRXMESH_RXMESH_SOURCE_DIR_TAG},polyscope=${PYRXMESH_USE_POLYSCOPE},double=${PYRXMESH_USE_DOUBLE},cudss=${PYRXMESH_USE_CUDSS},suitesparse=${PYRXMESH_USE_SUITESPARSE},cuda_arch=${PYRXMESH_CUDA_ARCHITECTURES_TAG}"
+)
+
+# RXMesh uses these option names internally. Force them before adding RXMesh so PyRXMesh controls the dependency build in both Git and local-source modes.
+set(RX_BUILD_TESTS ${PYRXMESH_BUILD_RXMESH_TESTS} CACHE BOOL "" FORCE)
+set(RX_BUILD_APPS ${PYRXMESH_BUILD_RXMESH_APPS} CACHE BOOL "" FORCE)
+set(RX_USE_POLYSCOPE ${PYRXMESH_USE_POLYSCOPE} CACHE BOOL "" FORCE)
+set(RX_USE_DOUBLE ${PYRXMESH_USE_DOUBLE} CACHE BOOL "" FORCE)
+set(RX_USE_CUDSS ${PYRXMESH_USE_CUDSS} CACHE BOOL "" FORCE)
+set(RX_USE_SUITESPARSE ${PYRXMESH_USE_SUITESPARSE} CACHE BOOL "" FORCE)
+set(RXMESH_INSTALL_INCLUDEDIR "pyrxmesh/include" CACHE STRING "" FORCE)
+set(RXMESH_INSTALL_THIRD_PARTY_INCLUDEDIR "pyrxmesh/third_party/include" CACHE STRING "" FORCE)
+set(RXMESH_INSTALL_LIBDIR "pyrxmesh/lib" CACHE STRING "" FORCE)
+set(RXMESH_INSTALL_BINDIR "pyrxmesh/bin" CACHE STRING "" FORCE)
+set(RXMESH_INSTALL_CMAKEDIR "pyrxmesh/cmake/RXMesh" CACHE STRING "" FORCE)
+if(PYRXMESH_INSTALL_PLUGIN_SDK)
+    set(RXMESH_INSTALL_COMPONENT "python" CACHE STRING "" FORCE)
+else()
+    set(RXMESH_INSTALL_COMPONENT "plugin_sdk" CACHE STRING "" FORCE)
+endif()
+
+if(PYRXMESH_RXMESH_SOURCE_DIR)
+    get_filename_component(PYRXMESH_RXMESH_SOURCE_DIR_ABS "${PYRXMESH_RXMESH_SOURCE_DIR}" ABSOLUTE)
+    if(NOT EXISTS "${PYRXMESH_RXMESH_SOURCE_DIR_ABS}/CMakeLists.txt")
+        message(FATAL_ERROR "PYRXMESH_RXMESH_SOURCE_DIR does not point to an RXMesh source tree: ${PYRXMESH_RXMESH_SOURCE_DIR_ABS}")
+    endif()
+    add_subdirectory("${PYRXMESH_RXMESH_SOURCE_DIR_ABS}" "${CMAKE_BINARY_DIR}/_deps/rxmesh-build")
+else()
+    FetchContent_Declare(rxmesh
+        GIT_REPOSITORY "${PYRXMESH_RXMESH_GIT_REPO}"
+        GIT_TAG "${PYRXMESH_RXMESH_GIT_TAG}"
+        GIT_SHALLOW TRUE
+    )
+    FetchContent_MakeAvailable(rxmesh)
+endif()
+
+set_target_properties(RXMesh PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+pybind11_add_module(_rxmesh MODULE
+    src/bindings.cu
+    src/bindings/core.cu
+    src/bindings/geometry.cu
+    src/bindings/handles.cu
+    src/bindings/mesh.cu
+    src/bindings/common.h
+    src/bindings/dlpack_minimal.h
+
+    src/bindings/py_attributes.cu
+    src/bindings/py_attribute.h
+
+    src/bindings/py_dense_matrix.cu
+    src/bindings/py_dense_matrix.h
+    src/bindings/dense_matrix_dlpack.h
+
+    src/bindings/py_sparse_matrix.cu
+    src/bindings/py_sparse_matrix.h
+    src/bindings/py_solvers.cu
+    src/bindings/py_solvers.h
+    src/bindings/py_hessian_sparse_matrix.h
+    src/bindings/py_jacobian_sparse_matrix.h
+    src/bindings/sparse_matrix_csr.h
+    src/bindings/sparse_matrix_dlpack.h
+)
+
+target_link_libraries(_rxmesh PRIVATE RXMesh)
+target_include_directories(_rxmesh
+    PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/include"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src"
+)
+target_compile_features(_rxmesh PRIVATE cxx_std_17)
+target_compile_definitions(_rxmesh
+    PRIVATE PYRXMESH_PLUGIN_ABI_VERSION=${PYRXMESH_PLUGIN_ABI_VERSION}
+    PRIVATE PYRXMESH_BUILD_CONFIG="${PYRXMESH_BUILD_CONFIG_TAG}"
+)
+set_target_properties(_rxmesh PROPERTIES
+    CUDA_SEPARABLE_COMPILATION ON
+    CUDA_RESOLVE_DEVICE_SYMBOLS ON
+)
+
+if(UNIX AND NOT APPLE)
+    set_target_properties(_rxmesh PROPERTIES
+        INSTALL_RPATH "$ORIGIN;$ORIGIN/lib;$ORIGIN/bin"
+    )
+endif()
+
+if(WIN32)
+    target_compile_definitions(_rxmesh
+        PRIVATE _USE_MATH_DEFINES
+        PRIVATE NOMINMAX
+        PRIVATE _CRT_SECURE_NO_WARNINGS
+    )
+endif()
+
+if(PYRXMESH_USE_CUDSS)
+    target_compile_definitions(_rxmesh PRIVATE USE_CUDSS)
+endif()
+
+install(TARGETS _rxmesh
+    LIBRARY DESTINATION pyrxmesh COMPONENT python
+    RUNTIME DESTINATION pyrxmesh COMPONENT python
+)
+
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/pyrxmeshConfig.cmake.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/pyrxmeshConfig.cmake"
+    @ONLY
+)
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/build_config.json.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/build_config.json"
+    @ONLY
+)
+
+if(PYRXMESH_INSTALL_PLUGIN_SDK)
+    install(FILES
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/pyrxmesh/plugin_api.h"
+        DESTINATION pyrxmesh/include/pyrxmesh
+        COMPONENT python
+    )
+    install(FILES
+        "${CMAKE_CURRENT_BINARY_DIR}/pyrxmeshConfig.cmake"
+        DESTINATION pyrxmesh/cmake
+        COMPONENT python
+    )
+endif()
+install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/build_config.json"
+    DESTINATION pyrxmesh
+    COMPONENT python
+)

pyrxmesh-0.2.1rc0/CUSTOM_CUDA_PLUGINS.md

@@ -0,0 +1,107 @@
+# Custom CUDA Plugins
+
+Most PyRXMesh workflows should stay in Python. Custom CUDA plugins are for the parts of RXMesh that require C++/CUDA device lambdas.
+
+The intended workflow is to keep orchestration and data management in Python, and put only the hot RXMesh lambda code in a small compiled plugin package.
+
+## Creating a Plugin Package
+
+```bash
+python -m pyrxmesh.plugin init my_kernels
+cd my_kernels
+python -m pip install -v --no-build-isolation .
+```
+
+The scaffolder generates a Python "src-layout" tree:
+
+```text
+my_kernels/
+  pyproject.toml
+  CMakeLists.txt
+  README.md
+  src/
+    my_kernels.cu             # CUDA source for the plugin
+    my_kernels/__init__.py    # Python package source
+  my_script.py                # your own scripts can live here
+```
+
+The generated plugin builds against the `pyrxmesh` package installed in the active Python environment. It reuses the RXMesh headers and library installed with PyRXMesh, so plugin builds should compile only the plugin code instead of rebuilding RXMesh. The plugin also checks the PyRXMesh/RXMesh build configuration at runtime.
+
+After `pip install`, `my_kernels` is in your environment's site-packages and importable from any directory, exactly like `pyrxmesh` itself.
+
+### Why src-layout?
+
+Python's `sys.path[0]` is always the directory containing the script you ran. If a plugin's Python source package sits next to that script (the natural place to put it), `import my_kernels` resolves to the **source** directory rather than the installed wheel. Because the compiled CUDA extension (`_my_kernels.<ext>`) lives only in the installed wheel, the import then fails.
+
+The src-layout sidesteps this by tucking Python sources under `src/my_kernels/`. The plugin root contains no importable `my_kernels/` directory, so `import my_kernels` always resolves to site-packages with the compiled extension alongside it. No `sys.path` munging or `cd` discipline is required.
+
+
+## Use a Plugin From Python
+
+Generated Python usage:
+
+```python
+import pyrxmesh as rx
+import my_kernels
+
+mesh = rx.RXMeshStatic("mesh.obj")
+coords = mesh.input_vertex_coordinates()
+edge_lengths = mesh.add_edge_attribute("edge_lengths", dtype="float32", dim=1)
+
+my_kernels.compute_edge_lengths(mesh, coords, edge_lengths)
+```
+
+The CUDA code receives PyRXMesh objects and unwraps them through
+`pyrxmesh/plugin_api.h`:
+
+```cpp
+auto coords = pyrxmesh::vertex_attribute<float>(coords_obj);
+auto out = pyrxmesh::edge_attribute<float>(out_obj);
+
+pyrxmesh::for_each<Op::EV, 256>(
+    mesh_obj,
+    [coords, out] __device__(const EdgeHandle& eh,
+                             const VertexIterator& iter) mutable {
+        const Eigen::Vector3f a = coords.to_eigen<3>(iter[0]);
+        const Eigen::Vector3f b = coords.to_eigen<3>(iter[1]);
+        out(eh) = (a - b).norm();
+    });
+```
+
+Use `pyrxmesh::for_each` for RXMesh query operations from plugin modules. It delegates launch-box preparation to the installed PyRXMesh runtime and then launches the plugin's CUDA lambda without an extra Python data copy.
+
+## Examples
+
+The repository includes a complete custom-kernel plugin example in [`examples/custom_kernel_plugin`](examples/custom_kernel_plugin) using the same src-layout the scaffolder emits:
+
+```text
+examples/custom_kernel_plugin/
+  pyproject.toml
+  CMakeLists.txt
+  run_edge_lengths.py
+  src/
+    rxmesh_edge_lengths.cu
+    rxmesh_edge_lengths/__init__.py
+```
+
+It computes one scalar edge-length attribute on the GPU using an RXMesh `Op::EV` device lambda, then reads the result back from Python.
+
+Build the example plugin from the PyRXMesh repository root:
+
+```bash
+python -m pip install -v --no-build-isolation examples/custom_kernel_plugin
+```
+
+After PyRXMesh is installed, this build links against the installed PyRXMesh package and should not fetch or compile RXMesh again.
+
+Run it as:
+
+```bash
+python examples/custom_kernel_plugin/run_edge_lengths.py --input mesh.obj
+```
+
+The example package shows the intended split where Python loads the mesh and owns the workflow while `src/rxmesh_edge_lengths.cu` contains only the performance critical RXMesh lambda.
+
+
+For PyRXMesh source-build and incremental-build notes, see
+[DEVELOPING.md](DEVELOPING.md).

pyrxmesh-0.2.1rc0/DEVELOPING.md

@@ -0,0 +1,110 @@
+# Developing PyRXMesh
+
+This guide is for building PyRXMesh from source, testing changes, and working against RXMesh branches, forks, or local checkouts. If you only want to use PyRXMesh from Python, start with [README.md](README.md).
+
+## Prerequisites
+
+You need the platform CUDA/C++ toolchain:
+
+- Windows: Visual Studio C++ tools plus NVIDIA CUDA Toolkit with `nvcc`.
+- Linux: GCC/Clang compatible with your CUDA Toolkit, NVIDIA CUDA Toolkit with
+  `nvcc`, and the OpenGL/X11 development packages required by Polyscope.
+
+## Conda Environment
+
+```bash
+conda env create -f environment.yml
+conda activate PyRXMesh
+```
+
+Install build requirements into the active environment when you want faster developer rebuilds without build isolation:
+
+```bash
+python -m pip install scikit-build-core pybind11 numpy
+```
+
+## Build From Source
+
+The normal developer build uses the local default CUDA architecture behavior and the RXMesh ref configured in `pyproject.toml`:
+
+```bash
+python -m pip install -v .
+```
+
+For a faster inner loop after installing build requirements:
+
+```bash
+python -m pip install -v --no-build-isolation .
+```
+
+## Select An RXMesh Source
+
+For release packages, the RXMesh ref should be source-controlled in `pyproject.toml`:
+
+```toml
+[tool.scikit-build.cmake.define]
+PYRXMESH_RXMESH_GIT_TAG = "main"
+```
+
+For local experiments, override the RXMesh tag or commit from the command line:
+
+```bash
+python -m pip install -v . -Ccmake.define.PYRXMESH_RXMESH_GIT_TAG=<tag-or-commit>
+```
+
+Examples:
+
+```bash
+python -m pip install -v . -Ccmake.define.PYRXMESH_RXMESH_GIT_TAG=main
+python -m pip install -v . -Ccmake.define.PYRXMESH_RXMESH_GIT_TAG=v0.2.1
+```
+
+To build against an RXMesh fork:
+
+```bash
+python -m pip install -v . \
+  -Ccmake.define.PYRXMESH_RXMESH_GIT_REPO=https://github.com/<user>/RXMesh.git \
+  -Ccmake.define.PYRXMESH_RXMESH_GIT_TAG=<tag-or-commit>
+```
+
+For local RXMesh development without fetching from Git:
+
+```bash
+python -m pip install -v . -Ccmake.define.PYRXMESH_RXMESH_SOURCE_DIR=C:/path/to/RXMesh
+```
+
+## Release-Like Local Build
+
+Release wheels build with Polyscope enabled and a broad CUDA architecture set:
+
+```bash
+python -m pip install -v . \
+  -Ccmake.define.CMAKE_CUDA_ARCHITECTURES="75;80;86;89;90" \
+  -Ccmake.define.PYRXMESH_USE_POLYSCOPE=ON
+```
+
+## Incremental Builds
+
+Builds reuse a persistent scikit-build-core build directory:
+
+```text
+build/{wheel_tag}
+```
+
+The first install for a Python/platform/RXMesh configuration is a full build. Subsequent installs with the same settings should be incremental.
+
+To force a clean rebuild, delete the matching `build/<wheel_tag>` directory.
+
+## Run Examples
+
+Examples are not part of the installed package, so editing them does not require reinstalling/recompiling PyRXMesh:
+
+```bash
+python examples/load_and_show.py --input mesh.obj
+```
+
+## Custom CUDA Plugins
+
+Most PyRXMesh workflows should stay in Python. For RXMesh operations that require CUDA device lambdas, PyRXMesh supports small compiled plugin packages that operate on PyRXMesh meshes and attributes without extra Python-side copies.
+
+See [CUSTOM_CUDA_PLUGINS.md](CUSTOM_CUDA_PLUGINS.md) for the plugin workflow.

pyrxmesh-0.2.1rc0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ahmed Mahmoud and PyRXMesh contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyrxmesh-0.2.1rc0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: PyRXMesh
+Version: 0.2.1rc0
+Summary: Python bindings for RXMesh, a CUDA/C++ library for mesh processing on the GPU.
+Author: Ahmed Mahmoud
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Project-URL: RXMesh, https://github.com/owensgroup/RXMesh
+Project-URL: Documentation, https://ahdhn.github.io/RXMeshDocs/
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# PyRXMesh
+
+Python bindings for [RXMesh](https://github.com/owensgroup/RXMesh), a CUDA/C++ library for GPU mesh processing.
+
+PyRXMesh allows you to keep mesh workflows in Python while using RXMesh data structures and GPU kernels underneath. It supports exchanging arrays and attributes with NumPy and PyTorch, building sparse matrices, and solving linear systems. We use a Python plugin to allow CUDA kernels to be written, compiled, and used directly in Python. Check out [CUSTOM_CUDA_PLUGINS.md](CUSTOM_CUDA_PLUGINS.md) for more details.
+
+
+## Installation
+
+Install PyRXMesh with:
+
+```bash
+python -m pip install PyRXMesh
+```
+
+PyRXMesh is a CUDA package. You need an NVIDIA driver compatible with the CUDA version used by the wheel. For source builds and development setup, see [DEVELOPING.md](DEVELOPING.md).
+
+## Simple Example
+
+```python
+import pyrxmesh as rx
+
+#Use GPU 0 
+rx.init(0) 
+
+mesh = rx.RXMeshStatic("mesh.obj")
+print(mesh.num_vertices, mesh.num_edges, mesh.num_faces)
+
+rx.show()
+```
+
+The repository includes a small viewer example:
+
+```bash
+python examples/load_and_show.py --input mesh.obj
+```
+
+## Mesh Attributes
+
+Attributes are data attached to vertices, edges, or faces
+
+```python
+import pyrxmesh as rx
+
+mesh = rx.RXMeshStatic("mesh.obj")
+
+coords = mesh.input_vertex_coordinates()
+velocity = mesh.add_vertex_attribute("velocity", dtype="float32",
+                                     dim=3, location=rx.Location.ALL)
+
+velocity.reset(0.0, rx.Location.DEVICE)
+
+host_coords = coords.to_numpy_copy(source=rx.Location.HOST)
+print(host_coords.shape)
+```
+
+## NumPy And Torch Interop
+
+Unsuffixed `to_*` methods return zero-copy views when possible. Methods ending
+in `_copy` make an explicit copy.
+
+```python
+import pyrxmesh as rx
+
+mesh = rx.RXMeshStatic("mesh.obj")
+attr = mesh.add_vertex_attribute("temperature", dtype="float32",
+                                 dim=1, location=rx.Location.ALL)
+
+attr.reset(1.0, rx.Location.ALL)
+
+view = attr.to_numpy(rx.Location.HOST)
+view[0, 0] = 42.0
+
+owned = attr.to_numpy_copy(source=rx.Location.HOST)
+print(owned[0, 0])
+```
+
+Torch views use DLPack:
+
+```python
+tensor = attr.to_torch(rx.Location.DEVICE)
+tensor += 2.0
+```
+
+## Dense And Sparse Matrices
+
+PyRXMesh exposes RXMesh dense matrices and CSR sparse matrices.
+
+```python
+import numpy as np
+import pyrxmesh as rx
+
+matrix = rx.DenseMatrix(4, 3, dtype="float32", location=rx.Location.ALL)
+values = np.arange(12, dtype=np.float32).reshape(4, 3)
+
+matrix.from_numpy_copy(values, target=rx.Location.ALL)
+print(matrix.norm2())
+```
+
+Sparse matrices are CSR-only:
+
+```python
+mesh = rx.RXMeshStatic("mesh.obj")
+laplace_like = mesh.sparse_matrix(rx.Op.VV, dtype="float32")
+
+row_ptr, col_idx, values = laplace_like.to_numpy_copy()
+print(laplace_like.shape, laplace_like.nnz)
+```
+
+You can multiply sparse matrices by dense vectors:
+
+```python
+x = np.ones((laplace_like.cols, 1), dtype=np.float32)
+y = laplace_like.multiply_vector(x)
+print(y.to_numpy_copy(source=rx.Location.HOST))
+```
+
+## Solvers
+
+RXMesh solver bindings work with `SparseMatrix` and `DenseMatrix` objects:
+
+```python
+import numpy as np
+import pyrxmesh as rx
+
+row_ptr = np.array([0, 2, 5, 7], dtype=np.int32)
+col_idx = np.array([0, 1, 0, 1, 2, 1, 2], dtype=np.int32)
+values = np.array([4, 1, 1, 3, 1, 1, 2], dtype=np.float32)
+
+A = rx.SparseMatrix.from_numpy_copy(row_ptr, col_idx, values,
+                                    shape=(3, 3), dtype="float32")
+
+b = rx.DenseMatrix(3, 1, dtype="float32", location=rx.Location.ALL)
+b.from_numpy_copy(np.array([[1], [2], [3]], dtype=np.float32))
+
+solver = rx.CGSolver(A, unknown_dim=1)
+x = solver.solve(b)
+
+print(x.to_numpy_copy(source=rx.Location.HOST))
+```
+
+## Documentation
+- [RXMeshDocs](https://ahdhn.github.io/RXMeshDocs/): RXMesh CUDA/C++ documentation website 
+- [DEVELOPING.md](DEVELOPING.md): build PyRXMesh from source and work against RXMesh forks, tags, or local checkouts.
+- [CUSTOM_CUDA_PLUGINS.md](CUSTOM_CUDA_PLUGINS.md): write small compiled CUDA plugins that operate on PyRXMesh meshes and attributes.