IO bridge Processes

[gkarray]

Issue Number: #687

Objective of pull request: Addition of IO bridge (Python only) Processes for getting input to/output from Lava: Injector and Extractor.

Pull request checklist

Your PR fulfills the following requirements:

• Issue created that explains the change and why it's needed
• Tests are part of the PR (for bug fixes / features)
• Docs reviewed and added / updated if needed (for bug fixes / features)
• PR conforms to Coding Conventions
• PR applys BSD 3-clause or LGPL2.1+ Licenses to all code files
• Lint (flakeheaven lint src/lava tests/) and (bandit -r src/lava/.) pass locally
• Build tests (pytest) passes locally

Pull request type

Please check your PR type:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation changes
• Other (please describe):

What is the current behavior?

• At the moment, the only ways to get data into Lava, from a Python application, is to go through the Dataloader or RingBuffer Processes, or the set() method on Process Var.
  • The Dataloader Process keeps data in disk, and only loads portions of it step-by-step.
  • The RingBuffer Process loads all data to memory from the start.
  • The set() method requires running Lava workloads one time step at a time, and calling it between each run() call.
• Similarly, the only ways to get data out of Lava, to use in a Python application, is to go through the RingBuffer Process, or the get() method on Process Var.
• The RingBuffer Process buffers data in memory, and one has to call get() at the end of the run on its data Var to get the data out.
• The get() method requires running Lava workloads one time step at a time, and calling it between each run() call.

What is the new behavior?

• With the Injector Process on the input side, users would be able to seamlessly integrate Lava workloads (running in non-blocking mode (!!)) into broader applications. These Lava workloads would be able to get dynamically generated input data from Python applications, without having to pause and re-run every time step.
  • "Dynamically generated input data" means: Without having to pre-load the data from the start (in contrast with the RingBuffer option).
  • "From Python applications" means: Not loading from disk (in contrast with the Dataloader option).
  • "Without having to pause and re-run every time step" means: Lava workload won't have to run one time step at a time (in contrast with the set() option).
• With the Extractor Process on the output side, users would be able to seamlessly integrate Lava workloads into broader applications. These broader applications would be able to get real-time output data from Lava workloads, without having to pause and re-run every time step.
  • "Real-time output data from Lava workloads" means: Without having to wait for a Lava run to finish to get data out (in contrast with the RingBuffer option).
  • "Without having to pause and re-run every time step" means: Lava workload won't have to run one time step at a time (in contrast with the get() option).

Does this introduce a breaking change?

• Yes
• No

Supplemental information

TODO:

• Add variants with VEC_SPARSE.
• Add (or change to) AsyncProcessModels, implementing the AsyncProtocol.

[tim-shea]

Great work on this PR @gkarray

At a high-level, I think it's an important feature to enable, but I'm not convinced this method is the right way to go about it. This pipe-from-the-parent-process will introduce temporal and behavioral coupling between lava and non-lava code, but may not behave as a user expects if their execution is not correctly synchronized.

At minimum, it would be good to see all of the following behaviors tested and clearly documented to users:

• Run the calling code and lava models for many timesteps
• Run the calling code and lava models for different number of timesteps (e.g. send_data 100 times while RunSteps=50 and vice versa)
• Start calling send_data before calling proc.run
• Send and receive non-trivial data structure
• Test the edge cases for pipe filling up and emptying out (i.e. if the calling code for InputBridge.send_data runs signficantly faster than the lava code, confirm whether it will eventually block or raise; vice versa for calling code for OutputBridge.recv_data)

[tim-shea]

Since I don't see any replies but I do see a bunch of new commits, I'm not sure what you think of my comments above, but here's a more concrete proposal for naming:

input_bridge.py > input_synchronizer.py
InputBridge > InputSynchronizer
AbstractPyLoihiInputBridgeProcessModel > PyInputSynchronizerModel
PyLoihiFloatingPointInputBridgeProcessModel > PyInputSynchronizerModelFloat
PyLoihiFixedPointInputBridgeProcessModel > PyInputSynchronizerModelFixed

output_bridge.py > output_synchronizer.py
OutputBridge > OutputSynchronizer
AbstractPyLoihiOutputBridgeProcessModel > PyOutputSynchronizerModel
etc...

You really don't need async protocol models for the synchronizer processes, because the way they're written makes them useful specifically for synchronizing your code to your synchronous Loihi model, hence the renames to describe their actual function.

See also Lif models.py, Dense models.py, etc, where the models start with Py, not PyLoihi, and include Model, but not ProcessModel.

Continuing:
in_bridge.py > async_injector.py
AsyncInputBridge > AsyncInjector
AsyncProcessDenseModel > AsyncInjectorModelFloat

Note that the process name should describe the behavior of all models, in this case Async should not refer to Async protocol vs Loihi protocol, but to the behavior in which the input is injected asynchronously with respect to the updates of the connected port. Basically, this process should allow me to sporadically send data or recv data without caring whether I send or recv the correct number of times, and without ever blocking my calling code or the connected port.

out_bridge.py > async_extractor.py
AsyncOutputBridge > AsyncExtractor
AsyncProcessModel > AsyncExtractorModelFloat

[tim-shea]

Very nice! Great cleanups, this is a clear, simple, and super useful little addition to the core Lava API.

Only top level suggestion to add is to drop the "bridge" in module paths, and just locate these three modules in io.

[mathisrichter]

Looks good overall - some minor changes and naming suggestions.
We did this in a live review, so my comments are a bit short; more reminders for @gkarray .

[tim-shea]

Great work Ghassen.