Merge pull request #107 from JeroenGar/streamline

Every Algorithm from the paper is referenced to its corresponding function

Author: JeroenGar

Cargo.toml

@@ -14,7 +14,7 @@ name = "bench"
 path = "src/bench.rs"
 
 [dependencies]
-jagua-rs = { features = ["spp"], git = "https://github.com/JeroenGar/jagua-rs.git", rev = "1fb0824457cea336e65cebdd8b3dfb8c9d88487a"}
+jagua-rs = { features = ["spp"], git = "https://github.com/JeroenGar/jagua-rs.git", rev = "8ad43e489a2d24f63cf9a15feae268af9569d65c"}
 #jagua-rs = { features = ["spp"], path = "../jagua-rs/jagua-rs" }
 rand = "0.9"
 rand_distr = "0.5"
@@ -24,19 +24,19 @@ log = { version = "0.4", features = ["release_max_level_info"] }
 fern = "0.7"
 serde = "1.0"
 serde_json = "1.0"
-tap = "1.0.1"
+tap = "1.0"
 slotmap = "1.0"
-float-cmp = "0.10.0"
-ordered-float = "5.0.0"
-rayon = "1.10.0"
-numfmt = "1.1.1"
-num_cpus = "1.16.0"
+float-cmp = "0.10"
+ordered-float = "5.0"
+rayon = "1.10"
+numfmt = "1.1"
+num_cpus = "1.17"
 jiff = "0.2"
 test-case = "3.3"
 clap = { version = "4.5", features = ["derive"] }
 anyhow = "1.0"
 ndarray = "0.16"
-rand_xoshiro = "0.7.0"
+rand_xoshiro = "0.7"
 
 getrandom = { version = "0.3", features = ["wasm_js"] }
 

src/eval/lbf_evaluator.rs

@@ -31,7 +31,7 @@ impl<'a> LBFEvaluator<'a> {
 }
 
 impl<'a> SampleEvaluator for LBFEvaluator<'a> {
-    fn eval(&mut self, dt: DTransformation, _upper_bound: Option<SampleEval>) -> SampleEval {
+    fn evaluate_sample(&mut self, dt: DTransformation, _upper_bound: Option<SampleEval>) -> SampleEval {
         self.n_evals += 1;
         let cde = self.layout.cde();
         let transf = dt.into();

src/eval/sample_eval.rs

@@ -38,7 +38,7 @@ impl Eq for SampleEval {}
 
 /// Simple trait for types that can evaluate samples
 pub trait SampleEvaluator {
-    fn eval(&mut self, dt: DTransformation, upper_bound: Option<SampleEval>) -> SampleEval;
+    fn evaluate_sample(&mut self, dt: DTransformation, upper_bound: Option<SampleEval>) -> SampleEval;
 
     fn n_evals(&self) -> usize;
 }

src/eval/sep_evaluator.rs

@@ -37,20 +37,21 @@ impl<'a> SeparationEvaluator<'a> {
 
 impl<'a> SampleEvaluator for SeparationEvaluator<'a> {
     /// Evaluates a transformation. An upper bound can be provided to early terminate the process.
-    fn eval(&mut self, dt: DTransformation, upper_bound: Option<SampleEval>) -> SampleEval {
+    /// Algorithm 7 from https://doi.org/10.48550/arXiv.2509.13329
+    fn evaluate_sample(&mut self, dt: DTransformation, upper_bound: Option<SampleEval>) -> SampleEval {
         self.n_evals += 1;
         let cde = self.layout.cde();
 
-        // evals with higher loss than this will always be rejected
+        //samples which evaluate higher than this will certainly be rejected
         let loss_bound = match upper_bound {
             Some(SampleEval::Collision { loss }) => loss,
             Some(SampleEval::Clear { .. }) => 0.0,
             _ => f32::INFINITY,
         };
-        // Reload the detection map for the new query and update the loss bound
+        //reload the hazard collector to prepare for a new query
         self.collector.reload(loss_bound);
 
-        // Query the CDE, all colliding hazards will be stored in the detection map
+        //query the CDE, all colliding hazards will be stored in the detection map
         collect_poly_collisions_in_detector_custom(cde, &dt, &mut self.shape_buff, self.item.shape_cd.as_ref(), &mut self.collector);
 
         if self.collector.early_terminate(&self.shape_buff) {

src/eval/specialized_jaguars_pipeline.rs

@@ -38,17 +38,18 @@ pub fn collect_poly_collisions_in_detector_custom(
     #[cfg(feature = "simd")]
     collector.poles_soa.load(&shape.surrogate().poles);
 
-    // Start off by checking a few poles to detect obvious collisions quickly
+
     {
-        //TODO: clean this up
+        // We start off by checking a few poles in order to detect obvious collisions quickly and quickly raise the loss.
+        // Potentially allows us to fail fast (early terminate) without checking all edges.
+        // We check poles until the area of the poles checked exceeds 50% of the shape.
         let area_threshold = shape.area * 0.5 / PI;
         let mut area_sum = 0.0;
         for pole in shape.surrogate().poles.iter() {
             cde.quadtree.collect_collisions(pole, collector);
             if collector.early_terminate(shape) { return; }
             area_sum += pole.radius * pole.radius;
             if area_sum > area_threshold {
-                // If the area of the poles exceeds 80% of the shape's area, we can stop early.
                 break;
             }
         }
@@ -57,7 +58,7 @@ pub fn collect_poly_collisions_in_detector_custom(
     // Find the virtual root of the quadtree for the shape's bounding box. So we do not have to start from the root every time.
     let v_quadtree = cde.get_virtual_root(shape.bbox);
 
-    // Collect collisions for all edges.
+    // Collect collisions for each edge of the polygon.
     // Iterate over them in a bit-reversed order to maximize detecting new hazards early.
     let custom_edge_iter = BitReversalIterator::new(shape.n_vertices())
         .map(|i| shape.edge(i));
@@ -66,7 +67,7 @@ pub fn collect_poly_collisions_in_detector_custom(
         if collector.early_terminate(shape) { return; }
     }
 
-    //Check if there are any other collisions due to containment
+    // Check if there are any other collisions due to containment
     for qt_haz in v_quadtree.hazards.iter() {
         match &qt_haz.presence {
             // No need to check these, guaranteed to be detected by edge intersection
@@ -188,7 +189,8 @@ impl<'a> HazardCollector for SpecializedHazardCollector<'a> {
     }
 
     fn remove_by_key(&mut self, hkey: HazKey) {
-        let (_, idx) = self.detected.remove(hkey).expect("key should be present in the collector");
+        let (_, idx) = self.detected.remove(hkey)
+            .expect("key should be present in the collector");
         if idx < self.loss_cache.0 {
             //wipe the cache if a hazard was removed that was in it
             self.loss_cache = (0, 0.0);

src/optimizer/compress.rs

@@ -7,6 +7,7 @@ use crate::optimizer::separator::Separator;
 use crate::util::listener::{ReportType, SolutionListener};
 use crate::util::terminator::Terminator;
 
+/// Algorithm 13 from https://doi.org/10.48550/arXiv.2509.13329
 pub fn compression_phase(
     instance: &SPInstance, 
     sep: &mut Separator, 

src/optimizer/explore.rs

@@ -17,6 +17,7 @@ use crate::sample::uniform_sampler::convert_sample_to_closest_feasible;
 use crate::util::listener::{ReportType, SolutionListener};
 use crate::util::terminator::Terminator;
 
+/// Algorithm 12 from https://doi.org/10.48550/arXiv.2509.13329
 pub fn exploration_phase(instance: &SPInstance, sep: &mut Separator, sol_listener: &mut impl SolutionListener,  term: &impl Terminator, config: &ExplorationConfig) -> Vec<SPSolution> {
     let mut current_width = sep.prob.strip_width();
     let mut best_width = current_width;

src/optimizer/mod.rs

@@ -17,6 +17,7 @@ mod worker;
 pub mod explore;
 pub mod compress;
 
+///Algorithm 11 from https://doi.org/10.48550/arXiv.2509.13329
 pub fn optimize(instance: SPInstance, mut rng: Xoshiro256PlusPlus, sol_listener: &mut impl SolutionListener, terminator: &mut impl Terminator, expl_config: &ExplorationConfig, cmpr_config: &CompressionConfig) -> SPSolution {
     let mut next_rng = || Xoshiro256PlusPlus::seed_from_u64(rng.next_u64());
     let builder = LBFBuilder::new(instance.clone(), next_rng(), LBF_SAMPLE_CONFIG).construct();

src/optimizer/separator.rs

@@ -68,6 +68,7 @@ impl Separator {
         }
     }
 
+    /// Algorithm 9 from https://doi.org/10.48550/arXiv.2509.13329
     pub fn separate(&mut self, term: &impl Terminator, sol_listener: &mut impl SolutionListener) -> (SPSolution, CTSnapshot) {
         let mut min_loss_sol = (self.prob.save(), self.ct.save());
         let mut min_loss = self.ct.get_total_loss();
@@ -89,7 +90,7 @@ impl Separator {
                     self.ct.get_total_loss(),
                     self.ct.get_total_weighted_loss(),
                 );
-                sep_stats += self.move_colliding_items();
+                sep_stats += self.move_items_multi();
                 let (loss, w_loss) = (
                     self.ct.get_total_loss(),
                     self.ct.get_total_weighted_loss(),
@@ -117,7 +118,7 @@ impl Separator {
                     n_iter_no_improvement += 1;
                 }
 
-                self.ct.increment_weights();
+                self.ct.update_weights();
                 n_iter += 1;
             }
 
@@ -141,15 +142,16 @@ impl Separator {
         (min_loss_sol.0, min_loss_sol.1)
     }
 
-    fn move_colliding_items(&mut self) -> SepStats {
+    /// Algorithm 10 from https://doi.org/10.48550/arXiv.2509.13329
+    fn move_items_multi(&mut self) -> SepStats {
         let master_sol = self.prob.save();
 
         let mut separate_multi = || -> SepStats {
             self.workers.par_iter_mut().map(|worker| {
                 // Sync the workers with the master
                 worker.load(&master_sol, &self.ct);
                 // Let them modify
-                worker.move_colliding_items()
+                worker.move_items()
             }).sum()
         };
 

src/optimizer/worker.rs

@@ -31,8 +31,9 @@ impl SeparatorWorker {
         self.ct = ct.clone();
     }
 
-    pub fn move_colliding_items(&mut self) -> SepStats {
-        //collect all colliding items and shuffle them
+    /// Algorithm 5 from https://doi.org/10.48550/arXiv.2509.13329
+    pub fn move_items(&mut self) -> SepStats {
+        //collect all colliding items and order them randomly
         let candidates = self.prob.layout.placed_items.keys()
             .filter(|pk| self.ct.get_loss(*pk) > 0.0)
             .collect_vec()
@@ -41,23 +42,23 @@ impl SeparatorWorker {
         let mut total_moves = 0;
         let mut total_evals = 0;
 
-        //give each item a chance to move to a better (eval) position
+        //give each item the opportunity to move to a better (eval) position
         for &pk in candidates.iter() {
             //check if the item is still colliding
             if self.ct.get_loss(pk) > 0.0 {
                 let item_id = self.prob.layout.placed_items[pk].item_id;
                 let item = self.instance.item(item_id);
 
-                // create an evaluator to evaluate the samples during the search
+                //create an evaluator to evaluate the samples during the search
                 let evaluator = SeparationEvaluator::new(&self.prob.layout, item, pk, &self.ct);
 
-                // search for a better position for the item
+                //search for a better position for the item
                 let (best_sample, n_evals) =
                     search::search_placement(&self.prob.layout, item, Some(pk), evaluator, self.sample_config, &mut self.rng);
 
                 let (new_dt, _eval) = best_sample.expect("search_placement should always return a sample");
 
-                // move the item to the new position
+                //move the item to the new position
                 self.move_item(pk, new_dt);
                 total_moves += 1;
                 total_evals += n_evals;