liftsim

English | 简体中文

LiftSim

LiftSim is a light-weight elevator simulator

Install

pip install metagym[liftsim]

For local installation, execute following commands:

git clone https://github.com/PaddlePaddle/MetaGym
cd MetaGym
pip install .[liftsim]

Quick Start

Liftsim environment follows the standard gym APIs to create, run, render and close an environment.

• reset(self): reset the environment to intial state, returns observation
• step(self, action): takes action as input, returns the observation of the next step, reward, done, info. Every step in Elevator simulation takes an actual time step of 0.5 seconds.
  • done: always False, i.e., won't stop until it is done.
  • info: a dictionary inlcuding the total wait time "time_consume" (float), consumption of energy "energy_consume" (float), number of customers who abandoned elevators because of waiting for too long "give_up_persons" (int). Refer to Reward for details
• render(self): render one frame,

# We show a simple example to start LiftSim here
import gym
import metagym.liftsim

env = gym.make('liftsim-v0')
observation = env.reset()
action = [2, 0, 4, 0, 7, 0, 10, 0]
for i in range(100):
    env.render()    # use render to show animation
    next_obs, reward, done, info = env.step(action)

Action

Action must be a list with length of 2*n, which represent the command toward n different elevators (the default configuration has elevators n=4). Each command takes two elements

• The first element represent the DispatchTarget, which lies between 1 and MaxFloorNumber. Also DispatchTarget can either take a negative value -1, which represents that the previously specified DispatchTarget is not changed, or it can take the value of 0, which orders the elevator cart to stop ASAP.
• The second element represent the elevator moving direction after reaching the target. It may be -1 (Downwards), 0 (no direction), and 1 (upwards).

Observation

The observation includes the following structure

• MansionState：namedtuple, represents the overall states of all elevators

Name	name	Description
ElevatorStates	List of ElevatorState	A list of state of each elevator
RequiringUpwardFloors	List of int	Floors where there are customers requiring uplift
RequiringDownwardFloors	List of int	Floors where there are customers requiring downlift

• ElevatorState：namedtuple, state of an elevator

Name	Type	Description
Floor	float	Current floor where elevator locates
MaximumFloor	int	The maximum floor of the current mansion
Velocity	float	The current velocity of the elevator
MaximumSpeed	float	The maximum speed allowed for the elevator cart
Direction	int	The moving direction of the elevator cart, -1/0/1
DoorState	float	The open ratio of the cart door
CurrentDispatchTarget	int	The current specified dispatch target
DispatchTargetDirection	int	The current specified dispatched direction
LoadWeight	float	The current load of the elevator cart (kg)
MaximumLoad	float	The maximum load of the elevator cart (kg)
ReservedTargetFloors	list	The current required floors of the elevator cart
OverloadedAlarm	float	Whether the elevator is overloaded
DoorIsOpening	boolean	Whether the cart door is completely open
DoorIsClosing	Boolean	Whether the cart door is completely closed

Examples

We hereby present a demonstration of dispatching an elevator system with Deep Q Network Example

Reward

The reward is calculated from three components:

• time_consume: the waiting time of all customers accumulated in a timestep, in seconds
• energy_consume: the energy comumed in a time step by the elevators, in J
• given_up_persons: number of people who give up waiting for the elevators because the waiting time is out of range.

We provide two different reward settings

Economic Settings

reward = - (time_consume + 0.01 * energy_consume + 100 * given_up_persons) * 1e-4

Customer-Oriented Settings

reward = - (time_consume + 5e-4 * energy_consume + 300 * given_up_persons) * 1e-4

Configurations

LiftSim is a configurable elavator simulator You can change the customer generation pattern by modifying [PersonGenerator] in config.ini Also you may create your own unique pattern

A uniform random customer generator

[PersonGenerator]
PersonGeneratorType = UNIFORM
ParticleNumber = 12
GenerationInterval = 150

Curstom customer generator

[PersonGenerator]
PersonGeneratorType = CUSTOM
CustomDataFile = mansion_flow.npy

You may change mansion_flow.npy to your own customer flow data

Related resources

Citation

@misc{LiftSim,
    author = {Fan Wang, Bo Zhou, Yunxiang Li, Kejiao Li},
    title = {{LiftSim: a configurable lightweight simulator of elevator systems}},
    year = {2020},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/PaddlePaddle/MetaGym/tree/master/metagym/liftsim}},
}