/
index.html
437 lines (313 loc) · 12.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0016)http://localhost -->
<html>
<head>
<style>
td {
padding-right: 8pt;
padding-top: 4pt;
}
</style>
</head>
<document>
<img width="100%" src="img/epos_image_top.png"/>
<h1>The I-EPOS Project</h1>
I-EPOS is open source under the GNU General Public License v2.0 and it is accessible at
<a href="https://github.com/epournaras/EPOS">https://github.com/epournaras/EPOS</a>.
The project website is <a href="http://epos-net.org/">http://epos-net.org/</a>.
<h1>Getting Started</h1>
<ul>
<li>Start the virtual machine with configuration file <a href="vm/I-EPOS.ovf">vm/I-EPOS.ovf</a> and virtual disk <a href="vm/I-EPOS.vmdk">vm/I-EPOS.vmdk</a>.
<br/>
If you cannot start the virtual machine, try using <a href="https://www.virtualbox.org/wiki/Downloads">Oracle VirtualBox</a>. It was tested in Windows 10 and Mac OS Sierra.
</li>
<li>Login to user "I-EPOS VM" with password "iepos"</li>
<li>Now let us try to execute the program.<br>
Start the file "I-EPOS" on the homescreen with a double click.</li>
<li>The configuration window opens. This is the place where the simulation can be configured. It should look as follows:
<br/>
<img width="330pt" src="img/configuration.png"/></li>
<li>Click the "Run" button to start the simulation.</li>
<li>After a few seconds the result window should appear, showing the results of the simulation. More about this later. The window should look as follows:
<br/>
<img width="330pt" src="img/results.png"/></li>
<li>Click on the "Next" button in order to view the results of the second iteration. The bottom part of the result window should change.
The window should now look as follows:
<br/>
<img width="330pt" src="img/results2.png"/></li>
</ul>
<h1>Step-by-Step Instructions</h1>
The instructions assume that the VM is started, the user is logged in and is on the homescreen as described in Getting Started.
<ol type="A">
<li><p>
We consider a bicycle sharing system implemented in a city. Stations are set up all across the city each with bicycles and some free parking slots. As users drive across the city they move bicycles between the different stations. We notice that
over time some stations lack of bicycles, while others are running out of parking capacity. We solve this problem with I-EPOS.
</p>
<ol>
<li><p>
Start I-EPOS from the homescreen.
</p></li>
<li><p>
Select the dataset by clicking the "Browse" button to right of "Data Set Location",
and selecting the directory "bicycle".
</p></li>
<li><p>
We balance the bicycle load accross the stations by minimizing to zero or close to zero the changes in the number of bicycles stored in each station. Therefore, we leave the "Global Cost Location" at "zero.target". I-EPOS will try to
minimize the squared distance between the global cost and the target, that is the zero vector in this
case.
</p></li>
<li><p>
For now we are only interested in minimizing the global cost, so please set the "Local Cost Influence"
to 0.
</p></li>
<li><p>
The other parameters should be left as they are.
They specify that we want to execute I-EPOS in a binary tree over 15 iterations, which is sufficient
for the algorithm to converge for this example.
The "Seed" defines the seed for the random number generator used by I-EPOS.
Choosing a different value would result in slightly different results.
</p></li>
<li><p>
Click the "Run" button to start the simulation.
</p></li>
<li><p>
While I-EPOS is executing, it tries to find combinations of user plans that make the total change in
the number of bikes (referred to as global response) as small as possible.
When the result window opens, it shows in the top section how the algorithm managed to reduce the
global cost from its initial guess over a course of multiple iterations.
The initial guess is already
quite a lot better than the solution we get if we would let users freely choose bicycle stations. In
this case the global cost would be nearly 4000.
In the following iterations the global cost is quickly reduced and reaches its minimum after finishing
iteration 12.
</p><p>
On the bottom left we see the global response after the first iteration.
Each dimension in this plot represents the change in the number of bikes for one bicycle station
over a 2 hour time frame.
The initial guess of the algorithm shows that a station is missing 16 bikes after 2 hours of users
leaving from or arriving at the station.
If users could travel however they liked, the largest change would be over 50 bikes.
</p><p>
On the bottom right we see the network of agents. Each agent that changed its selection compared to
the previous iteration is marked with the color black.
Since this is the state after the first iteration, all agents had to select some initial plan and
therefore changed their selection.
</p></li>
<li><p>
Navigate through the iterations using the buttons "Next" and "Previous" to see how I-EPOS manages to
improve the global response step by step.
Notice how the global response gets gradually more stable over the iterations.
In the end I-EPOS is able to stabilize all stations so far that they loose or gain one
bicycle at most, compared to the 16 in the first iteration.
</p><p>
In the first few iterations we also see how I-EPOS ensures monotonic improvement of the global cost
- by limiting the change to a subset of agents.
</p></li>
<li><p>
Close the report window, so that you are back at the homescreen.
</p></li>
</ol>
</li>
<li><p>
We notice that the users may not prefer the suggestions I-EPOS makes.
If the users could freely choose their plans, the global response would be as follows:
</p><img src="img/bicycle_ml.png"/>
<p>
In order to make the system more appealing to users, we configure I-EPOS to take their preferences into account,
encoded in the local cost.
</p>
<ol>
<li><p>
Start I-EPOS from the homescreen.
</p></li>
<li><p>
Select the bicycle dataset again as explained above.
</p></li>
<li><p>
Set the "Local Cost Influence" to 0.9
</p></li>
<li><p>
Click the "Run" button to start the simulation.
</p></li>
<li><p>
I-EPOS now needs less iterations to reduce the global cost (top), since the local influence
to the plan selection process limits the flexibility of the algorithm in terms of global cost
minimzation.
The average local cost of all agents is also plotted as a dashed line. With about 0.004 it is nearly
optimal. Due to the fact that the users in the dataset can have multiple plans with minimal local
cost, I-EPOS still has enough freedom to greatly reduce the global cost.
</p><p>
The global response (bottom left) is already pretty similar
to the user preferred result shown above. However, I-EPOS manages to turn this initial solution
that many users like into a solution with much lower global cost without sacrifycing on the local
cost.
</p></li>
<li><p>
Navigate through the iterations again using the buttons "Next" and "Previous" to see how I-EPOS
manages to improve the global response step by step.
Notice that the global response is not as stable as it was in our previous simulation.
Observe that I-EPOS mainly reduces the large spikes in the user preferred response
(shown above) that have the largest effect on the global cost.
</p></li>
</ol>
</li>
<li><p>
Now assume that users have an app that provides recommendations which bicycle stations they should use.
However, not all of our users make use of the app.
We want to use I-EPOS to let all participating users help us to stabilize traffic from
non-participating users.
</p>
<ol>
<li><p>
Start I-EPOS from the homescreen.
</p></li>
<li><p>
Select the bicycle dataset again as explained in point A.
</p></li>
<li><p>
Select the target by clicking the "Browse" button to right of "Global Cost Location",
and selecting the file "incentive.target".
This target describes that we want the left half of the stations to lose 5 bikes and
the right half of the stations to receive 5 bikes over a 2 hour period.
This should correct all bicycle moves made by non-participating users.
</p></li>
<li><p>
Set the "Local Cost Influence" to 0.5 .
Usually we would of course choose 0.9 again. However, with a reduced local cost influence the results of
this scenario are more apparent.
</p></li>
<li><p>
Click the "Run" button to start the simulation.
</p></li>
<li><p>
This scenario now shows high negative values of bicycles in the first half of the stations on the
left, while the right half of the stations show highly positive values. The longer convergence
period of this scenario shown in the global cost plot (top) indicates that matching the target
is challenging in this case.
</p></li>
</ol>
</li>
</ol>
<h1>Live deployment</h1>
<p>
An implementation of I-EPOS for live deployment in which agents run in parallel as seprate processes
is available in the following branch:
<a href="https://github.com/epournaras/EPOS/tree/LiveExperiment">https://github.com/epournaras/EPOS/tree/LiveExperiment</a>. Note that this implementation is functional, yet experimental and it is work-in-progress to fully align it with simulations performed by the main software.
</p>
<p>
In order to execute it, <a href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">
Oracle Java 8</a> has to be installed.
It is at the moment only executable via commandline:<br/>
<code>cd experimental</code><br/>
<code>java -jar IEPOS.jar</code>
</p>
<h1>File reference</h1>
<table>
<tr>
<td><a href="conf">conf/</a></td>
<td>Contains configuration files used by I-EPOS.</td>
</tr>
<tr>
<td><a href="datasets">datasets/</a></td>
<td>Contains sample datasets for I-EPOS.</td>
</tr>
<tr>
<td><a href="datasets/bicycle">datasets/bicycle/</a></td>
<td>
The bicycle dataset. It contains data of a bicycle sharing system.
Each user of this system is represented as an agent.
The possible plans of each agent are encoded as a vector with values as the incoming
minus the outgoing bicycles of a user in each station at a
certain time slot. For example, a user traveling from station 1
to station 3 and from station 4 to station 3 has the following
plan: (-1, 0, 2, -1, ...). I-EPOS can select recommended
stations for each user agent such that the number of bicycles
among the stations remains balanced.
</td>
</tr>
<tr>
<td><a href="datasets/energy">datasets/energy/</a></td>
<td>
The energy dataset. It contains data about the electricity consumption of households.
Each household is represented as an agent.
The possible plans of each agent are encoded as a vector with each value being the electricity consumption at one point in time.
I-EPOS can be used to select plans in a way that electricity demand peaks are reduced.
</td>
</tr>
<tr>
<td><a href="datasets/gaussian">datasets/gaussian/</a></td>
<td>
The gaussian dataset. It contains generated data.
The possible plans of each agent are drawn from a multivariate standard normal distribution.
</td>
</tr>
<tr>
<td><a href="datasets/full_datasets.zip">datasets/full_datasets.zip</a></td>
<td>
Contains versions of the bicycle and energy dataset with more agents.
</td>
</tr>
<tr>
<td><a href="experimental/IEPOS.jar">experimental/IEPOS.jar</a></td>
<td>
Contains the experimental live version executable of I-EPOS.
</td>
</tr>
<tr>
<td><a href="img">img/</a></td>
<td>
Contains the image files shown in this document.
</td>
</tr>
<tr>
<td><a href="lib">lib/</a></td>
<td>Contains the libraries used by I-EPOS.</td>
</tr>
<tr>
<td><a href="videos">videos/</a></td>
<td>Contains videos showing different algorithms in action.
They demonstrate how agents change their plan selections over time.
At the end of the videos a plot is shown that summarizes how the global cost got reduced over
multiple iterations.</td>
</tr>
<tr>
<td><a href="vm">vm/</a></td>
<td>Contains the virtual machine configuration as well as its virtual hard disk.</td>
</tr>
<tr>
<td><a href="IEPOS.jar">IEPOS.jar</a></td>
<td>The I-EPOS executable.
In order to execute it, <a href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">
Oracle Java 8</a> has to be installed.
It is executable via double click on some platforms, or alternatively via commandline:
<code>java -jar IEPOS.jar</code>
</td>
</tr>
<tr>
<td><a href="index.html">index.html</a></td>
<td>This document.</td>
</tr>
<tr>
<td><a href="manual.pdf">manual.pdf</a></td>
<td>A description how to use I-EPOS and how to extend the functionality by adding custom datasets and custom cost functions.</td>
</tr>
<tr>
<td><a href="README.txt">README.txt</a></td>
<td>The readme file.</td>
</tr>
</table>
<h1>Troubleshooting</h1>
If you need help in using or extending I-EPOS, feel free to contact us.
<table>
<tr>
<td>Evangelos Pournaras</td>
<td><a href="epournaras@ethz.ch">epournaras@ethz.ch</a></td>
</tr>
<tr>
<td>Peter Pilgerstorfer</td>
<td><a href="peter.pilgerstorfer@outlook.com">peter.pilgerstorfer@outlook.com</a></td>
</tr>
</table>
<img width="100%" src="img/epos_image_bot.png"/>
</document>
</html>