Update docs

traits/src/kernel.rs

@@ -22,7 +22,7 @@ pub trait Kernel {
     ///           for each target in consecutive order the value of the kernel and the three components
     ///           of its derivative.
     ///
-    /// The following code gives an example of how to use it together with the [rlst] dense matrix type.
+    /// The following code gives an example of how to use it together with the `rlst` dense matrix type.
     /// ```
     /// use rlst::dense::*;
     /// use bempp_kernel::traits::*;
@@ -52,7 +52,7 @@ pub trait Kernel {
 
     /// Multi-threaded evaluation of a Green's function kernel.
     ///
-    /// The method parallelizes over the given targets. It expects a Rayon [ThreadPool]
+    /// The method parallelizes over the given targets. It expects a Rayon `ThreadPool`
     /// in which the multi-threaded execution can be scheduled.
     fn evaluate_mt(
         &self,
@@ -77,7 +77,7 @@ pub trait Kernel {
     ///           in consecutive order the interaction of all sources with the first target and then the corresponding derivatives,
     ///           followed by the interactions with the second target, and so on. See the example for illustration.
     ///
-    /// The following code gives an example of how to use it together with the [rlst] dense matrix type.
+    /// The following code gives an example of how to use it together with the `rlst` dense matrix type.
     /// ```
     /// use rlst::dense::*;
     /// use bempp_kernel::traits::*;

tree/src/constants.rs

@@ -2,21 +2,28 @@
 
 use crate::types::morton::{KeyType, MortonKey};
 
+/// Default value chosen for subcommunicator size in Hyksort, must be a power of 2.
 pub const K: i32 = 2;
 
+/// Default value chosen for maximum number of particles per leaf in adaptive trees.
 pub const NCRIT: u64 = 150;
 
+/// Maximum possible level of octree recursion, by definition.
 pub const DEEPEST_LEVEL: KeyType = 16;
 
+/// The default level of recursion chosen in adaptive octrees.
 pub const DEFAULT_LEVEL: KeyType = 3;
 
+/// The 'size' of each level in terms of octants along each axis, at the maximum depth of recursion.
 pub const LEVEL_SIZE: KeyType = 65536;
 
+/// The root node of any octree.
 pub const ROOT: MortonKey = MortonKey {
     anchor: [0, 0, 0],
     morton: 0,
 };
 
+/// Transfer vectors in component form to nearest octant neighbours.
 pub const DIRECTIONS: [[i64; 3]; 26] = [
     [-1, -1, -1],
     [-1, -1, 0],
@@ -46,6 +53,7 @@ pub const DIRECTIONS: [[i64; 3]; 26] = [
     [1, 1, 1],
 ];
 
+/// Lookup tables for encoding 'z' position in a Morton encoding from Cartesian coordinates.
 pub const Z_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00000000, 0x00000001, 0x00000008, 0x00000009, 0x00000040, 0x00000041, 0x00000048, 0x00000049,
     0x00000200, 0x00000201, 0x00000208, 0x00000209, 0x00000240, 0x00000241, 0x00000248, 0x00000249,
@@ -81,6 +89,7 @@ pub const Z_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00249200, 0x00249201, 0x00249208, 0x00249209, 0x00249240, 0x00249241, 0x00249248, 0x00249249,
 ];
 
+/// Lookup tables for encoding 'y' position in a Morton encoding from Cartesian coordinates.
 pub const Y_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00000000, 0x00000002, 0x00000010, 0x00000012, 0x00000080, 0x00000082, 0x00000090, 0x00000092,
     0x00000400, 0x00000402, 0x00000410, 0x00000412, 0x00000480, 0x00000482, 0x00000490, 0x00000492,
@@ -116,6 +125,7 @@ pub const Y_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00492400, 0x00492402, 0x00492410, 0x00492412, 0x00492480, 0x00492482, 0x00492490, 0x00492492,
 ];
 
+/// Lookup tables for encoding 'x' position in a Morton encoding from Cartesian coordinates.
 pub const X_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00000000, 0x00000004, 0x00000020, 0x00000024, 0x00000100, 0x00000104, 0x00000120, 0x00000124,
     0x00000800, 0x00000804, 0x00000820, 0x00000824, 0x00000900, 0x00000904, 0x00000920, 0x00000924,
@@ -151,6 +161,7 @@ pub const X_LOOKUP_ENCODE: [KeyType; 256] = [
     0x00924800, 0x00924804, 0x00924820, 0x00924824, 0x00924900, 0x00924904, 0x00924920, 0x00924924,
 ];
 
+/// Lookup tables for decoding 'z' position in a Morton encoding from Cartesian coordinates.
 pub const Z_LOOKUP_DECODE: [KeyType; 512] = [
     0, 1, 0, 1, 0, 1, 0, 1, 2, 3, 2, 3, 2, 3, 2, 3, 0, 1, 0, 1, 0, 1, 0, 1, 2, 3, 2, 3, 2, 3, 2, 3,
     0, 1, 0, 1, 0, 1, 0, 1, 2, 3, 2, 3, 2, 3, 2, 3, 0, 1, 0, 1, 0, 1, 0, 1, 2, 3, 2, 3, 2, 3, 2, 3,
@@ -170,6 +181,7 @@ pub const Z_LOOKUP_DECODE: [KeyType; 512] = [
     4, 5, 4, 5, 4, 5, 4, 5, 6, 7, 6, 7, 6, 7, 6, 7, 4, 5, 4, 5, 4, 5, 4, 5, 6, 7, 6, 7, 6, 7, 6, 7,
 ];
 
+/// Lookup tables for decoding 'y' position in a Morton encoding from Cartesian coordinates.
 pub const Y_LOOKUP_DECODE: [KeyType; 512] = [
     0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 2, 2, 3, 3, 2, 2, 3, 3, 2, 2, 3, 3, 2, 2, 3, 3,
     0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 2, 2, 3, 3, 2, 2, 3, 3, 2, 2, 3, 3, 2, 2, 3, 3,
@@ -189,6 +201,7 @@ pub const Y_LOOKUP_DECODE: [KeyType; 512] = [
     4, 4, 5, 5, 4, 4, 5, 5, 4, 4, 5, 5, 4, 4, 5, 5, 6, 6, 7, 7, 6, 6, 7, 7, 6, 6, 7, 7, 6, 6, 7, 7,
 ];
 
+/// Lookup tables for decoding 'x' position in a Morton encoding from Cartesian coordinates.
 pub const X_LOOKUP_DECODE: [KeyType; 512] = [
     0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1,
     2, 2, 2, 2, 3, 3, 3, 3, 2, 2, 2, 2, 3, 3, 3, 3, 2, 2, 2, 2, 3, 3, 3, 3, 2, 2, 2, 2, 3, 3, 3, 3,
@@ -208,15 +221,17 @@ pub const X_LOOKUP_DECODE: [KeyType; 512] = [
     6, 6, 6, 6, 7, 7, 7, 7, 6, 6, 6, 6, 7, 7, 7, 7, 6, 6, 6, 6, 7, 7, 7, 7, 6, 6, 6, 6, 7, 7, 7, 7,
 ];
 
-// Number of bits used for Level information.
+/// Number of bits used for Level information.
 pub const LEVEL_DISPLACEMENT: usize = 15;
 
-// Mask for the last 15 bits.
+/// Mask for the last 15 bits.
 pub const LEVEL_MASK: KeyType = 0x7FFF;
 
-// Mask for lowest order byte.
+/// Mask for lowest order byte.
 pub const BYTE_MASK: KeyType = 0xFF;
+
+/// Number of bits in a byte.
 pub const BYTE_DISPLACEMENT: KeyType = 8;
 
-// Mask encapsulating a bit.
+/// Mask encapsulating a bit.
 pub const NINE_BIT_MASK: KeyType = 0x1FF;

tree/src/implementations/helpers.rs

@@ -1,3 +1,6 @@
+//! Helper functions used in testing tree implementations, specifically test point generators, 
+//! as well as helpers for handling surfaces that discretise a box corresponding to a Morton key.
+
 use std::collections::HashMap;
 
 use rand::prelude::*;
@@ -7,6 +10,7 @@ use rlst::dense::{base_matrix::BaseMatrix, rlst_mat, Dynamic, Matrix, VectorCont
 
 use crate::types::morton::MortonKey;
 
+/// Alias for an rlst container for point data.
 pub type PointsMat =
     Matrix<f64, BaseMatrix<f64, VectorContainer<f64>, Dynamic, Dynamic>, Dynamic, Dynamic>;
 
@@ -38,7 +42,7 @@ pub fn points_fixture(npoints: usize, min: Option<f64>, max: Option<f64>) -> Poi
     points
 }
 
-//. Points fixture for testing, uniformly samples in the bounds [[0, 1), [0, 1), [0, 500)] for the x, y, and z
+///. Points fixture for testing, uniformly samples in the bounds [[0, 1), [0, 1), [0, 500)] for the x, y, and z
 /// axes respectively.
 ///
 /// # Arguments
@@ -66,7 +70,7 @@ pub fn points_fixture_col(npoints: usize) -> PointsMat {
 /// are expected in column major order [x_1, x_2...x_N, y_1, y_2....y_N, z_1, z_2...z_N]
 ///
 /// # Arguements:
-/// * `coordinates`
+/// * `coordinates` - points on the surface of a box.
 pub fn find_corners(coordinates: &[f64]) -> Vec<f64> {
     let n = coordinates.len() / 3;
 

tree/src/implementations/impl_domain.rs

@@ -1,3 +1,4 @@
+//! Constructor for a single node Domain.
 use crate::types::{domain::Domain, point::PointType};
 
 impl Domain {

tree/src/implementations/impl_domain_mpi.rs

@@ -1,3 +1,4 @@
+//! Implementation of an equivalent MPI type for a Domain object, and constructor for distributed Domains.
 use memoffset::offset_of;
 use mpi::{
     datatype::{Equivalence, UncommittedUserDatatype, UserDatatype},

tree/src/implementations/impl_morton.rs

@@ -1,3 +1,4 @@
+//! Implementations of constructors and transformation methods for Morton keys, as well as traits for sorting, and handling containers of Morton keys.
 use itertools::{izip, Itertools};
 use std::{
     cmp::Ordering,

tree/src/implementations/impl_morton_mpi.rs

@@ -1,3 +1,4 @@
+//! Implementation of an equivalent MPI type for Morton keys.
 use crate::types::morton::{KeyType, MortonKey};
 use memoffset::offset_of;
 use mpi::{

tree/src/implementations/impl_multi_node.rs

@@ -1,3 +1,4 @@
+//! Implementation of constructors for multi node trees from distributed point data.
 use itertools::Itertools;
 use std::collections::{HashMap, HashSet};
 

tree/src/implementations/impl_point.rs

@@ -1,3 +1,4 @@
+//! Implementation of traits for handling, and sorting, containers of point data.
 use std::cmp::Ordering;
 use std::hash::{Hash, Hasher};
 

tree/src/implementations/impl_point_mpi.rs

@@ -1,3 +1,4 @@
+//! Implementation of an equivalent MPI type for point data.
 use crate::types::{
     morton::{KeyType, MortonKey},
     point::{Point, PointType},

tree/src/implementations/impl_single_node.rs

@@ -1,3 +1,4 @@
+//! Implementation of constructors for single node trees.
 use itertools::Itertools;
 use std::collections::{HashMap, HashSet};
 

tree/src/implementations/mod.rs

@@ -1,3 +1,5 @@
+//! Implementations of methods for data structures specified in the `types` crate.
+
 pub mod helpers;
 pub mod impl_domain;
 pub mod impl_morton;

tree/src/implementations/mpi_helpers.rs

@@ -1,4 +1,4 @@
-/// Helper Routines for MPI functionality
+//! Helper Routines for MPI functionality
 use mpi::{
     datatype::Equivalence,
     topology::{Communicator, UserCommunicator},

tree/src/types/domain.rs

@@ -1,4 +1,4 @@
-//! Data structures and methods for defining the computational domain.
+//! Data structures for defining the computational domain.
 
 use crate::types::point::PointType;
 

tree/src/types/mod.rs

@@ -1,4 +1,4 @@
-//! # Type declaration
+//! Type declarations for Morton Keys, Single and Multinode Trees, Cartesian points, and Single and Multinode domains.
 pub mod domain;
 pub mod morton;
 #[cfg(feature = "mpi")]

tree/src/types/morton.rs

@@ -1,4 +1,4 @@
-//! Data structures and methods for Morton Keys.
+//! Data structures for Morton Keys.
 pub type KeyType = u64;
 
 #[repr(C)]

tree/src/types/multi_node.rs

@@ -1,4 +1,4 @@
-//! Data structures and methods to create distributed octrees with MPI.
+//! Data structures to create distributed octrees with MPI.
 use mpi::topology::UserCommunicator;
 
 use std::collections::{HashMap, HashSet};

tree/src/types/point.rs

@@ -1,4 +1,4 @@
-//! Data structures and methods for Cartesian Points in 3D.
+//! Data structures for Cartesian Points in 3D.
 use crate::types::morton::MortonKey;
 
 pub type PointType = f64;

tree/src/types/single_node.rs

@@ -1,4 +1,4 @@
-//! Data Structures and methods to create octrees on a single node.
+//! Data Structures to create octrees on a single node.
 use std::collections::{HashMap, HashSet};
 
 use crate::types::{