Public transport

This page describes how the model builds the public transport part of a journey. That part is a chain of rides and transfers from a first boarding stop to a last alighting stop, with its travel time and price. The model computes the chains once per analysis date and part of the day, for all stops, and stores them in the chain cache. From chains to journeys describes how the output step puts a walking or cycling leg before and after a chain, per departure moment.

Contents

See also: Create routable network from GTFS files for the network that this page starts from, Public transport fares for the price of a single ride, and Script reference for the templates and their items.


Why chains

Public transport differs from walking, cycling and the car in two ways.

  • The departure time matters. A traveller cannot board a vehicle that has already left, and waiting costs time. The model therefore works in a time-expanded graph, in which a node is a stop at a moment.
  • The Dutch fare system does not add up per link. Regional transport charges a boarding fare once per fare journey, plus a price per kilometre. NS charges a fare between the first and the last station of an NS journey, and a journey by train that changes between NS and a regional train agency pays one boarding fare. One Dijkstra search over all public transport cannot compute such a price.

The model therefore first computes the rides within one fare group. It then joins rides through transfers into chains and computes the price again at every join. A chain grows by one transfer per round, as in the RAPTOR algorithm, up to Max_transfers (3) transfers. The steps:

  1. The timetable within the time window becomes a time-expanded graph (Get_Windowed_Agency_Set_T).
  2. The graph is split into two fare groups: regional transport (Set_R) and the NS fare network (Set_L).
  3. A Dijkstra search per fare group gives the rides, OD_R and OD_L, each with its price (MakeODs.dms).
  4. The transfers connect the arrival of a ride to the departure of a next ride (CreateTransfers_T, Transfers.dms).
  5. The chain joiner joins chains, transfers and rides in rounds, with the price of the chain and a Pareto selection (ChainJoiner_T).
  6. Per stop block the Pareto front of the chains goes to the chain cache (ChainGeneration_PerBlock_T).

Demand-responsive transport (flex) takes part in steps 1, 3 and 5; it has a section of its own.


Step 1: the network in the time window

The time-expanded graph

A link of the public transport network (SourceData/Infrastructure/GTFS/PublicTransportNet) is one of two kinds. A scheduled link is a vehicle travelling from one stop to the next. A waiting link is the time that a vehicle stands still at a stop within its trip. Each link has a departure event and an arrival event. Get_Windowed_Agency_Set_T turns the links into a graph:

  1. It selects the links that depart at or after the first departure moment (impl/FirstDepartureMoment), arrive before the end of the time window (impl/LastArrivalMoment), take at most MaxPTTime (90 min), and belong to the fare group (step 2).
  2. It takes the departure and the arrival of every link as a combination of time, stop and route, and keeps the unique ones: the NodeSet.
  3. F1 and F2 of a link point to its departure node and its arrival node. They are the from-node and the to-node of the Dijkstra search in step 3.

No link runs back in time, so time never decreases along a path. A scheduled link can take 0 seconds: the feed gives whole minutes, and a vehicle often reaches the next stop in the same minute. Such a link joins two nodes with the same time; without it, a ride would end at the stop where the link begins (#172). Because a node includes the route, a path cannot change from one route to another: a ride follows one route, with one boarding. A change of vehicle is always a transfer, in step 5.

The time window

The window runs from the first departure moment of the run to Impl/PT_LastArrivalMoment. That moment is the last departure moment plus MaxPTTime, plus Advanced/MaxWaitingTimeAtOrigin (899 s) when the waiting at home does not count in the travel time (Advanced/IncludeWaitingAtHomeInTravelTime, default FALSE). In the morning rush hour, with departure moments from 07:00 to 07:45, the window runs from 07:00 to 09:29 (PublicTransport_Prep/PT_Chains_Window).

Events as numbers

An event, a stop at a moment, is one uint64 of the unit c_Time_Stops:

c_Time_Stop_rel = time_index * #Stops + stop_index

Division and remainder give the time and the stop back. Every join between rides, transfers and chains is an equality join on such numbers.

Step 2: two fare groups

The model splits the network by fare into two sets. Each is a selection of Get_Windowed_Agency_Set_T in PublicTransport_Prep/impl:

  • Set_R, regional transport outside the NS fare network: the links of every agency that is not NS (Classifications/Agencies/IsRO). IsRO is the opposite of IsNS, which marks NS, NS International and European Sleeper. Foreign carriers such as NMBS, De Lijn, VIAS, DB and Eurobahn are in this set and get their price from the fare table. The set takes a link by the agency of its route (PTnet_prep/IsRegionalLink), so that it also holds the waiting links of these trips, which have no agency of their own. Without them, a regional ride could not continue past a stop where the vehicle stands still.
  • Set_L, the NS fare network: the links of NS and, with Advanced/IsNSInternationalInLnet (default TRUE, #3), of NS International (Agencies/IsLnet). The set leaves out the trains on which an NS ticket is never valid (Routes/IsWithoutNSTicket: the route names in OVprijzen/NS/TrainsWithoutNSTicket, Eurostar, Thalys, Nightjet and European Sleeper). It also holds the waiting links at NS stations. Without them, an NS ride could not continue past a station where the train stops.

European Sleeper is therefore in neither set. Both sets keep only the links over which a ride can run (PTnet_prep/IsRideLink): a link that takes time, or a scheduled link of 0 seconds between two different stops (step 1). With Advanced/IncludeFlex FALSE both lose the links of flex routes.

Step 3: the rides

OD_R and OD_L run the GeoDMS operator impedance_matrix (Dijkstra) over Set_R and Set_L, from every node to every node that it reaches:

  • The impedance is the scheduled Duration, and the search stops at MaxPTTime.
  • The alternative impedance is Length, so that every ride also carries the distance travelled in km (alt_imp).
  • OD_R uses the pareto option (Advanced/ParetoLegs_R, default TRUE, #19, #115). All paths between two nodes take the same time, and with this option the search keeps the shortest of them, which is the cheapest in the regional fare. OD_L does not need it (ParetoLegs_L FALSE), because the NS fare depends on the first and the last station and not on the distance.

The filters

OD_R/Result and OD_L/Result keep the rides that pass these filters:

  • The boarding stop and the alighting stop are not in the same stop cluster (IsStartEndWithinSameStopCluster). A stop cluster is a pair of stops within Advanced/DistanceStopClusters (100 m) of each other, such as two platforms of one station, or a stop with itself.
  • The GTFS allows boarding at the start and alighting at the end (IsBoardAlightAllowed: pickup_type and drop_off_type in stop_times.txt are not 1; #3).
  • OD_R only: the ride does not lie abroad (IsOD_completely_foreign): it is not a ride of an agency that runs abroad (Classifications/Agencies/IsForeign) with both its boarding and its alighting stop outside the Dutch concession areas. A crossing of a ferry whose piers lie outside the areas stays (#150).
  • OD_L only: the ride is domestic (IsDomesticRide): a ride of NS, or a ride between two NS stations in the Netherlands that has an NS fare, such as NS International within the country.
  • With extra time on flex rides (OD_R) or on rides with a trip surcharge (OD_L), the travel time including that extra time is at most MaxPTTime.

The price of a ride

The fares themselves are on Public transport fares. Per ride the model keeps the parts of the price that the chain joiner combines in different ways:

Part Fare group What it is
Price_I R the boarding fare (FixedPrice) of the fare table row of the ride
Price_O R the price per km (VariablePrice) times the distance of the ride, plus Advanced/FlexCallCosts on a flex ride
Price_L L the NS fare between the NS stations of the boarding and the alighting stop (TariffUnitsMatrix)
Price_S L and R in L the trip surcharge of a special train (OVprijzen/NS/TripSurchargeTrains, #3), with Advanced/IncludeTripSurcharge; in R the fixed fare per ride (#55) or the surcharge per ride (#164) of the fare table row of the ride

What a ride carries

Besides price and travel time, every ride carries what the next steps need:

  • its boarding event and alighting event as row numbers in uq_c_FromTime_Stop and uq_c_ToTime_Stop, the unique events of all rides of both fare groups; these are the keys of all later joins;
  • for the fare rules of step 5: BoardingTime_RO, Last_RO_AlightTime and Last_RO_IsTrain on a regional ride, BoardingTime_NS and Last_NS_AlightTime on an NS ride, and First_NS_Station and Last_NS_Station;
  • for the train journey of step 5: TrainJourney_TE, the tariff units of a train, and Last_Train_AlightTime, and on a regional train its fare rule per tariff unit (TariffUnitFareTable_rel, PricePerTariffUnit and MinFareDistance), so that the chain joiner can price it over the tariff units of the whole train journey;
  • its mode as ModeCode (the mode id plus 1), and its distance per mode (TravelDist_Bus to TravelDist_Ferry).

Step 4: the transfers

A transfer takes the traveller from the alighting stop of one ride to the boarding stop of the next ride. The traveller changes at the same stop or walks to a stop nearby, and then waits for the next vehicle. Transfers.dms makes four sets with CreateTransfers_T, one per pair of fare groups: Transfers_R_R, Transfers_R_L, Transfers_L_L and Transfers_L_R (the first letter is the fare group of the arriving ride).

Candidates

  1. The template reduces the arrivals of the first set and the departures of the second set to their unique events (Uq_From, Uq_To), because many rides share an event.
  2. join_near_values_uint32 pairs every arrival with every departure within Advanced/MaxTransferDist (500 m, straight line).
  3. Per pair the template computes the walking distance (Walking_Dist, straight line) and the walking time at Advanced/TransferEffectiveSpeed: TransferWalkingSpeed (4.5 km/h) divided by the detour factor TransferDetourFactor (1.2). It also computes the transfer time (Transfer_Time_rel, the departure minus the arrival) and the waiting time at the next stop (WaitingAtStop_Time_rel, the transfer time minus the walking time).

Valid transfers

A transfer is valid (IsValidTransfer) when:

  • the transfer time is at least the minimum transfer time (below);
  • the next vehicle departs strictly after the arrival, so that a transfer always takes time, also at the same stop;
  • the transfer time is at most MaxPTTime.

The minimum transfer time

The minimum transfer time is the walking time, except between two different stops (platforms) of the same NS station that both have a transfer time in the NS timetable. There it is at least that transfer time (#123). Within a station, the walking time over the straight distance is too short: 0.7 minutes from platform 1 to platform 5 at Utrecht Centraal, where 9292 requires 4 to 6 minutes.

  • The transfer times come from the station list (stations.dat) of the IFF timetable of the NDOV Loket. The model reads the delivery of ModelParameters/IFF_file_date (13 October 2026) as SourceData/Infrastructure/Infrastructure/IFF_Stations. The transfer time is 5 minutes at the 44 major hubs, such as Utrecht Centraal, Amsterdam Centraal and Zwolle, and 4 or 2 minutes elsewhere.
  • The station of a stop is its NS station (Stops/NS_Stations_rel), whose code is the IFF code; the transfer time of the stop is Stops/IFF_TransferTime_rel.
  • Advanced/IFF_TransferTime (default TRUE) switches this rule; the chain cache carries _iff<date> in its signature.
  • The model does not use the exceptions per pair of trains in changes.dat. They include shorter transfers across one platform, so the model may reject such a transfer that the timetable plans.

Example: in the morning rush of 2023, the walking time alone allows 154,354 NS-to-NS transfers, and the IFF times make 6,643 of them (4.3%) invalid.

Costs and keys

Every valid transfer gets a cost, Time_cost: the walking minutes times Transfer_Walking_Time_Costs (0.19 euro per minute) plus the waiting minutes times Transfer_Waiting_Time_Costs (0.05 euro per minute), each rounded to cents. It counts in Price_augm of the chain, not in Price. The keys for step 5 are uq_c_Exit_rel, the arrival event in uq_c_ToTime_Stop, and uq_c_Reboard_rel, the departure event in uq_c_FromTime_Stop.

Step 5: the chains

Which chains

Classifications/Chains lists the chain types: every string of 1 to Max_transfers + 1 letters R and L. With the default of 3 transfers that is 2 + 4 + 8 + 16 = 30 types (R, L, RR, RL, LR, LL, RRR, and so on). A type of two or more letters is its left part, all letters but the last, joined through a transfer to one ride of the last letter. RLR, for example, is a chain of type RL, a transfer of Transfers_L_R and a ride of OD_R. So the model computes a type from the type one letter shorter. It computes every type, and every type takes part in the result (Chains/ToBeCalculated and Chains/Allowed); the price rules below handle every combination of fare groups.

Stop blocks

The chain step works per stop block, to limit its memory:

  1. The stops get a random order (BlockSelections/rnd_rel, rnd_permutation) and are cut into Advanced/NumberOfStopBlocks (500) blocks of at most Advanced/MaxStopBlockSize (104) stops. The random order spreads busy stops evenly over the blocks.
  2. Per block, ChainGeneration_PerBlock_T restricts the one-ride types R and L to the rides that board at a stop of the block, no later than Impl/PT_LastBoardingMoment (see Keeping the chain step small).
  3. The transfers and the right ride of every join are not restricted, so a chain that boards in the block can transfer anywhere and reach every stop.

In the OD pair mode (Impl/IsOD, see Routes of an OD pair) the blocks hold only the stops where a pre-transport leg of the origin ends (impl/OD_VStops). There are as many blocks as these stops need with at most MaxStopBlockSize stops per block (impl/NrStopBlocks), and the stops go to the blocks one by one in a random order, so that the blocks differ by at most one stop in size.

The join

ChainJoiner_T joins in two steps with join_equal_values_uint64, which makes only the pairs with equal keys, and selects between them:

  1. Join_Left_Transf0 joins every left chain to every transfer that starts at its arrival event (uq_c_ToTime_Stop_rel equals uq_c_Exit_rel). Join_Left_Transf keeps the pairs that can still stay within MaxPTTime with the shortest right ride.
  2. Join_Left_Transf_Pareto keeps of those pairs only the ones that no other pair of their group beats (#151). A group is the boarding event of the left chain, the boarding event at the end of the transfer, the first NS station of the open NS journey and the tariff units of a train journey that a next train can continue (TE_key, see The Pareto selection in the chain joiner). With a grade-separated transfer penalty (Advanced/GradeSeparatedTransferPenalty above 0), the group also holds whether the last ride of the left chain is boarded at street level, because the penalty of the transfer depends on it. All pairs of a group reach the same right rides at the same moment. They differ only in their travel time (a flex ride or a trip surcharge adds time), in what they have paid and in how their fare journeys can still continue. The criteria are the travel time, the sum of the price parts that later rides only add to (Price_S, Price_F and Price_O, and the time costs Price_T when the front chooses on Price_augm), the boarding fare Price_I, the time since the last check-out from a regional ride, and TrainState, which says whether a next train continues the train journey of the chain or a next regional train shares its boarding fare. A pair with an open NS journey is only compared with pairs with the same NS fare and the same last NS check-out, because a next NS ride can continue the journey in one case and start a new one in the other. The selection changes no chain; of two chains with the same price and time it can keep the other one.
  3. Join_LeftT_Right joins every such pair to every right ride that departs at the boarding event of the transfer (uq_c_Reboard_rel equals uq_c_FromTime_Stop_rel).

The new chain takes its boarding event from the left chain and its alighting event from the right ride. In the next round it is the left chain.

Travel time

The travel time of a joined chain is the travel time of the left chain, plus the transfer time (walking and waiting), plus the travel time of the right ride (Traveltime_wo_Penalty). The model adds Advanced/GradeSeparatedTransferPenalty (default 0) when the transfer is not between two modes that are boarded at street level. That is the case for a transfer from or to metro, rail or ferry (Modes/IsStreetLevel 0). The penalty stands for the stairs, escalators and lifts at stations.

Beside the travel time, a chain keeps two parts of it (#146). The first is the walking at its transfers, with the penalty (TransferWalkTime, from Walking_time of the transfers). The second is the waiting at its transfers, and the extra time per boarding of a flex ride or a train with a trip surcharge (PTWaitTime). It comes from WaitingAtStop_time of the transfers, from Advanced/FlexExtraWaitingTime of a ride on a flex line, and from the extra time of a train with a trip surcharge (OVprijzen/NS/TripSurchargeTrains/ExtraTime, 0 by default). The travel time of such a ride holds its extra time as well. A ride is one boarding, so it walks no transfer. The walking of a transfer is the straight-line distance between its two stops at Advanced/TransferEffectiveSpeed, and the rest of its transfer time is waiting. So a transfer between two trains that use the same stop of the feed has no walking, and all its transfer time is waiting. The rest of the travel time is the time in the vehicles. The chain cache stores both parts. The output gives them together with the time in the vehicles, InVehicleTime (see Output files).

A joined chain is valid when its boarding stop differs from its alighting stop (IsTravelToSameStop) and its travel time is at most MaxPTTime (IsJourneyLongerThanAllowed). The valid chains are Valid1.

The price of a chain

A chain carries the price parts of step 3, which the chain joiner combines at every join:

  • Price_I, the regional boarding fare. When a regional ride follows another regional ride within Advanced/MaxTransferTimeForBoardingSurcharge (35 min) of the last regional alighting, it continues the fare journey, and only the higher of the two boarding fares counts. Otherwise both count. The test is RO_continuation_allowed: Last_RO_AlightTime of the left chain plus 35 minutes is not before BoardingTime_RO of the right ride. In the model’s terms the second ride is then an O ride (continuation) instead of an R ride (new boarding). A regional ride other than a train, such as a bus, a tram, a metro or a ferry with the OV-chip (not one on a fixed fare per ride), continues the fare journey after any regional ride; a regional train continues it only after a regional train (Last_RO_IsTrain), so a bus and then a regional train pay two boarding fares (#53). A regional train that continues a train journey pays no boarding fare of its own (The train journey).
  • Price_O, the regional price per km: the sum of the rides. A regional train that continues a train journey counts at its price in that journey, minus what that price adds to Price_I as paid boarding fare (Price_I_InTrainJourney, see The train journey).
  • Price_L, the NS fare of the current NS journey. When both the left chain and the right ride have NS, the model looks up the through fare Price_NS. That is the NS fare from the first NS station of the left chain (First_NS_Station) to the last NS station of the right ride:
    • When the left chain ends with an NS ride and the right ride is NS (NS_through_fare_certain), the through fare always applies.
    • With a regional ride in between, the through fare applies under two conditions. The next NS ride boards within 35 minutes of the last NS alighting (NS_transfer_allowed), and the through fare is cheaper than the two fares apart (NS_through_fare_cheaper).
    • When the through fare does not apply, the NS fare of the left chain moves to Price_F and Price_L becomes the fare of the right ride, and when the right ride continues a train journey, its fare in that journey (Right_Price_L).
  • Price_F, the fares of earlier NS journeys, which the later rounds leave as they are.
  • Price_S, the trip surcharges of NS and the fixed fares and surcharges per ride of regional transport: always the sum, and apart from Price_L and Price_I so that a through fare or the highest boarding fare does not lose them.
  • Price_T, the costs of walking and waiting at the transfers: the sum of their Time_cost.

The price is the sum of the parts that the chain has, and the augmented price adds the transfer costs:

Price      = Price_I + Price_O + Price_L + Price_F + Price_S
Price_augm = Price + Price_T

First_NS_Station follows the current NS journey: that of the left chain when the through fare applies, otherwise that of the right ride. Last_NS_Station, Last_NS_AlightTime, Last_RO_AlightTime and Last_RO_IsTrain come from the right ride when it is of that fare group, otherwise from the left chain. TrainJourney_TE adds the tariff units of the right train when it continues the train journey, and otherwise takes those of the right ride; Last_Train_AlightTime is that of the right ride. So the rules apply again when the next round adds a ride.

The train journey

A train journey is a series of consecutive train rides in a chain, of NS and of regional train agencies, with transfers of at most Advanced/MaxTransferTimeForBoardingSurcharge (35 min) between them; any other ride in between ends it. The Dutch fare system prices it as one journey: a transfer between NS and a regional train agency with the OV-chip charges no new boarding fare (Staatsblad 2017, 76, explanatory note; Kamerstukken II 2012/13, 23 645, nr. 523), as the advice Het spoor naar slagkracht (2011, chapter 7) proposed. A ride with the OV-chip is any ride except a regional ride on a fixed fare per ride (IsFixedFareRide). The chain joiner prices a train journey as 9292 does (#53):

  • A train continues the train journey of the left chain when it is a train with the OV-chip that boards within 35 minutes of the alighting from the train that the left chain ends with (TrainContinues).
  • The first train pays its own fare. Every next train pays the fare of its own agency over the tariff units of the train journey up to and including the ride, minus that fare over the tariff units of the trains before it (TrainJourney_TE). NS pays its fare per number of tariff units (OVprijzen/NS/NS_FareByTariffUnits, in Right_Price_L). A regional train pays the fare of its table per tariff unit (OVprijzen/TariffUnitFaresByTable) or its price per km per tariff unit with the minimum distance of its fare rule (Price_O_InTrainJourney). A fare list ends at its highest number of tariff units, and a longer journey pays the fare of that number.
  • A regional train after NS so pays no boarding fare, and NS after a regional train costs less than an NS ticket for the same stretch, because the first tariff units of NS are the most expensive. After a short regional train, NS costs only what the NS fare over the whole train journey exceeds the minimum NS fare. The chain joiner can therefore keep a cheaper but slower chain that a journey planner does not propose, because a planner like 9292 plans on travel time.
  • A regional ride other than a train, such as a bus, within 35 minutes after a regional train in the train journey pays no new boarding fare. The chain counts the price of that regional train as paid boarding fare, up to the boarding fare of the train (Price_I_InTrainJourney); when the train costs less than that, the ride after it pays the rest of its boarding fare.
  • A regional train on a fixed fare per ride is no OV-chip ride: it neither continues nor starts a train journey, so the train after it pays its own fare.
  • A regional train with the OV-chip between stations outside the NS tariff network has no tariff units. It continues a train journey at its price per km, and the journey keeps the tariff units of the trains before it. As the first train it starts no train journey, and the train after it pays its own fare.
  • An NS journey is the NS rides that share one through fare (Price_L); unlike a train journey, it can run on across a regional ride that is not a train, such as a bus. When a train journey comes before an NS journey (NS_TE_before, the tariff units of the trains before its first NS ride), the through fare of the NS journey is the NS fare over the tariff units before it plus those from the first to the last NS station, minus the NS fare over the units before it (Price_NS). With NS, a regional train and NS again, the through fare from the first to the last NS station applies when it is cheaper than the two NS rides at their prices in the train journey; the tariff units of the regional train in between do not count in it. Whether the fare system allows that is not known.

The Pareto selection in the chain joiner

Per round the chain joiner keeps the Pareto-optimal chains of Valid1 per group (Part_key): the boarding event, the alighting event, the first NS station of the current NS journey and the tariff units of a train journey that a next train can continue (TE_key). The group includes the station because the NS fare is degressive. Take two chains to the same event that began their NS journey at different stations. When the next round adds an NS ride at the through fare, they can swap places in price, so the one that is more expensive now must not drop out. The tariff units are in the group for the same reason: a next train pays its fare over the whole train journey minus that over the units before it. More units make a next train sometimes cheaper and sometimes more expensive, so they cannot be a criterion. TE_key stops at TrainJourney_TE_KeyMax, the highest number of tariff units of the NS fare list and of the tables per tariff unit, because from there on a next train pays the same.

The criteria are Classifications/ChainJoinerParetoAttr, in this order:

  1. Price when the final front uses it (MinimiseCriteria), otherwise Price_augm;
  2. remaining_time_excl_RO_transfer and remaining_time_excl_NS_transfer (below);
  3. TravelTime, only when the final front uses the travel time and a ride or transfer can have a time penalty (ChainJoinerParetoAttr_Candidates/HasTimePenalty: GradeSeparatedTransferPenalty, the extra time of flex, or the extra time of a trip surcharge);
  4. Price_augm as a tie-break, when the first criterion is Price;
  5. TrainState: 0 when the chain ends with a train whose train journey a next train can continue, 1 when its last regional ride with the OV-chip is a regional train, after which a next regional train shares the boarding fare, otherwise 2. Less is better, because a next train can then still continue the train journey or share the boarding fare.

Within a group every chain has the same boarding and alighting event. Without a time penalty, every chain then has the same travel time, and the travel time needs no criterion. With a penalty, a chain with more changes of level, a flex ride or a surcharge train has a longer TravelTime. The travel time must then count, or such a chain could stay in place of a faster one.

The remaining times keep a chain that is more expensive now but can still become cheaper. remaining_time_excl_NS_transfer is the time from the end of the through-fare window (the last NS alighting plus 35 minutes) to the end of the time window. remaining_time_excl_RO_transfer is the same for the regional continuation. Both are minimised. A chain whose last NS or regional ride alights later can still give a next ride the through fare or the continuation. So the chain joiner does not drop it against a chain that is only cheaper now.

One sweep with an epsilon

The selection is one call of pareto_optimal_eps (GeoDMS #1282), which sorts the rows of each group and sweeps them once. With the default criteria and a time penalty, its arguments (ChainJoinerParetoAttr/ParetoArgs) are:

pareto_optimal_eps(Part_key, Price,
    remaining_time_excl_RO_transfer, 0.0,
    remaining_time_excl_NS_transfer, 0.0,
    TravelTime, ChainParetoTimeEpsilon,
    Price_augm, 1.0,
    TrainState, 0.0)

The epsilons are relative. The first criterion only sets the order and has none. The price comes first because the reporting theme is accessibility poverty. The cheapest row of a group always stays. A more expensive row stays only when it is better on another criterion, on the travel time by more than Advanced/ChainParetoTimeEpsilon (0.01). Every row that drops out thus has a cheaper row that stays and is at most 1% slower. The remaining times and TrainState are compared exactly. Price_augm with epsilon 1 only orders rows that are equal on the other criteria. Of those, the row with the lowest transfer costs stays, and the tie-break adds no rows.

Price_augm is only a tie-break because both alternatives are worse. On Price_augm alone, the chain joiner could drop the cheapest chain of a group for a more expensive one with less transfer time. The final front on price and travel time should keep that cheapest chain. With Price and Price_augm as two full criteria, the chain joiner keeps the cheapest chain, but also the more expensive chains with less transfer time. These have the same travel time and can never reach the final front. Yet each is joined again in the next round, which makes the chain step more than twice as slow, as measured on the first stop block of 1 October 2024.

The same operator, with the same epsilons, makes the front per stop block (step 6), the front per departure moment and the merge of the components. Classifications holds the epsilon per criterion in EpsilonExpr. The signatures of the chain cache and of the output carry _chainrel1pct when the epsilon is active (Impl/ChainPareto_FileTag).

Keeping the chain step small

The four-ride types dominate the chain step, above all RRRR. On the first stop block of 1 October 2024, for example, that type joins 268 million candidate combinations, of which 112 million are valid and 1 million stay. These measures keep the step small:

  • Join_Left_Transf drops the combinations of left chain and transfer that exceed MaxPTTime even with the shortest right ride (MinRightTraveltime). The second join is then smaller, with the same valid chains.
  • Join_Left_Transf_Pareto keeps per group only the pairs of left chain and transfer that can still give a better chain (see The join). A regional ride continues past every stop where the vehicle stands still, so it has an alighting event at every later stop. Without this selection, the second join of RRRR on the first stop block of the morning of 14 October 2025 held 2.2 billion valid combinations; with it, 123 million.
  • The modes of a chain are one uint32, ModeCode. It has 4 bits per ride, holding the mode id plus 1 (0 is no ride), with the first ride in the highest bits, so five rides fit in 20 bits. The chain joiner composes it as Left_rel->ModeCode * Right/ModeFactor + Right_rel->ModeCode, only for the chains that stay. ModeFactor is 16 for a ride and 16 to the power of the number of rides for a chain. The output step decodes the letters (ModeUsed) per departure moment, once per distinct code. A string of letters would cost about 420 bytes of memory per row; the code costs 4.
  • The Pareto group is one 64-bit number, Part_key; an integrity check guards that it fits.
  • A chain starts only at a boarding time up to Impl/PT_LastBoardingMoment. That moment is the last departure moment plus the longest pre-transport leg over the pre-transport types of the variant (Impl/PT_Chains_Max_V_Time), plus MaxWaitingTimeAtOrigin. No journey can use a chain that boards later. Because this bound depends on the pre-transport types of the variant, the chain cache carries _v<PT_Chains_Max_V_Time> in its signature.

The first three measures leave the chains unchanged; the last leaves out only chains that no journey uses.

Grouping per alighting stop instead of per alighting event, with the arrival time as an extra criterion, would also be exact when the final front uses Price and there is no time penalty. On the first stop block of 1 October 2024 it removes only 6% of the combinations and makes pareto_optimal_eps slower on the larger groups, so the model groups per alighting event.

Step 6: the front per stop block and the chain cache

The front per stop block

When all chain types of a stop block are computed, Allowed_Chains unites them. It keeps the Pareto front per boarding event and alighting stop (OD_pair_key), on the criteria of the final front (Classifications/FinalParetoAttr, from MinimiseCriteria: by default Price and TravelTime). Unlike the chain joiner, this groups on the stop and not on the event. Of two chains from the same boarding event to the same stop, the faster one also arrives earlier. So a chain that is slower and not cheaper can never be part of a better journey. The arrival time stays in the chain.

In the OD pair mode only the chains to a stop from which the destination can be reached stay (EndsAtD).

The cache

Every stop block writes its front to a parquet file of its own, compressed with zstd, <chain cache>/<n>of<N>.parquet (ChainGeneration_PerBlock/<block>/Parquet). Per chain it holds the modes (ModeCode), Price, Price_augm, Price_S, Traveltime and its two parts TransferWalkTime and PTWaitTime (all three in seconds), the distance per mode (decametres), and the boarding and alighting event (uq_c_FromTime_Stop_rel, uq_c_ToTime_Stop_rel, row numbers in units of the model). Prices are in cents. The model holds prices, times and distances as uint16 and writes them as uint32, because GDAL would write a uint16 as int16, which ends at 32767. The prices are filled only when the run needs them (Impl/PriceExportsAndIntegrityChecksNeeded: a price criterion or Export_PriceInformation).

After the parquet, the block writes <n>of<N>.done. The chain step skips a block with that file (PT_Chains_Blocks/ToDo); in the OD pair mode the block also needs the dictionary of the parts of its chains, <n>of<N>_onderdelen.mmd (see Routes of an OD pair). So an interrupted chain step resumes at the first missing block, and it makes a half-written block again. batch\WriteChainBlocks.ps1 requests the blocks in portions of 20, and those of an OD pair one at a time. With Advanced/PT_Chains_PerBlock FALSE all blocks go to one cache instead (ChainGeneration_Single).

The chain cache is IntermediateResults/PT_Chains_<analysis date>_<time window>_<hash>, where the hash comes from its signature, PT_Chains_Signature. The signature holds every setting that the chains depend on: the date, the feed and the window, the criteria, Max_transfers, MaxPTTime, the Pareto option of the search for rides, the epsilon, flex, NS International and trip surcharge, the price method, the transfer and stop settings, _v<PT_Chains_Max_V_Time>, the IFF transfer times, and the revision Impl/PT_Chains_Revision. The full signature is in signature.txt in the folder of the cache. The model reads the cache only when the signature matches; see Cache names.

Reading the cache

PublicTransport_Prep/PT reads the blocks back, read-only. PT_V reads per block only the chains that board at a stop where a pre-transport leg of the component ends (uq_c_FromTime_Stop/IsVBoarding). It uses collect_by_cond, which reads the cache per tile. Writing and reading are separate items. The writer of a block (ChainGeneration_PerBlock/<block>/Parquet) writes the chains that the block calculates. The reader (PT_Chains_Blocks/PerBlock/<block>/Read) has no calculation of its own: it reads the file, and stops with an error when the signature of the cache is missing or differs. So a run that reads the cache does not calculate the chains again. The one cache of Advanced/PT_Chains_PerBlock FALSE has a bare reader that declares nothing, as GeoDMS requires of a read-only MMD reader (GeoDMS #1245); see The chain cache on the Script reference.

The boarding and alighting events in the cache are row numbers in uq_c_FromTime_Stop and uq_c_ToTime_Stop. A run that reads the cache derives those two lists again from the rides of step 3. That is why the output step also builds the network and the rides. The signature ensures that the lists are the same as when the cache was written.

The cache does not depend on the pre- or post-transport type of a component, on the ownership criteria or on the direct trips. Of the pre-transport, it takes only the longest maximum time over the pre-transport types of the variant. The public transport components of a variant therefore share one chain cache, which UpdateAll.cmd makes once. A component outside the variant, such as the GuiComponent in GeoDmsGui, adds its own pre-transport type, so that the window of the chains is never shorter than its own.

Demand-responsive transport (flex)

Area-based demand-responsive services and dial-a-ride buses are in the GTFS feeds as ordinary routes with trips, although a passenger has to book them. SourceData/Infrastructure/GTFS/RelevantSelection/Routes/IsFlex marks a route as flex when one of three things holds (#113, #116):

  1. Its short name or long name, in lower case, contains one of the terms in Classifications/FlexRouteTerms: flex (Bravoflex, Connexxion FLEX, Overal Flex, FlexRRReis, SyntusFlex, U-flex), texelhopper, opstapper and belbus.
  2. It is a bus route, and at least Advanced/FlexBookedStopShare (0.5) of its stop times in the feed have pickup_type or drop_off_type 2, which means “phone the agency” (IsBookedBus). This finds services such as Transdev OV-op-Maat, Qbuzz BestelBuzz, Arriva Vlinder and EBS Maasvlaktehopper. In the feeds a route is booked at all its stop times or at none, so the share hardly matters. The rule leaves out trains, because for them the value 2 means a reservation.
  3. It is a bus route of an agency with a line number in Classifications/FlexLineRanges (IsFlexLineNumber): Qbuzz 6000 to 9999, the Opstapper in Friesland. Its names are those of its stops, such as “6011 Twijzelerheide - Buitenpost Station”. The feed of 2026 marks exactly these routes as booked; the feed of 2025 does not.

Routes/FlexReason gives the rule per route. /Output/FlexLines/Report writes the flex routes of a feed with their reason to Output/flex_<feed>_<analysis date>_routes.csv. With the feed of 30 September 2025 that is 464 routes: 18 by name, 41 by booked stop times and 421 by line number. Some routes have more than one reason.

Flex parameters

Four parameters in ModelParameters/Advanced set how these routes take part:

Parameter Default Effect
IncludeFlex TRUE FALSE removes all links of flex routes, scheduled and waiting links, from both fare groups.
FlexMinInterval 15 min Minimum interval between the trips of a flex route. Per trip pattern (route, first stop, last stop, number of stops) and service day only the first trip in each interval, counted from 00:00 of the GTFS day, enters the network of that day (SourceData/Infrastructure/GTFS/LoadFeeds/FlexOptions). 0 keeps all trips.
FlexExtraWaitingTime 30 min Added to the travel time of every ride on a flex route, for the booking and the uncertain pickup time. It counts towards MaxPTTime and makes the travel time a criterion of the chain joiner.
FlexCallCosts 0.00 euro Added to the price of every ride on a flex route, in Price_O: the chain joiner adds Price_O over the rides of a chain, whereas it takes Price_I once per fare journey.

A ride follows one route, so a flex ride is exactly one boarding of a flex route, and its extra time and costs belong to the ride (OD_extra_attributen.dms, IsFlexRide). The signatures of the chain cache and of the output carry the setting (Impl/Flex_FileTag). It is _noflex without flex, or _flex<interval>i<waiting time>w<call costs in ct>ct with flex, or nothing when all three are 0. The defaults, chosen with PBL in #116, give _flex15i30w0ct.

Why the minimum interval

Some feeds schedule a flex service as a trip every minute. In the feeds of 2026, the main patterns of U-flex Maarssen/Utrecht-Noordwest and Houten-Schalkwijk run 296 to 728 trips per direction per day. The other patterns of the same services run every 15 to 20 minutes. Taken literally, that is a bus every minute. Without thinning, with the feed of 25 September 2026, a stop of such a service would have about 550 rides per departure, against a median of 6 over all stops. Then 15 of the 486 stop blocks would need 150 to 200 GB each.

The thinning compares only the trips of one service day, separately for D−1, D and D+1. A feed often gives the same trip a trip_id of its own for each kind of weekday or each period of the timetable. Compared over all days of the feed, the first trip of an interval would often run only on another day, and the interval would then have no trip on the analysis day (#171).

Limitations

  • The model does not recognise a demand-responsive service without a flex term in its name, without booked stop times in the feed and without a line number range. The line number range of the Opstapper holds for Qbuzz. When another agency takes over the service, the range has to follow.
  • A service that runs to a timetable but has to be booked, such as some Vlinders, counts as flex and so gets the extra waiting time per ride.
  • The public transport hubs (OV_Knooppunten) count all trips, including the flex trips that the minimum interval removes from the network. So the destinations, and the car caches that carry their name, do not depend on the flex parameters.

Parameters

Parameter Default Description
MaxPTTime 90 min Maximum time in public transport, including transfers and waiting; cut of the rides and limit of the chains.
Max_transfers 3 Maximum number of transfers in a chain (1 to 4).
Transfer_Walking_Time_Costs, Transfer_Waiting_Time_Costs 0.19, 0.05 euro/min Costs of walking and waiting at a transfer, in Price_augm.
Advanced/MaxTransferDist 500 m Maximum straight-line distance of a transfer.
Advanced/TransferWalkingSpeed 4.5 km/h Walking speed at a transfer.
Advanced/TransferDetourFactor 1.2 Detour factor of a transfer walk; TransferEffectiveSpeed is TransferWalkingSpeed divided by it, over the straight distance.
Advanced/IFF_TransferTime TRUE Minimum transfer time between platforms of one NS station from the IFF timetable.
Advanced/GradeSeparatedTransferPenalty 0 min Time penalty for a transfer from or to metro, rail or ferry.
Advanced/DistanceStopClusters 100 m Stops within this distance form a cluster; a ride within a cluster is left out.
Advanced/MaxTransferTimeForBoardingSurcharge 35 min Window within which a regional ride continues the fare journey, a train continues the train journey and an NS ride can get the through fare.
Advanced/IsNSInternationalInLnet, Advanced/IncludeTripSurcharge TRUE, TRUE NS International in the NS fare network; trip surcharges of special trains.
Advanced/ParetoLegs_R, Advanced/ParetoLegs_L TRUE, FALSE Pareto option of the search for the regional and the NS rides.
Advanced/ChainParetoTimeEpsilon 0.01 Relative epsilon on the travel time in the Pareto selections.
Advanced/NumberOfStopBlocks, Advanced/MaxStopBlockSize 500, 104 Stop blocks of the chain step; their product must exceed the number of stops.
Advanced/PT_Chains_PerBlock TRUE A cache per stop block instead of one cache.
Advanced/IncludeFlex, FlexMinInterval, FlexExtraWaitingTime, FlexCallCosts TRUE, 15 min, 30 min, 0 euro See Flex parameters.
Advanced/FlexBookedStopShare 0.5 Share of the booked stop times from which a bus route counts as flex; see Demand-responsive transport (flex).

Table of contents