ctn-waterloo/nengo — pull request #265 by arvoelke (2014-02-26 21:10:37+00:00)
Title: Decouple API from Builder

Branching off Trevor's "builder_nochange", this commit attempts to complete his efforts to decouple objects.py from builder.py. This is a massive PR, and github did not do a great job at diffing. Let me know when you would like to go through the changes in person.

Reorganization:
- objects.py renamed to api.py
- nonlinearities.py moved into api.py (TODO: remove all math from API)
- builder.py signals/operaters moved into core.py
- util.py added as a catch-all for generic functions/tools

API Changes:
- Builder no longer modifies any objects
- Network is now an empty subclass of Model (only a syntactic difference)
- Default contexts are more robust and error friendly
- Objects attempt to act as pure data containers. Builder-specific manipulations of attributes and logic is delayed to build time
- All Model objects subclass from NengoObject to make it easy to serialize the entire model.

Builder Changes:
- Recurses on a hierarchical model
- Error handling for duplicate objects and proper association of Neurons with Ensembles
- Built model is incrementally added to a standalone BuiltModel object
- State of the build is managed more explicitly
- Builder created per model, to make the scope of its state more explicit (and more easily thread-safe in the future)

TODO:
- Add and update doctypes in api.py and builder.py
- Do validation in api.py during construction and recursively on the Model object
- Remove dependency of some tests/examples on temporary Builder state (also think about the best way to expose the necessary data to any frontend)
- Simplify case handling in build methods (e.g. \_build_connection) by reworking the NengoObject hierarchy