Installation

Basic Install

1. Install Python and use a virtualenv.

2. Install LiCoRICE dependencies for Debian:

   sudo apt update
   sudo apt install -y libevent-dev libsqlite3-dev libmsgpack-dev libopenblas-base libopenblas-dev gfortran sqlite3
   

   Or Mac using Homebrew:

   brew install openblas msgpack libevent
   

   Note

   If numpy is unable to link openblas , it may be necessary to put export OPENBLAS=$(brew --prefix openblas) in your ~/.bashrc or similar.

3. Install LiCoRICE using pip. Make sure the virtualenv you created in step 1 is activated:

   pip install licorice
   

4. To install the latest development version of LiCoRICE, you can instead use:

   pip install git+https://github.com/bil/licorice@main
   

5. Ensure Correct Permissions

   To ensure you have the correct permissions, create a new limits file with sudo vi /etc/security/limits.d/licorice.conf and add these lines to ensure your user can run licorice. Replace <user> with the user you are using to run licorice.

   <user> - rtprio 95
   <user> - memlock unlimited
   <user> - nice -20
   

   Now log out and back in and you are set up for non-realtime licorice development and usage!

That’s all for a basic install (soft realtime) of LiCoRICE!

Improve Realtime Timings

If you have stricter timing needs, the following optional steps can be taken on Debian:

Option 1 (easy): linux-lowlatency

Install the linux-lowlatency package:

sudo apt-get install linux-lowlatency

This will install a new lowlatency kernel on your machine, so make sure you reboot and select the correct kernel from the boot menu. You can check which kernel you’re using by running:

uname -r

Option 2 (advanced): custom kernel

Modify BIOS settings and compile a custom realtime kernel:

1. Disable all ACPI and USB support in the BIOS of the target system.

   USB and ACPI features throw interrupts which can interfere with realtime performance.

   If USB support is needed for peripherals, enable only the minimum USB version necessary on as few ports as possible if such options in the BIOS exist.

2. Compiling a realtime kernel is not a requirement to run LiCoRICE, but realtime performance is one of the central features of the platform. Without a realtime kernel, timing assurances are harder to deliver. Tick violations are more likely to occur as model complexity grows. For basic platform testing and evaluation, a realtime kernel is not necessary, but for any production deployments, realtime kernel compilation is strongly advised.

   The instructions for realtime kernel compilation here should be applied to a stock install of Ubuntu server 20.04 LTS.

   From the top-level LiCoRICE repository directory, run:

   LICO_ENABLE_USB=0 ./install/kernel_setup.sh
   

   This script will take from one to five hours to complete, depending on the speed and processor count of the system. Reboot to finish installation when notified. Any USB keyboards will not work after this point (USB support is disabled in this realtime kernel), use a PS/2 keyboard or ssh into the system.

   Note: if USB support is necessary (e.g., system requires realtime support for a USB peripheral), install the USB enabled kernel instead via LICO_ENABLE_USB=1 ./install/kernel_setup.sh instead. Enabling USB support will degrade system performance by a small amount, but may still fit within application tolerances. In general, a limited number of USB devices do not preclude consistently meeting 1ms ticks. Regardless, it is important to always verify timings for a given system deployment.

3. The default installed kernel version is listed in the kernel_setup.sh script as KERNEL_RT_VERSION. Feel free to change this to fit your needs. For example, on an Ubuntu 18.04 system, you may wish to run:

   UBUNTU_VERSION=18.04 KERNEL_RT_VERSION=4.16.18-rt12 LICO_ENABLE_USB=0 ./install/kernel_setup.sh
   

We do not currently offer guidance for achieving firmer realtime guarantees on systems other than Debian, but contributions and testing are very welcome!