Update documentation

LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2017 Cordell Bloor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,7 +1,62 @@
-## Ubuntu Dependencies
+```````````````````````````````````````````
+ _|_|_|_|            _|
+ _|        _|    _|  _|    _|_|    _|  _|_|
+ _|_|_|    _|    _|  _|  _|_|_|_|  _|_|
+ _|        _|    _|  _|  _|        _|
+ _|_|_|_|    _|_|_|  _|    _|_|_|  _|
 
-    sudo apt install cmake build-essential ninja-build
+```````````````````````````````````````````
+
+An ASCII art fluid simulator
+
+[![block of water](https://asciinema.org/a/125371.png)][ex1]
+
+## About
+Euler is a basic Eulerian fluid simulator based on the first edition of "Fluid
+Simulation for Computer Graphics" by Robert Bridson. The book is an improved
+version of his [SIGGRAPH 2007 Course Notes][1], which were developed in
+conjunction with Matthias Müller-Fischer.
+
+The project aim is to be minimal, correct and fun. It runs on Linux and OSX,
+but unfortunately not on Windows.
 
 ## How to Build
 
-    cmake -H. -B.build -G Ninja && cmake --build .build
+    cmake -H. -Bbuild && cmake --build build
+
+## How to Run
+Just pass a scenario file as an argument. Scenario files are plain text files,
+where `0` represents fluid, `X` represents a solid wall, `?` represents a fluid
+source and `=` represents a fluid sink. Maybe check out one of the
+[sample scenarios](scenarios) for ideas.
+
+    build/euler scenarios/block.txt
+
+Don't tell anyone, but I heard there's also a `--rainbow` flag you can pass.
+[I wonder what that does...][ex2]
+
+## Other Simulators
+There are some pretty cool simulators out there. [GridFluidSim3D][2] by Ryan
+Guy and [WebGL-PIC-FLIP-Fluid][3] by Austin Eng appear to be based off the
+second edition of Bridson's book. They are more featureful and much faster than
+Euler due to GPU acceleration, but the underlying fluid simulation is similar.
+
+## Bugs and Limitations
+* Fluid volume is not conserved. This can be corrected for, but conservation
+of volume, mass and momentum are not inherent properties of the simulation.
+* This implementation uses marker particles to track the fluid. They are rather
+noisy in comparison to level set methods and they tend to cluster.
+* Bridson recommends using RK2 integration for advection, but this simulation
+only uses RK1 integration. That necessitates smaller timesteps.
+* No preconditioning is done for the conjugate-gradient pressure solve, so
+the iteration limit is hit quite regularly.
+* Certain configurations of fluid and solid boundaries are only solvable with
+negative pressures. That is physically impossible, so those pressures are
+clamped to zero. This seems to suggest there is a bug in the implementation of
+pressure equations related to solid boundaries.
+
+[1]: https://www.cs.ubc.ca/~rbridson/fluidsimulation/fluids_notes.pdf
+[2]: https://github.com/rlguy/GridFluidSim3D
+[3]: https://github.com/austinEng/WebGL-PIC-FLIP-Fluid
+[ex1]: https://asciinema.org/a/125371
+[ex2]: https://asciinema.org/a/125380

scenarios/waterfall.txt

@@ -0,0 +1,38 @@
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+X????????????????????                                                                            X
+X????????????????????                                                                            X
+X????????????????????                                                                            X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                                                                                                X
+X                        X                                                                       X
+X                        X                                                                       X
+X                        X                                                                       X
+XXXXXXXXXXXXXXXXXXXXXXXXXX                                                                       X
+                         X                        X                                              X
+                         X                        X                                              X
+                         X                        X                                              X
+                         X                        X                                              X
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX                                              X
+=                                                                                                X
+=                                                                                                X
+=                                                                                                X
+=                                                                                                X
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX