Added entrypoint to start emulator, improved README

README.md

@@ -32,6 +32,7 @@ Install it as follows:
   ```
 </details>
 
+
 ## Downloading Notebooks and Overlays
 
 PyACCL provides a few Jupyter notebooks and associated FPGA overlays for Alveo boards. After installing the PyACCL package, you can download these with:
@@ -44,3 +45,17 @@ There are several notebooks available to get you started with PyACCL:
 * Intros to (Py)ACCL [primitives](src/pyaccl/notebooks/primitives.ipynb) and [collectives](src/pyaccl/notebooks/collectives.ipynb)
 * Short guides to using [compression](src/pyaccl/notebooks/compression.ipynb) and [communicators](src/pyaccl/notebooks/communicators.ipynb)
 * Quick overview of [performance-related flags](src/pyaccl/notebooks/performance.ipynb)
+
+## Running Tests
+
+PyACCL includes tests for single ACCL instances and systems of ACCL instances. The tests are designed to run against ACCL emulator/simulator sessions as well as the single-FPGA ACCL test overlay, which connects 3 ACCL instances on a single Alveo board. 
+
+To run the tests, add the ACCL emulator executable `cclo_emu` to your path and start your emulator/simulator session:
+```sh
+pyaccl-emulate -n <NRANKS>
+```
+then run the following command from the pyaccl root folder:
+```sh
+mpirun -np <NRANKS> python3 -m pytest --with-mpi
+```
+If your system has an Alveo board and `NRANKS` is less or equal to 3, the test fixture will try and download the appropriate overlay for it, otherwise it will skip hardware testcases. Similarly, the test fixture will attempt to identify a valid emulator/simulator session with the appropriate number of ranks, then run testcases against it. If you omit `--with-mpi`, only single-instance tests will run, i.e. tests for `copy()` and `combine()` primitives.

setup.cfg

@@ -55,6 +55,7 @@ testing =
 [options.entry_points]
 console_scripts = 
     pyaccl-scan = pyaccl.scan:scan
+    pyaccl-emulate = pyaccl.emu:run_emulator
 pynq.notebooks =
     pyaccl = pyaccl.notebooks
 

src/pyaccl/emu.py

@@ -0,0 +1,66 @@
+# /*******************************************************************************
+#  Copyright (C) 2021 Xilinx, Inc
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+# *******************************************************************************/
+
+import os
+import subprocess
+import argparse
+import signal
+
+def emulate_cclo_instances(ranks: int, log_level: int, start_port: int, use_udp: bool, kernel_loopback: bool):
+    env = os.environ.copy()
+    print("Starting emulator...")
+    env['LOG_LEVEL'] = str(log_level)
+    args = ['mpirun', '-np', str(ranks), '--tag-output', 'cclo_emu', 'udp' if use_udp else 'tcp',
+            str(start_port), "loopback" if kernel_loopback else ""]
+    print(' '.join(args))
+    with subprocess.Popen(args, env=env, stderr=subprocess.DEVNULL) as p:
+        try:
+            p.wait()
+        except KeyboardInterrupt:
+            try:
+                print("Stopping emulator...")
+                p.send_signal(signal.SIGINT)
+                p.wait()
+            except KeyboardInterrupt:
+                try:
+                    print("Force stopping emulator...")
+                    p.kill()
+                    p.wait()
+                except KeyboardInterrupt:
+                    signal.signal(signal.SIGINT, signal.SIG_IGN)
+                    print("Terminating emulator...")
+                    p.terminate()
+                    p.wait()
+        if p.returncode != 0:
+            print(f"Emulator exited with error code {p.returncode}")
+
+def run_emulator():
+    parser = argparse.ArgumentParser(description='Run ACCL emulator')
+    parser.add_argument('-n', '--nranks', type=int, default=1,
+                        help='How many ranks to use for the emulator')
+    parser.add_argument('-l', '--log-level', type=int, default=3,
+                        help='Log level to use, defaults to 3 (info)')
+    parser.add_argument('-s', '--start-port', type=int, default=5500,
+                        help='Start port of emulator')
+    parser.add_argument('-u', '--udp', action='store_true', default=False,
+                        help='Run emulator over UDP instead of TCP')
+    parser.add_argument('--no-kernel-loopback', action='store_true', default=False,
+                        help="Do not connect user kernel data ports in loopback")
+    args = parser.parse_args()
+    emulate_cclo_instances(args.nranks, args.log_level, args.start_port, args.udp,
+        not args.no_kernel_loopback)
+