but this is a start, and we would like to expand this list in the future.

Sometimes also referred to as the internal transit model. This is OTPs internal model witch is a

unified model of GTFS and Transmodel(NeTEx) relevant for OTP. The model is optimized for transit

routing.


For a given day(start at 04:00 until 04:00+1d), list all patterns relevant for boarding or

alighting on that day. A PatternForDay is included If it runs on that day. When searching for a

pattern, we might have to look at the next or previous day to find an instance e can use as a

starting point for the boarding search.

OTPs internal model will use a fixed time and time zone for all alight and board times. It do not

follow the imported agency/operator time-zone or service time. We will keep enough information to

be able to map back to the service time of the operator/agency. This is important to be able to

match these in real-time updates.

Below are some main important features described.

- Describe the use of BitSet for filtering

- Filtering with request parameters (modes, agencies, lines)

- Filtering to find active patterns for stops reached in last round in Raptor

- Optimizations:

- BitSets should be deduplicated

- A Set can be used to combine all BitSets to eliminate BitSet merge operations

- Cache `merge(stop : BitSet, activePatterns : BitSet) -> BitSet`. Many stops will have the same

set of visiting patterns.

We can use patternMask to find all relevant patterns in a multi-day search - supporting journeys

ending in another day. There is no need to distinguish between scheduled and realtime patterns for

this, just make sure we include the super set.

Here is an example explaining most of the notation used in the diagrams.


- `A ––––– B` Strong reference. There is a relationship between A and B. A and B may reference

each other, but the details are left to the implementation.

- `A ––––> B` Strong reference. There is a relationship between A and B. A has a reference to B.

- `A – – > B` Weak reference/uses: A uses B.

- Composition - `A ♦︎–> B` B is part of A and B is bound to the life-cycle of A.

- Aggregation - `A ♢–> B` B is part of A, but may live when A dies. B is shared.

- The **calendar** package is the main package with all classes inside and its relations outside.

- `(o.o.t.m.network)` means this class belong to the `org.opentripplanner.transit.model.network`

package.

- `<< classifier >>` Used to mark interfaces or group types

- `: RaptorTripPattern` means this class implements/extends `RaptorTripPattern`.

- `(o.o.t.m.network)` means this class belong to the `org.opentripplanner.transit.model.network`

package.

- `#patternIndex` - The pattern is indexed using an [integer index](#indexing-the-main-entities)

UML Diagrams are used to illustrate the model. Colors are used to emphasise relationships,

similarities or just visual grouping. For class diagrams we use a modified version of

- Read(Moment/Interval/Event) - live until the next realtime update

- Dependencies - Be careful when referencing short-lived type from long-lived types

- Safe: Yellow ⟶ Orange ⟶ Red ⟶ Green ⟶ Blue

The issue [#4002 - Transit model refactor for easier integration with RT-updaters and transit model maintenance](https://github.com/opentripplanner/OpenTripPlanner/issues/4002) contains a list of reminding tasks. Also, a lot of code is tagged with:

- `TODO RTM` - Refactor Transit Model

Some concepts and features are excluded from most of the design models - for simplicity. This is

of cause not excluded from the code, but we focus on serving the main use-case - Raptor routing.

- Mutable part of the model used by realtime updaters.

- Views and indexes making it easier for APIs to traverse the model.

- The model focus on relationships, not exact listing of fields and methods.

- Some fields and methods are included to give the reader a better context, but not all.

- Wheelchair accessibility

- Constrained transfers

- Raptor search

- w/ realtime, ignore realtime, include planned-cancellations

- Realtime updates

- Cancel: Trip, Stop, Call(cancel either alighting or boarding, not both)

- Replace/update: Trip, Stop, Call (update on arrival and/or departure times)

- Insert/add: Trip, Stop, (Call, if it does not exist)

- Planned information is kept and it should be possible to revert to planned, previous update is not

- Index (API data queries)

- query(get, find, list) for all entities (Agency, Operator, Route, Trip, Stop ...)

- list Routes, Trips, TripPatterns for stop

- list Rotes, Trips, Calls for a stop in a given period of time

- Frequency based and scheduled trips

- Support late platform assignment

- Support for routing with at least N seats. This requires request scoped patterns.

The diagram show the main access point(`TransitService`) and the main packages and their

dependencies.


(THIS IS WORK IN PROGRESS! The packages are probably almost ok, but the dependencies are not...)

- [framework](framework/package.md) - framework to support other transit model classes.

- basic - Value objects used across multiple packages.

- organization - Agency(*Authority*), operator and contact info

- [calendar](calendar/package.md) - Operating days and patterns on day

Main outline of Raptor[1] Algorithm

- Find the set of patterns[2] matching the request (q : BitSet = pattern indexes)

- Set access times for stops S reached

- Loop N times [3]:

- For all patterns visiting stops with new arrivals

- Board best trip in pattern

- Alight at each stop in pattern

- transfer from all stops reach by transit

1. Raptor, not Range Raptor(not relevant here)

2. By pattern here we mean RaptorTripPattern/RoutingTripPattern

3. N is the max number of transfers in the network

Indexes is used to speed up the plan search. For most indexes we can use regular maps and

references between entities. But, in some cases we want to optimize, and we use `int` based

indexes. For example Raptor keep stop arrivals in big arrays - so Raptor expect the transit model

to pass in a stop index as an int, not the stop reference. In fact, Raptor never access the actual

Stop instance during the search.

% is used as a prefix on fields and methods added to improve performance.

OTP uses int indexes for calendar-intervals, stops, trips, and trip patterns. These indexes allow

us to avoid accessing these objects during the trip routing, and instead look these objects by

their indexes after the search - when creating the itineraries.

All stops are indexed, raptor do not access stops. Raptor keep its state in an array of stop

arrivals, this matches the stop index.

The transit data model is broken into ~24h "periods"s or *operating days*, we reference these

intervals using the **#dayIndex**.

Both a trip reference and an index is returned by Raptor for each transit leg today. We should be

able to use only the index.

RaptorTripPattern are indexed, this allows us to use BitSet to represent a set of patterns. This

comes in handy when we want to find all patterns for a set of stops.