rx-sim 3.2.0
generate ticket log based on parameters file, client arrivings and employee schedules
Requires Python: >=3.11

# simulation

simul.py
--------------------------------  


Usage: rxsim [OPTIONS]

Options:  
  -c, --client file       name of csv client file  [required]  
  -e, --employee file     name of csv employee file  [required]  
  -p, --param file        name of csv parameter file  [required]  
  -s, --store store_name  store name  [required]  
  -o, --output dir        output directory  
  -v, --verbose           Enables verbose mode  
  --maxclient             generate a maxclient csv file with number of client inside store  
  --runmp                 run simulation in multiprocess mode on linux  
  --version               Show the version and exit.  
  -h, --help              Show this message and exit.  

rxsim generates <store>_sim.feather ticket log file with simulated client arrivings and servings based on:
    hourly nb client from client_file
    employee schedule from employee_file
    service definition from parameter_file
        
It also adds breaks taken by employees in ticket log.  
<store>_sim.feather contains columns :  
- LOCATION : name of store  
- WEEKN : week number  
- WEEKDAY : iso day of week  
- TICKET_ID : unique ticket number  
- USER_MAIL : email or id of employee serving  
- GENERATION_DATE : datetime of ticket generation  
- START_DATE : datetime of service start  
- END_DATE : datetime of service end  
- SERVICEW : type of service given  
- WAITING : waiting time in minutes  
- DURATION : length of service in minutes  
- STATUT: terminated or canceled  
- NPS_SCORE : Net Promoter Score  

    
Simulation is based on parameters defined in client_file, employee_file and parameter_file.

Client_file defines client arrivals. Mandatory columns are:
- WEEKDAY: ISO weekday (1 for Monday, 7 for Sunday)
- HOUR: 0 to 23
- ARRIVING: number of clients arriving each hour

Client_file can also have optional columns:
- <SERVICE_NAME>_ARRIVING : number of clients wanting <SERVICE_NAME> each hour. If not defined, SERVICE_WEIGHT in parameters file is used to compute ratio by service.

Employee_file defines employee schedule. Mandatory columns are :
- WEEKDAY: ISO weekday (1 for Monday, 7 for Sunday)
- HOUR: 0 to 23
- EMPLOYEES: list of employee id (name or email)
- SERVICES: list of services offered by each employee (from EMPLOYEES colunmn), one service by line or separated by _
- employee name: one column by employee. Working schedule for employee, 1 if employee at work at WEEKDAY, HOUR row. This value also represents probability of break employee can take.

Employee_file can also have optional columns:
- EMP_PRIORITY : define relative priority between employees to serve a new client (0 higher priority than 1, 2,...)
- RULE_REnnn : define employees where eule REnnn is applied. REnnn must be define in rules.py
- RULE_GLOBALnnn : define rule (constraint) applied on employees once a hour. GLOBALnnn must be define in rules.py
- EMP_GROUP : defines the group to which the employee belongs. Used to determine pause duration and global_rule behaviour

Parameter_file defines simulation parameters. Mandatory columns are :
- SIMUL_DATES: start and end date of simulation, in format yyyy-mm-dd
- SERVICE_NAME: list of services offered
- SERVICE_PRIORITY : relative priority between services (0 more priority than 1, 2, ...)
- SERVICE_WEIGHT: relative probability weight of each service.
- SERVICE_DURATION_MEAN: average lenght of each service (in mn)
- SERVICE_DURATION_MIN: minimum length of each service (in mn)
- SERVICE_DURATION_MAX: maximum length of each service (in mn)
- SERVICE_DURATION_SHAPE: gamma shape of each service
- SERVICE_DELAY0_MEAN: mean delay in seconds taken by employee before taking a new client, when client waits for employee
- SERVICE_DELAY0_MAX : maximum delay in seconds taken by employee before taking a new client, when client waits for employee
- SERVICE_DELAY0_SHAPE : gamma shape of delay when client waits for employee
- SERVICE_DELAY1_MEAN: mean delay in seconds taken by employee before taking a new client, when employee waits for clients
- SERVICE_DELAY1_MAX : maximum delay in seconds taken by employee before taking a new client, when employee waits for clients
- SERVICE_DELAY1_SHAPE : gamma shape of delay when employee waits for clients

Parameter_file can also have optional columns:
- MAX_NB_PAUSE : maximum number of pause each day for each employee. default 2
- MIN_TIME_BETWEEN_PAUSE : minimum time in mn between 2 consecutives pause for each employee. default 80mn
- MAX_NB_CLIENT_IN_STORE : maximum number of clients able to be in store. default 1000
- PAUSE_DURATION : minimum and maximum duration in minutes of employee breaks, in minutes. default : 50 to 90 mn
- SERVICE_CLIENT_WAIT_MEAN : mean time in minutes a client can wait before leaving. default 21mn
- SERVICE_CLIENT_WAIT_SHAPEA : beta shape a time a client can wait before leaving. default 2.5
- CANCELED_TICKET_DURATION_MEAN : mean time in seconds to managed canceled ticket. default : 50s
- CANCELED_TICKET_DURATION_SHAPE : gamma shape for duration of managing canceled ticket. default: 50
- EMP_GROUP, PAUSE_MIN, PAUSE_MAX : define minimum and maximum duration of pause for each employee group. EMP_GROUP values must be the same as EMP_GROUP values in employee file.
- PREVIOUS_SERVICE : define chaining services for multi-step services
- PREVIOUS_SERVICE_PROB : probability (between 0 and 100) to add SERVICE_NAME in multi-step-services
- PREVIOUS_SERVICE_DELAY_MAX : Max delay between PREVIOUS_SERVICE and SERVICE_NAME


Client arrivals follow a normal distribution, based on hourly number of clients with a small variation.  
Service asked by each client is determined randomly with relative weight probability from SERVICE_ARRIVING.  
If not defined for all services, SERVICE_WEIGHT in parameters file is used to compute ratio by service.  
Service length is determined by using a gamma distribution with mean equals SERVICE_DURATION_MEAN and shape SERVICE_DURATION_SHAPE.  
Service length is always between SERVICE_DURATION_MIN and SERVICE_DURATION_MAX.  

There are 5 types of service, defined with DURATION and WEIGHT :


|          | Real | Fix | Self | False Entry | False No Entry |
|----------|------|-----|------|-------------|----------------|
| DURATION | > 0  | > 0 | > 0  | 0           | 0              |
| WEIGHT   | > 0  | 0   | -2   | > 0         | <= 0           |
        

                                            
Real service is a task done by an employee to an in store physical client.  
Fix service is like RDV, OUTBOUND or admin task.  
Fix service arrivals are spread evenly each hour. (ie each 20mn if 3 arrivals by hour). A small variation is added.  
Self service is a service done by a client by himself without employee.  
False service is just a milestone in the customer journey.  
There are also 4 reserved online services : 'INBOUND', 'OUTBOUND', 'ADMIN', 'Admin'  
Online services are not done to instore client.