3.3 Customized Dispatching Interface

Dispatching mechanism

In PULSim, a request of infrastructure resources will be pended in case of conflicts or deadlocks. If a request of infrastructure resources is conflict-free and deadlock-free, the train still has to evaluate the operational situation, before it occupies the requested infrastructure resources. The decision of whether or not give up the chance of occupancy depends on the applied dispatching algorithm. By a First Come First Serve (FCFS) strategy, the train will always take the chance to occupy the requested infrastructure resources. The FCFS strategy is implemented in PULSim as default. If a dispatching strategy other than FCFS is applied, the train may give up the chance of occupancy according to some dispatching objectives (e.g. to reduce total waiting time). The request will be then pended for the next round of dispatching. In addition, the dispatching mechanism also supports the implementation to apply alternative routes. The workflow of train dispatching in PULSim is shown below:

Java interface for customized train disptaching

If a train is allowed to occupy the requested infrastructure resources (conflict-free and deadlock-free), several possible actions will be generated by PULSim, including:

• to occupy the infrastructure resources
• to give up of occupancy
• to apply alternative routes (not implemented yet)

A java interface is defined for users to provide customized train dispatching:

public interface IDispatchingListener {
    public boolean has_initialized();

    /*
     *  state: the current state for dispatching
     *  actions: list of possible actions
     */
    public int determine_action(State state, List<Action> actions);

    public void save_action(Action action, Duration currentPending);

    public void training();
}

Through the interface, the current state and a list of possible actions will be given as input. A state describes the current operational situation. Depending on the development of the algorithm, the specification of the state will be further developed and defined. The methods save_action() and training() are used for the machine learning algorithm.

Users can implement the method "determineAction" to determine a dispatching action. The method returns an index of the given actions, which indicates the chosen action according to a specific dispatching objective (e.g. with minimum waiting time).

Implementation of Python script

A customized Python script is illustrated to randomly select a given dispatching action from the given actions:

def determineAction(self, actions, conflictTrains):
    gc.disable()
    action_index = 0

    # add your own logic here
    # example for with FCFS (probability 90%) or give up the chance of occupancy
    if random.uniform(0, 1) < 0.1: 
        action_index = 1

    gc.collect()
    
    return action_index

The Python script implements the method "determineAction" defined in the java interface. If it is set as an external dispatching script, the implementation will be integrated as a call-back function. During the simulation, PULSim will call the method to replace the default FCFS strategy. The current operational situation can be retrieved from the simulator, e.g. getDalays() from a train or get all trains from the simulator. In this example, the train will give up the chance to occupy the said infrastructure resources with 10% probability. Users can configure the external dispatching script in PULSim.

Note: The external dispatching script can be saved at anywhere. However, the file name of the script should be fixed as railapp.dispatching.services.Py4JDispatchingService.py, in order to initialize the corresponding Py4J service class inside of PULSim.