Unify parameter names and improve docs.

Author: kylc

Cargo.toml

@@ -19,7 +19,7 @@ kiddo = "5.2.2"
 mimalloc = { version = "0.1.48", features = ["v3"] }
 nalgebra = { version = "0.34.1", features = ["rand"] }
 parry3d-f64 = "0.25"
-pyo3 = { version = "0.27.0", features = ["abi3-py39"] }
+pyo3 = { version = "0.27.0", features = ["abi3-py39", "experimental-inspect"] }
 rand = { version = "0.9.2", default-features = false, features = ["std"] }
 rand_chacha = "0.9.0"
 rayon = "1.11.0"

python/miniacd/cli.py

@@ -46,26 +46,26 @@ def random_rgb() -> tuple[int, int, int]:
     type=click.FloatRange(min=0.0),
     help="Concavity threshold at which mesh parts will be accepted",
 )
-@click.option(
-    "--mcts-depth",
-    default=3,
-    type=click.IntRange(min=0),
-    help="Monte Carlo tree search search depth",
-)
 @click.option(
     "--mcts-iterations",
     default=150,
     type=click.IntRange(min=0),
     help="Monte Carlo tree search search iterations",
 )
 @click.option(
-    "--mcts-nodes",
+    "--mcts-depth",
+    default=3,
+    type=click.IntRange(min=1),
+    help="Monte Carlo tree search search depth",
+)
+@click.option(
+    "--mcts-grid-nodes",
     default=20,
-    type=click.IntRange(min=0),
+    type=click.IntRange(min=1),
     help="The discretization size in the Monte Carlo tree search",
 )
 @click.option(
-    "--seed",
+    "--mcts-random-seed",
     default=0,
     type=click.IntRange(min=0),
     help="Random generator seed for deterministic output",
@@ -78,8 +78,8 @@ def main(
     threshold: float,
     mcts_depth: int,
     mcts_iterations: int,
-    mcts_nodes: int,
-    seed: int,
+    mcts_grid_nodes: int,
+    mcts_random_seed: int,
 ):
     """
     miniacd decomposes watertight 3D meshes into convex components
@@ -91,10 +91,10 @@ def main(
     parts = miniacd.run(
         mesh,
         threshold=threshold,
-        max_depth=mcts_depth,
-        iterations=mcts_iterations,
-        num_nodes=mcts_nodes,
-        random_seed=seed,
+        mcts_depth=mcts_depth,
+        mcts_iterations=mcts_iterations,
+        mcts_grid_nodes=mcts_grid_nodes,
+        mcts_random_seed=mcts_random_seed,
         print=True,
     )
 

src/lib.rs

@@ -27,15 +27,19 @@ pub struct Config {
     /// The minimum acceptable concavity metric for an individual part to be
     /// accepted.
     pub threshold: f64,
-    /// The number of samples taken from the MCTS before choosing a move.
-    pub iterations: usize,
+    /// The number of iterations taken for each MCTS step which chooses a single
+    /// slicing plane.
+    pub mcts_iterations: usize,
     /// The depth of the MCTS, i.e. the number of lookahead moves when deciding
     /// on the next move.
-    pub max_depth: usize,
-    pub exploration_param: f64,
+    pub mcts_depth: usize,
+    /// The exploration parameter for computing the upper confidence bound
+    /// (UCB).
+    pub mcts_exploration: f64,
     /// The number of discrete slices taken per axis at each node in the MCTS.
-    pub num_nodes: usize,
-    pub random_seed: u64,
+    pub mcts_grid_nodes: usize,
+    /// A seed for the deterministic RNG.
+    pub mcts_random_seed: u64,
     /// Print the progress bar? Enable for human users, disable for tests etc.
     pub print: bool,
 }
@@ -44,11 +48,11 @@ impl Default for Config {
     fn default() -> Self {
         Self {
             threshold: 0.1,
-            iterations: 150,
-            max_depth: 3,
-            exploration_param: f64::sqrt(2.0),
-            num_nodes: 20,
-            random_seed: 0,
+            mcts_iterations: 150,
+            mcts_depth: 3,
+            mcts_exploration: f64::sqrt(2.0),
+            mcts_grid_nodes: 20,
+            mcts_random_seed: 0,
             print: false,
         }
     }

src/mcts.rs

@@ -414,7 +414,7 @@ fn refine(
 /// probability to lead to a large reward when followed by more slices.
 pub fn run(input_part: &Part, config: &Config) -> Option<CanonicalPlane> {
     // A deterministic random number generator.
-    let mut rng = ChaCha8Rng::seed_from_u64(config.random_seed);
+    let mut rng = ChaCha8Rng::seed_from_u64(config.mcts_random_seed);
 
     // The root MCTS node contains just the input part, unmodified.
     let root_node = MctsNode::new(
@@ -423,24 +423,24 @@ pub fn run(input_part: &Part, config: &Config) -> Option<CanonicalPlane> {
             parent_rewards: vec![],
             depth: 0,
         },
-        all_actions(config.num_nodes, &mut rng),
+        all_actions(config.mcts_grid_nodes, &mut rng),
         None,
         None,
     );
 
     // Run the MCTS algorithm for the specified compute time to compute a
     // probabilistic best path.
     let mut mcts = Mcts::new(root_node);
-    for _ in 0..config.iterations {
-        let mut v = mcts.select(config.exploration_param);
+    for _ in 0..config.mcts_iterations {
+        let mut v = mcts.select(config.mcts_exploration);
 
-        if !mcts.nodes[v].is_terminal(config.max_depth) {
-            mcts.expand(v, config.num_nodes, &mut rng);
+        if !mcts.nodes[v].is_terminal(config.mcts_depth) {
+            mcts.expand(v, config.mcts_grid_nodes, &mut rng);
             let children = &mcts.nodes[v].children;
             v = *children.choose(&mut rng).unwrap();
         }
 
-        let reward = mcts.nodes[v].state.simulate(config.max_depth);
+        let reward = mcts.nodes[v].state.simulate(config.mcts_depth);
         mcts.backprop(v, reward);
     }
 
@@ -454,7 +454,7 @@ pub fn run(input_part: &Part, config: &Config) -> Option<CanonicalPlane> {
             &best_path,
             // TODO: use one node width scaled to mesh bbox
             1.0,
-            config.max_depth,
+            config.mcts_depth,
         );
         Some(refined_plane)
     } else {

src/py.rs

@@ -37,29 +37,31 @@ mod pyminiacd {
     }
 
     #[pyfunction]
-    #[pyo3(signature=(mesh,
-                      threshold=0.1,
-                      iterations=150,
-                      max_depth=3,
-                      num_nodes=20,
-                      random_seed=42,
-                      print=true))]
+    #[pyo3(signature=(
+        mesh: "PyMesh",
+        threshold: "float" = 0.1,
+        mcts_iterations: "int" = 150,
+        mcts_depth: "int" = 3,
+        mcts_grid_nodes: "int" = 20,
+        mcts_random_seed: "int" = 42,
+        print: "bool" = true
+    ) -> "list[PyMesh]")]
     fn run(
         mesh: &PyMesh,
         threshold: f64,
-        iterations: usize,
-        max_depth: usize,
-        num_nodes: usize,
-        random_seed: u64,
+        mcts_iterations: usize,
+        mcts_depth: usize,
+        mcts_grid_nodes: usize,
+        mcts_random_seed: u64,
         print: bool,
     ) -> Vec<PyMesh> {
         let config = Config {
             threshold,
-            iterations,
-            max_depth,
-            exploration_param: f64::sqrt(2.0),
-            num_nodes,
-            random_seed,
+            mcts_iterations,
+            mcts_depth,
+            mcts_exploration: f64::sqrt(2.0),
+            mcts_grid_nodes,
+            mcts_random_seed,
             print,
         };