You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
MDPvis is a visualization designed to assist in the MDP simulation and optimization process. See the forthcoming research paper for more details, "Facilitating Testing and Debugging of Markov Decision Processes with Interactive Visualization." To play with a live version of the visualization, visit [mdpvis.github.io/](http://mdpvis.github.io/).
3
+
MDPvis is a visualization designed to assist in the MDP simulation and optimization process. See "[Facilitating Testing and Debugging of Markov Decision Processes with Interactive Visualization](http://ieeexplore.ieee.org/xpl/login.jsp?tp=&arnumber=7357198&url=http%3A%2F%2Fieeexplore.ieee.org%2Fxpls%2Fabs_all.jsp%3Farnumber%3D7357198)." To play with a live version of the visualization, visit [mdpvis.github.io/](http://mdpvis.github.io/).
4
4
5
5
We built MDPvis as a web-based visualization so it would be:
6
6
@@ -22,142 +22,128 @@ If you don't use our hosted version of the MDPvis web application, you will need
22
22
2. Clone MDPvis into your MDP simulator code base, `cd YOUR_SIMULATOR;git clone git@github.com:MDPvis/MDPvis.github.io.git`. You can use a [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for this if you don't mind figuring out how they work. If you are going to contribute back to MDPvis, you should probably clone your fork of MDPvis.
4. Install a few Python libraries with `pip install -U flask-cors`.
25
-
5. Navigate into the MDPvis directory and start the server with `python flask_server.py`
26
-
27
-
At this point the server will start, but it will likely fail because the Flask server expects your MDP simulator to define a file in its code base called `domain_bridge.py`. The next (and final) section helps you define this file.
25
+
5. Navigate into the MDPvis directory and start the server with `./serve.sh`
26
+
6. Visit http://localhost:8000
27
+
7. Select one of the pre-existing simulation and optimization servers, or bridge MDPvis to your domain
28
28
29
29
# Bridging MDPvis and Your Domain
30
30
31
-
MDPvis interfaces with any MDP simulator+optimizer that is callable by a web server. If you use the web server packages with MDPvis, you can update an example `domain_bridge.py` file found in `example_domain_bridges`, otherwise we recommend viewing the example domain bridges and writing a version of the file as appropriate for your platform.
31
+
MDPvis interfaces with any MDP simulator+optimizer that is callable by a web server.
32
32
33
-
The bridges take the HTTP requests from the visualization, transforms the query parameters to those expected by the simulator or optimizer, invokes the simulator or optimizer, then returns the results to MDPvis. There are four distinct requests that the bridge should support. We detail these requests below
33
+
Your domain web server is responsible for serving four HTTP requests from the visualization, transforms the query parameters to those expected by the simulator or optimizer, invokes the simulator or optimizer, then returns the results to MDPvis. There are four distinct requests that the bridge should support. We detail these requests below.
34
34
35
-
The visualization expects your code to support the following requests. If your domain is written in Python, we recommend porting one of the example `domain_bridge.py` files to your domain.
36
35
37
36
## /initialize
38
37
39
-
The initialize endpoint doesn't query the simulator or optimizer, but it does provide a set of parameters that will influence those systems when requests are made. Here your responsibility is to return a [JSON](http://www.copterlabs.com/blog/json-what-it-is-how-it-works-how-to-use-it/) object listing the:
38
+
The `/initialize` endpoint provides a set of parameters that will be sent to the simulator or optimizer on future requests. Here your responsibility is to return a [JSON](http://www.copterlabs.com/blog/json-what-it-is-how-it-works-how-to-use-it/) object listing these properties:
40
39
41
40
* Name
42
41
* Description
43
42
* Current Value
44
43
* Minimum Value
45
44
* Maximum Value
45
+
* Step (How fast the value changes when pressing a button)
46
+
* Units
46
47
47
-
of each parameter. An example of this data structure in Python is:
In the MDPvis user interface, each control will be grouped into panels for the reward, model (transition function), and policy.
86
-
87
-
## /rollouts?QUERY
88
-
89
-
When requesting Monte Carlo rollouts, MDPvis will send the current set of parameters as defined in the initialization and assigned in the user interface. The job of the domain bridge is to map the parameters of the user interface into parameters to invoke the simulator. After simulations have completed, the data should be JSON serialized. An example of the data in Python is:
90
51
91
-
return [
52
+
# The control panels that appear at the top of the screen
53
+
"parameter_collections": [
54
+
{
55
+
"panel_title": "Sampling Effort",
56
+
"panel_icon": "glyphicon-retweet",
57
+
"panel_description": "Define how many trajectories you want to generate, and to what time horizon.",
58
+
"quantitative": [ # Real valued parameters
59
+
{
60
+
"name": "Sample Count",
61
+
"description": "Specify how many trajectories to generate",
62
+
"current_value": 10,
63
+
"max": 1000,
64
+
"min": 1,
65
+
"step": 10,
66
+
"units": "#"
67
+
},
68
+
{
69
+
"name": "Horizon",
70
+
"description": "The time step at which simulation terminates",
71
+
"current_value": 10,
72
+
"max": 10000,
73
+
"min": 1,
74
+
"step": 10,
75
+
"units": "Time Steps"
76
+
},
77
+
{
78
+
"name": "Seed",
79
+
"description": "The random seed used for simulations",
80
+
"current_value": 0,
81
+
"max": 100000,
82
+
"min": 1,
83
+
"step": 1,
84
+
"units": "NA"
85
+
}
86
+
]
87
+
}
88
+
]
89
+
}
90
+
91
+
In the MDPvis user interface, each control will be grouped into panels under the `panel_title`
92
+
and display the [icon](http://getbootstrap.com/components/#glyphicons) specified by `panel_icon`.
93
+
94
+
## /trajectories?QUERY
95
+
96
+
When requesting Monte Carlo trajectories, MDPvis will send the current set of parameters as defined in the initialization and assigned in the user interface. The job of the web server is to map the parameters of the user interface into parameters to invoke the simulator. After simulations have completed, the data should be JSON serialized. An example of the data in Python is:
MDPvis does not require you to integrate `/optimize` and `/state`, but it is very useful for exploring most problems. Here all the same parameters as are sent to `/rollouts` are sent to `/optimize`, but this query only returns an updated policy. Here is a python example:
105
-
106
-
return [
107
-
{"Constant": 10},
108
-
{"Fuel Load 8": 3},
109
-
{"Fuel Load 24": -1}
110
-
]
111
-
112
-
## /state?QUERY
105
+
]}
113
106
114
-
This query will be issued when a user clicks an individual rollout in the visualization. All the parameters used to generate the rollout will be sent, with an additional parameter for the rollout number. The expectation is you will use this information to re-generate the rollout and use the simulator to generate descriptive statistics and/or images for the states.
107
+
These data are two trajectories of two states each. An additional special state variable, `image row`, gives
108
+
an array of images or videos that should be displayed when selecting a trajectory. For example:
There is a default set of visualizations, but if you want to add your own visualizations you should be aware of the three visualization types in MDPvis. These break Monte Carlo rollouts into visualizations for a single time step, variables through time (temporal distributions), and details on a single rollout. Details on these three aspects are below.
Monte Carlo rollouts produce a distribution of states at every time step. This view gives details on the distribution for the currently selected time step. Users may select the current time step for all these visualizations simultaneously from the top of the visualization area, or from the temporal distribution area.
119
+
will attempt to display the images `traj1-1.png` and `traj1-1.png` when the user clicks the associated trajectory.
135
120
136
-
* Histogram
137
-
* Bar Chart (comparison mode)
121
+
## /optimize?QUERY
138
122
139
-
**Temporal Distributions**
123
+
MDPvis does not require you to integrate `/optimize` and `/state`, but it is very useful for exploring most problems. Here all the same parameters as are sent to `/trajectories` are sent to `/optimize`, but this query only returns an updated policy. Here is a python example for a logistic regression based policy:
140
124
141
-
In this area we show how the distribution of state variables develops through time.
125
+
return {"Constant": 10,
126
+
"Fuel Load 8": 3,
127
+
"Fuel Load 24": -1}
142
128
143
-
* Fan Chart
144
-
* Fan Chart (comparison mode)
145
-
* Time Series
129
+
Here is an example where the policy parameters represent versions of a neural network. This would allow for comparing between the performances of different neural networks and
130
+
asking for additional training of an existing network.
146
131
147
-
**Single Rollout**
132
+
return [
133
+
{"network version": 5}
134
+
]
148
135
149
-
Here a single rollout is shown. This could give a sequence of state snapshots provided as images from the MDP simulator.
136
+
## /STATE_DETAIL
150
137
151
-
* State images (provided by simulator)
152
-
* Stats panel
138
+
This query will be issued when a user clicks an individual trajectory in the visualization and the state detail area populates with the images and videos specified by the trajectory's "image row" variable. The expectation is you will use the file name to re-generate the trajectory and use the simulator to generate descriptive statistics, videos, and/or images for the states.
153
139
154
140
## Implementing a New Visualization
155
141
156
142
If you are interested in implementing a new visualization within MDPvis, we encourage you to make contact by opening an issue in this visualization. The code base is under active development and will be changing substantially to be more easily extensible.
157
143
158
144
You've been warned. Here are the steps:
159
145
160
-
1. Select a visualization aspect (Single Time Step Distributions, Temporal Distributions, Single Rollout)
146
+
1. Select a visualization aspect (Single Time Step Distributions, Temporal Distributions, Single Trajectory)
161
147
1. Copy an existing visualization's script that has the chosen aspect
162
148
1. Add the script to index.html
163
149
1. Update the index.js script to call your visualization and add it to the DOM.
@@ -172,4 +158,3 @@ Maintainer Mailing Address: PO Box 79, Corvallis, OR 97339, United States of Ame
172
158
173
159
Implementation by: Sean McGregor
174
160
With: Hailey Buckingham, Thomas G. Dietterich, Rachel Houtman, Claire Montgomery, and Ronald Metoyer
0 commit comments