Merge branch 'main' into dyn

Author: Ahdhn

.gitignore

@@ -10,6 +10,7 @@ input/*
 !input/cloth.obj
 !input/plane_5.obj
 !input/sphere1.obj
+!input/bunnyhead.obj
 build/
 build_debug/
 include/rxmesh/util/git_sha1.cpp

CMakeLists.txt

@@ -187,6 +187,12 @@ find_package(CUDAToolkit REQUIRED)
 target_link_libraries(RXMesh INTERFACE CUDA::cusparse)
 target_link_libraries(RXMesh INTERFACE CUDA::cusolver)
 
+#Eigen
+include("cmake/eigen.cmake")
+target_link_libraries(RXMesh INTERFACE Eigen3::Eigen)
+# https://eigen.tuxfamily.org/dox/TopicCUDA.html
+target_compile_definitions(RXMesh INTERFACE "EIGEN_DEFAULT_DENSE_INDEX_TYPE=int")
+
 include(GoogleTest)
 add_subdirectory(apps)
 add_subdirectory(tests)

README.md

@@ -13,6 +13,7 @@
   * [**Structures**](#structures)
   * [**Computation**](#computation)
   * [**Viewer**](#viewer)
+  * [**Matrices and Vectors**](#matrices-and-vectors)
 - [**Replicability**](#replicability)
 - [**Bibtex**](#bibtex)
 
@@ -25,16 +26,23 @@ RXMesh is a surface triangle mesh data structure and programming model for proce
 
 - *[RXMesh: A High-performance Mesh Data Structure and Programming Model on the GPU  [S41051]](https://www.nvidia.com/gtc/session-catalog/?tab.scheduledorondemand=1583520458947001NJiE&search=rxmesh#/session/1633891051385001Q9SE)—NVIDIA GTC 2022*
 
-This repository provides 1) source code to reproduce the results presented in the paper (git tag [`v0.1.0`](https://github.com/owensgroup/RXMesh/tree/v0.1.0)) and 2) ongoing development of RXMesh. For 1), all input models used in the paper can be found [here](https://ucdavis365-my.sharepoint.com/:f:/g/personal/ahmahmoud_ucdavis_edu/En-vEpIdSGBHqvCIa-MVXRQBg5g7GfM3P3RwZBHL4Hby3w?e=2EVnJd). Models were collected from [Thingi10K](https://ten-thousand-models.appspot.com/) and [Smithsonian 3D](https://3d.si.edu/explore) repository. 
+The library also features a sparse and dense matrix infrastructure that is tightly coupled with the mesh data structure. We expose various [cuSolver](https://docs.nvidia.com/cuda/cusolver/index.html), [cuSparse](https://docs.nvidia.com/cuda/cusparse/), and [cuBlas](https://docs.nvidia.com/cuda/cublas/) operations through the sparse and dense matrices, tailored for geometry processing applications.
+
+This repository provides 1) source code to reproduce the results presented in the paper (git tag [`v0.1.0`](https://github.com/owensgroup/RXMesh/tree/v0.1.0)) and 2) ongoing development of RXMesh.
 
 ## **Compilation**
-The code can be compiled on Ubuntu (GCC 9) and Windows (Visual Studio 2019) providing that CUDA (>=11.1.0) is installed. To run the executable(s), an NVIDIA GPU should be installed on the machine.
+The code can be compiled on Ubuntu, Windows, and WSL providing that CUDA (>=11.1.0) is installed. To run the executable(s), an NVIDIA GPU should be installed on the machine.
 
 ### **Dependencies**
 - [OpenMesh](https://www.graphics.rwth-aachen.de:9000/OpenMesh/OpenMesh) to verify the applications against reference CPU implementation
 - [RapidJson](https://github.com/Tencent/rapidjson) to report the results in JSON file(s)
 - [GoogleTest](https://github.com/google/googletest) for unit tests
 - [spdlog](https://github.com/gabime/spdlog) for logging
+- [glm](https://github.com/g-truc/glm.git) for small vectors and matrices operations 
+- [Eigen](https://gitlab.com/libeigen/eigen) for small vectors and matrices operations 
+- [Polyscope ](https://github.com/nmwsharp/polyscope) for visualization  
+- [cereal](https://github.com/USCiLab/cereal.git) for serialization 
+
 
 All the dependencies are installed automatically! To compile the code:
 
@@ -109,7 +117,7 @@ The goal of defining a programming  model is to make it easy to write applicatio
     vertex_color(vh, 2) = 0.6;
     ```
 
-- **Iterators** are used during query operations to iterate over the output of the query operation. The type of iterator defines the type of mesh element iterated on e.g., `VertexIterator` iterates over vertices which is the output of `VV`, `EV`, or `FV` query operations. Since query operations are only supported on the device, iterators can be only used inside the kernel. Iterators are usually populated internally. 
+- **Iterators** are used during query operations to iterate over the output of the query operation. The type of iterator defines the type of mesh element iterated on e.g., `VertexIterator` iterates over vertices which is the output of `VV`, `EV`, or `FV` query operations. Since query operations are only supported on the device, iterators can be only used inside the GPU kernel. Iterators are usually populated internally. 
 
   - Example: Iterating over faces 
       ```c++  
@@ -140,7 +148,7 @@ The goal of defining a programming  model is to make it easy to write applicatio
             vertex_color(vh, 2) = 0.9;
         });
     ```
-  Alternatively, `for_each` operations could be written the same way as Queries operations (see below) using `for_each_dispatcher()`. This might be useful if the user would like to combine a `for_each` with queries operations in the same kernel. For more examples, checkout [`ForEach`](/tests/RXMesh_test/test_for_each.cuh) unit test. 
+  Alternatively, `for_each` operations could be written the same way as Queries operations (see below). This might be useful if the user would like to combine a `for_each` with queries operations in the same kernel. For more examples, checkout [`ForEach`](/tests/RXMesh_test/test_for_each.cuh) unit test. 
 
 - **Queries** operations supported by RXMesh with description are listed below 
 
@@ -161,30 +169,39 @@ The goal of defining a programming  model is to make it easy to write applicatio
     ```cpp
     template<uint32_t blockSize>
     __global__ void vertex_normal (Context context){      
-	    auto compute_vn = [&](FaceHandle face_id, VertexIterator& fv) {
+	    auto compute_vn = [&](const FaceHandle face_id, const VertexIterator& fv) {
         	//This thread is assigned to face_id
 
         	// get the face's three vertices coordinates
-        	Vector<3, T> c0(coords(fv[0], 0), coords(fv[0], 1), coords(fv[0], 2));
-        	Vector<3, T> c1(coords(fv[1], 0), coords(fv[1], 1), coords(fv[1], 2));
-	        Vector<3, T> c2(coords(fv[2], 0), coords(fv[2], 1), coords(fv[2], 2));
+        	vec3<T> c0(coords(fv[0], 0), coords(fv[0], 1), coords(fv[0], 2));
+        	vec3<T> c1(coords(fv[1], 0), coords(fv[1], 1), coords(fv[1], 2));
+	        vec3<T> c2(coords(fv[2], 0), coords(fv[2], 1), coords(fv[2], 2));
 
           //compute face normal
-          Vector<3, T> n = cross(c1 - c0, c2 - c0);
+          vec3<T> n = cross(c1 - c0, c2 - c0);
 
 	        // add the face's normal to its vertices
         		for (uint32_t v = 0; v < 3; ++v)     // for every vertex in this face
 	            for (uint32_t i = 0; i < 3; ++i)   // for the vertex 3 coordinates
         		        atomicAdd(&normals(fv[v], i), n[i]);          
 	    };
 
-	    //Query dispatcher must be called by all threads in the block. 
-	    //Dispatcher will first perform the query, store the results in shared memory, then 
-	    //run the user-defined computation i.e., compute_vn
-	    query_block_dispatcher<Op::FV, blockSize>(context, compute_vn);
+      //Query must be called by all threads in the block. Thus, we create this cooperative_group
+      //that uses all threads in the block and pass to the Query 
+      auto block = cooperative_groups::this_thread_block();
+      
+      Query<blockThreads> query(context);
+
+      //Qeury will first perform the query, store the results in shared memory. ShmemAllocator is 
+      //passed to the function to make sure we don't over-allocate or overwrite user-allocated shared
+      //memory 
+      ShmemAllocator shrd_alloc;
+
+      //Finally, we run the user-defined computation i.e., compute_vn
+      query.dispatch<Op::FV>(block, shrd_alloc, compute_vn);
     } 
     ```
-  To save computation, `query_block_dispatcher` could be run on a subset of the input mesh element i.e., _active set_. The user can define the active set using a lambda function that returns true if the input mesh element is in the active set. 
+  To save computation, `query.dispatch` could be run on a subset of the input mesh element i.e., _active set_. The user can define the active set using a lambda function that returns true if the input mesh element is in the active set. 
 
   - Example: defining active set
     ```cpp
@@ -194,11 +211,11 @@ The goal of defining a programming  model is to make it easy to write applicatio
         // ....         
 	    };
 
-	    auto computation = [&](FaceHandle face_id, VertexIterator& fv) {          
+	    auto computation = [&](const FaceHandle face_id, const VertexIterator& fv) {          
         // ....         
 	    };
 
-	    query_block_dispatcher<Op::FV, blockSize>(context, computation, active_set);
+	    query.dispatch<Op::FV, blockSize>(context, computation, active_set);
     } 
     ```
 
@@ -242,13 +259,10 @@ Starting v0.2.1, RXMesh integrates [Polyscope](https://polyscope.run) as a mesh
 > cd build 
 > cmake -DUSE_POLYSCOPE=True ../
 ``` 
-By default, the parameter is set to True on Windows and False on Linux machines. RXMesh implements the necessary functionalities to pass attributes to Polyscope—thanks to its [data adaptors](https://polyscope.run/data_adaptors/). However, this needs attributes to be moved to the host first before passing it to Polyscope. For more information about Polyscope's different visualization options, please checkout Polyscope's [Surface Mesh documentation](https://polyscope.run/structures/surface_mesh/basics/).
+By default, the parameter is set to True. RXMesh implements the necessary functionalities to pass attributes to Polyscope—thanks to its [data adaptors](https://polyscope.run/data_adaptors/). However, this needs attributes to be moved to the host first before passing it to Polyscope. For more information about Polyscope's different visualization options, please checkout Polyscope's [Surface Mesh documentation](https://polyscope.run/structures/surface_mesh/basics/).
 
   - Example: [render vertex color](./tests/Polyscope_test/test_polyscope.cu)      
     ```cpp
-    //initialize polyscope 
-    polyscope::init();
-    
     RXMeshStatic rx("dragon.obj");
 
     //vertex color attribute 
@@ -273,36 +287,62 @@ By default, the parameter is set to True on Windows and False on Linux machines.
     	<img src="./assets/polyscope_dragon.PNG" width="80%"><br>
     </p>    
 
+### **Matrices and Vectors**
+- **Large Matrices:** RXMesh has built-in support for large sparse and dense matrices built on top of [cuSparse](https://docs.nvidia.com/cuda/cusparse/) and [cuBlas](https://docs.nvidia.com/cuda/cublas/), respectively. For example, attributes can be converted to dense matrices as follows 
 
-## **Replicability**
-This repo was awarded the [replicability stamp](http://www.replicabilitystamp.org#https-github-com-owensgroup-rxmesh) by the Graphics Replicability Stamp Initiative (GRSI) :tada:
+```cpp
+
+RXMeshStatic rx("input.obj");
+
+//Input mesh coordinates as VertexAttribute
+std::shared_ptr<VertexAttribute<float>> x = rx.get_input_vertex_coordinates();
+
+//Convert the attributes to a (#vertices x 3) dense matrix 
+std::shared_ptr<DenseMatrix<float>> x_mat = x->to_matrix();
+
+//do something with x_mat
+//....
 
-The scripts used to generate the data shown in the paper can be found under
-* [Figure 6](https://github.com/owensgroup/RXMesh/blob/main/tests/RXMesh_test/benchmark.sh)
-* [Figure 8 (a)](https://github.com/owensgroup/RXMesh/blob/main/apps/MCF/benchmark.sh)
-* [Figure 8 (b)](https://github.com/owensgroup/RXMesh/blob/main/apps/Geodesic/benchmark.sh)
-* [Figure 8 (c)](https://github.com/owensgroup/RXMesh/blob/main/apps/Filtering/benchmark.sh)
-* [Figure 8 (d)](https://github.com/owensgroup/RXMesh/blob/main/apps/VertexNormal/benchmark.sh)
+//Populate the VertexAttribute coordinates back with the content of the dense matrix
+x->from_matrix(x_mat.get());
 
-Each script should be run from the script's containing directory after compiling the code in the `build/` directory. The only input parameter needed is the path to the input OBJ files. The resulting JSON files will be written to the `output/` directory. 
+```
+Dense matrices can be accessed using the usual row and column indices or via the mesh element handle (Vertex/Edge/FaceHandle) as a row index. This allows for easy access to the correct row associated with a specific vertex, edge, or face. Dense matrices support various operations such as absolute sum, AXPY, dot products, norm2, scaling, and swapping.
+
+RXMesh supports sparse matrices, where the sparsity pattern matches the query operations. For example, it is often necessary to build a sparse matrix of size #V x #V with non-zero values at (i, j) only if the vertex corresponding to row i is connected by an edge to the vertex corresponding to column j. Currently, we only support the VV sparsity pattern, but we are working on expanding to all other types of queries.
+
+The sparse matrix can be used to solve a linear system via Cholesky, LU, or QR factorization (relying on [cuSolver](https://docs.nvidia.com/cuda/cusolver/index.html))). The solver offers two APIs. The high-level API reorders the input sparse matrix (to reduce non-zero fill-in after matrix factorization) and allocates the additional memory needed to solve the system. Repeated calls to this API will reorder the matrix and allocate/deallocate the temporary memory with each call. For scenarios where the matrix remains unchanged but multiple right-hand sides need to be solved, users can utilize the low-level API, which splits the solve method into pre_solve() and solve(). The former reorders the matrix and allocates temporary memory only once. The low-level API is currently only supported for Cholesky-based factorization. Check out the MCF application for an example of how to set up and use the solver.
+
+Similar to dense matrices, sparse matrices also support accessing the matrix using the VertexHandle and multiplication by dense matrices.
+
+- **Small Matrices:**
+It is often necessary to perform operations on small matrices as part of geometry processing applications, such as computing the SVD of a 3x3 matrix or normalizing a 1x3 vector. For this purpose, RXMesh attributes can be converted into glm or Eigen matrices, as demonstrated in the vertex_normal example above. Both glm and Eigen support small matrix operations inside the GPU kernel.
+
+
+
+## **Replicability**
+This repo was awarded the [replicability stamp](http://www.replicabilitystamp.org#https-github-com-owensgroup-rxmesh) by the Graphics Replicability Stamp Initiative (GRSI) :tada:. Visit git tag [`v0.1.0`](https://github.com/owensgroup/RXMesh/tree/v0.1.0) for more information about replicability scripts.
 
 ## **Bibtex**
 ```
 @article{Mahmoud:2021:RAG,
-  author = {Mahmoud, Ahmed H. and Porumbescu, Serban D. and Owens, John D.},
-  title = {{RXM}esh: A {GPU} Mesh Data Structure},
-  journal = {ACM Transactions on Graphics},
-  year = 2021,
-  volume = 40,
-  number = 4,
-  month = aug,
-  issue_date = {August 2021},
-  articleno = 104,
-  numpages = 16,
-  pages = {104:1--104:16},
-  url = {https://escholarship.org/uc/item/8r5848vp},
-  full_talk = {https://youtu.be/Se_cNAol4hY},
-  short_talk = {https://youtu.be/V_SHMXnCVws},
-  doi = {10.1145/3450626.3459748}
+  author       = {Ahmed H. Mahmoud and Serban D. Porumbescu and John D. Owens},
+  title        = {{RXM}esh: A {GPU} Mesh Data Structure},
+  journal      = {ACM Transactions on Graphics},
+  year         = 2021,
+  volume       = 40,
+  number       = 4,
+  month        = aug,
+  issue_date   = {August 2021},
+  articleno    = 104,
+  numpages     = 16,
+  pages        = {104:1--104:16},
+  url          = {https://escholarship.org/uc/item/8r5848vp},
+  full_talk    = {https://youtu.be/Se_cNAol4hY},
+  short_talk   = {https://youtu.be/V_SHMXnCVws},
+  doi          = {10.1145/3450626.3459748},
+  acmauthorize = {https://dl.acm.org/doi/10.1145/3450626.3459748?cid=81100458295},
+  acceptance   = {149/444 (33.6\%)},
+  ucdcite      = {a140}
 }
 ```

apps/ARAP/CMakeLists.txt

@@ -0,0 +1,22 @@
+add_executable(ARAP)
+
+set(SOURCE_LIST
+    arap.cu	
+)
+
+target_sources(ARAP 
+    PRIVATE
+    ${SOURCE_LIST}
+)
+
+set_target_properties(ARAP PROPERTIES FOLDER "apps")
+
+set_property(TARGET ARAP PROPERTY CUDA_SEPARABLE_COMPILATION ON)
+
+source_group(TREE ${CMAKE_CURRENT_LIST_DIR} PREFIX "ARAP" FILES ${SOURCE_LIST})
+
+target_link_libraries(ARAP     
+    PRIVATE RXMesh
+)
+
+#gtest_discover_tests( ARAP )