> A timetable-based discrete-event simulation package for train movement across railway networks of the Indian Railways. --- ## 📌 About the Simulator This simulator models train movements on a railway network using a **discrete-event simulation** approach. It constructs the event list from the passenger and freight train timetable to be simulated across a railway network of interest, advancing the simulation clock to the next event at each step. ### Core Classes | Class | Description | |---|---| | `Train` | Unique ID, direction, type (passenger/freight), schedule, origin, destination, max speed | | `BlockSection` | Track segment between stations; manages occupancy, queue, and automatic block section logic | | `Station` | Station lines, platforms, and connections to block sections | ### How Events Are Processed - **Arrival event** → checks if a station line is free; if not, delays train until one becomes available - **Departure event** → checks if next block section is free; if occupied, train is added to queue - Completed events are marked with a very large timestamp and excluded from future processing - **Passenger trains always take priority** over freight trains in block section queues ### Key Features - Block section queue management with passenger-over-freight priority - Autoblock sections supporting multiple trains with speed-based safe separation (3.6 km headway) - Two parallel block section variants (`_1` and `_2`) for UP direction trains - Station line assignment based on platform availability and block section connections - Planned vs simulated timetable captured per train with deviation metrics --- ## How to Use ### Step 0 — Installation - Download the package from http://web.iitd.ac.in/~varunr/IndRailSim.zip - Extract the contents. - The simulation may be run directly by modifying the files in this folder. - The file `final_sim_sj_3April.py' is the primary simulation script. ### Step 1 — Prepare Input Data - IndRailSim takes as input two constructs: the railway network description and the passenger and/or freight train timetable to be executed. - The railway network consists of the following elements: stations and block sections (track sections connecting two adjacent saions). - The railway network is thus specified by instantiating objects of the station class and block section class. The package already contains an example simulaion of a timetable with 309 trains including both passenger and freight trains across a railway network within the Waltair division in India. - Stations in the network for this example have been instantiated in the `stations.py' file. - Stations in the network for a new simulation can be specified by modifying the 'station_dict' dictionary at the top of the `stations.py' file. - Block section elements in the network can be specified by instantiating objects of the 'block_sec' class (defined in the `blocksections.py' file). - For the example simualtion, all block sections in the network are instantiated in the 'blocksections_data.py' file. - Block sections in the network for a new simulation can be specified by modifying the instantiations in the 'blocksections_data.py' file. - IMPORTANT: automatic block sections are not specified as part of the instantiation of block sections. Instead, they are specified by adding a list at the beginning of the simulation with a list of adjacent stations that have automatic block sections between then. For example the following list is added at the top of 'final_sim_sj_3April.y': ### autoblock_stations = ['alm', 'kuk', 'vzm'] This implies that block sections between 'alm' and 'kuk' and 'kuk' and 'vzm' are automatic block sections and are treated as such. - The timetable or schedule to be instantiated is done by instantiating objects of the train class, with each train object representing a train journey across the network to simulated. The timetable of a train is to be specified within the 'tr_schedule' attribute of the `train' class (defined in the 'trains.py' file). The overall (i.e., across train) timetable to be simulated is constructed automatically from the schedules of individual train objects. - For the example simulation, all 300+ trains have been instantiated in the file 'p_g_trainclass_309_trains_2day.py'. - Trains for a new simulation can be specified by modifying the instantiations in the 'p_g_trainclass_309_trains_2day.py'. Run `final_sim_sj_3April.py`: - Load raw CSV movement data from Waltair Division - Filter to relevant stations and date window - Generate the train class Python file ### Step 2 — Run the Simulation Run `final_sim_sj_3April.py`: - Imports generated train class, stations and block sections - Discrete event loop processes all arrival and departure events in the timetable ### Step 3 — View Results An Excel file called 'output.xlsx' is generated containing: - Planned and simulated timetables of each train (simulated below planned) - Absolute deviation per station (in minutes) - Y/N flag for trains within 5-minute threshold - Planned and simulated completion times for the overall timetable A time-distance chart is also generated as a graphical output. - The chart is generated for a 24 hour window within the simulated schedule. - Passenger trains shown in **green**, goods trains in **red** - A time window is specified for the example simulation in the function by specifying the start time of the 24 hour time window. See line # 1716 of `final_sim_sj_3April.py`, and modify it for the 24-hour time window of your choice. ### Step 5 — Run the animator - The simulator also generates an output JSON file 'schedule_simulated.json'. - The above JSON file, along with a JSON representation of the network, is provided as input to the animator. Note that the JSON animator requires representation of the network in the format specified in the 'network.json' (within the 'input' folder) file for the example railway network. We are working on programming the automatic creation of the network JSON file from the network representation within the main simulation - should be done in a week or two (wrt 13 April 2026). - Run the main.py file. A user input window will pop up and asks the user to provide the network and simulated schedule JSON files. After providing these, the animator starts. The animator provides capabilities of pausing, stopping and exiting, increasing and decreasing playback speed, etc. ## 📋 Requirements ```bash pip install numpy pandas openpyxl matplotlib pygame pip install jupyter nbconvert ``` --- ## 🔑 Key Conventions | Convention | Value | |---|---| | Direction 0 (DOWN) | Example: PSA → KTV | | Direction 1 (UP) | Example: KTV → PSA | | Autoblock stations | `alm`, `kuk`, `vzm` | | Headway distance | 3.6 km | | Sentinel timestamp | `2100-06-01 22:50:00` | | Block section naming | `stn1_stn2_dir` e.g. `nml_vzm_0` | """