org.opentripplanner.transit.raptor.rangeraptor.transit.TransitCalculator Maven / Gradle / Ivy
Show all versions of otp Show documentation
package org.opentripplanner.transit.raptor.rangeraptor.transit;
import static org.opentripplanner.util.time.TimeUtils.hm2time;
import java.util.Iterator;
import org.opentripplanner.transit.raptor.api.request.SearchParams;
import org.opentripplanner.transit.raptor.api.transit.IntIterator;
import org.opentripplanner.transit.raptor.api.transit.RaptorConstrainedTripScheduleBoardingSearch;
import org.opentripplanner.transit.raptor.api.transit.RaptorRoute;
import org.opentripplanner.transit.raptor.api.transit.RaptorTimeTable;
import org.opentripplanner.transit.raptor.api.transit.RaptorTransfer;
import org.opentripplanner.transit.raptor.api.transit.RaptorTransitDataProvider;
import org.opentripplanner.transit.raptor.api.transit.RaptorTripPattern;
import org.opentripplanner.transit.raptor.api.transit.RaptorTripSchedule;
import org.opentripplanner.transit.raptor.api.transit.RaptorTripScheduleSearch;
/**
* The transit calculator is used to calculate transit related stuff, like calculating
* earliest boarding time and time-shifting the access paths.
*
* The calculator is shared between the state, worker and path mapping code. This make the
* calculations consistent and let us hide the request parameters. Hiding the request parameters
* ensure that this calculator is used.
*
* There is one calculator for FORWARD search and one for REVERSE search. The documentation and
* argument names uses a search-direction agnostic vocabulary. We try to use the terms "source" and
* "target", in stead of "from/to" and "board/alight".
*
* -
* In a FORWARD search the "source" means "from" and "TARGET" means "to".
*
* -
* In a BACKWARD search the "source" means "to" and "TARGET" means "from". The traversal of the
* graph happens from the destination towards the origin - backwards in time. The "from/to"
* refer to the "natural way" we think about a journey, while "source/target" the destination
* is the source and the origin is the target in a BACKWARD search.
*
*
* "Source" and "target" may apply to stop-arrival, trip, board-/aligh-slack, and so on.
*
* For a BACKWORD search the "source" means "from" (stop-arrival, trip, and so on).
*
* @param The TripSchedule type defined by the user of the raptor API.
*/
public interface TransitCalculator extends TimeCalculator {
/**
* For a forward search return the trip arrival time at stop position including alightSlack.
* For a reverse search return the next trips departure time at stop position with the
* boardSlack added.
*
* @param trip the current boarded trip
* @param stopPositionInPattern the stop position/index
*/
int stopArrivalTime(T trip, int stopPositionInPattern, int slack);
/**
* Stop the search when the time exceeds the latest-acceptable-arrival-time.
* In a reverse search this is the earliest acceptable departure time.
*
* @return true if time exceeds limit, false means good to go.
*/
boolean exceedsTimeLimit(int time);
/**
* Return a reason why a arrival time do not pass the {@link #exceedsTimeLimit(int)}
*/
String exceedsTimeLimitReason();
/**
* Selects the earliest or latest possible departure time depending on the direction.
* For forward search it will be the earliest possible departure time, while for reverse search
* it uses the latest arrival time.
*
* Returns -1 if transfer is not possible after the requested departure time
*/
int departureTime(RaptorTransfer transfer, int departureTime);
/**
* Return an iterator, iterating over the minutes in the RangeRaptor algorithm.
*/
IntIterator rangeRaptorMinutes();
/**
* Return TRUE if the Range Raptor should perform only ONE iteration.
* This is defined happens if the search window is less than or equals
* to the iteration step duration.
*/
boolean oneIterationOnly();
/**
* Return an iterator, iterating over the stop positions in a pattern.
* Iterate from '0' to 'nStopsInPattern - 1' in a forward search and from
* 'nStopsInPattern - 1' to '0' in a reverse search.
*
* @param nStopsInPattern the number of stops in the trip pattern
*/
IntIterator patternStopIterator(int nStopsInPattern);
/**
* Create a trip search, to use to find the correct trip to board/alight for
* a given pattern. This is used to to inject a forward or reverse
* search into the worker (strategy design pattern).
*
* @param timeTable the trip time-table to search
* @return The trip search strategy implementation.
*/
RaptorTripScheduleSearch createTripSearch(RaptorTimeTable timeTable);
/**
* Same as {@link #createTripSearch(RaptorTimeTable)}, but create a
* trip search that only accept exact trip timeLimit matches.
*/
RaptorTripScheduleSearch createExactTripSearch(RaptorTimeTable timeTable);
/**
* Return a transfer provider for the given pattern. When searching forward the
* given {@code target} is the TO pattern/stop, while when searching in reverse the given
* target is the FROM pattern/stop.
*/
RaptorConstrainedTripScheduleBoardingSearch transferConstraintsSearch(RaptorRoute route);
/**
* Return a calculator for test purpose. The following parameters are fixed:
*
* - 'binaryTripSearchThreshold' = 10
*
- 'earliestDepartureTime' = 08:00:00
*
- 'latestArrivalTime', = 10:00:00
*
- 'iterationStep' = 60 seconds
*
* @param forward if true create a calculator for forward search, if false search
*/
static TransitCalculator testDummyCalculator(boolean forward) {
return forward
? new ForwardTransitCalculator<>(
10,
hm2time(8,0),
2 * 60 * 60, // 2 hours
TIME_NOT_SET,
60
)
: new ReverseTransitCalculator<>(
10,
hm2time(8,0),
2 * 60 * 60, // 2 hours
TIME_NOT_SET,
60
);
}
/**
* Return {@code true} if it is allowed/possible to board at a particular stop index, on a
* normal search. For a backwards search, it checks for alighting instead. This should include
* checks like: Does the pattern allow boarding at the given stop? Is this accessible to
* wheelchairs (if requested).
*/
boolean boardingPossibleAt(RaptorTripPattern pattern, int stopPos);
/**
* Same as {@link #boardingPossibleAt(RaptorTripPattern, int)}, but for switched alighting/boarding.
*/
boolean alightingPossibleAt(RaptorTripPattern pattern, int stopPos);
/**
* Returns an iterator over all transfers "from" (or "to" for reverse searches) a stopIndex.
*
* @see RaptorTransitDataProvider#getTransfersFromStop(int)
* @see RaptorTransitDataProvider#getTransfersToStop(int)
*/
Iterator getTransfers(RaptorTransitDataProvider transitDataProvider, int fromStop);
}