Add documentation

Author: mscroggs

src/grid/common.rs

@@ -4,6 +4,7 @@ use crate::grid::traits::Geometry;
 use rlst_common::types::Scalar;
 use rlst_dense::traits::{Shape, UnsafeRandomAccessByRef};
 
+/// Compute a physical point
 pub fn compute_point<T: Scalar, Table: UnsafeRandomAccessByRef<4, Item = T> + Shape<4>>(
     geometry: &impl Geometry<T = T>,
     table: Table,
@@ -26,6 +27,7 @@ pub fn compute_point<T: Scalar, Table: UnsafeRandomAccessByRef<4, Item = T> + Sh
     }
 }
 
+/// Compute a Jacobian
 pub fn compute_jacobian<T: Scalar, Table: UnsafeRandomAccessByRef<4, Item = T> + Shape<4>>(
     geometry: &impl Geometry<T = T>,
     table: Table,
@@ -52,6 +54,7 @@ pub fn compute_jacobian<T: Scalar, Table: UnsafeRandomAccessByRef<4, Item = T> +
     }
 }
 
+/// Compute a normal from a Jacobian of a cell with topological dimension 2 and geometric dimension 3
 pub fn compute_normal_from_jacobian23<T: Scalar>(jacobian: &[T], normal: &mut [T]) {
     assert_eq!(jacobian.len(), 6);
     assert_eq!(normal.len(), 3);

src/grid/flat_triangle_grid.rs

@@ -1,3 +1,7 @@
+//! A flat triangle grid
+//!
+//! In this grid, every cell is a flat triangle
+
 mod builder;
 mod grid;
 

src/grid/flat_triangle_grid/builder.rs

@@ -13,6 +13,7 @@ use rlst_dense::{
 };
 use std::collections::HashMap;
 
+/// Grid builder for a flat triangle grid
 pub struct SerialFlatTriangleGridBuilder<T: Float + Scalar<Real = T>> {
     points: Vec<T>,
     cells: Vec<usize>,

src/grid/flat_triangle_grid/grid.rs

@@ -1,4 +1,4 @@
-//! Serial implementation of a grid
+//! Flat triangle grid
 
 use crate::grid::traits::Ownership;
 use crate::grid::traits::{Geometry, GeometryEvaluator, Grid, Topology};
@@ -22,10 +22,11 @@ use rlst_dense::{
 use rlst_proc_macro::rlst_static_type;
 use std::collections::HashMap;
 
-/// A serial grid
+/// A flat triangle grid
 pub struct SerialFlatTriangleGrid<T: Float + Scalar<Real = T>> {
     index_map: Vec<usize>,
 
+    // Geometry information
     pub(crate) coordinates: Array<T, BaseArray<T, VectorContainer<T>, 2>, 2>,
     pub(crate) element: CiarletElement<T>,
     midpoints: Vec<rlst_static_type!(T, 3)>,
@@ -35,11 +36,13 @@ pub struct SerialFlatTriangleGrid<T: Float + Scalar<Real = T>> {
     pub(crate) jacobians: Vec<rlst_static_type!(T, 3, 2)>,
     cell_indices: Vec<usize>,
 
+    // Topology information
     entities_to_vertices: Vec<Vec<Vec<usize>>>,
     pub(crate) cells_to_entities: Vec<Vec<Vec<usize>>>,
     entities_to_cells: Vec<Vec<Vec<CellLocalIndexPair<usize>>>>,
     entity_types: Vec<ReferenceCellType>,
 
+    // Point and cell ids
     point_indices_to_ids: Vec<usize>,
     point_ids_to_indices: HashMap<usize, usize>,
     cell_indices_to_ids: Vec<usize>,
@@ -50,6 +53,7 @@ impl<T: Float + Scalar<Real = T>> SerialFlatTriangleGrid<T>
 where
     for<'a> Array<T, ArrayViewMut<'a, T, BaseArray<T, VectorContainer<T>, 2>, 2>, 2>: MatrixInverse,
 {
+    /// Create a flat triangle grid
     pub fn new(
         coordinates: Array<T, BaseArray<T, VectorContainer<T>, 2>, 2>,
         cells: &[usize],
@@ -182,8 +186,6 @@ where
 
         Self {
             index_map,
-
-            // Geometry
             coordinates,
             element,
             midpoints,
@@ -192,14 +194,10 @@ where
             normals,
             jacobians,
             cell_indices,
-
-            // Topology
             entities_to_vertices,
             cells_to_entities,
             entities_to_cells,
             entity_types,
-
-            // ids
             point_indices_to_ids,
             point_ids_to_indices,
             cell_indices_to_ids,
@@ -315,12 +313,14 @@ impl<T: Float + Scalar<Real = T>> Geometry for SerialFlatTriangleGrid<T> {
     }
 }
 
+/// Geometry evaluator for a flat triangle grid
 pub struct GeometryEvaluatorFlatTriangle<'a, T: Float + Scalar<Real = T>> {
     grid: &'a SerialFlatTriangleGrid<T>,
     points: SliceArray<'a, T, 2>,
 }
 
 impl<'a, T: Float + Scalar<Real = T>> GeometryEvaluatorFlatTriangle<'a, T> {
+    /// Create a geometry evaluator
     fn new(grid: &'a SerialFlatTriangleGrid<T>, points: &'a [T]) -> Self {
         let tdim = reference_cell::dim(grid.element.cell_type());
         assert_eq!(points.len() % tdim, 0);
@@ -459,6 +459,7 @@ mod test {
     };
 
     fn example_grid_flat() -> SerialFlatTriangleGrid<f64> {
+        //! Create a flat test grid
         let mut points = rlst_dynamic_array2!(f64, [4, 3]);
         points[[0, 0]] = 0.0;
         points[[0, 1]] = 0.0;
@@ -484,6 +485,7 @@ mod test {
     }
 
     fn example_grid_3d() -> SerialFlatTriangleGrid<f64> {
+        //! Create a non-flat test grid
         let mut points = rlst_dynamic_array2!(f64, [4, 3]);
         points[[0, 0]] = 0.0;
         points[[0, 1]] = 0.0;
@@ -508,8 +510,19 @@ mod test {
         )
     }
 
+    fn triangle_points() -> Array<f64, BaseArray<f64, VectorContainer<f64>, 2>, 2> {
+        //! Create a set of points inside the reference triangle
+        let mut points = rlst_dynamic_array2!(f64, [2, 2]);
+        *points.get_mut([0, 0]).unwrap() = 0.2;
+        *points.get_mut([0, 1]).unwrap() = 0.5;
+        *points.get_mut([1, 0]).unwrap() = 0.6;
+        *points.get_mut([1, 1]).unwrap() = 0.1;
+        points
+    }
+
     #[test]
     fn test_cell_points() {
+        //! Test that the cell points are correct
         let g = example_grid_flat();
         for (cell_i, points) in [
             vec![
@@ -539,17 +552,9 @@ mod test {
         }
     }
 
-    fn triangle_points() -> Array<f64, BaseArray<f64, VectorContainer<f64>, 2>, 2> {
-        let mut points = rlst_dynamic_array2!(f64, [2, 2]);
-        *points.get_mut([0, 0]).unwrap() = 0.2;
-        *points.get_mut([0, 1]).unwrap() = 0.5;
-        *points.get_mut([1, 0]).unwrap() = 0.6;
-        *points.get_mut([1, 1]).unwrap() = 0.1;
-        points
-    }
-
     #[test]
     fn test_compute_point_flat() {
+        //! Test the compute_point function of an evaluator
         let g = example_grid_flat();
         let points = triangle_points();
 
@@ -573,6 +578,7 @@ mod test {
 
     #[test]
     fn test_compute_point_3d() {
+        //! Test the compute_point function of an evaluator
         let g = example_grid_3d();
         let points = triangle_points();
         let evaluator = g.get_evaluator(points.data());
@@ -596,6 +602,7 @@ mod test {
 
     #[test]
     fn test_compute_jacobian_3d() {
+        //! Test the compute_jacobian function of an evaluator
         let g = example_grid_3d();
         let points = triangle_points();
         let evaluator = g.get_evaluator(points.data());
@@ -624,6 +631,7 @@ mod test {
     }
     #[test]
     fn test_compute_normal_3d() {
+        //! Test the compute_normal function of an evaluator
         let g = example_grid_3d();
         let points = triangle_points();
         let evaluator = g.get_evaluator(points.data());
@@ -658,6 +666,7 @@ mod test {
 
     #[test]
     fn test_midpoint_flat() {
+        //! Test midpoints
         let g = example_grid_flat();
 
         let mut midpoint = vec![0.0; 3];
@@ -677,6 +686,7 @@ mod test {
 
     #[test]
     fn test_midpoint_3d() {
+        //! Test midpoints
         let g = example_grid_3d();
 
         let mut midpoint = vec![0.0; 3];
@@ -696,6 +706,7 @@ mod test {
 
     #[test]
     fn test_counts() {
+        //! Test the entity counts
         let g = example_grid_flat();
         assert_eq!(Topology::dim(&g), 2);
         assert_eq!(Geometry::dim(&g), 3);
@@ -708,7 +719,8 @@ mod test {
     }
 
     #[test]
-    fn test_cell_entities_points() {
+    fn test_cell_entities_vertices() {
+        //! Test the cell vertices
         let t = example_grid_3d();
         for (i, vertices) in [[0, 1, 2], [0, 2, 3]].iter().enumerate() {
             let c = t.cell_to_entities(i, 0).unwrap();
@@ -718,7 +730,8 @@ mod test {
     }
 
     #[test]
-    fn test_cell_entities_intervals() {
+    fn test_cell_entities_edges() {
+        //! Test the cell edges
         let t = example_grid_3d();
         for (i, edges) in [[0, 1, 2], [3, 4, 1]].iter().enumerate() {
             let c = t.cell_to_entities(i, 1).unwrap();
@@ -728,7 +741,8 @@ mod test {
     }
 
     #[test]
-    fn test_cell_entities_triangles() {
+    fn test_cell_entities_cells() {
+        //! Test the cells
         let t = example_grid_3d();
         for i in 0..2 {
             let c = t.cell_to_entities(i, 2).unwrap();
@@ -738,7 +752,8 @@ mod test {
     }
 
     #[test]
-    fn test_entities_to_cells_points() {
+    fn test_entities_to_cells_vertices() {
+        //! Test the cell-to-vertex connectivity
         let t = example_grid_3d();
         let c_to_e = (0..t.entity_count(ReferenceCellType::Triangle))
             .map(|i| t.cell_to_entities(i, 0).unwrap())
@@ -767,6 +782,7 @@ mod test {
 
     #[test]
     fn test_entities_to_cells_edges() {
+        //! Test the cell-to-edge connectivity
         let t = example_grid_3d();
         let c_to_e = (0..t.entity_count(ReferenceCellType::Triangle))
             .map(|i| t.cell_to_entities(i, 1).unwrap())

src/grid/mixed_grid.rs

@@ -1,3 +1,7 @@
+//! A mixed grid
+//!
+//! In this grid, cells can be of any type, and the grid may contain multiple cell types
+
 mod builder;
 mod geometry;
 mod grid;

src/grid/mixed_grid/builder.rs

@@ -16,6 +16,7 @@ use rlst_dense::{
 };
 use std::collections::HashMap;
 
+/// Grid builder for a mixed grid
 pub struct SerialMixedGridBuilder<const GDIM: usize, T: Float + Scalar<Real = T>> {
     elements_to_npoints: HashMap<(ReferenceCellType, usize), usize>,
     points: Vec<T>,

src/grid/mixed_grid/geometry.rs

@@ -36,6 +36,7 @@ pub struct SerialMixedGeometry<T: Float + Scalar> {
 unsafe impl<T: Float + Scalar> Sync for SerialMixedGeometry<T> {}
 
 impl<T: Float + Scalar> SerialMixedGeometry<T> {
+    /// Create a geometry
     pub fn new(
         coordinates: Array<T, BaseArray<T, VectorContainer<T>, 2>, 2>,
         cells_input: &[usize],
@@ -225,13 +226,15 @@ impl<T: Float + Scalar> Geometry for SerialMixedGeometry<T> {
     }
 }
 
+/// Geometry evaluator for a mixed grid
 pub struct GeometryEvaluatorMixed<'a, T: Float + Scalar> {
     geometry: &'a SerialMixedGeometry<T>,
     tdim: usize,
     tables: Vec<Array<T, BaseArray<T, VectorContainer<T>, 4>, 4>>,
 }
 
 impl<'a, T: Float + Scalar> GeometryEvaluatorMixed<'a, T> {
+    /// Create a geometry evaluator
     fn new(geometry: &'a SerialMixedGeometry<T>, points: &'a [T]) -> Self {
         let tdim = reference_cell::dim(geometry.elements[0].cell_type());
         assert_eq!(points.len() % tdim, 0);
@@ -304,6 +307,7 @@ mod test {
     use rlst_dense::{rlst_dynamic_array2, traits::RandomAccessMut};
 
     fn example_geometry() -> SerialMixedGeometry<f64> {
+        //! A geometry with a single cell type
         let p1triangle = create_element(
             ElementFamily::Lagrange,
             bempp_element::cell::ReferenceCellType::Triangle,
@@ -331,6 +335,7 @@ mod test {
     }
 
     fn example_geometry_mixed() -> SerialMixedGeometry<f64> {
+        //! A geometry with a mixture of cell types
         let p1triangle = create_element(
             ElementFamily::Lagrange,
             bempp_element::cell::ReferenceCellType::Triangle,
@@ -367,13 +372,15 @@ mod test {
 
     #[test]
     fn test_counts() {
+        //! Test the point and cell counts
         let g = example_geometry();
         assert_eq!(g.point_count(), 4);
         assert_eq!(g.cell_count(), 2);
     }
 
     #[test]
     fn test_cell_points() {
+        //! Test the cell points
         let g = example_geometry();
         for (cell_i, points) in [
             vec![vec![0.0, 0.0], vec![1.0, 0.0], vec![1.0, 1.0]],
@@ -397,13 +404,15 @@ mod test {
 
     #[test]
     fn test_counts_mixed() {
+        //! Test the point and cell counts
         let g = example_geometry_mixed();
         assert_eq!(g.point_count(), 5);
         assert_eq!(g.cell_count(), 2);
     }
 
     #[test]
     fn test_cell_points_mixed() {
+        //! Test the cell points
         let g = example_geometry_mixed();
         for (cell_i, points) in [
             (
@@ -432,6 +441,7 @@ mod test {
 
     #[test]
     fn test_midpoint() {
+        //! Test midpoints
         let g = example_geometry();
 
         let mut midpoint = vec![0.0; 2];
@@ -448,6 +458,7 @@ mod test {
 
     #[test]
     fn test_midpoint_mixed() {
+        //! Test midpoints
         let g = example_geometry_mixed();
 
         let mut midpoint = vec![0.0; 2];

src/grid/mixed_grid/grid.rs

@@ -1,4 +1,4 @@
-//! Serial implementation of a grid
+//! Mixed grid
 
 use crate::grid::mixed_grid::{geometry::SerialMixedGeometry, topology::SerialMixedTopology};
 use crate::grid::traits::Grid;
@@ -17,7 +17,7 @@ use rlst_dense::{
 };
 use std::collections::HashMap;
 
-/// A serial grid
+/// A mixed grid
 pub struct SerialMixedGrid<T: Float + Scalar> {
     topology: SerialMixedTopology,
     geometry: SerialMixedGeometry<T>,
@@ -27,6 +27,7 @@ impl<T: Float + Scalar> SerialMixedGrid<T>
 where
     for<'a> Array<T, ArrayViewMut<'a, T, BaseArray<T, VectorContainer<T>, 2>, 2>, 2>: MatrixInverse,
 {
+    /// Create a mixed grid
     pub fn new(
         points: Array<T, BaseArray<T, VectorContainer<T>, 2>, 2>,
         cells: &[usize],