Updates the readme

andyljones · Jul 20, 2020 · 1060748 · 1060748
1 parent 4e5d816
commit 1060748
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 68 deletions.
diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -356,8 +356,20 @@ TODO-DOCS Models concept
 
 Subpackages
 ===========
+There are several roughly independent pieces of code in megastep.
 
-TODO-DOCS Subpackages concept
+Firstly there's megastep itself. This is the environment development library, with its CUDA kernels and modules 
+and raggeds.
+
+Then there's :mod:`~megastep.cubicasa`, which is a database of 5000 floorplans. The cubicasa module while small in
+and of itself, requires some hefty geospatial dependencies. It uses these to cut the original floorplan SVGs into
+pieces and reassemble them as arrays that are useful for reinforcement learning research. It's offered as an extra
+install because many users might want to avoid installing all those dependencies.
+
+Finally there's :mod:`~rebar`. rebar is my - Andy Jones's - personal reinforcement learning toolbox. While the bits
+of it that megastep depend on are stable and well-documented, the rest of it is not. That it's still in the megastep
+repo is a bit of a historical artefact. One of my next tasks after getting megastep sorted is to get rebar equally
+well documented and tested, and then probably carve the unstable bits out into their own repo and package.
 
 .. _spaces:
 

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -15,58 +15,27 @@ All the state is kept in `pytorch <https://pytorch.org/>`_ tensors, and only the
 rendering kernels are written in CUDA. Game logic is pretty fast compared to physics and rendering, so that
 can be done in Python with the ops provided by pytorch. Thanks, pytorch. 
 
-.. _inheritance:
-
-Why doesn't megastep use inheritance?
--------------------------------------
-A general adage in software is to prefer `composition over inheritance <https://stackoverflow.com/questions/49002/prefer-composition-over-inheritance>`_.
-It's a good rule of thumb, but I feel that of the realities of research code make the preference even more extreme.
-
-Research code is a very unusual kind of code. It's `written many times and read once (if ever) <https://devblogs.microsoft.com/oldnewthing/20070406-00/?p=27343>`_,
-it's typically written by one person in a short period of time and it's typically only a few thousand lines of code
-that are understood inside and out. Because of this, researchers can happily trade off a lot of otherwise-good
-development practices in favour of iteration velocity - the ability to adapt your codebase to a new idea quickly and
-easily.
-
-Since megastep is explicitly intended to be a foundation for research, flexibility and iteration velocity feel far more 
-important than the robustness you get from inheritance. 
-
-.. _openai-gym:
-
-Why don't you use the OpenAI Gym interface?
--------------------------------------------
-There are a couple of ways in which megastep departs from the `Gym interface <https://gym.openai.com/docs/#environments>`_.
-
-The first way is that all the observations, rewards, and resets are vectorized. This is necessary, as megastep is 
-naturally vectorized in a way that the Gym envs aren't. 
-
-The second, more debatable way is that the Gym returns observations, rewards and resets as a tuple, and takes actions. 
-megastep meanwhile :ref:`passes dicts of these things in both directions <decision-world>`. The advantage of this is
-opacity: if you want to pass some extra information between env and agent - the most common kind being when a reset 
-occurs so that the agent can clear its memory - it's just an extra key in the dict. The experience collection loop 
-that mediates between env and agent doesn't need to know anything about it. 
-
-Writing a shim that turns any megastep env into an Gym env should be easy enough if you're so inclined.
-
-.. _cubicasa-license:
+What about other OSes?
+----------------------
+If you're on a different OS, then it's possible megastep will work, but I can't provide you any support. You're welcome
+to ask for help on the GitHub issues page, but you'll be relying on the community to come up with an answer.
 
-What's with the cubicasa license?
----------------------------------
-The cubicasa dataset - the dataset of 5000 home layouts - is derived from the `Cubicasa5k <https://github.com/CubiCasa/CubiCasa5k>`_ 
-dataset. This dataset was released under a CreativeCommons Non-Commercial License, while megastep as a whole is under a 
-MIT license. Since the cubicasa dataset in this project is a heavily-modified version of the original dataset, I think
-it could be plausibly considered `transformative use <https://www.copyright.gov/fair-use/more-info.html#:~:text=Transformative%20uses%20are%20those%20that,purpose%20of%20encouraging%20creative%20expression.>`_
-and so be re-released under an MIT license. But as an independent researcher with no legal team, I can't risk claiming 
-that. Rather I've emailed Cubicasa and asked for their blessing on this interpretation.
+What if I don't have CUDA?
+--------------------------
+If you haven't got CUDA, megastep will not work. There are some parts of megastep - like the cubicasa package - 
+that you may still find useful, but in that case I recommend just copy-pasting the code you want from Github.
 
-In the meantime though, downloading the cubicasa dataset is hidden behind a is-this-commercial-use prompt. Not ideal,
-but the best I could come up with.
+How can I install *just* megastep?
+----------------------------------
+The default :ref:`install <install>` pulls in everything needed to run the demos and tutorials. If you want something
+minimal:
+
+..code-block:: shell 
 
-If you would like to use megastep for commercial purposes, you are absolutely welcome to - just use a different geometry
-sampler to the default one. There are the :mod:`~megastep.toys` geometries already available, and writing a maze 
-generator should be fairly simple - just output a dict conforming :ref:`to the spec <geometry>`.
+    pip install megastep
 
-.. _why:
+ie, omit the bit in square brackets. You can read more about what's missing in the :ref:`subpackages <subpackages>`
+section.
 
 Why did you write megastep?
 ---------------------------
@@ -94,7 +63,8 @@ should aim my efforts at the compute side of things rather than the simulation s
 That's me though! If you're interested in taking megastep forward, here are some research directions I had queued up:
  * Add better physics. Right now the physics is that there are dynamic circles and static lines, and if two objects
    collide they stop moving. With better physics, you could plausibly recreate `OpenAI's Hide & Seek <https://openai.com/blog/emergent-tool-use/>`_
-   work. Demonstrate transfer learning across sims. Can behaviour learned in a fast, cheap simulation like this one
+   work. 
+ * Demonstrate transfer learning across sims. Can behaviour learned in a fast, cheap simulation like this one
    be transferred to an expensive sim like `AirSim <https://microsoft.github.io/AirSim/>`_?
  * Generative geometric modelling. Deepmind have a cool paper on learning priors about the world `from egomotion alone <https://deepmind.com/blog/article/neural-scene-representation-and-rendering>`_. 
    Again, can this be demonstrated on far cheaper hardware if you work in a faster simulator? 
@@ -116,27 +86,25 @@ What are some alternatives to megastep?
  * `CuLE <https://github.com/NVlabs/cule>`_
  * `AirSim <https://microsoft.github.io/AirSim/>`_
 
-What about other OSes?
-----------------------
-If you're on a different OS, then it's possible megastep will work, but I can't provide you any support. You're welcome
-to ask for help on the GitHub issues page, but you'll be relying on the community to come up with an answer.
+.. _cubicasa-license:
 
-What if I don't have CUDA?
---------------------------
-If you haven't got CUDA, megastep will not work. There are some parts of megastep - like the cubicasa package - 
-that you may still find useful, but in that case I recommend just copy-pasting the code you want from Github.
+What's with the cubicasa license?
+---------------------------------
+The cubicasa dataset - the dataset of 5000 home layouts - is derived from the `Cubicasa5k <https://github.com/CubiCasa/CubiCasa5k>`_ 
+dataset. This dataset was released under a CreativeCommons Non-Commercial License, while megastep as a whole is under a 
+MIT license. Since the cubicasa dataset in this project is a heavily-modified version of the original dataset, I think
+it could be plausibly considered `transformative use <https://www.copyright.gov/fair-use/more-info.html#:~:text=Transformative%20uses%20are%20those%20that,purpose%20of%20encouraging%20creative%20expression.>`_
+and so be re-released under an MIT license. But as an independent researcher with no legal team, I can't risk claiming 
+that. Rather I've emailed Cubicasa and asked for their blessing on this interpretation.
 
-How can I install *just* megastep?
-----------------------------------
-The default :ref:`install <install>` pulls in everything needed to run the demos and tutorials. If you want something
-minimal:
-
-..code-block:: shell 
+In the meantime though, downloading the cubicasa dataset is hidden behind a is-this-commercial-use prompt. Not ideal,
+but the best I could come up with.
 
-    pip install megastep
+If you would like to use megastep for commercial purposes, you are absolutely welcome to - just use a different geometry
+sampler to the default one. There are the :mod:`~megastep.toys` geometries already available, and writing a maze 
+generator should be fairly simple - just output a dict conforming :ref:`to the spec <geometry>`.
 
-ie, omit the bit in square brackets. You can read more about what's missing in the :ref:`subpackages <subpackages>`
-section.
+.. _why:
 
 How should I cite this?
 -----------------------
@@ -148,4 +116,39 @@ How should I cite this?
       url = {https://andyljones.com/megastep},
       version = {0.1},
       date = {2020-07-07},
-    }
+    }
+   
+.. _inheritance:
+
+Why doesn't megastep use inheritance?
+-------------------------------------
+A general adage in software is to prefer `composition over inheritance <https://stackoverflow.com/questions/49002/prefer-composition-over-inheritance>`_.
+It's a good rule of thumb, but I feel that of the realities of research code make the preference even more extreme.
+
+Research code is a very unusual kind of code. It's `written many times and read once (if ever) <https://devblogs.microsoft.com/oldnewthing/20070406-00/?p=27343>`_,
+it's typically written by one person in a short period of time and it's typically only a few thousand lines of code
+that are understood inside and out. Because of this, researchers can happily trade off a lot of otherwise-good
+development practices in favour of iteration velocity - the ability to adapt your codebase to a new idea quickly and
+easily.
+
+Since megastep is explicitly intended to be a foundation for research, flexibility and iteration velocity feel far more 
+important than the robustness you get from inheritance. 
+
+.. _openai-gym:
+
+Why don't you use the OpenAI Gym interface?
+-------------------------------------------
+There are a couple of ways in which megastep departs from the `Gym interface <https://gym.openai.com/docs/#environments>`_.
+
+The first way is that all the observations, rewards, and resets are vectorized. This is necessary, as megastep is 
+naturally vectorized in a way that the Gym envs aren't. 
+
+The second, more debatable way is that the Gym returns observations, rewards and resets as a tuple, and takes actions. 
+megastep meanwhile :ref:`passes dicts of these things in both directions <decision-world>`. The advantage of this is
+opacity: if you want to pass some extra information between env and agent - the most common kind being when a reset 
+occurs so that the agent can clear its memory - it's just an extra key in the dict. The experience collection loop 
+that mediates between env and agent doesn't need to know anything about it. 
+
+Writing a shim that turns any megastep env into an Gym env should be easy enough if you're so inclined.
+
+