org.opentripplanner.transit.raptor.api.request.DynamicSearchWindowCoefficients Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of otp Show documentation
The OpenTripPlanner multimodal journey planning system
There is a newer version: 2.5.0
package org.opentripplanner.transit.raptor.api.request;


/**
 * The dynamic search window coefficients is used to calculate EDT(earliest-departure-time),
 * LAT(latest-arrival-time) and SW(raptor-search-window) request parameters using heuristics.
 * The heuristics perform a Raptor search (one-iteration) to find a trip witch we use to find a
 * lower bound for the travel duration time - the "minTripTime". The heuristic search is used for
 * other purposes too, and is very fast.
 * 
 * At least the EDT or the LAT must be passed into Raptor to perform a Range Raptor search. If
 * unknown/missing the parameters(EDT, LAT, DW) is dynamically calculated. The dynamic coefficients
 * affect the performance and should be tuned to match the deployment.
 * 

 * The request parameters are calculated like this:
 * 
 *     DW  = round_N(C + T * minTripTime)
 *     LAT = EDT + DW + minTripTime
 *     EDT = LAT - (DW + minTripTime)
 * 
 * The {@code round_N(...)} method is will round the input to the closest multiplication of N.
 * 
 * The 3 coefficients above are:
 * 

 *     {@code C} - {@link #minWinTimeMinutes()}
 *     {@code T} - {@link #minTripTimeCoefficient()}
 *     {@code N} - {@link #stepMinutes()}
 * 
 * In addition the this an upper bound on the calculation of the search window:
 * {@link #maxWinTimeMinutes()}.
 */
public interface DynamicSearchWindowCoefficients {

    /**
     * {@code T} - The coefficient to multiply with {@code minTripTime}. Use a value between
     * {@code 0.0} to {@code 3.0}. Using {@code 0.0} will give you a raptor-search-window ≈
     * {@link #minWinTimeMinutes()}.
     */
    default double minTripTimeCoefficient() { return 0.75f; }

    /**
     * {@code C} - The constant minimum number of minutes for a raptor search window. Use a value
     * between 20-180 minutes in a normal deployment.
     */
    default int minWinTimeMinutes() { return 40; }

    /**
     * Set an upper limit to the calculation of the dynamic search window to prevent exceptionable
     * cases to cause very long search windows. Long search windows consumes a lot of resources and
     * may take a long time. Use this parameter to tune the desired maximum search time.
     * 
     * This is the parameter that affect the response time most, the downside is that a search is
     * only guarantied to be pareto-optimal within a search-window.
     * 

     * The default is 3 hours. The unit is minutes.
     */
    default int maxWinTimeMinutes() { return 3 * 60; }

    /**
     * {@code N} - The search window is rounded of to the closest multiplication of N minutes.
     * If N=10 minutes, the search-window can be 10, 20, 30 ... minutes. It the computed
     * search-window is 5 minutes and 17 seconds it will be rounded up to 10 minutes.
     * 
     * Use a value between {@code 1 and 60}. This should be less than the {@code C}
     * (min-raptor-search-window) coefficient.
     */
    default int stepMinutes() { return 10; }
}