This repo extends Flatland Railway Simulator with helpful features.
-
class XRailEnv extends RailEnv
XRailEnv is an extended version of the Flatland environment and supports multiple resources allocation to an agent at time.
-
class FlatlandDynamics extends XRailEnv
FlatlandDynamics extends XRailEnv and implements vehicle movement dynamics. The simulation takes into account rolling stock properties such as maximal allowed velocity and traction power, topology (gradient) and physical train length.
-
Minimal train following time can be globally controlled
-
Multi-resource allocation can be implemented. This allows to implement mutual exclusive use of railroad switch cluster, connecting "edge cluster" and/or any other multi-ressource allocation problems - Railway-specific features can be implemented, e.g "Fahrstrassenausschluss", .. , "Flankenschutz"
-
Dynamics - train power based acceleration (physics) and train specific "comfort" braking (with fixed negative acceleration).
Completely new experiments can be carried out using these extensions. In the current version of Flatland exactly one resource can be assigned to an agent at time. This allows solving a simplified resource allocation problem for railway operation - which is certainly not far away from problems in real railway world. But no important features such as " Flankenschutz" or "Durchrutschweg" can be modeled. With the multiple resource allocation technics - which allows to assigne more than one resource to an agent at time - this leads to a more realistic model and allows to model important aspects of railway safety. In consequence the modeling gets much more complex with respect of details/data requirement, but this leads to much more realistic simulation results. Another important aspect in the augmentation of reality is that the agents behave dynamically in terms of movement. Agents are able to dynamically interact with each others. The vehicle movement dynamics of each agent can be enabled by using the FlatlandDynamics environment. By combing all of those extensions the simulation will become very realistic.
The goal of this extension package is that researchers can show where the limits and strengths of their proposed methods lie. Some optimization methods will not be able to deal with vehicle dynamics; some algorithms are not suitable for solving problems with multiple resource allocation at time. Others are might very slow to solve such complex dynamic problems and there is might a solution which can solve it in raisonable time, but the solution quality must be further improved. It's very exciting to see where the effective limits of each method lie and whether someone find a real-time solver of all kind of those problems.
-
The illustration on the left shows all crossings (switches) and the illustration on the right shows all switch neighbours. A switch neighbours is an infrastructure element that has an intersection (crossing) as its neighbour.
The figure illustrates the mapping of crossings (switches) and switch neighbours to the infrastructure.
-
The left illustration shows all connecting edges (cluster). The number represents the cluster id. Cells with the same cluster id belong to the same cluster. The right illustration shows all switch clusters. A switch cluster contains one or more crossing (switch) cells where each switch within the cluster are all neighbors. The switches in the same cluster have the same switch cluster id.
-
The Flatland Resource Allocator extension allows the implementation of a simultaneous allocation of multiple resources to an agent, and also allows the concept of minimal headway (train-following), which roughly simulates the real infrastructure behavior. A two-minute train sequence (n-flatland time steps) is often used in many real railway systems - the entire system is therefore designed for a minimum headway of n seconds. With the help of the multi-resource allocator it is possible to implement "flank protection", ... and dynamic movement.
-
The diagram on the left illustrates the speed diagram for each train. The traveled distance [m] is plotted on the x-axis. The speed in kilometers per hour [km/h] is shown on the y-axis. The orange curve shows the maximum allowed speed. The blue curve is the simulated speed. The length of the train is easy to see because the last axle of the train must have allowed a higher speed, otherwise the train will not accelerate. The diagram on the right illustrates the acculeration [m/s] on the y-axis. On the x-axis traveled distance [m] is plotted again. The red colored part of the velocity and acceleration curve shows where the agent has to brake hard due to an active malfunction.
-
The rolling stock data stores the technical characteristics of each locomotive, including tractive effort and speed limits. The DynamicAgent stores the physical properties such as mass and length of the complete train (agent) and requires the rolling stock data to simulate the tractive effort and acceleration.
The figure illustrates the traction characteristics. The speed is plotted on the x-axis. The maximum tractive effort is plotted on the y-axis. Traction power is limited by the maximum force that traction can exert on the wheel and is further limited by the maximum power of the motor.
$$F = m a := Force : [kN]$$ $$P = F v := Power : [kW]$$ $$v := Velocity : [{ m \over s}]$$ $$m := Mass : [10^3kg]$$ $$a := Acceleration : [{m \over s^{2}}]$$ Where
$P_{max}$ is the maximum power of the traction.$P_{max}$ depends on two factors$F_{max}$ and$v_{F_{max}}$ . Where$F_{max}$ is the overall maximum force the traction can deliver and where$v_{F_{max}}$ is the speed up to which the vehicle can deliver the maximum force.The power consumption (for acceleration) must be positive and less than the maximum power of the traction
$P_{max}$ and it cannot exceed the maximum force$F_{max}$ .$$0 <= P <= P_{max}$$ $$P_{max} = F_{max} v_{F_{max}}$$ $$F <= \min({ P_{max} \over v} , F_{max})$$ -
Resources colored orange, red or black are occupied by the train. Orange indicates a resource reserved for the train but not required by either the braking distance or the physical train. Red and black resources are security related. Black is the physical train and red resources are needed for braking. The physical train can occupy more than one cell since the train length can be greater than the length of the underlaying cell. In the visualization, however, a train that would fit into one cell can also take up more than one cell if part of the train is in the next cell and part is still in the current one. Green resources are still occupied. They are intended to approximately simulate the time required to handle all security elements - they represents the minimal train following time.
The Example is showing a moving block based simulation. The rendering is done with FlatlandDynamicsRenderer.
- Google coLab notebook - Recife export
- Google coLab notebook - Simulation with multi-resource reservation
- Google coLab notebook - Flatland dynamics
The code is tested with Python 3.6, 3.7 and is expected to also work with higher versions of Python.
Install Anaconda and create a new conda environment:
$ conda create python=3.6 --name flatland-ext
$ conda activate flatland-ext
The Flatland code source is available from AIcrowd gitlab and Flatland railway extension can be found at github:
$ git clone http://gitlab.aicrowd.com/flatland/flatland.git
$ cd flatland
$ pip install -r requirements_dev.txt
$ python setup.py install
$ cd ..
$ git clone https://github.com/aiAdrian/flatland_railway_extension.git/
$ cd flatland_railway_extension
$ python setup.py install
$ cd ..
Install flatland railway extension:
$ pip install flatland-railway-extension
Test that the installation works:
$ python -c "import flatland_railway_extension.examples.demo_flatland_dynamics"
Troubleshooting1
Some examples can be found at: flatland_railway_extension.examples.*
The initial implementation is authored by Adrian Egli's ( aiAdrian) neurips2020 flatland challenge solution (submission)
If you use this or any idea out of this code for/in any academic publication or commercial products - you must credit the authors.
Footnotes
-
On Windows Subsystem for Linux (WSL) you may need to install some additional packages
pip install pyvirtualdisplay
,pip install piglet
andsudo apt install libnvidia-gl-440
to get the rendering working. However, using Flatland Railway Extension with WSL is not recommended, we recommend native Windows or Linux operating system. OS/X is not tested yet. ↩