Added README.md

[dyncnn.git] / README.md

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..eaee433
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# Description
+
+This is an attempt at predicting the dynamics of interacting objects
+with a deep network.
+
+I wrote a simple 2d physics engine in C++ that simulates moment of
+inertia, fluid frictions, and elastic collisions, and a residual
+network in Lua/Torch that predicts the final configuration of a set of
+rectangles, given a starting configuration and the location where a
+force is applied.
+
+Results and analysis are available
+in [`Fleuret (2016),`](https://fleuret.org/francois/publications.html#fleuret-2016) and you can have a look at
+a [`2min video.`](https://fleuret.org/francois/files/fleuret-NIPS-intuitive-physics-spotlight.mp4)
+
+This package is composed of a simple 2d physics simulator called
+'flatland' written in C++, to generate the data-set, and a deep
+residual network 'dyncnn' written in the Lua/Torch7 framework.
+
+You can run the reference experiment by executing the `run.sh` shell
+script.
+
+It will
+
+1. Generate the data-set of 40k triplets of images,
+
+2. Train the deep network, and output validation results every 100
+   epochs. This takes ~30h on a GTX 1080 with cuda 8.0, cudnn 5.1, and
+   recent torch.
+
+3. Generate two pictures of the internal activations.
+
+4. Generate a graph with the loss curves if gnuplot is installed.