X-Git-Url: https://fleuret.org/cgi-bin/gitweb/gitweb.cgi?p=dyncnn.git;a=blobdiff_plain;f=README.md;fp=README.md;h=eaee433aac9cb8295b68035c0919e22598dd88f9;hp=0000000000000000000000000000000000000000;hb=aa2b6b28aef52cac1bdc30dc289b6460ea5e2132;hpb=8cce872485111eaa79ce60041715227a8ff4d45f

diff --git a/README.md b/README.md
new file mode 100644
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.