Add utility functions for mapping between sparse matrix patterns.

PiperOrigin-RevId: 795543910
Change-Id: I92be3afc3cd90020027737fffdba18c45e25f825

src/engine/engine_util_misc.h

@@ -166,6 +166,9 @@ MJAPI void mju_n2d(double* res, const mjtNum* vec, int n);
 // gather mjtNums
 MJAPI void mju_gather(mjtNum* res, const mjtNum* vec, const int* ind, int n);
 
+// gather mjtNums, set to 0 at negative indices
+MJAPI void mju_gatherMasked(mjtNum* res, const mjtNum* vec, const int* ind, int n);
+
 // scatter mjtNums
 MJAPI void mju_scatter(mjtNum* res, const mjtNum* vec, const int* ind, int n);
 
@@ -175,6 +178,18 @@ MJAPI void mju_gatherInt(int* res, const int* vec, const int* ind, int n);
 // scatter integers
 MJAPI void mju_scatterInt(int* res, const int* vec, const int* ind, int n);
 
+// build gather indices mapping src to res, assumes pattern(res) \subseteq pattern(src)
+MJAPI void mju_sparseMap(int* map, int nr,
+                         const int* res_rowadr, const int* res_rownnz, const int* res_colind,
+                         const int* src_rowadr, const int* src_rownnz, const int* src_colind);
+
+// build masked-gather map to copy a lower-triangular src into symmetric res
+//  `cursor` is a preallocated buffer of size `nr`
+MJAPI void mju_lower2SymMap(int* map, int nr,
+                            const int* res_rowadr, const int* res_rownnz, const int* res_colind,
+                            const int* src_rowadr, const int* src_rownnz, const int* src_colind,
+                            int* cursor);
+
 // insertion sort, increasing order
 MJAPI void mju_insertionSort(mjtNum* list, int n);