balanced_vrp_clustering 0.4.0

data/rust/balanced_vrp_clustering_core/src/compatibility.rs

@@ -0,0 +1,78 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use crate::types::{Centroid, Item, Vehicle};
+
+pub fn compatible_characteristics(item: &Item, vehicle: &Vehicle) -> bool {
+    if !item.v_id.is_empty() && item.v_id.iter().all(|v| !vehicle.id.contains(v)) {
+        return false;
+    }
+    if item.skills.iter().any(|s| !vehicle.skills.contains(s)) {
+        return false;
+    }
+    if !item
+        .day_skills
+        .iter()
+        .any(|d| vehicle.day_skills.contains(d))
+    {
+        return false;
+    }
+    true
+}
+
+pub fn compatible_item_centroid(item: &Item, centroid: &Centroid) -> bool {
+    if !item.v_id.is_empty() && item.v_id.iter().all(|v| !centroid.v_id.contains(v)) {
+        return false;
+    }
+    if item.skills.iter().any(|s| !centroid.skills.contains(s)) {
+        return false;
+    }
+    if !item
+        .day_skills
+        .iter()
+        .any(|d| centroid.day_skills.contains(d))
+    {
+        return false;
+    }
+    true
+}
+
+pub fn vehicle_as_centroid_props(vehicle: &Vehicle) -> Centroid {
+    Centroid {
+        lat: vehicle.depot_lat,
+        lon: vehicle.depot_lon,
+        id: vehicle.id.first().cloned().unwrap_or_default(),
+        load: Default::default(),
+        v_id: vehicle.id.clone(),
+        skills: vehicle.skills.clone(),
+        day_skills: vehicle.day_skills.clone(),
+        matrix_index: vehicle.depot_matrix_index,
+        duration_from_and_to_depot: 0.0,
+        capacity_offence_coeff: 0.0,
+        route_time: 0.0,
+        area: 0.0,
+        visit_count: 0.0,
+        visit_density: 0.0,
+        min_speed: 0.0,
+        max_speed: 0.0,
+        speed: 0.0,
+        total_work_days: vehicle.total_work_days,
+        vehicle_count: vehicle.vehicle_count,
+        capacities: vehicle.capacities.clone(),
+    }
+}

data/rust/balanced_vrp_clustering_core/src/distance.rs

@@ -0,0 +1,179 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+const R: f64 = 6_378_137.0;
+const L: f64 = 111_321.0;
+const RADIANS_IN_A_DEGREE: f64 = std::f64::consts::PI / 180.0;
+
+pub fn deg2rad(degree: f64) -> f64 {
+    degree * RADIANS_IN_A_DEGREE
+}
+
+pub fn euclidean_distance(loc_a: (f64, f64), loc_b: (f64, f64)) -> f64 {
+    if loc_a.0 == 0.0 && loc_b.0 == 0.0 {
+        return 0.0;
+    }
+    let delta_lat = loc_a.0 - loc_b.0;
+    let delta_lon = (loc_a.1 - loc_b.1) * deg2rad((loc_a.0 + loc_b.0) / 2.0);
+    L * (delta_lat * delta_lat + delta_lon * delta_lon).sqrt()
+}
+
+pub fn flying_distance(loc_a: (f64, f64), loc_b: (f64, f64)) -> f64 {
+    if loc_a.0 == 0.0 || loc_b.0 == 0.0 {
+        return 0.0;
+    }
+    if (loc_a.0 - loc_b.0).abs() < 30.0
+        && loc_a.0.abs().max(loc_b.0.abs()) + (loc_a.1 - loc_b.1).abs() < 100.0
+    {
+        return euclidean_distance(loc_a, loc_b);
+    }
+    let deg2rad_loc_a_lat = deg2rad(loc_a.0);
+    let deg2rad_loc_b_lat = deg2rad(loc_b.0);
+    let intermediate = ((deg2rad_loc_b_lat - deg2rad_loc_a_lat) / 2.0).sin().powi(2)
+        + ((deg2rad(loc_b.1) - deg2rad(loc_a.1)) / 2.0).sin().powi(2)
+            * deg2rad_loc_b_lat.cos()
+            * deg2rad_loc_a_lat.cos();
+    R * 2.0 * (intermediate.sqrt()).atan2((1.0 - intermediate).sqrt())
+}
+
+pub fn matrix_distance(matrix: &[Vec<f64>], a_idx: usize, b_idx: usize) -> f64 {
+    let d = matrix[a_idx][b_idx];
+    let b_dist = matrix[b_idx][a_idx];
+    if d <= b_dist { d } else { b_dist }
+}
+
+pub fn compute_approximate_route_time(
+    area: f64,
+    visit_count: f64,
+    speed: f64,
+    total_work_days: f64,
+) -> f64 {
+    let k0 = 0.765 * 1.45;
+    total_work_days * k0 * (area * visit_count / total_work_days.powf(1.5)).sqrt() / speed
+}
+
+pub fn approximate_polygon_area(coordinates: &[(f64, f64)]) -> f64 {
+    if coordinates.len() <= 2 {
+        return 0.0;
+    }
+    let mut area = 0.0;
+    let mut coor_p = coordinates[0];
+    for coor in &coordinates[1..] {
+        area += deg2rad(coor.1 - coor_p.1)
+            * (2.0 + deg2rad(coor_p.0).sin() + deg2rad(coor.0).sin());
+        coor_p = *coor;
+    }
+    (area * R * R / 2.0).abs()
+}
+
+pub fn position_and_distance_to_line(
+    l_begin: (f64, f64),
+    l_end: (f64, f64),
+    point: (f64, f64),
+) -> (f64, f64) {
+    let lat_diff = l_end.0 - l_begin.0;
+    let lon_diff = l_end.1 - l_begin.1;
+    let position = lat_diff * (point.1 - l_begin.1) - lon_diff * (point.0 - l_begin.0);
+    let dist = position.abs() / (lat_diff * lat_diff + lon_diff * lon_diff).sqrt();
+    (position, dist)
+}
+
+pub fn approximate_quadrilateral_polygon<F>(
+    coordinates: &[(f64, f64)],
+    mut rand_index: F,
+) -> Vec<(f64, f64)>
+where
+    F: FnMut(usize) -> usize,
+{
+    if coordinates.is_empty() {
+        return vec![];
+    }
+    let crand_idx = rand_index(coordinates.len());
+    let crand = coordinates[crand_idx];
+    let c0 = coordinates
+        .iter()
+        .max_by(|a, b| {
+            flying_distance(crand, **a)
+                .partial_cmp(&flying_distance(crand, **b))
+                .unwrap()
+        })
+        .copied()
+        .unwrap();
+    let c1 = coordinates
+        .iter()
+        .max_by(|a, b| {
+            flying_distance(c0, **a)
+                .partial_cmp(&flying_distance(c0, **b))
+                .unwrap()
+        })
+        .copied()
+        .unwrap();
+    let c2 = coordinates
+        .iter()
+        .max_by(|a, b| {
+            flying_distance(c1, **a)
+                .partial_cmp(&flying_distance(c1, **b))
+                .unwrap()
+        })
+        .copied()
+        .unwrap();
+    let mut c3 = None;
+    let mut c4 = None;
+    let mut max_up = 0.0;
+    let mut max_down = 0.0;
+    for c_i in coordinates {
+        let (position, distance_to_line) =
+            position_and_distance_to_line(c1, c2, *c_i);
+        if position > 0.0 && distance_to_line > max_up {
+            max_up = distance_to_line;
+            c3 = Some(*c_i);
+        } else if position < 0.0 && distance_to_line > max_down {
+            max_down = distance_to_line;
+            c4 = Some(*c_i);
+        }
+    }
+    let mut result = vec![c1];
+    if let Some(p) = c3 {
+        result.push(p);
+    }
+    result.push(c2);
+    if let Some(p) = c4 {
+        result.push(p);
+    }
+    result.push(c1);
+    result
+}
+
+pub fn check_if_projection_inside_the_line_segment(
+    point: (f64, f64),
+    line_beg: (f64, f64),
+    line_end: (f64, f64),
+    margin: f64,
+) -> bool {
+    let line_direction = [line_end.0 - line_beg.0, line_end.1 - line_beg.1];
+    let point_direction = [point.0 - line_beg.0, point.1 - line_beg.1];
+    let denom: f64 = line_direction.iter().map(|x| x * x).sum();
+    if denom == 0.0 {
+        return false;
+    }
+    let projection_scaler: f64 = (0..2)
+        .map(|i| line_direction[i] * point_direction[i])
+        .sum::<f64>()
+        / denom;
+    projection_scaler >= 0.0 + 0.5 * margin && projection_scaler <= 1.0 - 0.5 * margin
+}

data/rust/balanced_vrp_clustering_core/src/lib.rs

@@ -0,0 +1,29 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+pub mod clusterer;
+pub mod compatibility;
+pub mod distance;
+pub mod limits;
+pub mod local_speed;
+pub mod relations;
+pub mod rng;
+pub mod types;
+
+pub use clusterer::build_from_input;
+pub use types::{BuildOutput, InputConfig};

data/rust/balanced_vrp_clustering_core/src/limits.rs

@@ -0,0 +1,62 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use crate::types::{CutLimit, Item, Vehicle};
+use std::collections::HashMap;
+
+pub fn compute_limits(
+    cut_symbol: Option<&str>,
+    cut_ratio: f64,
+    vehicles: &[Vehicle],
+    items: &[Item],
+) -> (Vec<HashMap<String, f64>>, Vec<CutLimit>) {
+    let strict_limits: Vec<HashMap<String, f64>> = vehicles
+        .iter()
+        .map(|vehicle| {
+            let mut s_l = HashMap::new();
+            s_l.insert("duration".to_string(), vehicle.duration);
+            for (unit, limit) in &vehicle.capacities {
+                s_l.insert(unit.clone(), *limit);
+            }
+            s_l
+        })
+        .collect();
+
+    let mut metric_limits = vec![CutLimit { limit: 0.0 }; vehicles.len()];
+
+    if let Some(cut) = cut_symbol {
+        let mut total_quantity = 0.0;
+        for item in items {
+            total_quantity += item.quantities.get(cut).copied().unwrap_or(0.0);
+        }
+        let total_capacity: f64 = vehicles
+            .iter()
+            .map(|v| v.capacities.get(cut).copied().unwrap_or(0.0))
+            .sum();
+        for (i, vehicle) in vehicles.iter().enumerate() {
+            let vehicle_share = if total_capacity > 0.0 {
+                vehicle.capacities.get(cut).copied().unwrap_or(0.0) / total_capacity
+            } else {
+                1.0 / vehicles.len() as f64
+            };
+            metric_limits[i].limit = cut_ratio * total_quantity * vehicle_share;
+        }
+    }
+
+    (strict_limits, metric_limits)
+}

data/rust/balanced_vrp_clustering_core/src/local_speed.rs

@@ -0,0 +1,99 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use crate::distance::flying_distance;
+use crate::types::Item;
+use std::collections::HashMap;
+
+pub const LOCAL_SPEED_CELL_DEG: f64 = 0.01;
+pub const LOCAL_SPEED_NEIGHBOR_LIMIT: usize = 100;
+
+pub fn build_spatial_grid(items: &[Item]) -> HashMap<(i32, i32), Vec<usize>> {
+    let mut grid: HashMap<(i32, i32), Vec<usize>> = HashMap::new();
+    for (idx, item) in items.iter().enumerate() {
+        let key = (
+            (item.lat / LOCAL_SPEED_CELL_DEG) as i32,
+            (item.lon / LOCAL_SPEED_CELL_DEG) as i32,
+        );
+        grid.entry(key).or_default().push(idx);
+    }
+    grid
+}
+
+pub fn spatial_neighbors(item: &Item, grid: &HashMap<(i32, i32), Vec<usize>>) -> Vec<usize> {
+    let cx = (item.lat / LOCAL_SPEED_CELL_DEG) as i32;
+    let cy = (item.lon / LOCAL_SPEED_CELL_DEG) as i32;
+    let mut neighbors = Vec::new();
+    for dx in -1..=1 {
+        for dy in -1..=1 {
+            if let Some(bucket) = grid.get(&(cx + dx, cy + dy)) {
+                neighbors.extend(bucket.iter().copied());
+            }
+        }
+    }
+    neighbors
+}
+
+pub fn calculate_local_speeds(items: &mut [Item]) {
+    let local_max_speed = 60.0 / 3.6;
+    let local_min_speed = 5.0 / 3.6;
+    let grid = build_spatial_grid(items);
+
+    for i in 0..items.len() {
+        if items[i].local_speed.is_some() {
+            continue;
+        }
+        let depot_duration_a = items[i].duration_from_and_to_depot[0];
+        let a_lat = items[i].lat;
+        let a_lon = items[i].lon;
+
+        let mut candidates: Vec<(f64, usize)> = Vec::new();
+        for j in spatial_neighbors(&items[i], &grid) {
+            if i == j {
+                continue;
+            }
+            let depot_diff = (depot_duration_a - items[j].duration_from_and_to_depot[0]).abs();
+            if depot_diff <= 1.0 {
+                continue;
+            }
+            let flying_dist = flying_distance((a_lat, a_lon), (items[j].lat, items[j].lon));
+            if flying_dist <= 5.0 {
+                continue;
+            }
+            candidates.push((flying_dist, j));
+        }
+
+        let calculated_speed = if candidates.is_empty() {
+            local_min_speed
+        } else {
+            candidates.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
+            let speeds: Vec<f64> = candidates
+                .iter()
+                .take(LOCAL_SPEED_NEIGHBOR_LIMIT)
+                .map(|(dist, j)| {
+                    dist / (depot_duration_a - items[*j].duration_from_and_to_depot[0]).abs()
+                })
+                .collect();
+            let sum: f64 = speeds.iter().take(2).sum();
+            sum * 1.1
+        };
+
+        let speed = calculated_speed.max(local_min_speed).min(local_max_speed);
+        items[i].local_speed = Some(speed);
+    }
+}

data/rust/balanced_vrp_clustering_core/src/main.rs

@@ -0,0 +1,46 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use balanced_vrp_clustering_core::{build_from_input, InputConfig};
+use clap::Parser;
+use std::fs;
+use std::path::PathBuf;
+
+#[derive(Parser)]
+#[command(name = "bvrp-cluster")]
+#[command(about = "Balanced VRP clustering (Rust core)")]
+struct Cli {
+    #[arg(short, long)]
+    input: PathBuf,
+
+    #[arg(short, long)]
+    output: Option<PathBuf>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+    let json = fs::read_to_string(&cli.input).expect("read input");
+    let input: InputConfig = serde_json::from_str(&json).expect("parse input");
+    let result = build_from_input(&input);
+    let out_json = serde_json::to_string_pretty(&result).expect("serialize output");
+    if let Some(path) = cli.output {
+        fs::write(path, out_json).expect("write output");
+    } else {
+        println!("{out_json}");
+    }
+}

data/rust/balanced_vrp_clustering_core/src/relations.rs

@@ -0,0 +1,143 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use crate::types::Item;
+use std::collections::HashMap;
+
+const LINKING_RELATIONS: &[&str] = &[
+    "order",
+    "same_route",
+    "sequence",
+    "same_vehicle",
+    "shipment",
+];
+const BINDING_RELATIONS: &[&str] = &["order", "same_route", "sequence", "same_vehicle"];
+
+pub fn connect_linked_items(
+    items: &mut [Item],
+    related_item_indices: &HashMap<String, Vec<Vec<usize>>>,
+) {
+    for relation in LINKING_RELATIONS {
+        if let Some(groups) = related_item_indices.get(*relation) {
+            for linked_indices in groups {
+                assert_eq!(
+                    linked_indices.len(),
+                    linked_indices.iter().collect::<std::collections::HashSet<_>>().len(),
+                    "Each relation group should contain only unique indices"
+                );
+            }
+        }
+    }
+
+    let non_binding: Vec<&str> = LINKING_RELATIONS
+        .iter()
+        .copied()
+        .filter(|r| !BINDING_RELATIONS.contains(r))
+        .collect();
+
+    for relation in non_binding {
+        if let Some(groups) = related_item_indices.get(relation) {
+            for mut linked_indices in groups.clone() {
+                if linked_indices
+                    .iter()
+                    .any(|&ind| items[ind].linked_next.is_some())
+                {
+                    panic!("A service should not appear in multiple non-binding linking relations");
+                }
+                linked_indices.push(linked_indices[0]);
+                for i in 0..linked_indices.len() - 1 {
+                    let current = linked_indices[i];
+                    let next = linked_indices[i + 1];
+                    items[current].linked_next = Some(next);
+                }
+            }
+        }
+    }
+
+    for relation in BINDING_RELATIONS {
+        if let Some(groups) = related_item_indices.get(*relation) {
+            for mut linked_indices in groups.clone() {
+                linked_indices.push(linked_indices[0]);
+                for i in 0..linked_indices.len() - 1 {
+                    let mut item_idx = linked_indices[i];
+                    let mut next_idx = linked_indices[i + 1];
+                    let item_has = items[item_idx].linked_next.is_some();
+                    let next_has = items[next_idx].linked_next.is_some();
+
+                    if !item_has && !next_has {
+                        items[item_idx].linked_next = Some(next_idx);
+                    } else if item_has && next_has {
+                        let first_loop_end = item_idx;
+                        let mut walk = items[item_idx].linked_next.unwrap();
+                        while walk != first_loop_end && walk != next_idx {
+                            item_idx = walk;
+                            walk = items[item_idx].linked_next.unwrap();
+                        }
+                        if items[item_idx].linked_next == Some(next_idx) {
+                            continue;
+                        }
+                        let second_loop_end = next_idx;
+                        let mut walk2 = items[next_idx].linked_next.unwrap();
+                        while walk2 != second_loop_end {
+                            next_idx = walk2;
+                            walk2 = items[next_idx].linked_next.unwrap();
+                        }
+                        items[item_idx].linked_next = Some(second_loop_end);
+                        items[next_idx].linked_next = Some(first_loop_end);
+                    } else {
+                        if item_has {
+                            std::mem::swap(&mut item_idx, &mut next_idx);
+                        }
+                        items[item_idx].linked_next = Some(next_idx);
+                        let loop_end = next_idx;
+                        let mut walk = items[next_idx].linked_next.unwrap();
+                        while walk != loop_end {
+                            next_idx = walk;
+                            walk = items[next_idx].linked_next.unwrap();
+                        }
+                        if next_idx != item_idx {
+                            items[next_idx].linked_next = Some(item_idx);
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Mirrors Ruby `do_forall_linked_items_of`
+pub fn do_forall_linked<F>(items: &[Item], start: usize, mut f: F)
+where
+    F: FnMut(usize),
+{
+    let mut linked_item: Option<usize> = None;
+    loop {
+        if linked_item == Some(start) {
+            break;
+        }
+        let current = if let Some(li) = linked_item {
+            items[li].linked_next.unwrap_or(start)
+        } else if let Some(next) = items[start].linked_next {
+            next
+        } else {
+            start
+        };
+        f(current);
+        linked_item = Some(current);
+    }
+}

data/rust/balanced_vrp_clustering_core/src/rng.rs

@@ -0,0 +1,50 @@
+// Copyright © Cartoway
+//
+// This file is part of balanced_vrp_clustering.
+//
+// Cartoway balanced_vrp_clustering is free software. You can redistribute it and/or
+// modify since you respect the terms of the GNU Affero General
+// Public License as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// Cartoway Planner is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.  See the Licenses for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with Cartoway Planner. If not, see:
+// <http://www.gnu.org/licenses/agpl.html>
+//
+
+use rand::rngs::StdRng;
+use rand::{Rng, SeedableRng};
+
+/// Seeded RNG for clustering (deterministic per seed).
+pub struct RubyRng {
+    inner: StdRng,
+}
+
+impl RubyRng {
+    pub fn new(seed: u64) -> Self {
+        Self {
+            inner: StdRng::seed_from_u64(seed),
+        }
+    }
+
+    /// Ruby `rand` without args: float in [0, 1)
+    pub fn rand_f64(&mut self) -> f64 {
+        self.inner.gen::<f64>()
+    }
+
+    /// Ruby `rand(max)` for positive integer max: 0..max
+    pub fn rand_usize(&mut self, max: usize) -> usize {
+        if max == 0 {
+            return 0;
+        }
+        (self.rand_f64() * max as f64) as usize % max
+    }
+
+    pub fn rand_range_f64(&mut self, min: f64, max: f64) -> f64 {
+        min + self.rand_f64() * (max - min)
+    }
+}