I’m trying to build a diagram of the Nengo organisation and I’m a bit confused. What’ the relation between the Nengo API, the Nengo builder and the Nengo front-end?
Here’s what I currently understand. Each back-end has to implement the Nengo API. To do this, they each have their on builder. The Nengo API is a synonym for the Nengo front-end?
Hm… so, I think it’s important to differentiate levels and audience here; when talking about Nengo generally, I wouldn’t talk about the API or the builder as those aren’t super meaningful terms when you’re trying to get a bird’s-eye view of all the Nengo projects. Those are more developer / implementation-level details that most users don’t have to think about. And in the majority of the documentation, I think we mostly want to be using broader terms. So I would just say that there’s Nengo core, which is how you make models, and then there are several Nengo simulators, which is how you run models.
On that lower level, Nengo core has the 5 main objects (ensemble, node, connection, probe, network) and all the other things that support those 5 objects (learning rules, neuron types, synapses, solvers, etc). Collectively, I would call those the front-end. It also has the simulator, which uses the builder, and I would collectively call those two things the (Nengo core) backend. I never really intended the builder to be a thing that people would have to know anything about, but it seems to have become a thing since other projects have used bits and pieces of it. But it’s just a part of the backend, essentially translating the frontend objects into backend objects.
The term API seems to have different definitions for different people… to me, the API is the subset of a project that is explicitly documented and advertised to the public as being how you use the project. So in the case of the Nengo frontend, it’s what we’ve listed here. That’s a subset of all of the things that exist in what I would consider the frontend part of Nengo core, but it’s everything that I think a typical user should need to know. Of course, I am definitely wrong about what users need to know, so we rely on people to ask questions and point out what is not documented but needs to be.
So yeah, there isn’t really a general “Nengo API” per se, each project has an API. The Nengo core API is important because other projects rely on it, but those projects also have APIs that should be documented. We’ve discussed but not yet documented what each backend needs to implement to be a backend (or maybe we have but not in a prominent place), so mostly the backends are implementing the parts of the simulator that are used in examples and the GUI. That document, btw, would be more of a “specification” than an API; the Nengo core backend API is documented, but that’s not what we expect other backends to implement. Hopefully we’ll get better at that over time, but as you know writing documentation takes a lot of time and effort and is not nearly as rewarding as writing code.