README file

For the paper:
Solving for Equilibrium in the Basic Bathtub Model
Arnott and Buli (2017)
============================================================================

Code can be found at: 

http://math.ucr.edu/~buli/Bathtub_Code/Bathtub_Code.html

============================================================================

How To Use The Code
----------------------------------------------------------------------------

There is a set of 4 MATLAB files, for each case considered
in the paper Arnott and Buli (2017). For the fixed trip 
distance parameter L, there is a maximum number of cycles, 
specifically three full cycles and one partial cycle. The 
difference in each of the files is:

1) Size of the matrices (4.24) and (4.25). The matirices
increase in size by one in the number of rows and columns
as the number of cycles increases. 

2) The \delta u and \delta t values are different depending 
on the number of cycles, and if the system is congested or 
hypercongested. 

3) The way the new value of start time is computed in the 
inner loop. Code is present for using a fixed \delta t which 
is subtracted from the current value of start time. Also, a
Newton's Method was also used, so that code is present as 
well. 

The utility parameters for the logarithmic utility function
were chosen to give sensible results, as stated in the paper. 
The utility values were estimated to give values similar to 
the exponential utility function given in the paper 
Hjorth, K et. all (2015). 

The code for the algorithm can be run directly in the MATLAB 
console as a script, without any additional functions or downloads. 
The G and H function file requires saved data found in the sub-
folder labeled "Saved Data". 

For example, 
to use the algorithm for the one partial entry cycle code, and one 
specific value of utility, the while loop in lines 211 and 
575 can be commented out. For example, with the logarthimic 
utility function, lines 180/181 can be commented out, and 
182/183 can be uncommented, to create Figure 5.1 from the 
paper. To find an appropriate starting value t_up, the G and H 
function code can be run to give an approximate starting value
for the time of the first departure.

The code for one full, one partial entry cycle is currently 
set to only produce Figure 5.3, ie. for one value of utility where
aggregate hypercongestion is seen. This can be changed to get the 
equilibrium for all the utility levels for one full, one partial
entry cycle by commenting out the analagous lines of code as the 
case in the above paragraph. 

The code for the other cases can similarly be modified to plot the 
equilibrium functions. If the value of the trip distance, L, is 
changed, then the G functions will have to be recomputed using the 
G and H function file on the website.

The G and H function plot includes the G functions for the provided 
utility values for the logarithmic utility function case using the 
MATLAB function "fimplcit". The G functions can also be computed 
using the contourplot command. Both methods are included, but the 
fimplicit method is the one implemented. For better resolution, 
increase the value of 'MeshDensity' in the plot command. For higher
values, the plot becomes more refined at lower utilities, but the 
computation takes longer, and the file will be of large size (GB's). 
 
The Figure 1 that is printed, is of the G and H functions, which is 
Figure 4.2 in the paper. 

The figures involving the number of commuters can also be created 
via the G and H function file. Figure 2 is the plot of utility vs the 
number of commuters N. Figure 3 recreates Figure 5.4(a) from the paper.
Figure 4 is the plot of number of commuters vs. the time of the 
first entry.