balanced_vrp_clustering 0.4.0

data/lib/balanced_vrp_clustering_native.rb

@@ -0,0 +1,39 @@
+# 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 'rbconfig'
+
+ROOT = File.expand_path('..', __dir__)
+NATIVE_CRATE_DIR = File.join(ROOT, 'rust', 'balanced_vrp_clustering_native')
+LIB_DIR = File.join(ROOT, 'lib')
+DLEXT = RbConfig::CONFIG['DLEXT']
+SO_NAME = "balanced_vrp_clustering_native.#{DLEXT}"
+
+# After gem install, rb_sys places the shared lib next to extconf (rust/.../crate).
+SEARCH_PATHS = [
+  File.join(LIB_DIR, SO_NAME),
+  File.join(NATIVE_CRATE_DIR, SO_NAME),
+  File.join(NATIVE_CRATE_DIR, 'target', 'release', SO_NAME)
+].freeze
+
+path = SEARCH_PATHS.find { |p| File.exist?(p) }
+raise LoadError, "balanced_vrp_clustering_native not built. Run: bundle exec rake native:compile" unless path
+
+require path

data/lib/concerns/overloadable_functions.rb

@@ -0,0 +1,64 @@
+# Copyright © Mapotempo, 2020
+#
+# This file is part of Mapotempo.
+#
+# Mapotempo 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.
+#
+# Mapotempo 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 Mapotempo. If not, see:
+# <http://www.gnu.org/licenses/agpl.html>
+#
+require 'active_support/concern'
+
+module OverloadableFunctions
+  extend ActiveSupport::Concern
+
+  def compatible_characteristics?(service_chars, vehicle_chars)
+    # Compatile service and vehicle
+    # if the vehicle cannot serve the service due to sticky_vehicle_id
+    return false if !service_chars[:v_id].empty? && (service_chars[:v_id] & vehicle_chars[:id]).empty?
+
+    # if the service needs a skill that the vehicle doesn't have
+    return false if !(service_chars[:skills] - vehicle_chars[:skills]).empty?
+
+    # if service and vehicle have no matching days
+    return false if (service_chars[:day_skills] & vehicle_chars[:day_skills]).empty?
+
+    true # if not, they are compatible
+  end
+
+  def compute_limits(cut_symbol, cut_ratio, vehicles, data_items)
+    strict_limits = vehicles.collect{ |vehicle|
+      s_l = { duration: vehicle[:duration] } # incase duration is not supplied inside the capacities
+      vehicle[:capacities]&.each{ |unit, limit|
+        s_l[unit] = limit
+      }
+      vehicle[:duration] = s_l[:duration] # incase duration is only supplied inside the capacities
+      vehicle[:capacities] ||= { duration: s_l[:duration] } # incase capacities field were not suplied at all
+      s_l
+    }
+
+    if cut_symbol
+      total_quantity = Hash.new(0)
+      @unit_symbols ||= nil
+      (@unit_symbols || (cut_symbol && [cut_symbol]))&.each{ |unit|
+        total_quantity[unit] = data_items.sum{ |item| item[3][unit].to_f }
+      }
+
+      total_capacity = vehicles.sum{ |vehicle| vehicle[:capacities][cut_symbol].to_f }
+      metric_limits = vehicles.collect{ |vehicle|
+        vehicle_share = total_capacity.positive? ? vehicle[:capacities][cut_symbol] / total_capacity : 1.0 / vehicles.size
+        { limit: cut_ratio * total_quantity[cut_symbol] * vehicle_share }
+      }
+    end
+
+    [strict_limits, metric_limits]
+  end
+end

data/lib/helpers/helper.rb

@@ -0,0 +1,283 @@
+# Copyright © Mapotempo, 2020
+#
+# This file is part of Mapotempo.
+#
+# Mapotempo 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.
+#
+# Mapotempo 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 Mapotempo. If not, see:
+# <http://www.gnu.org/licenses/agpl.html>
+#
+
+module Helper
+  R = 6_378_137 # Earth's radius in meters
+
+  L = 111_321   # Length of a degree (of lon and lat) in meters
+
+  RADIANS_IN_A_DEGREE = Math::PI / 180.0
+
+  BALANCE_VIOLATION_COLOR_LIMITS = [
+    [0.50, 'red'],
+    [0.25, 'purple'],
+    [0.10, 'blue'],
+    [0.05, 'white'],
+    [0.00, 'green']
+  ].freeze
+
+  def self.fixnum_max
+    (2**(0.size * 8 - 2) - 1)
+  end
+
+  def self.fixnum_min
+    -(2**(0.size * 8 - 2))
+  end
+
+  def self.deg2rad(degree)
+    # Converts degrees to radians
+    degree * RADIANS_IN_A_DEGREE
+  end
+
+  def self.approximate_polygon_area(coordinates)
+    # A rudimentary way to calculate area (m^2) from coordinates.
+    # When the shape is vaguely convex, it gives okay results.
+    # https://stackoverflow.com/a/32912727/1200528
+    return 0.0 unless coordinates.size > 2
+
+    area = 0.0
+    coor_p = coordinates.first
+    coordinates[1..-1].each{ |coor|
+      area += deg2rad(coor[1] - coor_p[1]) * (2 + Math.sin(deg2rad(coor_p[0])) + Math.sin(deg2rad(coor[0])))
+      coor_p = coor
+    }
+
+    (area * R**2 / 2).abs
+  end
+
+  def self.approximate_quadrilateral_polygon(coordinates)
+    # Approximates the tetragon of a coordinate list.
+    # First two very distant points (c1 and c2) are selected based on a
+    # random distant point crand and c0.
+    # Then two more points (c3 and c4) are selected on each side of the
+    # line created by c1-c2 to maximize the coverage.
+
+    # c1 and c2 are approximately the most distant two points.
+    crand = coordinates[rand(coordinates.size)]
+    c0 = coordinates.max_by{ |c_i| Helper.flying_distance(crand, c_i) }
+    c1 = coordinates.max_by{ |c_i| Helper.flying_distance(c0, c_i) }
+    c2 = coordinates.max_by{ |c_i| Helper.flying_distance(c1, c_i) }
+
+    # find two points (c3 and c4) on each side of the line passing through c1 and c2
+    # which are the farthest away from the line.
+    c3 = c4 = nil
+    max_distance = { up: 0, down: 0 }
+    coordinates.each{ |c_i|
+      position, distance_to_line = position_and_distance_to_line(c1, c2, c_i)
+
+      if position.positive? && distance_to_line > max_distance[:up]
+        max_distance[:up] = distance_to_line
+        c3 = c_i
+      elsif position.negative? && distance_to_line > max_distance[:down]
+        max_distance[:down] = distance_to_line
+        c4 = c_i
+      end
+    }
+
+    # in case it is a triangle compact it
+    [c1, c3, c2, c4, c1].compact
+  end
+
+  def self.position_and_distance_to_line(l_begin, l_end, point)
+    # position and aproximate distance of a point to the line passing through points (l_begin, l_end)
+    lat_diff = l_end[0] - l_begin[0]
+    lon_diff = l_end[1] - l_begin[1]
+
+    [
+      position = lat_diff * (point[1] - l_begin[1]) - lon_diff * (point[0] - l_begin[0]),
+      position.abs / Math.sqrt(lat_diff**2 + lon_diff**2)
+    ]
+  end
+
+  def self.compute_approximate_route_time(area, visit_count, speed, total_work_days)
+    # Based on Equation (6) of doi:10.1016/j.cor.2004.07.001
+
+    k1 = 0.765    # a coefficient that depends on the distance metric and routing strategy
+    k2 = 1.45     # is a corrective coefficient (route factor) reflecting the road network impedance
+    k0 = k1 * k2
+
+    total_work_days * k0 * Math.sqrt(area * visit_count / total_work_days**1.5) / speed.to_f
+  end
+
+  def self.flying_distance(loc_a, loc_b)
+    return 0.0 unless loc_a[0] && loc_b[0]
+
+    if (loc_a[0] - loc_b[0]).abs < 30 && [loc_a[0].abs, loc_b[0].abs].max + (loc_a[1] - loc_b[1]).abs < 100
+      # These limits ensures that relative error cannot be much greather than 2%
+      # For a distance like Bordeaux - Berlin, relative error between
+      # euclidean_distance and flying_distance is 0.1%.
+      # That is no need for trigonometric calculation.
+      return euclidean_distance(loc_a, loc_b)
+    end
+
+    deg2rad_loc_a_lat = deg2rad(loc_a[0])
+    deg2rad_loc_b_lat = deg2rad(loc_b[0])
+
+    intermediate = Math.sin((deg2rad_loc_b_lat - deg2rad_loc_a_lat) / 2)**2 +
+                   Math.sin((deg2rad(loc_b[1]) - deg2rad(loc_a[1])) / 2)**2 * Math.cos(deg2rad_loc_b_lat) * Math.cos(deg2rad_loc_a_lat)
+
+    R * 2 * Math.atan2(Math.sqrt(intermediate), Math.sqrt(1 - intermediate))
+  end
+
+  def self.euclidean_distance(loc_a, loc_b)
+    return 0.0 unless loc_a[0] && loc_b[0]
+
+    delta_lat = loc_a[0] - loc_b[0]
+    delta_lon = (loc_a[1] - loc_b[1]) * Math.cos(deg2rad((loc_a[0] + loc_b[0]) / 2.0)) # Correct the length of a lon difference with cosine of avereage latitude
+
+    L * Math.sqrt(delta_lat**2 + delta_lon**2)
+  end
+
+  def self.unsquared_matrix(matrix, a_indices, b_indices)
+    a_indices.map{ |a|
+      b_indices.map { |b|
+        matrix[b][a]
+      }
+    }
+  end
+
+  def self.check_if_projection_inside_the_line_segment(point_coord, line_beg_coord, line_end_coord, margin)
+    # margin: if (0 > margin > 1), the percentage of the line segment that will be considered as "outside"
+    # margin: if (margin < 0), the percentage that the "inside" zone is extended
+    # [0, 1]: coordinates [lat, lon] or [lon, lat]
+    line_direction = [0, 1].collect{ |i| line_end_coord[i] - line_beg_coord[i] }
+    point_direction = [0, 1].collect{ |i| point_coord[i] - line_beg_coord[i] }
+
+    projection_scaler = [0, 1].sum{ |i| line_direction[i] * point_direction[i] } / [0, 1].sum{ |i| line_direction[i]**2 }
+    # If projection_scaler
+    # >1:        the projection is after the line segment end
+    # <0:        it is before the line segment begin
+    # otherwise: it is on the line segment define by begin_coord end end_coord
+
+    # If the following holds, it is inside the margin of the line segment
+    projection_scaler >= 0 + 0.5 * margin && projection_scaler <= 1 - 0.5 * margin
+  end
+
+  def self.colorize_balance_violations(balance_violations)
+    balance_violations.collect{ |i|
+      i = i.round(2)
+
+      color_index = 0
+      BALANCE_VIOLATION_COLOR_LIMITS.each{ |cl|
+        break if i.abs >= cl[0]
+
+        color_index += 1
+      }
+
+      i.to_s.send("#{BALANCE_VIOLATION_COLOR_LIMITS[color_index][1]}#{i.negative? ? 'ish' : ''}")
+    }
+  end
+
+  def self.output_cluster_stats(centroids, logger = nil)
+    return unless logger
+
+    header = %w[
+      zone
+      nb_vehicles
+      capacities
+      skills
+      nb_visits
+      total_duration(excel_format)
+      total_visit_duration
+      total_intra_zone_route_duration
+      total_depot_route_duration
+    ]
+    rows = centroids.map.with_index do |c, i|
+      props = c[4] || {}
+      load = c[3] || {}
+      visit_duration = load[:duration].to_f
+      route_time = props[:route_time].to_f
+      depot_duration = props[:duration_from_and_to_depot].to_f
+      work_days = (props[:total_work_days] || 1).to_f
+
+      [
+        i + 1,
+        props[:vehicle_count],
+        props[:capacities],
+        props[:skills],
+        props[:visit_count],
+        (visit_duration + route_time + depot_duration * work_days) / 86400,
+        visit_duration / 86400,
+        route_time / 86400,
+        (depot_duration * work_days) / 86400
+      ].join(',')
+    end
+
+    logger.debug "cluster_stats:\n#{header.join(',')}\n#{rows.join("\n")}"
+  end
+end
+
+# Some functions for convenience
+# In the same vein as active_support Enumerable.sum implementation
+module Enumerable
+  # Provide the average on an array
+  #  [5, 15, 7].mean # => 9.0
+  def mean(type = :arithmetic)
+    return nil if empty?
+
+    case type
+    when :arithmetic
+      inject(0) { |sum, x| sum + x } / size.to_f
+    when :geometric
+      # can overflow for large inputs
+      reduce(:*)**(1.0 / size) if all?(&:positive?)
+    else
+      raise RuntimeError, "Unknown mean type: #{type}"
+    end
+  end
+
+  # If the array has an odd number, then simply pick the one in the middle
+  # If the array size is even, then we return the mean of the two middle.
+  #  [5, 15, 7].median # => 7
+  def median(already_sorted = false)
+    return nil if empty?
+
+    ret = already_sorted ? self : sort
+    m_pos = size / 2 # no to_f!
+    size.odd? ? ret[m_pos] : ret[m_pos - 1..m_pos].mean
+  end
+
+  # The mode is the single most popular item in the array.
+  #  [5, 15, 10, 15].mode # => 15
+  def mode
+    modes(false)[0]
+  end
+
+  # In case there are multiple elements with the highest occurence
+  #  [5, 15, 10, 10, 15].modes # => [10, 15]
+  #  [5, 15, 10, 15].modes     # => [15] (Note that modes() returns an array)
+  def modes(find_all = true)
+    return nil if empty?
+
+    histogram = each_with_object(Hash.new(0)) { |n, h| h[n] += 1 }
+    modes = nil
+    histogram.each_pair do |item, times|
+      modes << item if find_all && !modes.nil? && times == modes[0]
+      modes = [times, item] if (modes && times > modes[0]) || (modes.nil? && times > 1)
+    end
+    modes.nil? ? nil : modes[1...modes.size]
+  end
+
+  # group_by like counting routine for convenience
+  def count_by(&block)
+    self.group_by(&block)
+        .map{ |key, items| [key, items&.count] }
+        .to_h
+  end
+
+end

data/lib/helpers/hull.rb

@@ -0,0 +1,188 @@
+# Copyright © Mapotempo, 2019
+#
+# This file is part of Mapotempo.
+#
+# Mapotempo 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.
+#
+# Mapotempo 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 Mapotempo. If not, see:
+# <http://www.gnu.org/licenses/agpl.html>
+#
+
+# Implementation of
+# CONCAVE HULL: A K-NEAREST NEIGHBOURS APPROACH FOR THE COMPUTATION OF THE REGION OCCUPIED BY A SET OF POINTS
+# By Adriano Moreira and Maribel Yasmina Santos
+
+module Hull
+  def self.get_hull(vector)
+    concave_hull(vector, 5) || convex_hull(vector)
+  end
+
+  # vector of unique points
+  def self.concave_hull(vector, k = 3)
+    if vector.size <= 3
+      vector
+    else
+      k = [k, vector.size - 1].min
+      self.concave_hull_(vector, k)
+    end
+  end
+
+  def self.concave_hull_(vector, k = 3)
+    if k == vector.size
+      log 'ConcaveHull build fail'
+      return nil
+    end
+    kk = [[k, 3].max, vector.size - 1].min # make sure k>=3 and k neighbours can be found
+    first_point = vector.min_by{ |i| i[1] } # find min y point
+    hull = [first_point] # initialize the hull with the first point
+    current_point = first_point
+    dataset = vector - [first_point]
+    previous_angle = 0
+    while (current_point != first_point || hull.size == 1) && !dataset.empty?
+      if hull.size == 3
+        dataset += [first_point] # add the firstPoint again
+      end
+      k_nearest_points = nearestpoints(dataset, current_point, kk) # find the nearest neighbours
+      # sort the candidates (neighbours) in descending order of right-hand turn
+      c_points = k_nearest_points.sort_by{ |point| -angle(point, current_point, previous_angle) }
+      its = true
+      i = -1
+      while its && i < c_points.size - 1 # select the first candidate that does not intersects any of the polygon edges
+        i += 1
+        last_point = (c_points[i] == first_point) ? 1 : 0
+        j = 1
+        its = false
+        while !its && j < hull.size - last_point
+          its = intersect?(hull[-1], c_points[i], hull[-j - 1], hull[-j])
+          j += 1
+        end
+      end
+      # since all candidates intersect at least one edge, try again with a higher number of neighbours
+      if its
+        return concave_hull_(vector, kk + 1)
+      end
+
+      previous_angle = angle(c_points[i], current_point)
+      current_point = c_points[i]
+      hull << current_point # a valid candidate was found
+      dataset -= [current_point]
+    end
+
+    # check if all the given points are inside the computed polygon
+    dataset.size.times{ |ii|
+      inside = point_in_polygon(dataset[ii], hull)
+      if !inside
+        # since at least one point is out of the computed polygon, try again with a higher number of neighbours
+        return concave_hull_(vector, kk + 1)
+      end
+    }
+
+    hull
+  end
+
+  def self.convex_hull(vector)
+    log 'Perform Convex hull'
+    vector.sort!{ |a, b| a.last <=> b.last || a.first <=> b.first }.uniq!
+    return vector if vector.size <= 3
+
+    lower = []
+    vector.each{ |point|
+      lower.pop while lower.size > 1 && cross(lower[-2], lower[-1], point) <= 0
+      lower << point
+    }
+    upper = []
+    vector.reverse_each{ |point|
+      upper.pop while upper.size > 1 && cross(upper[-2], upper[-1], point) <= 0
+      upper << point
+    }
+    lower + upper
+  end
+
+  def self.nearestpoints(dataset, current_point, kk)
+    dataset.sort_by { |d|
+      (d[0] - current_point[0])**2 + (d[1] - current_point[1])**2
+    }[0..kk]
+  end
+
+  def self.angle(point, current_point, previous_angle = 0)
+    (Math.atan2(point[1] - current_point[1], point[0] - current_point[0]) - previous_angle) % (Math::PI * 2) - Math::PI
+  end
+
+  def self.intersect?(s1p1, s1p2, s2p1, s2p2)
+    p0_x, p0_y = s1p1
+    p1_x, p1_y = s1p2
+    p2_x, p2_y = s2p1
+    p3_x, p3_y = s2p2
+
+    s10_x = p1_x - p0_x
+    s10_y = p1_y - p0_y
+    s32_x = p3_x - p2_x
+    s32_y = p3_y - p2_y
+
+    denom = s10_x * s32_y - s32_x * s10_y
+    if denom.zero?
+      return false
+    end
+
+    denom_positive = denom > 0
+
+    s02_x = p0_x - p2_x
+    s02_y = p0_y - p2_y
+    s_numer = s10_x * s02_y - s10_y * s02_x
+    if (s_numer < 0) == denom_positive
+      return false
+    end
+
+    t_numer = s32_x * s02_y - s32_y * s02_x
+    if (t_numer < 0) == denom_positive
+      return false
+    end
+
+    if ((s_numer > denom) == denom_positive) || ((t_numer > denom) == denom_positive)
+      return false
+    end
+
+    t = t_numer / denom
+    x = p0_x + (t * s10_x)
+    y = p0_y + (t * s10_y)
+
+    if [s1p1, s1p2, s2p1, s2p2].include?([x, y])
+      return false
+    end
+
+    true
+  end
+
+  def self.point_in_polygon(point, polygon)
+    inside = false
+    size = polygon.size
+    size.times.each{ |i|
+      min, max = [polygon[i][0], polygon[(i + 1) % size][0]].minmax
+      next if min >= point[0] || point[0] > max
+
+      # vertical ray, could return non homogenous result with a point on a vertical edge
+      p = (polygon[i][1] - polygon[(i + 1) % size][1])
+      q = (polygon[i][0] - polygon[(i + 1) % size][0])
+      point_y = (point[0] - polygon[i][0]) * p / q + polygon[i][1]
+      if point_y > point[1]
+        inside = !inside
+      end
+    }
+    inside
+  end
+
+  def self.cross(o, a, b)
+    oy, ox = o
+    ay, ax = a
+    by, bx = b
+    (ax - ox) * (by - oy) - (ay - oy) * (bx - ox)
+  end
+end