balanced_vrp_clustering 0.4.0

data/rust/balanced_vrp_clustering_core/src/types.rs

@@ -0,0 +1,234 @@
+// 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 serde::{Deserialize, Deserializer, Serialize};
+use std::collections::HashMap;
+
+fn deserialize_usize_from_number<'de, D>(deserializer: D) -> Result<usize, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    #[derive(Deserialize)]
+    #[serde(untagged)]
+    enum Num {
+        Int(usize),
+        Float(f64),
+    }
+    match Num::deserialize(deserializer)? {
+        Num::Int(v) => Ok(v),
+        Num::Float(v) => Ok(v as usize),
+    }
+}
+
+fn deserialize_f64<'de, D>(deserializer: D) -> Result<f64, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Ok(Option::<f64>::deserialize(deserializer)?.unwrap_or(0.0))
+}
+
+fn deserialize_f64_default_one<'de, D>(deserializer: D) -> Result<f64, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Ok(Option::<f64>::deserialize(deserializer)?.unwrap_or(1.0))
+}
+
+fn deserialize_vec_f64<'de, D>(deserializer: D) -> Result<Vec<f64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw: Vec<Option<f64>> = Vec::deserialize(deserializer)?;
+    Ok(raw.into_iter().map(|v| v.unwrap_or(0.0)).collect())
+}
+
+fn deserialize_option_vec_f64<'de, D>(deserializer: D) -> Result<Option<Vec<f64>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw: Option<Vec<Option<f64>>> = Option::deserialize(deserializer)?;
+    Ok(raw.map(|values| values.into_iter().map(|v| v.unwrap_or(0.0)).collect()))
+}
+
+fn deserialize_f64_map<'de, D>(deserializer: D) -> Result<HashMap<String, f64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw: HashMap<String, Option<f64>> = HashMap::deserialize(deserializer)?;
+    Ok(raw
+        .into_iter()
+        .map(|(k, v)| (k, v.unwrap_or(0.0)))
+        .collect())
+}
+
+fn deserialize_distance_matrix<'de, D>(deserializer: D) -> Result<Option<Vec<Vec<f64>>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw: Option<Vec<Vec<Option<f64>>>> = Option::deserialize(deserializer)?;
+    Ok(raw.map(|rows| {
+        rows.into_iter()
+            .map(|row| row.into_iter().map(|v| v.unwrap_or(0.0)).collect())
+            .collect()
+    }))
+}
+
+pub const INCOMPATIBILITY_DISTANCE_PENALTY: f64 = 4_294_967_296.0; // 2^32
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct InputConfig {
+    pub name: Option<String>,
+    pub seed: u64,
+    pub cut_symbol: Option<String>,
+    #[serde(deserialize_with = "deserialize_f64")]
+    pub cut_ratio: f64,
+    #[serde(deserialize_with = "deserialize_usize_from_number")]
+    pub max_iterations: usize,
+    pub vehicles: Vec<VehicleInput>,
+    pub items: Vec<ItemInput>,
+    #[serde(default, deserialize_with = "deserialize_distance_matrix")]
+    pub distance_matrix: Option<Vec<Vec<f64>>>,
+    pub centroid_indices: Vec<usize>,
+    #[serde(default)]
+    pub related_item_indices: HashMap<String, Vec<Vec<usize>>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct VehicleInput {
+    pub id: Vec<String>,
+    pub depot: DepotInput,
+    #[serde(default, deserialize_with = "deserialize_f64_map")]
+    pub capacities: HashMap<String, f64>,
+    #[serde(default)]
+    pub skills: Vec<String>,
+    #[serde(default)]
+    pub day_skills: Vec<String>,
+    #[serde(default, deserialize_with = "deserialize_f64")]
+    pub duration: f64,
+    #[serde(default = "default_one", deserialize_with = "deserialize_f64_default_one")]
+    pub total_work_days: f64,
+    #[serde(default = "default_one", deserialize_with = "deserialize_f64_default_one")]
+    pub vehicle_count: f64,
+}
+
+fn default_one() -> f64 {
+    1.0
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct DepotInput {
+    #[serde(default, deserialize_with = "deserialize_option_vec_f64")]
+    pub coordinates: Option<Vec<f64>>,
+    pub matrix_index: Option<usize>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ItemInput {
+    pub id: String,
+    #[serde(deserialize_with = "deserialize_f64")]
+    pub lat: f64,
+    #[serde(deserialize_with = "deserialize_f64")]
+    pub lon: f64,
+    #[serde(default, deserialize_with = "deserialize_f64_map")]
+    pub quantities: HashMap<String, f64>,
+    #[serde(default)]
+    pub v_id: Vec<String>,
+    #[serde(default)]
+    pub skills: Vec<String>,
+    #[serde(default)]
+    pub day_skills: Vec<String>,
+    pub matrix_index: Option<usize>,
+    #[serde(default, deserialize_with = "deserialize_vec_f64")]
+    pub duration_from_and_to_depot: Vec<f64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct BuildOutput {
+    pub iterations: usize,
+    pub clusters: Vec<Vec<String>>,
+    pub elapsed_ms: u64,
+}
+
+#[derive(Debug, Clone)]
+pub struct CentroidWeights {
+    pub limit: Vec<f64>,
+    pub compatibility: f64,
+}
+
+#[derive(Debug, Clone)]
+pub struct Item {
+    pub id: String,
+    pub lat: f64,
+    pub lon: f64,
+    pub quantities: HashMap<String, f64>,
+    pub v_id: Vec<String>,
+    pub skills: Vec<String>,
+    pub day_skills: Vec<String>,
+    pub matrix_index: Option<usize>,
+    pub duration_from_and_to_depot: Vec<f64>,
+    pub linked_next: Option<usize>,
+    pub centroid_weights: CentroidWeights,
+    pub needs_to_stay_at_the_top: bool,
+    pub moved_up: bool,
+    pub moved_down: bool,
+    pub weighted_visit_distance: f64,
+    pub local_speed: Option<f64>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Centroid {
+    pub lat: f64,
+    pub lon: f64,
+    pub id: String,
+    pub load: HashMap<String, f64>,
+    pub v_id: Vec<String>,
+    pub skills: Vec<String>,
+    pub day_skills: Vec<String>,
+    pub matrix_index: Option<usize>,
+    pub duration_from_and_to_depot: f64,
+    pub capacity_offence_coeff: f64,
+    pub route_time: f64,
+    pub area: f64,
+    pub visit_count: f64,
+    pub visit_density: f64,
+    pub min_speed: f64,
+    pub max_speed: f64,
+    pub speed: f64,
+    pub total_work_days: f64,
+    pub vehicle_count: f64,
+    pub capacities: HashMap<String, f64>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Vehicle {
+    pub id: Vec<String>,
+    pub depot_lat: f64,
+    pub depot_lon: f64,
+    pub depot_matrix_index: Option<usize>,
+    pub capacities: HashMap<String, f64>,
+    pub skills: Vec<String>,
+    pub day_skills: Vec<String>,
+    pub duration: f64,
+    pub total_work_days: f64,
+    pub vehicle_count: f64,
+}
+
+#[derive(Debug, Clone)]
+pub struct CutLimit {
+    pub limit: f64,
+}

data/rust/balanced_vrp_clustering_core/tests/integration.rs

@@ -0,0 +1,71 @@
+// 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 std::fs;
+
+#[test]
+fn golden_tiny_builds() {
+    let path = concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../../benchmark/fixtures/json/tiny.json"
+    );
+    if !std::path::Path::new(path).exists() {
+        return; // skip when fixtures not exported
+    }
+    let json = fs::read_to_string(path).expect("read tiny.json");
+    let input: InputConfig = serde_json::from_str(&json).expect("parse");
+    let output = build_from_input(&input);
+    assert_eq!(output.clusters.len(), 2);
+    assert_eq!(
+        output.clusters.iter().map(|c| c.len()).sum::<usize>(),
+        4
+    );
+    assert!(output.iterations > 0);
+}
+
+#[test]
+fn parses_json_null_numeric_fields() {
+    let json = r#"{
+        "seed": 1,
+        "cut_ratio": null,
+        "max_iterations": 10,
+        "vehicles": [{
+            "id": ["v1"],
+            "depot": { "coordinates": [null, 48.5] },
+            "duration": null,
+            "total_work_days": null,
+            "vehicle_count": null,
+            "capacities": { "visits": null }
+        }],
+        "items": [{
+            "id": "p1",
+            "lat": null,
+            "lon": null,
+            "quantities": { "visits": null },
+            "duration_from_and_to_depot": [null, 120.0]
+        }],
+        "distance_matrix": [[null, 2.0]],
+        "centroid_indices": []
+    }"#;
+    let input: InputConfig = serde_json::from_str(json).expect("parse nulls as zero");
+    assert_eq!(input.cut_ratio, 0.0);
+    assert_eq!(input.items[0].lat, 0.0);
+    assert_eq!(input.items[0].duration_from_and_to_depot, [0.0, 120.0]);
+    assert_eq!(input.distance_matrix.as_ref().unwrap()[0][0], 0.0);
+}

data/rust/balanced_vrp_clustering_native/Cargo.toml

@@ -0,0 +1,33 @@
+# 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>
+#
+
+[package]
+name = "balanced_vrp_clustering_native"
+version = "0.4.0"
+edition = "2021"
+description = "Ruby native extension for balanced VRP clustering"
+license = "AGPL-3.0-or-later"
+
+[lib]
+crate-type = ["cdylib"]
+name = "balanced_vrp_clustering_native"
+
+[dependencies]
+balanced_vrp_clustering_core = { path = "../balanced_vrp_clustering_core" }
+magnus = { version = "0.8" }
+serde_json = "1"

data/rust/balanced_vrp_clustering_native/extconf.rb

@@ -0,0 +1,26 @@
+# 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>
+#
+
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('balanced_vrp_clustering_native') do |config|
+  config.profile = ENV.fetch('BVRP_NATIVE_PROFILE', 'release').to_sym
+end

data/rust/balanced_vrp_clustering_native/src/lib.rs

@@ -0,0 +1,57 @@
+// 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 magnus::{function, prelude::*, Error, Ruby, RString};
+
+fn build_from_json(input: RString) -> Result<RString, Error> {
+    let ruby = Ruby::get().expect("Ruby not initialized");
+    let json_str = input
+        .to_string()
+        .map_err(|e| Error::new(ruby.exception_arg_error(), e.to_string()))?;
+
+    let config: InputConfig = serde_json::from_str(&json_str).map_err(|e| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("invalid JSON input: {e}"),
+        )
+    })?;
+
+    let output = build_from_input(&config);
+    let out_json = serde_json::to_string(&output).map_err(|e| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("failed to serialize output: {e}"),
+        )
+    })?;
+
+    Ok(ruby.str_new(&out_json))
+}
+
+/// Returns true when the native extension loaded successfully.
+fn available() -> bool {
+    true
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("BalancedVRPClusteringNative")?;
+    module.define_singleton_method("build_from_json", function!(build_from_json, 1))?;
+    module.define_singleton_method("available?", function!(available, 0))?;
+    Ok(())
+}

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: balanced_vrp_clustering
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Cartoway
+bindir: bin
+cert_chain: []
+date: 2026-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
+executables: []
+extensions:
+- rust/balanced_vrp_clustering_native/extconf.rb
+extra_rdoc_files: []
+files:
+- lib/balanced_vrp_clustering.rb
+- lib/balanced_vrp_clustering/ai4r_compat.rb
+- lib/balanced_vrp_clustering/rust_engine.rb
+- lib/balanced_vrp_clustering_native.rb
+- lib/concerns/overloadable_functions.rb
+- lib/helpers/helper.rb
+- lib/helpers/hull.rb
+- rust/Cargo.lock
+- rust/Cargo.toml
+- rust/balanced_vrp_clustering_core/Cargo.toml
+- rust/balanced_vrp_clustering_core/src/clusterer.rs
+- rust/balanced_vrp_clustering_core/src/compatibility.rs
+- rust/balanced_vrp_clustering_core/src/distance.rs
+- rust/balanced_vrp_clustering_core/src/lib.rs
+- rust/balanced_vrp_clustering_core/src/limits.rs
+- rust/balanced_vrp_clustering_core/src/local_speed.rs
+- rust/balanced_vrp_clustering_core/src/main.rs
+- rust/balanced_vrp_clustering_core/src/relations.rs
+- rust/balanced_vrp_clustering_core/src/rng.rs
+- rust/balanced_vrp_clustering_core/src/types.rs
+- rust/balanced_vrp_clustering_core/tests/integration.rs
+- rust/balanced_vrp_clustering_native/Cargo.toml
+- rust/balanced_vrp_clustering_native/extconf.rb
+- rust/balanced_vrp_clustering_native/src/lib.rs
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Gem for clustering points of a given VRP.
+test_files: []