Building PopART

These instructions assume you are building PopART on Ubuntu 20.04. These instructions describe how to install every required dependency. If you are starting from an existing Ubuntu 20.04 installation you may already have some of these dependencies installed. If so, please ensure the versions of these dependencies are compatible with these instructions. Other Linux-based operating systems may also work but package names and supported versions of packages may vary.

Installing Required Tooling

You will need the following tools installed on your system if they are not installed already:

Wget, Git

sudo apt-get install wget git -y

PIP3 (package installer for python 3)

sudo apt-get install python3-pip -y
ln -s /usr/bin/python3 /usr/bin/python

NOTE: If you have python 2.x installed on your system you can ignore the symlink.

Ninja (version 1.8.2, optional)

sudo apt-get install ninja-build -y

pkg-config

sudo apt-get install pkg-config -y

Installing Required PIP Packages

All Python dependencies necessary for building and running PopART can be found in requirements.txt. Install them by running

python3 -m pip install -r requirements.txt

If you would like to contribute to PopART, additional dependencies are required for development. These are found in requirements/dev.txt and can be installed by running:

python3 -m pip install -r requirements/dev.txt

Installing Third-Party Library Dependencies

PopART compiles against a number of libraries that must be available on your system:

Spdlog (version 1.8.0)

The version of the spdlog library in Ubuntu 20.04 (spdlog-dev) is not compatible with PopART. Instead, you need to build version 1.8.0 from source. To do this, in a directory of your choice, download the source from the spdlog GitHub page and build and install as follows:

export SPDLOG_INSTALL_DIR=$(pwd)/spdlog-1.8.0/install_dir/
git clone --branch v1.8.0 https://github.com/gabime/spdlog.git
cd spdlog && mkdir build && cd build
cmake .. -GNinja -DCMAKE_INSTALL_PREFIX=$SPDLOG_INSTALL_DIR && cmake --build . --target install

NOTE: You will need the value of SPDLOG_INSTALL_DIR later.

Pybind11 (version 2.6.2 or compatible)

The version of the pybind11 library in Ubuntu 20.04 (pybind11-dev) is 2.4.3, which is not compatible with PopART. Instead, you need to build version 2.6.2 from source. To do this, in a directory of your choice, download the source from the pybind GitHub page and build and install as follows:

export PYBIND11_INSTALL_DIR=$(pwd)/pybind11-2.6.2/install_dir/
wget https://github.com/pybind/pybind11/archive/v2.6.2.tar.gz
tar xvfz v2.6.2.tar.gz
rm v2.6.2.tar.gz
pushd pybind11-2.6.2
mkdir build
mkdir install_dir
cd build
cmake .. \
  -DCMAKE_INSTALL_PREFIX=$PYBIND11_INSTALL_DIR \
  -GNinja
ninja
ninja install
popd

NOTE: If you prefer building with make instead of ninja, remove the -DCMAKE_GENERATOR="Ninja" switch.

NOTE: You will need the value of PYBIND11_INSTALL_DIR later.

For more information, see: https://github.com/pybind/pybind11/blob/master/docs/compiling.rst.

Boost (version 1.80.0 or compatible)

The Boost library in Ubuntu 20.04 (libboost-dev) is 1.71.1, which is not compatible with PopART. Instead, you have to build version 1.80.0 from source. To do this, in a directory of your choice, download the source from the Boost download page and build and install as follows:

export BOOST_INSTALL_DIR=$(pwd)/boost_1_80_0/install_dir/
wget https://boostorg.jfrog.io/artifactory/main/release/1.70.0/source/boost_1_80_0.tar.gz
tar xvfz boost_1_80_0.tar.gz
rm boost_1_80_0.tar.gz
pushd boost_1_80_0
mkdir install_dir
./bootstrap.sh --prefix=$BOOST_INSTALL_DIR
./b2 -j8 link=static runtime-link=static --abbreviate-paths variant=release toolset=gcc "cxxflags= -fno-semantic-interposition -fPIC" cxxstd=14 --with-test --with-system --with-filesystem --with-program_options --with-graph --with-random install
popd

NOTE: The -j8 switch is used to reduce build times by building with up to 8 threads.

NOTE: You will need the value of BOOST_INSTALL_DIR later.

For more information, see: https://www.boost.org/doc/libs/1_80_0/more/getting_started/unix-variants.html.

Building ONNX (version 1.6.0 or compatible) from source

The ONNX library also needs to be compiled from source. To do this, in a directory of your choice, download the source from the ONNX GitHub page and build and install as follows:

export ONNX_INSTALL_DIR=$(pwd)/onnx-1.6.0/install_dir/
wget https://github.com/onnx/onnx/archive/v1.6.0.tar.gz
tar xvfz v1.6.0.tar.gz
rm v1.6.0.tar.gz
pushd onnx-1.6.0
mkdir install_dir
cmake .. \
  -DONNX_ML=0 \
  -DProtobuf_PROTOC_EXECUTABLE=$PROTOBUF_INSTALL_DIR/bin/protoc \
  -DCMAKE_INSTALL_PREFIX=$ONNX_INSTALL_DIR
make -j8
make install
popd

NOTE: The -j8 switch is used to reduce build times by building with up to 8 threads.

NOTE: You will need the value of ONNX_INSTALL_DIR later.

For more information, see: https://github.com/onnx/onnx.

CapnProto (version 0.7.0 or compatible)

CapnProto releases can be downloaded from the capnproto download page. In a directory of your choice, download and install as follows:

export CAPNPROTO_INSTALL_DIR=$(pwd)/capnproto-0.7.0/install_dir/
wget https://capnproto.org/capnproto-c++-0.7.0.tar.gz
tar xvfz capnproto-c++-0.7.0.tar.gz
rm capnproto-c++-0.7.0.tar.gz
pushd capnproto-c++-0.7.0
./configure --prefix=$CAPNPROTO_INSTALL_DIR
make -j8 check
make install
popd

NOTE: The -j8 switch is used to reduce test times by testing with up to 8 threads.

NOTE: You will need the value of CAPNPROTO_INSTALL_DIR later

For more information, see: https://capnproto.org/install.html

Trompeloeil (version 35 or compatible)

Trompeloeil can be downloaded from the trompeloeil GitHub page. In a directory of your choice, download and install as follows:

export TROMPELOEIL_INSTALL_DIR=$(pwd)/trompeloeil-35/install_dir/
wget https://github.com/rollbear/trompeloeil/archive/refs/tags/v35.tar.gz
tar xvfz v35.tar.gz
rm v35.tar.gz
pushd trompeloeil-35
mkdir build ; cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$TROMPELOEIL_INSTALL_DIR
cmake --build . --target install
popd

Installing Graphcore Library Dependencies

Poprithms

You can checkout Graphcore's poprithms library in a suitable directory from the public GitHub repository and install it as follows:

export POPRITHMS_INSTALL_DIR=$(pwd)/poprithms/install_dir/
git clone https://github.com/graphcore/poprithms.git
pushd poprithms
mkdir build; cd build;
cmake .. \
  -DBOOST_ROOT=$BOOST_INSTALL_DIR \
  -DCMAKE_INSTALL_PREFIX=$POPRITHMS_INSTALL_DIR \
  -DCMAKE_GENERATOR="Ninja"
ninja
ninja install
popd

NOTE: If you prefer building with make instead of ninja, remove the -DCMAKE_GENERATOR="Ninja" switch.

NOTE: Builds can be further accelerated by using ccache.

NOTE: You will need the value of POPRITHMS_INSTALL_DIR later.

For more information, see: https://github.com/graphcore/poprithms.

Poplar SDK

To obtain the Poplar SDK you need to register for access to Graphcore's support portal. Once you have access you can download the latest Ubuntu 18.04 from the support portal, unpack it in a suitable directory. For the remainder of this document the instructions assume you've set an environment variable POPLAR_INSTALL_DIR to point to the directory where Poplar is unpacked. Note that the Poplar SDK contains more than just Poplar and you will have to point the variable specifically to a subdirectory named something like poplar-ubuntu_18_04-xxxxx.

For more information, see: https://www.graphcore.ai/developer.

Configuring & Building PopART

Note that only Ubuntu 20.04 is supported for building PopART externally.

To build PopART, run the following commands in the directory where you checked out the repository:

export POPART_INSTALL_DIR=$(pwd)/popart/install_dir/
export PKG_CONFIG_PATH="$CAPNPROTO_INSTALL_DIR/lib/pkgconfig:$PKG_CONFIG_PATH"
git clone https://github.com/graphcore/popart.git
push popart
mkdir build; cd build;
cmake .. \
  -DBOOST_ROOT=$BOOST_INSTALL_DIR \
  -DCapnProto_ROOT=$CAPNPROTO_INSTALL_DIR \
  -DONNX_ROOT=$ONNX_INSTALL_DIR \
  -DPOPLAR_INSTALL_DIR=$POPLAR_INSTALL_DIR \
  -Dpoprithms_ROOT=$POPRITHMS_INSTALL_DIR \
  -DProtobuf_ROOT=$PROTOBUF_INSTALL_DIR \
  -Dpybind11_ROOT=$PYBIND11_INSTALL_DIR \
  -Dspdlog_ROOT=$SPDLOG_INSTALL_DIR \
  -Dtrompeloeil_ROOT=$TROMPELOEIL_INSTALL_DIR \
  -DCMAKE_INSTALL_PREFIX=$POPART_INSTALL_DIR \
  -GNinja
ninja
ninja install
popd

You could use any method supported by CMake to point it at dependencies. See thefind_package documentation in the CMake documentation. We have chosen to use <verbatim pkg name>_ROOT variables that point to the package installation directory.

DEPRECATION: <uppercase pkg name>_INSTALL_DIR variables, except POPLAR_INSTALL_DIR, have been deprecated and will be removed in a future release.

NOTE: Other CMake switches are available:

-DPOPART_BUILD_TESTING=0 - Switch that can be used to avoid compiling PopART test.
-DPOPART_STRICT_COMPARATOR_CHECKS=1 - Check for nullptr and invalid pointers when comparing containers of pointers.

NOTE: If you prefer building with make instead of ninja, remove the -GNinja switch.

NOTE: Builds can be further accelerated by using ccache.

NOTE: CapnProto’s CMake export simply wraps pkg-config. PKG_CONFIG_PATH is set in order to tell pkg-config where to find CapnProto.

Using PopART

Application Examples

There are a number of advanced PopART applications available in Graphcore's example repository on Github. See the README for a full list of examples implemented using PopART and PopXL

Licensing

The code is provided under the MIT license, see the License.txt file.

TensorFlow

The project includes derived work from the following: TensorFlow, https://github.com/tensorflow/tensorflow/

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Relevant files:

tests/integration/optimizer_tests/rmsprop_update_numpy.py

LLVM Project

The project includes derivative work from the following: LLVM Project, http://llvm.org/doxygen/MachineOutliner_8cpp_source.html

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Relevant files:

willow/src/subgraph/suffixtree.cpp

pybind11_mkdoc

The project includes derivative work from the following: pybind11_mkdoc, https://github.com/pybind/pybind11_mkdoc

pybind11_mkdoc is licensed under the following MIT license:

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Relevant files:

scripts/pybind11_mkdoc/

ONNX

The project includes derivative work from the following: ONNX, https://github.com/onnx/onnx

ONNX is licensed under the following MIT license:

MIT License

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Relevant files:

tests/integration/operators_test/rnn_helper.py
tests/integration/operators_test/gru_test.py
tests/integration/operators_test/lstm_test.py

optional-lite

The project includes derivative work from the following: optional-lite, https://github.com/martinmoene/optional-lite

Boost Software License - Version 1.0 - August 17th, 2003

Distributed under the Boost Software License, Version 1.0.

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Relevant Files:

willow/include/popart/vendored/optional.hpp

any-lite

The project includes derivative work from the following: any-lite, https://github.com/martinmoene/any-lite

Boost Software License - Version 1.0 - August 17th, 2003

Distributed under the Boost Software License, Version 1.0.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Relevant Files:

willow/include/popart/vendored/anylite.hpp

arjunchandra/popart

Building PopART

Installing Required Tooling

Wget, Git

PIP3 (package installer for python 3)

Ninja (version 1.8.2, optional)

pkg-config

Installing Required PIP Packages

Installing Third-Party Library Dependencies

Spdlog (version 1.8.0)

Pybind11 (version 2.6.2 or compatible)

Boost (version 1.80.0 or compatible)

Building ONNX (version 1.6.0 or compatible) from source

CapnProto (version 0.7.0 or compatible)

Trompeloeil (version 35 or compatible)

Installing Graphcore Library Dependencies

Poprithms

Poplar SDK

Configuring & Building PopART

Using PopART

Application Examples

Licensing

TensorFlow

LLVM Project

pybind11_mkdoc

ONNX

optional-lite

any-lite