b4f0cea8fa
This ~totally reworks the existing "runtime" stuff to be more principled and usable, such as from Python. It's still not fully production-quality, mainly in the department of memory management (e.g. it currently leaks memory; we need to figure out "who frees memrefs" + the analysis and transformation needed to do that (maybe use upstream buffer allocation pass?)). The user API is in include/npcomp/runtime/UserAPI.h, though include/npcomp/JITRuntime/JITModule.h is a friendlier wrapper. The stuff under {include,lib}/runtime is totally firewalled from the compiler and tiny (<6kB, though no attention has gone into optimizing that size). For example, we don't link in libSupport into the runtime, instead having our own bare bones replacements for basics like ArrayRef (the JITRuntime helps with bridging that gap, since it *can* depend on all common LLVM utilities). The overall features of npcomprt is that it exposes a module that with multiple function entry points. Each function has arguments and results that are tensor-valued, and npcomprt::Tensor is the runtime type that is used to interact with that (and a npcomprt::Ref<T> reference-counting wrapper is provided to wrap npcomprt::Tensor in the common case). From an implementation perspective, an npcomprt module at the LLVM/object/binary level exposes a single module descriptor struct that has pointers to other metadata (currently just a list of function metadata descriptors). All interactions with the npcomp runtime are keyed off of that module descriptor, including function lookups and dispatching. This is done to dodge platform ABI issues and also allow enough reflection to e.g. verify provided arguments. Most of the compiler-side work here was in LowerToNpcomprtABI and LowerToLLVM. Also, - Rename npcomp_rt/NpcompRt to npcomprt/Npcomprt; it was getting annoying to type the underscores/caps. - misc improvements to bash_helpers.sh |
||
---|---|---|
backend_test/iree | ||
build_tools | ||
cmake/modules | ||
docs | ||
include/npcomp | ||
lib | ||
pytest | ||
python | ||
python_native | ||
test | ||
tools | ||
.clang-format | ||
.gitignore | ||
.style.yapf | ||
CMakeLists.txt | ||
LICENSE | ||
README.md | ||
contributing.md |
README.md
NPComp - An aspirational MLIR based numpy compiler
NPComp aims to be an idiomatic subset of the Python language, suitable for extracting isolated, statically typed programs from a running Python session. It is inspired by many projects that have come before it, including:
- PyPy/RPython
- Numba
- Pythran
- TorchScript
- Autograph
As the name implies, NPComp also seeks to provide compiler-backed support for Numpy APIs.
The project spawned out of both LLVM's MLIR project and The IREE Project and seeks to use the MLIR and IREE tooling to enable progressive lowering of high level compute dominant sub-programs in a way that preserves high level semantic information that is expected to be useful for exploiting parallelism, generating high performance code, and enabling portability and deployment to a range of devices. Some of these goals overlap with existing projects, and to a first approximation, the experiment with NPComp is to determine whether rebasing on the MLIR tooling and ML backends like IREE produce a lift.
Before getting too excited, keep in mind that this project barely exists: it is very new and doesn't do anything useful yet :) We are using it as a testing ground for some new ideas and infrastructure improvement, and depending on how things turn out, may end up carrying it forward or breaking it up for parts.
See the features doc for a semi-curated status of what is implemented.
Architecture
The compiler is separated into:
- Frontend importer: Translates from various AST levels to corresponding MLIR dialects.
- Frontend compiler: MLIR passes and conversions, mostly operating on the basicpy and numpy dialects.
- Backend compiler and runtime: Some effort has been taken to make this pluggable, but right now, only the IREE Backend exists. There is in-tree work to also build a minimal reference backend directly targeting LLVM.
Repository Layout
The project is roughly split into the following areas of code:
- User-facing Python code
- _npcomp native module
- C++ include and lib trees, following LLVM/MLIR conventions
- LIT testing trees:
- test: Lit/FileCheck tests covering core MLIR based infra
- pytest/Compiler: Lit test suite that drive the compiler infra from Python
- backend_test: Lit test suites conditionally enabled for each backend
- tools: Scripts and binaries (npcomp-opt, npcomp-run-mlir, etc)
Quick start
LLVM_VERSION=10
export CC=clang-$LLVM_VERSION
export CXX=clang++-$LLVM_VERSION
export LDFLAGS=-fuse-ld=$(which ld.lld-$LLVM_VERSION)
export LLVM_SRC_DIR=/path/to/llvm-project
# Check out last known good commit.
LLVM_COMMIT="$(cat ./build_tools/llvm_version.txt)"
(cd $LLVM_SRC_DIR && git checkout $LLVM_COMMIT)
./build_tools/install_mlir.sh
./build_tools/cmake_configure.sh
# Build and run tests
# ./build_tools/test_all.sh runs all of these commands.
cd build
ninja
ninja check-npcomp
# Setup PYTHONPATH for interactive use
export PYTHONPATH="$(realpath build/python):$(realpath build/python_native):$(realpath build/iree/bindings/python)"
Interactive Use
The cmake configuration populates symlinks in the build/python
directory
mirroring the source layout. This allows edit-run without rebuilding (unless
if files are added/removed).
Configuring the PYTHONPATH
as above should be sufficient to run any
interactive tooling (python3
, Jupyter/Colab, etc).
Note that running the cmake_configure.sh
script will also output a .env
file in the workspace folder with the correct PYTHONPATH set. This allows
tools like VSCode to work by default for debugging.
Notes:
- Python sources are symlinked to the output directory at configure time. Adding sources will require a reconfigure. Editing should not.
- It is a very common issue to have both python 2.7 (aka. "python") and python 3.x (aka. "python3") on a system at a time (and we can only hope that one day this ends). Since the native library at development time binds to a specific version, if you try to run with a different python, you will get an error about the "native" module not being found.
Compiler development
For bash users, adding the following to your .bashrc
defines some aliases
that are useful during compiler development, such as shortcuts for builing
and running npcomp-opt
.
source $WHERE_YOU_CHECKED_OUT_NPCOMP/tools/bash_helpers.sh