torch-mlir/README.md

127 lines
4.8 KiB
Markdown
Raw Normal View History

# 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](https://mlir.llvm.org/)
and [The IREE Project](https://github.com/google/iree) 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](docs/features.md) for a semi-curated status of what is
implemented.
## Architecture
The compiler is separated into:
* [Frontend importer](python/npcomp/compiler/frontend.py): Translates from
various AST levels to corresponding MLIR dialects.
* Frontend compiler: MLIR passes and conversions, mostly operating on the
[basicpy](include/Dialect/Basicpy/IR/BasicpyOps.td) and
[numpy](include/Dialect/Numpy/IR/NumpyOps.td) dialects.
* Backend compiler and runtime: Some effort has been taken to make this
pluggable, but right now, only the [IREE Backend](python/npcomp/compiler/backend/iree.py)
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](python/npcomp)
* [_npcomp native module](python_native)
* C++ [include](include) and [lib](lib) trees, following LLVM/MLIR conventions
* LIT testing trees:
* [test](test): Lit/FileCheck tests covering core MLIR based infra
2020-06-21 03:01:49 +08:00
* [pytest/Compiler](pytest/Compiler): Lit test suite that drive the compiler
infra from Python
* [backend_test](backend_test): Lit test suites conditionally enabled for
each backend
* [tools](tools): Scripts and binaries (npcomp-opt, npcomp-run-mlir, etc)
2020-04-30 01:55:35 +08:00
2020-04-27 07:32:10 +08:00
## Quick start
2020-04-27 06:50:23 +08:00
2020-04-27 07:32:10 +08:00
```
2020-04-30 07:33:48 +08:00
LLVM_VERSION=10
export CC=clang-$LLVM_VERSION
export CXX=clang++-$LLVM_VERSION
export LDFLAGS=-fuse-ld=$(which ld.lld-$LLVM_VERSION)
2020-04-27 07:32:10 +08:00
export LLVM_SRC_DIR=/path/to/llvm-project
2020-04-30 07:33:48 +08:00
# Check out last known good commit.
LLVM_COMMIT="$(cat ./built_tools/llvm.version)"
(cd $LLVM_SRC_DIR && git checkout $LLVM_COMMIT)
2020-04-27 07:32:10 +08:00
./build_tools/install_mlir.sh
./build_tools/cmake_configure.sh
# Build and run tests
# ./build_tools/test_all.sh runs all of these commands.
2020-04-27 07:32:10 +08:00
cd build
ninja
ninja check-npcomp
# Note: currently, some python tests run separately
2020-04-27 07:32:10 +08:00
./python/run_tests.py
# Setup PYTHONPATH for interactive use
export PYTHONPATH="$(realpath build/python):$(realpath build/python_native):$(realpath build/iree/bindings/python)"
2020-04-27 06:50:23 +08:00
```
## Interactive Use
2020-05-03 10:54:49 +08:00
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).
2020-04-27 06:50:23 +08:00
Configuring the `PYTHONPATH` as above should be sufficient to run any
interactive tooling (`python3`, Jupyter/Colab, etc).
2020-04-27 06:50:23 +08:00
The `run_tests.py` script is special in that it sets up the PYTHONPATH
correctly when run.
2020-04-27 06:50:23 +08:00
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.
2020-04-27 06:50:23 +08:00
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
2020-04-27 06:50:23 +08:00
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.
2020-04-27 11:14:20 +08:00
## 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
```