NAC3 - New ARTIQ Compiler 3: Prealpha release

I am pleased to announce the Prealpha release of NAC3, a new compiler for ARTIQ. It is a major, backward-incompatible rewrite which features improved compilation speeds, a much better type system, a cleaner codebase, and more predictable and transparent operation. It is written in Rust, and uses PyO3 to interface with Python and Inkwell to interface with LLVM.

NAC3 is funded by M-Labs - in particular via the Sinara hardware - and developed in collaboration with the Hong Kong University of Science and Technology. We intend to continue researching, developing and improving this compiler over the years. Jobs and PhD positions are available, contact us for details (jobs AT m-labs.hk or parreaux AT ust.hk).

Installation

NAC3 is compatible with core devices running ARTIQ-7 firmware. It is not compatible with ARTIQ-6 firmware.

Pre-built NAC3 is available for Linux (with Nix) and Windows (with MSYS2; Python distributions for Windows based on the MSVC ABI such as Anaconda are not supported).

To install ARTIQ with NAC3, follow the instructions in the NAC3 repository at https://git.m-labs.hk/M-Labs/nac3/.

What to expect

• Faster compilation speeds.
• Stronger and more predictable type system.
• More explicit kernel code, with more type annotations and decorators.
• Rewriting your code to use those type annotations and decorators.
• Supports Kasli, Kasli-SoC, KC705, and ZC706 core devices.
• All major ARTIQ drivers ported, but only compile-tested for the most part.
• Important bugs and problems from the legacy compiler fixed.
• New bugs introduced - please report them (see below) and we should be able to fix them quickly.
• No escape analysis yet. Memory is allocated on the stack only as before, but the compiler does not check that it is used correctly. If you do something wrong, the device will crash. Improvement in this area is planned in the near future.
• Module types are not supported yet. Use from module import ... or from module import ... as ... to work around this limitation.
• Numpy arrays are not supported yet.

Crash-course in writing NAC3 kernels

This assumes familiarity with using the legacy ARTIQ compiler.

• Add a @nac3 decorator to all classes that should be taken into account by the compiler.
• Use @kernel and @portable decorators as before.
• Add a @rpc decorator to all functions and methods that need to be RPC.
• All @kernel, @portable and @rpc function declarations need to be type-annotated (all arguments and the return type).
• Class attributes used by kernels must be type-annotated in the class declaration using Kernel[...] or KernelInvariant[...]. The latter replaces the kernel_invariant set from the legacy compiler.
• Use standard Python type annotations and Numpy integer types, for example int32, list[int32], tuple[int32, int64], list[UserClass]. The T... type annotations from the legacy compiler no longer exist.
• In arithmetic operations, operands must be of the same type and explicit type conversions may be required. Examples: self.core.delay(1*ms) is incorrect because 1 is int32 and ms is float. Write self.core.delay(1.*ms) instead. at_mu(now_mu() + 10000) is incorrect because now_mu() returns int64 and 10000 is int32. Write at_mu(now_mu() + int64(10000)) instead.
• Large int64 constants can be defined using int64(...). To round a float to a 64-bit integer without avoidable overflows, use the special function round64.
• There is a new Option type which works like the Rust option and replaces the use of None.
• TypeVar and Generic from the typing module can be used, and have the expected effect on the compiled code.
• with parallel is now deep (but stops at function calls).

See the drivers in the artiq/coredevice folder of the nac3 Git branch of ARTIQ for examples.

Reporting successes or problems

If you have tried NAC3 Prealpha, please tell us about your experience by replying to this forum post or, if it is a clearly actionable item, by opening an Issue in the NAC3 issue tracker. Do not report NAC3 issues in the main ARTIQ issue tracker.