NetLogo User Community Models

(back to the NetLogo User Community Models)

Download If clicking does not initiate a download, try right clicking or control clicking and choosing "Save" or "Download". Try It in NetLogo Web

# Overview
## Purpose and Patterns
The model is designed to explore questions about how customers choose which stores to visit given a setting of the location of the stores and customers in a grid. A customer is assumed to favor the store which is near to home location and the waiting time at the store should also be low. Using this, we assume that the "unhappiness" of a customer depends on a linear combination of the travelling time from home to the store and average waiting time at the store over the past visits. At first the customer prefer the store nearest, but as the waiting time grows due to crowd, he/she looks for alternatives and then makes the best decision based on it. We can think of the store selection as a form of "Minority Game", but the with a location factor involved for the agents.

In patterns, we hope to see the trend of the average "unhappiness" of the population over the time, as the customers regurarly make decisions to choose the best store based on the past experiences and distance to store's location. The distribution of the customers at each store and "unhappiness" distribution of the population is also to be observed to draw conclusions about how biased the distribution is on the location of stores. Finally, we observer the pattern of unhappiness over the grid terrain, to conclude the effect of proximity of competing stores to uneven unhappiness distribution around the stores location.

## Entities, State variables and scales
The model has mainly the two entities Stores and Customers; the other minor being House entities.
### Customers
- ID and location of the home on grid (Each customer is associated with a unique home on the grid))
- Store visit count list (A list which maintains that how many times the customer have visited each store in the past)
- Store total waiting time list (A list which maintains that how much total time customer have spent waiting at each store)
- Rest time (A random value in range(1, MaxRestTime) to decide for how much time, a customer should rest at home before next visit)
- Wait time (Based on the current crowd and quantity, the time for which the customer must wait at store to get the request fulfilled)
- Demand (A random value in range(1, MaxDemanTime) to decide what is the required quantity by the customer while visit to a store)
- Target store ID (On starting a visit to store, the customer decides the best available store)
- A state variable or set of state variable to store the current state of person whose value can be one of ["at home", "travelling to store", "at store", "travelling to home"]
### Stores
- Quantity (The current quantity available at the store, can be negative if the crowd at the store is already waiting at the store for a placed order)
### Houses
Marks the home location of the unique customer associated with it.

### Scales and Limits
- The landscape is 21 X 21 patches in size with no wrapping at its edges.
- There is no time limit to the simulation. The user has to manually stop the go forever button.
### Global Variables
- Supply rate (same for each store)
- Max quantity of store (same for each store)
- Max Demand of customers for a visit
- Max Rest time of customers after a visit

## How to Use (Model Interface)
### Model Parameters
**Agent Population**
- num-consumers: The number of customers in the grid
- num-stores: The number of stores in the grid

**Store Parameters**
- store-capacity: The maximum quantity any store can hold
- supply-rate: The rate at which the quantity is replenished

**Customer Parameters**
- person-max-demand (The maximum required quantity by the customer on a visit)
- person-max-rest-time (The maximum time a customer rests at home before next visit)

### Procedure Buttons
- Setup: Setup and initialise the whole with the new location of stores and customers
- setup-consumers: Vary the location of customers keeping the location of stores same and reset the time and all entities variables
- setup-stores: Vary the location of stores keeping the location of customers same and reset the customer variables
- go-once: Run the model for a single time step
- go: Run the model forever
- reset-consumers: Reset the customer variables with the time and plots. The location of stores and customers do not change

### Visual Tools
- inner-influence-circles? : Whether to display the inner influence circles for each store
- outer-influence-circles? : Whether to diplay the outer influence circles for each store
- show-links? : Whether to display the links between stores and its current customer home locations
- show-unhappiness-terrain? : Whether to color the patches as per the unhappiness distribution over the grid

### Plots
- num-customers(Histogram): It shows the current number of customers for each store at the current time
- num-customers-waiting(Histogram): It shows the number of customers at each store which are currently waiting at the store for their demand to be fulfilled
- average-unhappiness(Line plot): Shows the average unhappiness of the customers value over the time
- unhappiness-distribution(Histogram): Show the distribution of the unhappiness over the customers population

### Monitors
- average-unhappiness: Shows the current average unhappiness of the customer population
- unhappiness-start-time: The first time when each customer has visited its target store at least once
- std-dev unhappiness: The standard deviation of the unhappiness values of the customer population
- mean inner-influence-radius: The mean of the inner influence radius of the stores
- std-dev inner-influence-radius: Standard deviation of the inner influence radius of the stores
- mean outer-influence-radius: The mean of the outer influence radius of the stores
- std-dev outer-influence-radius: Standard deviation of the outer influence radius of the stores

### Store Location Optimization
- move-shops-towards-customers: Moves the stores to the mean coordinate of their current customers home location and reset the customers and plots
- move-shops-towards-unhappiness-customers: Moves the stores the unhappiness weighted mean of their current customers home location and reset the customers and plots

## Process Overview and Scheduling
## Processes
### Logic for Customer
In a single discrete time unit, the execution in the flow chart of customer reaches a "flowchart state" (can be same as previous) from the previous "flowchart state".
The figure below explains the cycle of actions for the customer.
- The customer performs actions as per the current state in the flowchart. Accordingly, it moves or sets some state variables such as restTime, waitTime or completes an order transaction at a store in a single time unit.
- A customer is initially at the home location with a random RestTime between 1 and Max Rest time.
- With every tick, the rest time of the customer decreases by 1, if the customer is at home.
- When the rest time becomes zero, the customer makes a decision to which store to visit based on the store with least unhappiness value. (Unhappiness of a customer with respect to a store = Travelling distance from store + Average waiting time at the store)
- The state of the customer changes from "at home" to "travelling to store" and starts moving towards target-store.
- On reaching the target store, the state of customer is changed to "at store". On visit, the customer updates the quantity at store, the demand value. In case the quantity at the store is less the customer's demand, then the customer has to wait for the given time.
WaitTime = (Customer's demand - Quantity at Store) / Supply Rate
- Once the waiting time is over, the customer starts to move towards home location.
- Once reaching the home, the restTime is set in Random(1 , max-restTime).
- When the restTime becomes zero, the customer repeats the above steps starting from making a decision to which store to visit based on unhappiness value for each store for the given customer.

### Logic for Store
- At each time unit, the quantity of each store increases by the supply rate.
- If the quantity is more than the capacity of the store, quantity is set to the capacity.

## Schedules
- The order in which the customers and stores respectively perform actions is unimportant because there are no direct interactions.
- In our model implementation, first the customer agentset perform the action described in Customer Flowchart. The order of customers execution is random.
- After the customers have performed their respective actions, the stores update the quantity as per the supply rate. The order of stores execution is random and is unimportant.
- In each time unit, customers and stores execute one step in the flowchart moving to a new state (which may be the same as previous state).
- The visual outputs use synchronous updating such as the influence circles are updated at the end of the time step.
- There is no time limit for a run, so the user has to manually stop the go procedure if required.

# Design Concepts
### Basic Principles
**How Customers decide the Stores**
There are multiple factors by which a customer decide which store to visit such as travelling distance to the store, waiting time at the store, price, customer service, personal preferences and many more. Here in our models we have taken into consideration the first two factors that are the travelling distance to the store and waiting time at the store.

**'Unhappiness' value for a store of a customer**
Here we define the unhappiness value, as the unsatisfaction of the customer for the specific store. We take it as a linear combination of the travelling distance and average waiting time at the store. The customer keeps track of the average waiting at the store of his/her past visits to it.
So we define unhappiness value of a store for a customer as:
unhappiness value = Travelling Distance + Average Waiting Time for the customer in past visits
In case the customer has not visited a store once, the average waiting time for that store is taken to be 0. THe unhappiness value of the customer for calculating the average unhappiness and unhappiness distribution is taken to be the unappiness associated with its current target-store.

**Deciding target store for a customer**
The store that the customer will be visiting, will be the store which gives the minimum unhappiness value for the customer.

### Emergence
The key outcome of the model are the distribution of customers over the stores and the avaerage unhappiness value over the time period. Over the simulation, the customers would try to avoid the crowded stores with a preference of the location. The choices of the customers made over the time is based on the prediction from past experiences. The run of the model can be generally classified into three time phases - the initial phase, decision phase and the stable phase. In the initial phase, the customers are expected to prefer just the nearby store. But as certain store gets crowded, the customers of the specific store look for better alternatives stores. In the decision phase, the customer distribution keeps on changing as per the decision and crowd at the store and the average unhappiness values goes over a period of ups and downs. Finally after a long run, in stable phase, the average unhappiness value is expected to stabilise as the customers have made choice preferences based on the past visits to each store.

### Adaptation
**Deciding the target store**
When the customer wants to visit a store, it has to make the decision that which store it must visit. The choices available to each customer are all the stores on the grid. The decision is modeled as direct objective seeking, explained below.

### Objectives
**Direct Objective Seeking**
When deciding which store to visit, the customer chooses the store which gives the minimum unhappiness value to the customer. The unhappiness value as mentioned before is the sum of travelling time (taken as travelling distance here) and average waiting time at the store in past visits. In case the person has not visited the store before, then the waiting time for that store is taken to be zero. Each customer maintains the visit counts for each store, hence gets the average waiting time as (Total waiting time for the customer in past visits to the store) / Number of visits.

**To minimize the unhappiness value**
Each customer is making choices seeking to reduce its unhappiness value over the time. Due to each customer continuosly looking for better store alternatives, some stores over time get crowded forcing its existing customers to prefer other store alternatives.

### Learning
The average waiting time and thus the decision to choose the store based on minimum unhappiness value depends on the past experience of the customer at the store. As part of past experience, a customer maintains visit count to each store and the total waiting for the customer at the store in past visits, using this memory the customer calculates the average waiting time factor in unhappiness.
In case the customer has not visited the store at least once, the initial waiting time is assumed to be 0 for the customer.

### Prediction
**Implicit Prediction**
The adaptive behaviour of the customers is based on implicit prediction that choosing the store with minimum unhappiness value is likely to minimize the unhappiness value of the customer.

### Sensing
**Customers**
- Customers store the location and ID of the unique house agent associated with it.
- When a customer reaches it target store, it will know the current quantity (inventory) available at the store. It updates its waiting time at the store based on the available quantity at the store and its demand.
- Customer knows the location of each store and its distance from its home location.
- Customers sense the crowding at a store indirectly via the calculated waiting time at the store.
- Customer update the quantity of the target store upon reaching as per the its current demand.
- Customer all keeps track of its past experiences for each store.

**Stores**
- Stores can sense the number of customers associated with the store using the links between the stores and houses of current customers.
- Using the links connecting store and house locations of its current customers, the store can detect the distances of the current customers to its location.

**Houses**
- Each House is associated with a unique customer.

### Interaction
**Mediated Interaction between customers**
The customers interaction is mediated by the resource that they compete for, each customer is seeking to minimize its unhappiness value. A customer thus prefer less crowded stores over the more crowded ones, as it has to wait longer due to crowding at a store. As the number of stores and supply-rate is limited, the customers compete over the choices of the stores to get better experience.

**Direct Interaction between stores and customers**
When a customer reaches its target store, it updates the quantity available at the store as per its current demand. When the quantity available at the store is less than the demand, then the customer has to wait at the store for time = (demand - quantity at store) / supply-rate.

### Stochasticity
1. Uniform Random location of the customers and stores: In the beginning the customers at their associated home and the stores are located randomly over the grid.
2. RestTime: The time for which a customer must rest at home before going for next visit to store is random uniform in range 1 to person-max-rest-time.
3. Demand: The quantity required by a customer during a store visit is random uniform in range 1 to person-max-demand.
4. The order in which customers execute is random, to avoid bias on different customers arriving at same time at a store.

### Collectives
There are no major collectives in the model.
A minor case of collective in the model is the group of customers that belong to the same store. Their behaviour such as the demand value, rest time and distance from the store affects the other individual customers of the same store. Based on the arrival time and waiting at the store of the customer group, the individual customers may choose alternative stores.

### Observation
The models purpose is study the customer distribution and average unhappiness over the time. Also, the unhappiness distribution over the terrain and customer population. We also observe the influence of different stores based on the current setting of their location and proximity to other competing stores.

**Graphical Output**
- The color of the customer agent and its associated house shows where does its current unhappiness value lie in the unhappiness distribution of the population.
- Blue (Happiest ones) -- if the unhappiness value is below the mean - standard deviation of the distribution
- Green (Happy) -- else if the unhappiness value is below the mean of the distribution
- Orange (Unhappy) -- else if the unhappiness value is above the mean of the distribution
- Red (Unhappiest ones) -- if the unhappiness value is above the mean + standard deviation of the distribution
- The color of the patch shows a lighter tone of the color of the nearest house to the patch.
- Links between the stores and houses, shows the location of the house of the current customers of the store.
- The inner influence circles (every house inside the circle is the customer of the specified store only) and outer influence cirlces (show the distance from which the farthest customer is coming to the store)

**Plots**
- The distribution of customers over the stores (Histogram): Shows how many customers each store has at the current time
- The distribution of waiting customers over the stores (Histogram): Shows how many customers are currently waiting at each store
- Average Unhappiness (Line): The line plot shows how the average unhappiness varies over the complete simulation
- Unhappiness distribution over population (Histogram): Shows the count distribution of the unhappiness values over the population
**Output Monitors**
- Average Unhappiness value: The mean value of unhappiness value over the population (The unhappiness value for a customer is its unhappiness associated with its current target store)
- Standard Deviation of Unhappiness in Population: The standard deviation of the unhappiness values over the population
- Mean of inner influence radius: The mean of the inner influence radius of the stores
- Unhappiness Start Time: The first time at which each customers has visited at least one of the stores since the beginning of the simulation
- Standard Deviation of inner influence radius: The standard deviation of the radius of inner influence of the stores
- Mean of outer influence radius
- Standard Deviation of outer influence radius

# Details
## Initialization
- The location of the stores and customers is random over the grid.
- The intital quantity at each store is the store-capacity. The inventory at stores are assumed to be full in the beginning.
- The customers are located at the same location as the associated unique house.
- The visit count for each customer to each store is initialised to zero and the total waiting time for each store is zero as well.
- All the customers at the start are in "at home" state with a uniform random rest time in range 1 to max-person-rest-time.
- The color of the patches is initialized to some same color.
- The house id and house coordinates of the customer is set according to the house uniquely associated with the customer.

## Input data
The model does not use input data to represent the time-varying processes.

## Submodels
**Parameters to the Model**
- Supply rate (same for each store)
- Max quantity of store (same for each store)
- Max Demand of customers for a visit
- Max Rest time of customers after a visit

**Generating the house and customer pairs**
- For generating the house and customer pairs, first the customers are generated uniform random in the grid.
- Then each customer sprouts a house and the customer then stores its ID and location.

**Average Unhappiness Reporter**
- For calculating the average unhappiness, only those customers were considered which have at least visited the target store once.
- This was done to avoid unexpected trends in average unhappiness, due to many customers which are visiting the store for first time and the average waiting for that visit was thus taken as zero.
- Thus the mean is taken for the unhappiness values of the customers who have visited the current target store at least once.

**Calculating the Inner and Outer Influence circles**
- For the inner influence radius, the distance of the closest customer to the given store who is currently customer of any other store is taken.
- The outer influence raius, is the distance of the farthest current customers of the given store.

**Moving stores to Mean Location of current customers with and without unhappiness weights**
- We used these procedures to see if the store location can be optmized in the given distribution of customers over the grid.
- In attempt 1, after running the model for a long time, we can change the location of each stores as the mean coordinate of its current customers.
- In attempt 2, we move the stores to the unhappiness weighted mean coordinate of its current customers. That is x-coordinate = ( Sum(Unhappines of customer * x-coordinate of the customer) )/ (Number of customers of the given store). Similarly y-coordinate = (Sum(Unhappines of customer * y-coordinate of the customer)) / (Number of customers of the given store).

## Extending the Model
- In our model, we have only assumed a single type of commodity being sold by the stores. We can extend the model by having more than one commodities with different supply-rates for each commodity.
- Further the stores are assumed to have same suppy-rate, we can have different supply-rate for different stores. Different supply rates would signify the different production or procurement rate at the stores. Such as restaurent with larger cooking staff will have higher supply-rate of the quantities.
- The customer in our model, keeps track of all the past visits to each stores. We can implement a limit to the memory of the customer, such that the customer only remembers about the past 'n' visits.
- There can be customers influencing the customers that reside near their home location about the preference for the stores.

## Related Models
**Minority Game**
- At each step the minority agent group wins and their strategies are rewarded.
- We can think of our model as minority game on different stores, each person tries to avoid crowded stores but there is a cost factor of distance involved.

**El Farol**
- The problem also deals with reduced customer satisfaction when the customer finds the bar crowded during a visit.
- The agents here work on strategies seeking to visit the bar when it is uncrowded.

**Kolkata Paise Restaurant Problem**
- It is a variant of El Farol problem where customers have to choose between many restaurants.
- Each restaurant serves a limited number of customers and rest are not serviced.
- In our model as well, each customer has to decide which store to visit, but crowded stores result in long waiting times rather than denial of service.