org.cpsolver.ifs.util

## Class DistanceMetric

- java.lang.Object
- - org.cpsolver.ifs.util.DistanceMetric

-     public class DistanceMetric
      extends Object

  Common class for computing distances and back-to-back instructor / student conflicts. When property Distances.Ellipsoid is set, the distances are computed using the given (e.g., WGS84, see `DistanceMetric.Ellipsoid`). In the legacy mode (when ellipsoid is not set), distances are computed using Euclidian distance and 1 unit is considered 10 meters.
  For student back-to-back conflicts, Distances.Speed (in meters per minute) is considered and compared with the break time of the earlier class.
  For instructors, the preference is computed using the distance in meters and the three constants Instructor.NoPreferenceLimit (distance <= limit → no preference), Instructor.DiscouragedLimit (distance <= limit → discouraged), Instructor.ProhibitedLimit (distance <= limit → strongly discouraged), the back-to-back placement is prohibited when the distance is over the last limit.
  Version:
    IFS 1.3 (Iterative Forward Search)
    Copyright (C) 2006 - 2014 Tomáš Müller
    muller@unitime.org
    http://muller.unitime.org
    This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
    This library 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 GNU Lesser General Public License for more details.
    You should have received a copy of the GNU Lesser General Public License along with this library; if not see http://www.gnu.org/licenses/.
  Author:
    Tomáš Müller

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DistanceMetric.Ellipsoid`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DistanceMetric()` Default properties
    `DistanceMetric(DataProperties properties)` Configured using properties
    `DistanceMetric(DistanceMetric.Ellipsoid model)` With provided ellipsoid
    `DistanceMetric(DistanceMetric.Ellipsoid model, double speed)` With provided ellipsoid and student speed
    `DistanceMetric(DistanceMetric m)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addTravelTime(Long roomId1, Long roomId2, Integer travelTimeInMinutes)` Add travel time between two locations
    `protected double` | `deg2rad(double deg)` Degrees to radians
    `boolean` | `doComputeDistanceConflictsBetweenNonBTBClasses()` True if distances should be considered between classes that are NOT back-to-back.
    `int` | `getAllowedDistanceInMinutes()` Allowed distance in minutes (for `HardDistanceConflicts`)
    `int` | `getDistanceHardLimitInMinutes()` Hard distance limit in minutes (for `HardDistanceConflicts`)
    `double` | `getDistanceInMeters(Double lat1, Double lon1, Double lat2, Double lon2)` Deprecated. Use @{link `getDistanceInMeters(Long, Double, Double, Long, Double, Double)` instead (to include travel time matrix when available).
    `double` | `getDistanceInMeters(Long roomId1, Double lat1, Double lon1, Long roomId2, Double lat2, Double lon2)` Return travel distance between two locations.
    `int` | `getDistanceInMinutes(double lat1, double lon1, double lat2, double lon2)` Deprecated. Use @{link `getDistanceInMinutes(Long, Double, Double, Long, Double, Double)` instead (to include travel time matrix when available).
    `Integer` | `getDistanceInMinutes(Long roomId1, Double lat1, Double lon1, Long roomId2, Double lat2, Double lon2)` Return travel time between two locations.
    `int` | `getDistanceLongLimitInMinutes()` Long distance limit in minutes (for display)
    `double` | `getInstructorDiscouragedLimit()` Back-to-back classes in rooms within this limit have discouraged preference
    `double` | `getInstructorLongTravelInMinutes()` When Distances.ComputeDistanceConflictsBetweenNonBTBClasses is enabled, distance limit (in minutes) for a long travel.
    `double` | `getInstructorNoPreferenceLimit()` Back-to-back classes in rooms within this limit have neutral preference
    `double` | `getInstructorProhibitedLimit()` Back-to-back classes in rooms within this limit have strongly discouraged preference, it is prohibited to exceed this limit.
    `int` | `getMaxTravelDistanceInMinutes()` Maximal travel distance between rooms when no coordinates are given
    `String` | `getShortDistanceAccommodationReference()` Reference of the accommodation of students that need short distances
    `Integer` | `getTravelTimeInMinutes(Long roomId1, Long roomId2)` Return travel time between two locations.
    `Map<Long,Map<Long,Integer>>` | `getTravelTimes()` Return travel times matrix
    `boolean` | `isHardDistanceConflictsEnabled()` Hard distance conflicts enabled (for `HardDistanceConflicts`)
    `boolean` | `isLegacy()` True if legacy mode is used (Euclidian distance where 1 unit is 10 meters)
    `static void` | `main(String[] args)` Few tests
    `double` | `minutes2meters(int min)` Converts minutes to meters.
    `void` | `setComputeDistanceConflictsBetweenNonBTBClasses(boolean computeDistanceConflictsBetweenNonBTBClasses)`
    `void` | `setMaxTravelDistanceInMinutes(int maxTravelTime)` Set maximal travel distance between rooms when no coordinates are given

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DistanceMetric

          public DistanceMetric()

      Default properties

    - #### DistanceMetric

          public DistanceMetric(DistanceMetric m)

    - #### DistanceMetric

          public DistanceMetric(DistanceMetric.Ellipsoid model)

      With provided ellipsoid
      Parameters:
        `model` - ellipsoid model

    - #### DistanceMetric

          public DistanceMetric(DistanceMetric.Ellipsoid model,
                                double speed)

      With provided ellipsoid and student speed
      Parameters:
        `model` - ellipsoid model
        `speed` - student speed in meters per minute

    - #### DistanceMetric

          public DistanceMetric(DataProperties properties)

      Configured using properties
      Parameters:
        `properties` - solver configuration

  - ### Method Detail

    - #### deg2rad

          protected double deg2rad(double deg)

      Degrees to radians
      Parameters:
        `deg` - degrees
      Returns:
        radians

    - #### getDistanceInMeters

          @Deprecated
          public double getDistanceInMeters(Double lat1,
                                                        Double lon1,
                                                        Double lat2,
                                                        Double lon2)

      Deprecated. Use @{link `getDistanceInMeters(Long, Double, Double, Long, Double, Double)` instead (to include travel time matrix when available).
      Compute distance between the two given coordinates
      Parameters:
        `lat1` - first coordinate's latitude
        `lon1` - first coordinate's longitude
        `lat2` - second coordinate's latitude
        `lon2` - second coordinate's longitude
      Returns:
        distance in meters

    - #### getDistanceInMinutes

          @Deprecated
          public int getDistanceInMinutes(double lat1,
                                                      double lon1,
                                                      double lat2,
                                                      double lon2)

      Deprecated. Use @{link `getDistanceInMinutes(Long, Double, Double, Long, Double, Double)` instead (to include travel time matrix when available).
      Compute distance in minutes. Property Distances.Speed (in meters per minute) is used to convert meters to minutes, defaults to 1000 meters per 15 minutes (that means 66.67 meters per minute).
      Parameters:
        `lat1` - first coordinate's latitude
        `lon1` - first coordinate's longitude
        `lat2` - second coordinate's latitude
        `lon2` - second coordinate's longitude
      Returns:
        distance in minutes

    - #### minutes2meters

          public double minutes2meters(int min)

      Converts minutes to meters. Property Distances.Speed (in meters per minute) is used, defaults to 1000 meters per 15 minutes.
      Parameters:
        `min` - minutes to travel
      Returns:
        meters to travel

    - #### getInstructorNoPreferenceLimit

          public double getInstructorNoPreferenceLimit()

      Back-to-back classes in rooms within this limit have neutral preference
      Returns:
        limit in meters

    - #### getInstructorDiscouragedLimit

          public double getInstructorDiscouragedLimit()

      Back-to-back classes in rooms within this limit have discouraged preference
      Returns:
        limit in meters

    - #### getInstructorProhibitedLimit

          public double getInstructorProhibitedLimit()

      Back-to-back classes in rooms within this limit have strongly discouraged preference, it is prohibited to exceed this limit.
      Returns:
        limit in meters

    - #### getInstructorLongTravelInMinutes

          public double getInstructorLongTravelInMinutes()

      When Distances.ComputeDistanceConflictsBetweenNonBTBClasses is enabled, distance limit (in minutes) for a long travel.
      Returns:
        travel time in minutes

    - #### isLegacy

          public boolean isLegacy()

      True if legacy mode is used (Euclidian distance where 1 unit is 10 meters)
      Returns:
        true if the ellipsoid model is the old one

    - #### getMaxTravelDistanceInMinutes

          public int getMaxTravelDistanceInMinutes()

      Maximal travel distance between rooms when no coordinates are given
      Returns:
        travel time in minutes

    - #### setMaxTravelDistanceInMinutes

          public void setMaxTravelDistanceInMinutes(int maxTravelTime)

      Set maximal travel distance between rooms when no coordinates are given
      Parameters:
        `maxTravelTime` - max travel time in minutes

    - #### addTravelTime

          public void addTravelTime(Long roomId1,
                                    Long roomId2,
                                    Integer travelTimeInMinutes)

      Add travel time between two locations
      Parameters:
        `roomId1` - first room's id
        `roomId2` - second room's id
        `travelTimeInMinutes` - travel time in minutes

    - #### getTravelTimeInMinutes

          public Integer getTravelTimeInMinutes(Long roomId1,
                                                Long roomId2)

      Return travel time between two locations.
      Parameters:
        `roomId1` - first room's id
        `roomId2` - second room's id
      Returns:
        travel time in minutes

    - #### getDistanceInMinutes

          public Integer getDistanceInMinutes(Long roomId1,
                                              Double lat1,
                                              Double lon1,
                                              Long roomId2,
                                              Double lat2,
                                              Double lon2)

      Return travel time between two locations. Travel times are used when available, use coordinates otherwise.
      Parameters:
        `roomId1` - first room's id
        `lat1` - first room's latitude
        `lon1` - first room's longitude
        `roomId2` - second room's id
        `lat2` - second room's latitude
        `lon2` - second room's longitude
      Returns:
        distance in minutes

    - #### getDistanceInMeters

          public double getDistanceInMeters(Long roomId1,
                                            Double lat1,
                                            Double lon1,
                                            Long roomId2,
                                            Double lat2,
                                            Double lon2)

      Return travel distance between two locations. Travel times are used when available, use coordinates otherwise
      Parameters:
        `roomId1` - first room's id
        `lat1` - first room's latitude
        `lon1` - first room's longitude
        `roomId2` - second room's id
        `lat2` - second room's latitude
        `lon2` - second room's longitude
      Returns:
        distance in meters

    - #### getTravelTimes

          public Map<Long,Map<Long,Integer>> getTravelTimes()

      Return travel times matrix
      Returns:
        travel times matrix

    - #### doComputeDistanceConflictsBetweenNonBTBClasses

          public boolean doComputeDistanceConflictsBetweenNonBTBClasses()

      True if distances should be considered between classes that are NOT back-to-back. Distance in minutes is then to be compared with the difference between end of the last class and start of the second class plus break time of the first class.
      Returns:
        true if distances should be considered between classes that are NOT back-to-back

    - #### setComputeDistanceConflictsBetweenNonBTBClasses

          public void setComputeDistanceConflictsBetweenNonBTBClasses(boolean computeDistanceConflictsBetweenNonBTBClasses)

    - #### getShortDistanceAccommodationReference

          public String getShortDistanceAccommodationReference()

      Reference of the accommodation of students that need short distances

    - #### getAllowedDistanceInMinutes

          public int getAllowedDistanceInMinutes()

      Allowed distance in minutes (for `HardDistanceConflicts`)

    - #### getDistanceHardLimitInMinutes

          public int getDistanceHardLimitInMinutes()

      Hard distance limit in minutes (for `HardDistanceConflicts`)

    - #### getDistanceLongLimitInMinutes

          public int getDistanceLongLimitInMinutes()

      Long distance limit in minutes (for display)

    - #### isHardDistanceConflictsEnabled

          public boolean isHardDistanceConflictsEnabled()

      Hard distance conflicts enabled (for `HardDistanceConflicts`)

    - #### main

          public static void main(String[] args)

      Few tests
      Parameters:
        `args` - program arguments