Add some advanced features documentation. #1130

jgosmann · 2016-07-23T03:48:31Z

Description:
Extends the documentation with some advanced topics. In particular:

The Nengo RC file and available settings.
How to improve the performance.

Motivation and context:
The performance documentation is probably useful for new users who start to build larger models. Also it provides documentation for how to activate/deactivate the operator graph optimizer which is important because it provides a trade off between build time and simulation time.

In this documentation I had to reference the Nengo RC files which prompted me to add the missing documentation for that file and the settings too.

This PR closes #1119, addresses #1017.

Interactions with other PRs:
This adds documentation for the yet to be merged PR #1035. This assumes that the optimizer is active by default, but I could see this being changed. In that case this PR needs to be updated.

How has this been tested?
Build the docs and skimmed over it and tested cross-reference links. Should probably get a more careful read, preferably by a native speaker.

Where should a reviewer start?
Build the docs and start reading the "Advanced Topics" section.

How long should this take to review?

Average (neither quick nor lengthy)

Types of changes:

New feature (non-breaking change which adds functionality)

Checklist:

I have read the CONTRIBUTING.rst document.
I have updated the documentation accordingly❗
I have included a changelog entry.
I have added tests to cover my changes.
All new and existing tests passed.

Still to do:

Potential updates if adjustments are made in Operator graph optimizer #1035 before it gets merged.

mention-bot · 2016-07-23T03:48:33Z

@jgosmann, thanks for your PR! By analyzing the annotation information on this pull request, we identified @tbekolay to be a potential reviewer

Seanny123 · 2016-07-26T22:18:14Z

docs/improving_performance.rst

+build of a model will still take about the same time (technically a bit longer,
+because the computed decoders will be stored), but all subsequent builds of the
+same model can just load the stored decoders and will be faster. This will also
+work to some degree if changes to the model are made, but of course only for


Remove of course. It's kind of condescending. Maybe people don't know what caching is in this context.

Seanny123 · 2016-07-26T22:48:22Z

Left some inline comments to fix some phrasing.

jgosmann · 2016-07-27T02:49:24Z

I set this to "needs second review". Those changes can be easily made by whoever merges this if I don't get to it beforehand.

mgserafi · 2016-08-12T20:21:49Z

Made minor changes to the phrasing. Added @Seanny123's suggested changes.

tbekolay · 2016-08-19T21:17:09Z

I also took a look at this, only partly in order to get my review in for the week ;)

Docs look great, really nice addition, and nice to have an advanced features section for more esoteric information 👍 I pushed a commit with some slight rewordings. I also added the WIP label because this is blocked by #1035.

One thing that I would like to do (but am not sure how to do best) is not duplicate the nengorc information. Right now, that information is nicely laid out in the new nengorc.rst doc, but similar (yet not the same) documentation exists in nengo-data/nengorc, and also in nengo/rc.py. Ideally it would only be in one place, so the question is where. I think I would prefer it to be in the new doc that's in this PR, and then we should link that that document (somehow) in rc.py, and remove it from nengorc.

One thing that matplotlib does is link to and include a copy of a sample rc file in there, which we could also do with the include directive. I think it'd be especially nice if the nengorc included there is barebones instead of the super verbose version that matplotlib has (since the .rst file will always be able to render a nicer version of the docs).

jgosmann · 2016-08-19T21:40:02Z

I think it'd be especially nice if the nengorc included there is barebones instead of the super verbose version that matplotlib has

I think it is nice to have a verbose sample rc file because then I can edit it and have all the required information right there without the need to navigate to the documentation.

tbekolay · 2016-08-20T09:53:01Z

'kay, then why don't we include the verbose sample in the docs rather than duplicating the information?

jgosmann · 2016-08-20T14:28:49Z

Sure, but the sample file will need some updating (probably should've been updated in the first place).

tbekolay · 2016-08-23T15:30:15Z

Pushed a commit updating the sample file and rc.py so that there's only a tiny bit of duplication of information. In the generated output, the RC settings docs look pretty good to me now (the performance doc already looked good).

If you want to see the generated docs, I can send put the HTML files up somewhere, or you can try building the docs yourself. I do python setup.py build_sphinx; the only oddity is that you currently have to downgrade to ipython[all]==2.4.1 as the doc building hasn't been updated; I was working on updating it in the nbsphinx branch but that hit a few issues I haven't solved yet.

jgosmann · 2016-08-23T16:06:32Z

python setup.py build_sphinx

error: invalid command 'build_sphinx'

jgosmann · 2016-08-23T16:08:02Z

(I didn't have the requirement installed, but the error message is not really helpful in that case.)

tbekolay · 2016-08-23T16:11:01Z

(I didn't have the requirement installed, but the error message is not really helpful in that case.)

Yeah... we could add something to setup.py to detect that but it doesn't really seem worth the additional code as probably three people in the world have tried to build the docs.

jgosmann · 2016-08-23T16:49:27Z

To dos:

Mention that the optimizer can do certain optimizations only if SciPy is installed.
Add configuration options for optimizer to sample rc file.

tbekolay · 2016-08-23T16:53:34Z

Add configuration options for optimizer to sample rc file.

I did in my commit, I think... at least, I added the ones that were in the nengorc.rst doc.

jgosmann · 2016-08-23T17:01:52Z

Seem to be missing to me ... (or maybe I forgot to add those in the first place)

jgosmann · 2016-08-23T17:03:29Z

The [OpMergeOptimizer] section heading is missing (that was what I was searching for).

tbekolay · 2016-08-23T17:04:18Z

I added two options, see https://github.com/nengo/nengo/pull/1130/files#diff-e6c6a36ed8df7b1bd3ac3887920554ccR60, not sure if there are more...

tbekolay · 2016-08-23T17:05:27Z

Ah, right you are! Should probably be op_merge_optimizer to match the other sections, but yeah, I missed that.

jgosmann · 2016-08-23T17:13:45Z

Should probably be op_merge_optimizer to match the other sections, but yeah, I missed that.

It needs to match the class name with the current implementation.

jgosmann · 2016-08-23T17:23:59Z

Fixed those things.

tbekolay · 2016-10-18T20:47:12Z

As per the discussion at the dev meeting, when this is merged, it should close #340.

Seanny123

This still looks good to me. Special thanks to @mgserafi for the fixes I pointed out and really should have fixed myself.

jgosmann · 2017-04-18T17:18:40Z

Added commits to update this to match what has actually been merged to master.

Seanny123 · 2017-04-19T00:08:08Z

This is still good. The flake8 TravisCI errors should be fixed by bringing this branch up to date and I'm sure whoever resolves the conflicts will fix CHANGES.rst to refer to the right Nengo version.

tbekolay

Pushed a fixup with a few final touchups. I'll merge on @jgosmann's OK!

jgosmann · 2017-05-12T19:53:19Z

LGTM 🍰

* Methods to improve the performance. * Nengo RC file and documentation of possible settings. This mostly involves updating the docstrings in nengo/rc.py and including them in the documentation. Also included an intersphinx mapping to the Python 3 docs so that we can reference Python objects easily.

jgosmann added the needs review label Jul 23, 2016

Seanny123 reviewed Jul 26, 2016
View reviewed changes

Seanny123 added needs changes and removed needs review labels Jul 26, 2016

jgosmann added needs second review and removed needs changes labels Jul 27, 2016

mgserafi self-assigned this Aug 12, 2016

mgserafi added reviewed and removed needs second review labels Aug 12, 2016

tbekolay unassigned mgserafi Aug 19, 2016

tbekolay added the work in progress label Aug 19, 2016

tbekolay self-assigned this Aug 23, 2016

tbekolay removed their assignment Oct 18, 2016

Seanny123 removed the work in progress label Nov 10, 2016

jgosmann mentioned this pull request Nov 11, 2016

Operator graph optimizer #1035

Merged

15 tasks

jgosmann mentioned this pull request Dec 13, 2016

Ignore failed move of cache index and warn. #1235

Merged

3 tasks

tbekolay mentioned this pull request Dec 14, 2016

Add advanced connection documentation #1244

Merged

5 tasks

jgosmann mentioned this pull request Feb 6, 2017

Warn if cache move fails. #1264

Closed

4 tasks

Seanny123 approved these changes Mar 27, 2017

View reviewed changes

jgosmann added the needs changes label Apr 12, 2017

jgosmann self-assigned this Apr 12, 2017

tbekolay removed needs changes labels Apr 18, 2017

jgosmann removed their assignment Apr 18, 2017

tbekolay approved these changes May 12, 2017

View reviewed changes

tbekolay force-pushed the doc-performance branch from ea45ddb to 226e596 Compare May 12, 2017 20:13

tbekolay force-pushed the doc-performance branch from 226e596 to 76939b0 Compare May 12, 2017 20:17

tbekolay merged commit 76939b0 into master May 12, 2017

tbekolay deleted the doc-performance branch May 12, 2017 20:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add some advanced features documentation. #1130

Add some advanced features documentation. #1130

jgosmann commented Jul 23, 2016 •

edited

Loading

mention-bot commented Jul 23, 2016

Seanny123 Jul 26, 2016

Seanny123 commented Jul 26, 2016

jgosmann commented Jul 27, 2016

mgserafi commented Aug 12, 2016

tbekolay commented Aug 19, 2016

jgosmann commented Aug 19, 2016

tbekolay commented Aug 20, 2016

jgosmann commented Aug 20, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016 •

edited

Loading

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Aug 23, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Oct 18, 2016

Seanny123 left a comment

jgosmann commented Apr 18, 2017

Seanny123 commented Apr 19, 2017

tbekolay left a comment

jgosmann commented May 12, 2017

Add some advanced features documentation. #1130

Add some advanced features documentation. #1130

Conversation

jgosmann commented Jul 23, 2016 • edited Loading

mention-bot commented Jul 23, 2016

Seanny123 Jul 26, 2016

Choose a reason for hiding this comment

Seanny123 commented Jul 26, 2016

jgosmann commented Jul 27, 2016

mgserafi commented Aug 12, 2016

tbekolay commented Aug 19, 2016

jgosmann commented Aug 19, 2016

tbekolay commented Aug 20, 2016

jgosmann commented Aug 20, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016 • edited Loading

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Aug 23, 2016

tbekolay commented Aug 23, 2016

jgosmann commented Aug 23, 2016

jgosmann commented Aug 23, 2016

tbekolay commented Oct 18, 2016

Seanny123 left a comment

Choose a reason for hiding this comment

jgosmann commented Apr 18, 2017

Seanny123 commented Apr 19, 2017

tbekolay left a comment

Choose a reason for hiding this comment

jgosmann commented May 12, 2017

jgosmann commented Jul 23, 2016 •

edited

Loading

jgosmann commented Aug 23, 2016 •

edited

Loading