-
Notifications
You must be signed in to change notification settings - Fork 29
Service Controller
Service Controller is a sub component of Train Controller which will be exposed to the modeler by which modelers can modify the normal operation of the Train Controller and the trains. We provide a Lua interface to override the default behaviour of the Train Controller or define the logic for specific operation for all the trains. Here we have various APIs exposed to perform specific operations in the train system. If a certain property of a train has to be changed, for example to reset the safe distance, there will be an API called resetSafeDistance(parameters).
The trains are identified by their trainId and trainLine, since the trainIds are unique in a train line at a given point of time. Considering any API, whose function is to get or set any property of a specific train, its default parameters would be the trainId and the trainLine.
1.reset_safe_headway_sec(double sec,int trainId,std::string lineId)-This resets the safe headway seconds of a given train in a given train line. Headway is the time required for the train to reach the train ahead .
2.reset_safe_operation_distance(double distance,int trainId,std::string lineId)-This resets the safe of a given train from the train ahead in a given train line.
3.force_release_passengers(int trainID,std::string lineId,bool action)-This sets or unsets the force release passengers flag(signal) for a train. When the flag is set to true the train force alights the passengers at the next platform. By default the flag is set to false and after force alighting the passengers the flag is set to false automatically. The modeller can also explicitly set the flag to false.
4.restrict_passengers(string platformName,int trainId,string lineId,int type)-This restricts certain type of movement of passengers for a given train at a given line at a particular platform. The restriction can be of boarding or alighting or both.
5.reset_holding_time_at_station(string platformName,double duration,int trainId,string lineId)- This resets the default dwell holding time of a train at station, regardless of dwell time calculated from demand. It only affects the next instance of the train dwelling at the station.
5a.reset_max_holding_time_at_station(string platformName,double duration,int trainId,string lineId)- This resets the default maximum holding time of a train at station, regardless of demand. It only affects the next instance of the train dwelling at the station.
5b.reset_min_holding_time_at_station(string platformName,double duration,int trainId,string lineId)- This resets the default minimum holding time of a train at station, regardless of demand. It only affects the next instance of the train dwelling at the station.
6.terminate_trainservice(string lineId)-This Api is not specific to a particular train. This terminates the service of all the trains running at a particular time. The trains running at the given line are moved forward to the next platform ,where passengers are force alighted and the train is sent back to depot. Invoking this Api also prevents the dispatch of future trains in the system ,the ones already dispatched and queued for running are also sent back to depot.
7.get_dwelltime(int trainId,string lineId,string stationId)-This Api returns the waiting time remaining of a train at a given line at a given station. If the train is not at that station then this Api return -1.
8.get_opposite_lineid(string lineId)-This Api is specific to train controller. This Api gets the opposite line of a particular train line.eg if the train line is NE_1 then it returns NE_2 and vice versa. If train line is Ew_1 then it returns EW_2 and vice versa
9.get_distance_to_next_platform(string lineId,int trainId)-This gets the distance of a train to next platform. If the combination of trainId and lineId inputed is invalid then it returns -1.
10.get_next_platform(int trainId,string lineId)-This Api returns the next platform of a given train. The term next platform means the nearest platform at which the train is approaching or the platform where the train is currently waiting.
11.get_active_trains_size(string lineId)-This Api gets the number of active trains running at a particular line or waiting at platforms at that line.
12.get_active_train_by_index(int index,string lineId)-This Api gets the trainId of a given train by the index of the train in the list. This is basically used to get all active trains' ids in a particular line. To use this Api first get the size of active trains for a given line and then iterate till the size of the list of active trains and invoke this Api to get the trainIds from the list by the index.
13.perform_disruption(string startStation,string endStation,string time)-This performs disruption at a particular time. The parameters startstation and endstation indicate the first and last platforms of disrupted region. The call to this simulates the disruption scenario automatically where the trains move to closest next platform,force alights the passengers and wait there. If the trains are stuck between platforms(that is the train ahead is already at the next platform) then it ignores and safe distance and safe headway and gets very close to the train ahead, likewise the subsequent trains behind it get close the same way,force alights the passengers and waits there. If the train is at the train at the platform before the first platform of disrupted region then it force alights all the passengers and takes the Uturn to opposite platform on the opposite line. Note-Disruption can also be done by lua scripting invoking various Apis based on conditions which allow the modeller to change the behaviour have a finer control on the scenario.
14.insert_stop_point(int trainId,string lineId,double distance,double duration)-This inserts a stop Point in the path of a given train at a particular distance specified. The train stops at that point for the duration specified. The train also adjusts its speed and acceleration before arriving at the point so that it can stop at it. The points are located at certain distance to each other in a polyline,so if the distance specified leads somewhere between two points then the stop point taken is the prior one.
15.update_platform_list(int trainId,LuaRef platformsToBeIgnored,string lineId)-This Api updates the platform list of a particular train. By default the train stops at all the platforms we can override this by specifying the platforms to be ignored ,the trains simply do not stop at these platforms. If all subsequent platforms till the last last platform is to be ignored then the train is sent back to depot. Refer to #44.
16.terminate_single_train_service(int trainId,string lineId)-This Api terminates the service for a single train ,brings the train to nearest next platform,force alights all the passengers and return to the depot.
17.insert_unscheduled_train_trip(string lineId,string startTime,string startStation)-This Api inserts a train at the time specified which is not listed in the schedule of regular dispatch . The unscheduled trains are pushed into different queue than scheduled trains and they are given higher priority than scheduled trains. The trains can start their trip at any platform on the route not necessary at the first platform of the route. Before sending the train to platform the safe distance of trains ahead of it and behind it are checked and if they are maintained only then the train is send to platform.
18.set_disrupted_platforms(string startStation,string endStation,string lineID)-This Api sets the disruption at the platforms at a particular line at particular stretch of platforms from platform of start station to platform of end station.
19.get_disrupted_platforms(string lineID,int index)-This Api gets the disrupted platform by index from the list of disrupted platforms of a particular line. This is used while iterating over the list of disrupted platforms. Get the number of disrupted platforms and then iterate till the number invoking the the Api to get each disrupted platform.
20.get_disrupted_platforms_size(string lineId)-This Api returns the number of disrupted platforms at a particular line.
21.get_platform_by_offset(int trainId,string lineId,int offset)-This Api returns the platform by the offset,that is the platform after the offset number specified from the platform the train is currently approaching or from the platform the train is currently waiting.
22.set_uturn(int trainId,std::string lineId,bool takeUturn,double timeForUturn)-This Api sets or unsets Uturn signal to a particular train. When the Uturn signal is set the train takes a U turn to opposite platform on the opposite line after its dwell time has elapsed on the platform its currently approaching or waiting at.
23.get_next_requested(int trainId,string lineId)-This Api returns the next requested for a particular train. Next Requested is the action the train is supposed to take in the next frame tick.
The next requested can be
1.NO_REQUESTED
2.REQUESTED_AT_PLATFORM
3.REQUESTED_WAITING_LEAVING
4.REQUESTED_LEAVING_PLATFORM
5.REQUESTED_TAKE_UTURN
6.REQUESTED_TO_PLATFROM
7.REQUESTED_TO_DEPOT
These states are returned as integers when the Api is invoked.
24.get_trainid_train_ahead(int trainId,string lineId)-This Api returns the trainId of the train ahead of the train specified on the same line. If there is no train ahead of it then it returns -1.
25.set_ignore_safe_distance(int trainId,string lineId,bool ignore)-This Api sets a signal to ignore or consider the safe distance of the train ahead to calculate the effective speed ,acceleration and moving distance. It just sets the signal to make the safe distance criteria insignificant or take into consideration rather than changing the actual value of safe distance.
26.set_ignore_safe_headway(int trainId,string lineId,bool ignore)-This Api sets a signal to ignore or consider the safe headway of the train ahead to calculate the effective speed ,acceleration and moving distance. It just sets the signal to make the safe headway criteria insignificant or take into consideration rather than changing the actual value of safe headway.
27.get_force_alight_status(int trainId,string lineId)-This Api gets the force alighted state. When force_Release_Passenegers is invoked it sets a boolean variable forceAlighted to true. This is set to prevent the consecutive force alight,so while the forceAlighted variable is set ,you cannot set force alight signal by invoking force_Release_Passenegers Api. The forceAlight status has to be unset before invoking force_Release_Passenegers.
28.clear_disruption(string lineId)-This Api sets the disrupted platforms on a particular line to normal state.
29.is_stranded_during_disruption(int trainId,string lineId)-This Api returns true if the train has stopped between the platforms during the disruption,that is if the specified train is not able to make it up to the platform as there is already a train ahead of it stopped at platform or before it waiting for disruption to end.
30.get_disrupted_state(int trainId,string lineId)-This Api returns true if the train is waiting at the platform in disrupted region or before the platform(if there is a train ahead on the next platform or before it waiting for disruption to end) for the disruption to end.
31.set_subsequent_next_requested(int trainId,std::string lineId,int nextReq)-This Api stores the future next requested of a train.It updates subsequent_nextRequested variable which stores the future next requested. The train driver sets the next request from this variable if it is set to anything other than NO_REQUESTED.
32.set_force_alight_status(int trainId,std::string lineId,bool status)-This Api sets or unsets the force Alight status.The force alight status is set when the train has force alighted all its passengers.Till the force alight status is unset force_Release_Passenegers cannot be invoked. Based on some criteria you can unset the force alight status.This is basically to prevent the action of consecutive invoking of force alight status,that is while the train is force alighting or already force alighted the passengers ,invoking it again tampers the dwell time of the train at the station.
33.reset_moving_case(int trainId,std::string lineId,int caseVal)-This Api resets the moving case,that is it can change station case to normal case or normal case to station case.When changing normal case to station case,it allows only when it satisfies the station case condition ,otherwise it is not reset.
34.reset_speed_limit(double speedLimit,std::string startStation,std::string endStation,std::string lineId,std::string startTime,std::string endTime)-This Api resets the speed limit of the blocks on the route between the specified stations in the time range specified
35.reset_acceleration(double speedLimit,std::string startStation,std::string endStation,std::string lineId,std::string startTime,std::string endTime)-This Api resets the acceleration limit of the blocks on the route between the specified stations in the time range specified
36.is_stranded_during_disruption(int trainId,std::string lineId)-This Api gets the status of the train if it is stranded between the platforms during disruption,that is if it is in disrupted region and there is train already at platform so it cannot reach the platform.
37.get_uturn_platforms_size(std::string lineID)-This Api gets the total number of platforms on a line where U turn is possible.
38.get_uturn_platform_by_index(std::string lineId,int index)-This Api gets a particular Uturn platform by its index in the list along a particular line.It is basically to iterate over the Uturn platforms one after the other.
39.should_stop_due_to_disruption(int trainId,std::string lineId)-If disruption occurs at a particular line so the trains even before the disrupted region of the line get affected since Uturn is possible only at specific platforms ,if the train is before Uturn platform and even if the it is after U turn platform it determines if the train can go ahead to the platform after is current or coming platform by checking the number of platforms available ahead and number of trains ahead before disrupted region and considering if the train can get stranded between platforms.
40.is_disrupted_platform(std::string platformName)-This Api checks if a platform is in disrupted region or not.
41.set_disrupted_state(int trainId,std::string lineId)-This Api set the disrupted state of the train if it cannot move ahead of its current platform or coming platform due to disruption.
42.is_uturn_platform_on_the_way(int trainId,std::string lineId)-This Api checks if the Uturn platform is on the way further along the route before the disrupted region.
43.is_uturn_platform(std::string platformName,std::string lineId)-This Api checks if the given platform on the line is the Uturn platform,that is if the Uturn is possible on that platform to the opposite platform on the opposite line.
44.add_platform(int trainId,LuaRef platformsToBeAdded,std::string lineId)-This Api adds the platform on the train route if it was ignored by the update_platform_list initially so that the train does not skip that platform. Refer to #15.
45.modify_passenger_number_coefficients(std::string stationName,std::string platformName,double coefficientA,double coefficientB,double coefficientC)-This Api modifies the number of passengers on the platform via some scaling coefficients assigned by the user. The first parameter is station name. Second parameter is platform name. The remaining parameters scale the Boarding, Alighting, and Standing parameters respectively.
46.get_next_uturn_platform(int trainId,std::string lineId)-This API returns the next platform with the "u-turn" characteristic.