Skip to content

Commit

Permalink
[docs] Update installation guide (#177)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chhzh123
chhzh123 authored Sep 9, 2024
1 parent b816d40 commit fdf951e
Show file tree
Hide file tree
Showing 5 changed files with 144 additions and 102 deletions.
89 changes: 4 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,98 +9,17 @@
![GitHub](https://img.shields.io/github/license/cornell-zhang/allo)
[![CircleCI](https://circleci.com/gh/cornell-zhang/allo.svg?style=shield)](https://circleci.com/gh/cornell-zhang/allo.svg?style=shield)

Allo is an Accelerator Design Language (ADL) and compiler that facilitates the construction of large-scale, high-performance hardware accelerators in a modular and composable manner. Allo has several key features:
* **Progressive hardware customizations**: Allo decouples hardware customizations from algorithm specifications and treats each hardware customization as a primitive that performs a rewrite on the program. Allo not only decouples the loop-based transformations, but also extends the decoupling to memory, communication, and data types.
Allo is a Python-embedded Accelerator Design Language (ADL) and compiler that facilitates the construction of large-scale, high-performance hardware accelerators in a modular and composable manner. Allo has several key features:
* **Progressive hardware customizations**: Allo decouples hardware customizations from algorithm specifications and treats each hardware customization as a primitive that performs a rewrite on the program. Allo not only decouples the loop-based transformations, but also extends the decoupling to memory, communication, and data types. All the transformations are built on top of [MLIR](https://mlir.llvm.org/) that is easier to target different backends.
* **Reusable parameterized kernel templates**: Allo supports declaring type variables during kernel creation and instantiating the kernel when building the hardware executable, which is an important feature for building reusable hardware kernel libraries. Allo introduces a concise grammar for creating kernel templates, eliminating the need for users to possess complicated metaprogramming expertise.
* **Composable schedules**: Allo empowers users to construct kernels incrementally from the bottom up, adding customizations one at a time while validating the correctness of each submodule. Ultimately, multiple schedules are progressively integrated into a complete design using the `.compose()` primitive. This approach, unachievable by prior top-down methods, significantly enhances productivity and debuggability.


## Installation

Please clone the Allo repository to your local machine.

```bash
git clone https://github.com/cornell-zhang/allo.git
cd allo
```

We recommend creating a new conda environment for Allo. Since we are using the latest Python features, the minimum Python version is **3.12**.

```bash
conda create -n allo python=3.12
conda activate allo
```


### Prerequisites

We need to first install the [LLVM project](https://github.com/llvm/llvm-project/tree/llvmorg-18-init) and the [hcl-mlir dialect](https://github.com/cornell-zhang/hcl-dialect). Users can choose to use our provided docker or build from source.

#### Docker

To simplify the installation process, we provide a docker image that has already installed the LLVM-18.x project.
Please pull the image from Docker Hub, **patch LLVM, and install the hcl dialect** as described above.

```bash
# * The LLVM is installed in /root/llvm-project in the docker image, which has already been patched
# * A prebuilt hcl-dialect is installed in /root/hcl-dialect, but please note that it is not up-to-date
# You can pull the latest hcl-dialect using `git pull` and rebuild it if needed
docker pull chhzh123/hcl-dialect:llvm-18.x-py3.12
docker run --rm -it chhzh123/hcl-dialect:llvm-18.x-py3.12
```

#### Build from source

Users can also choose to build LLVM and the hcl dialect from source. Please follow the instructions below.

```bash
# Make sure you are under the correct Python environment
bash build.sh
```


### Install Allo

After installing LLVM and the hcl dialect, we can directly `pip install` Allo:

```bash
# Under the root directory of Allo
python3 -m pip install -e .
```

## Getting Started
Below is a minimal example of leveraging Allo to customize a GEMM kernel:
```python
import allo
from allo.ir.types import int32

# Allo kernel definition
def gemm(A: int32[32, 32], B: int32[32, 32]) -> int32[32, 32]:
C: int32[32, 32] = 0
for i, j, k in allo.grid(32, 32, 32):
C[i, j] += A[i, k] * B[k, j]
return C

# Schedule construction
s = allo.customize(gemm)

# Real-time transformation
s.split("i", factor=8)
print(s.module)
Please check out the [Allo documentation](https://cornell-zhang.github.io/allo) for installation instructions and tutorials.
If you encounter any problems, please feel free to open an [issue](https://github.com/cornell-zhang/allo/issues).

# Compilation
mod = s.build(target="llvm")

# Execution
import numpy as np
np_A = np.random.randint(0, 100, (32, 32)).astype(np.int32)
np_B = np.random.randint(0, 100, (32, 32)).astype(np.int32)
np_C = mod(np_A, np_B)

# Testing
golden_C = np.matmul(np_A, np_B)
np.testing.assert_allclose(np_C, golden_C, rtol=1e-5, atol=1e-5)
```

## Publications
Please refer to our [PLDI'24 paper](https://arxiv.org/abs/2404.04815) for more details. If you use Allo in your research, please use the following bibtex entry to cite us:
Expand Down
16 changes: 16 additions & 0 deletions build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,19 @@
# Copyright Allo authors. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0

export ALLO_HOME=$(pwd)

# Pull the LLVM project and hcl-mlir dialect
git submodule update --init --recursive

# Check the Python version
if ! python3 -c 'import sys; assert sys.version_info >= (3,12)' > /dev/null; then
echo "Error: Python 3.12 or later is required"
exit 1
fi

# Install the required Python packages
echo "Installing the required Python packages ..."
python3 -m pip install -r requirements.txt

# Note: we need to patch the LLVM project to add additional
Expand All @@ -32,6 +41,7 @@ make -j8

# Export the LLVM build directory
export LLVM_BUILD_DIR=$(pwd)
export PATH=$LLVM_BUILD_DIR/bin:$PATH
echo "LLVM build directory: $LLVM_BUILD_DIR"

# Build the hcl dialect
Expand All @@ -48,6 +58,12 @@ cmake -G "Unix Makefiles" .. \
make -j8

# Install hcl dialect
echo "Installing hcl dialect ..."
cd tools/hcl/python_packages/hcl_core
python3 -m pip install -e .

# Install allo
echo "Installing allo ..."
cd $ALLO_HOME
python3 -m pip install -e .
echo "Installation completed!"
2 changes: 1 addition & 1 deletion docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@

project = "Allo"
author = "Allo Authors"
copyright = "2023, Allo Authors"
copyright = "2024, Allo Authors"

# The full version, including alpha/beta/rc tags
release = "0.5"
Expand Down
61 changes: 58 additions & 3 deletions docs/source/developer/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,68 @@
Developer Setup
###############

Depending on which part of Allo you want to contribute to, you may set up the environment differently.

Developer Installation
----------------------

If you only want to change the frontend part of Allo, you can install the Allo package following the `general guide <../setup/index.html>`_.

If you need to change the backend part of Allo, you need to install the LLVM-18 project and make sure your LLVM commit is the same as `the one we referred to <https://github.com/cornell-zhang/hcl-dialect/tree/main/externals>`_.

.. code-block:: bash
mkdir -p build && cd build
# Python 3.12 is required
cmake -G "Unix Makefiles" ../llvm \
-DLLVM_ENABLE_PROJECTS=mlir \
-DLLVM_BUILD_EXAMPLES=ON \
-DLLVM_TARGETS_TO_BUILD="host" \
-DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DLLVM_INSTALL_UTILS=ON \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DPython3_EXECUTABLE=`which python3`
make -j8
.. note::

For Zhang Group students, you can ``export LLVM_HOME=/work/shared/users/common/llvm-project-18.x`` and ``export PATH=$LLVM_HOME/build-patch/bin:$PATH`` to use the pre-installed LLVM-18 project.

After installing the LLVM-18 project, you can build the hcl-mlir dialect from source:

.. code-block:: bash
git clone https://github.com/cornell-zhang/hcl-dialect.git
cd hcl-dialect
mkdir -p build && cd build
cmake -G "Unix Makefiles" .. \
-DMLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir \
-DLLVM_EXTERNAL_LIT=$LLVM_BUILD_DIR/bin/llvm-lit \
-DPYTHON_BINDING=ON \
-DOPENSCOP=OFF \
-DPython3_EXECUTABLE=`which python3` \
-DCMAKE_CXX_FLAGS="-Wfatal-errors -std=c++17"
make -j8
cd tools/hcl/python_packages/hcl_core
python3 -m pip install -e .
Every time you change the hcl-mlir dialect, you need to run ``make`` again to make the changes effective. Finally, you can install the Allo package:

.. code-block:: bash
python3 -m pip install -e .
It will connect the frontend with the backend.

Upstream Changes
----------------

It would be good to maintain your own `fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_ of
the Allo repository, which helps create a `PR (pull request) <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ and upstream changes easier.

To create your own fork, click on the "Fork" button on the top right of the `Allo repository <https://github.com/cornell-zhang/allo>`_.
This will create a copy of the repository under your own GitHub account. Please do *NOT* make it public
at this time. (By default, fork from a private repository should be private.)
This will create a copy of the repository under your own GitHub account.

Next, you can clone your fork to your local machine OR if you have already cloned the Allo repository, you can add your fork as a remote:

Expand Down Expand Up @@ -63,7 +119,6 @@ Basically, the development workflow is as follows:

Most of the ``git`` features are integrated in VSCode, please refer to the `document <https://code.visualstudio.com/docs/sourcecontrol/intro-to-git>`_ if you want to use the GUI.


Integration Tests
-----------------
We have configured `GitHub Actions <https://github.com/features/actions>`_ to run the tests on every PR, so please
Expand Down
78 changes: 65 additions & 13 deletions docs/source/setup/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,71 @@
Installation
############

To install and use Allo, we need to have the LLVM compiler infrastructure installed on our system.
We have already prepared a prebuilt version of LLVM on our server, so you can directly export it to your system path.
Please follow the instruction below to set up the environment.
If you want to install Allo on your local machine, you can refer to the `README <https://github.com/cornell-zhang/allo>`_ guideline in the Allo repository.

Make sure you have the access to the :code:`brg-zhang` or other Zhang group server. You can log into the server by
SSH or use VSCode Remote SSH extension. Please refer to `this website <https://code.visualstudio.com/docs/remote/ssh>`_
for more details on configuring VSCode. Those servers are only accessible from the campus network.

After logging into the server, the first step is to install an Anaconda environment. We recommend you to install your own
`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_, which is a lightweight version of Anaconda and contains
only the necessary packages. You can download the installer from the link above and install it on your system.
After the installation, you can create a new environment for Allo by running the following commands:
To install and use Allo, we need to first install the `LLVM-18 project <https://github.com/llvm/llvm-project/tree/llvmorg-18-init>`_ and the `hcl-mlir dialect <https://github.com/cornell-zhang/hcl-dialect>`_. You can choose to use our provided docker or build from source.

Install from Docker
-------------------

To simplify the installation process, we provide a docker image that has already installed the LLVM-18 project. Please pull the image from Docker Hub as described below. The LLVM is installed under the :code:`/root/llvm-project` folder in the docker image, and a prebuilt hcl-mlir dialect is installed in :code:`/root/hcl-dialect`.

.. code-block:: console
$ docker pull chhzh123/hcl-dialect:llvm-18.x-py3.12
$ docker run --rm -it chhzh123/hcl-dialect:llvm-18.x-py3.12
(docker) $ git clone https://github.com/cornell-zhang/allo.git && cd allo
(docker) $ python3 -m pip install -e .
Please note that the hcl-mlir dialect is not up-to-date. You can pull the latest hcl-mlir dialect and rebuild it if needed.

.. code-block:: console
(docker) $ cd /root/hcl-dialect
(docker) $ git remote update && git fetch
(docker) $ cd build && make -j8
(docker) $ cd tools/hcl/python_packages/hcl_core
(docker) $ python3 -m pip install -e .
Install from Source
-------------------

Please clone the Allo repository to your local machine.

.. code-block:: console
$ git clone https://github.com/cornell-zhang/allo.git
$ cd allo
We recommend creating a new conda environment for Allo. Since we are using the latest Python features, the minimum Python version is **3.12**.

.. code-block:: console
$ conda create -n allo python=3.12
$ conda activate allo
After creating the Python environment, you can install the required packages by running the following command.

.. code-block:: console
$ bash build.sh
You should see "Installation completed!" if the installation is finished.

Testing
-------

To make sure the installation is successful, you can run the following command to test the Allo package.

.. code-block:: console
$ python3 -m pytest tests/
Internal Installation
---------------------
For Zhang Group students, we have already prepared a prebuilt version of LLVM on our server, so you do not need to build everything from source. Please follow the instruction below to set up the environment.

Make sure you have the access to the :code:`brg-zhang` or other Zhang group server. You can log into the server by SSH or use VSCode Remote SSH extension. Please refer to `this website <https://code.visualstudio.com/docs/remote/ssh>`_ for more details on configuring VSCode. Those servers are only accessible from the campus network. Please use the VPN if you are off-campus.

After logging into the server, the first step is to install an Anaconda environment. We recommend you to install your own `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_, which is a lightweight version of Anaconda and contains only the necessary packages. You can download the installer from the link above and install it on your system. After the installation, you can create a new environment for Allo by running the following commands:

.. code-block:: console
Expand Down

0 comments on commit fdf951e

Please sign in to comment.