remove old code and add docstrings

vis/include/geometry.hpp

@@ -7,25 +7,10 @@
 #include <iostream>
 #include "combo_iterator.hpp"
 
-size_t get_key_from_gens(std::vector<int> &gens) {
-    size_t key = 0;
-    for (const auto gen : gens) {
-        key += (1u << (unsigned) gen);
-    }
-    return key;
-}
-
-size_t num_gens_from_key(size_t key) {
-    size_t mask = 1;
-    size_t count = 0;
-    while (mask <= key) {
-        if (key & mask)
-            count++;
-        mask <<= 1u;
-    }
-    return count;
-}
-
+/**
+ * An primitive with N indices.
+ * @tparam N
+ */
 template<unsigned N>
 struct Primitive {
     std::array<unsigned, N> inds;
@@ -53,12 +38,18 @@ struct Primitive {
     }
 };
 
+/**
+ * Produce a list of all generators for the group context. The range [0..group.ngens).
+ */
 std::vector<int> gens(const tc::Group &context) {
     std::vector<int> g_gens(context.ngens);
     std::iota(g_gens.begin(), g_gens.end(), 0);
     return g_gens;
 }
 
+/**
+ * Determine which of g_gens are the correct names for sg_gens within the current context
+ */
 std::vector<int> recontext_gens(
     const tc::Group &context,
     std::vector<int> g_gens,
@@ -79,24 +70,11 @@ std::vector<int> recontext_gens(
     std::sort(s_sg_gens.begin(), s_sg_gens.end());
 
     return s_sg_gens;
-
-//    std::sort(g_gens.begin(), g_gens.end());
-//
-//    std::vector<int> inv_g_map(g_gens.size());
-//    for (int i = 0; i < g_gens.size(); ++i) {
-//        inv_g_map[g_gens[i]] = i;
-//    }
-//
-//    std::transform(sg_gens.begin(), sg_gens.end(), sg_gens.begin(),
-//        [inv_g_map](const auto &gen) {
-//            return inv_g_map[gen];
-//        }
-//    );
-//
-//    std::sort(sg_gens.begin(), sg_gens.end());
-//    return sg_gens;
 }
 
+/**
+ * Determine whether the orientation of the group sg_gens is reversed from the group g_gens within group context
+ */
 int get_parity(
     const tc::Group &context,
     const std::vector<int> &g_gens,
@@ -116,6 +94,9 @@ int get_parity(
     return i & 1;
 }
 
+/**
+ * Solve the cosets generated by sg_gens within the subgroup generated by g_gens of the group context
+ */
 tc::Cosets solve(
     const tc::Group &context,
     const std::vector<int> &g_gens,
@@ -125,28 +106,6 @@ tc::Cosets solve(
     return context.subgroup(g_gens).solve(proper_sg_gens);
 }
 
-tc::Cosets solve_sg(
-    const tc::Group &context,
-    const std::vector<int> &sg_gens
-) {
-    return solve(context, gens(context), sg_gens);
-}
-
-tc::Cosets solve_g(
-    const tc::Group &context,
-    const std::vector<int> &g_gens
-) {
-    std::vector<int> sg_gens;
-    return solve(context, g_gens, sg_gens);
-}
-
-tc::Cosets solve(
-    const tc::Group &context
-) {
-    std::vector<int> sg_gens;
-    return solve_sg(context, sg_gens);
-}
-
 template<unsigned N>
 struct Mesh {
     std::vector<Primitive<N>> prims;
@@ -161,18 +120,27 @@ struct Mesh {
         return prims.size();
     }
 
+    /**
+     * Apply some context transformation to all primitives of this mesh.
+     */
     void apply(const tc::Cosets &table, int gen) {
         for (auto &prim : prims) {
             prim.apply(table, gen);
         }
     }
 
+    /**
+     * Reverse the orientation of all primitives in this mesh.
+     */
     void flip() {
         for (auto &prim : prims) {
             prim.flip();
         }
     }
 
+    /**
+     * Convert the indexes of this mesh to those of a different context, using g_gens to build the parent context and sg_gens to build this context.
+     */
     [[nodiscard]]
     Mesh<N> recontext(
         const tc::Group &context,
@@ -180,8 +148,8 @@ struct Mesh {
         const std::vector<int> &sg_gens
     ) const {
         const auto proper_sg_gens = recontext_gens(context, g_gens, sg_gens);
-        const auto table = solve_g(context, g_gens);
-        const auto path = solve_g(context, sg_gens).path;
+        const auto table = solve(context, g_gens, {});
+        const auto path = solve(context, sg_gens, {}).path;
 
         auto map = path.template walk<int, int>(0, proper_sg_gens, [table](int coset, int gen) {
             return table.get(coset, gen);
@@ -209,7 +177,7 @@ struct Mesh {
         Mesh<N> base = recontext(context, g_gens, sg_gens);
         const auto proper_sg_gens = recontext_gens(context, g_gens, sg_gens);
 
-        const auto table = solve_g(context, g_gens);
+        const auto table = solve(context, g_gens, {});
         const auto path = solve(context, g_gens, sg_gens).path;
 
         const auto all = path.template walk<Mesh<N>, int>(base, gens(context), [table](Mesh<N> from, int gen) {
@@ -220,6 +188,9 @@ struct Mesh {
         return merge(all);
     }
 
+    /**
+     * Produce a mesh of higher dimension by fanning a single point to all primitives in this mesh.
+     */
     [[nodiscard]]
     Mesh<N + 1> fan(int root) const {
         std::vector<Primitive<N + 1>> res(prims.size());
@@ -232,6 +203,9 @@ struct Mesh {
     }
 };
 
+/**
+ * Union several meshes of the same dimension
+ */
 template<unsigned N>
 Mesh<N> merge(const std::vector<Mesh<N>> &meshes) {
     size_t size = 0;
@@ -248,6 +222,9 @@ Mesh<N> merge(const std::vector<Mesh<N>> &meshes) {
     return Mesh(prims);
 }
 
+/**
+ * Produce a mesh of primitives that fill out the volume of the subgroup generated by generators g_gens within the group context
+ */
 template<unsigned N>
 Mesh<N> triangulate(
     const tc::Group &context,