Skip to content
This repository has been archived by the owner on Jan 3, 2023. It is now read-only.

[WIP]Shrestha/update readme option3 #235

Open
wants to merge 24 commits into
base: master
Choose a base branch
from
Open

[WIP]Shrestha/update readme option3 #235

Changes from 21 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
0e31430
Fixed OpExecutor.cpp: SRC and SINK nodes must only be linked via cont…
Sep 26, 2018
3c15179
Make changes to Readme. Added build instructions to option 3. And few…
Sep 27, 2018
245c4f3
Make changes to Readme. Added build instructions to option 3. And few…
Sep 27, 2018
f53212f
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
4a32900
format Table
Sep 27, 2018
6768017
Check links
Sep 27, 2018
71dd5bd
Check links
Sep 27, 2018
3ba89fc
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
fccf5db
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
1933e0a
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
3092e06
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
2cb20f2
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
106d88b
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
76df8d5
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
46b7f24
Links and other refactoring
Sep 27, 2018
2b1e95f
Links and other refactoring
Sep 27, 2018
adadbf1
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Sep 27, 2018
ee6f7bc
Minor changes
Sep 27, 2018
57e8414
Minor Changes
Sep 27, 2018
02a46c9
Merge remote-tracking branch 'origin/master' into shrestha/Update_Rea…
Sep 28, 2018
49a6f51
Merge branch 'master' into shrestha/Update_Readme_Option3
avijit-nervana Oct 4, 2018
01dd1b9
Merge branch 'master' into shrestha/Update_Readme_Option3
avijit-nervana Oct 9, 2018
97d8657
Added keras preprocessing to the list
Oct 18, 2018
ec9a92a
Merge branch 'shrestha/Update_Readme_Option3' of https://github.com/N…
Oct 18, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 115 additions & 84 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,57 @@
# Intel® nGraph™ Compiler and runtime for TensorFlow*
# nGraph-Tensorflow : Intel® nGraph™ Compiler and Runtime for TensorFlow

Copy link
Contributor

@sayantan-nervana sayantan-nervana Sep 27, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nGraph-Tensorflow is the name of this too: https://github.com/NervanaSystems/ngraph-tensorflow
But I suppose it is clear from the context which is which.
@avijit-nervana ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That repo will likely be retired at some point so I'm not sure it matters too much, but I think nGraph-TensorFlow is still a little confusing. To me it kind of sounds like a fork of TensorFlow, which is not what ngraph-tf is.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it would be nice to have a name for the repo. Earlier, we were referencing it as 'ngraph-tensorflow bridge'. Bridge is more of an internal usage, so we removed it. Our current version, does not explicitly call out a name but at many places we reference 'ngraph-tf bridge'. Requires more brainstorming.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sayantan-nervana That repo is now private - so won't matter much. I agree with @shresthamalik that it needs more brainstorming. For now I would recommend not introducing this.

This repository contains the code needed to enable Intel® nGraph™ Compiler and
runtime engine for TensorFlow. Use it to speed up your TensorFlow training and
inference workloads. The nGraph Library and runtime suite can also be used to
customize and deploy Deep Learning inference models that will "just work" with
a variety of nGraph-enabled backends: CPU, GPU, and custom silicon like the
[Intel® Nervana™ NNP](https://itpeernetwork.intel.com/inteldcisummit-artificial-intelligence/).
nGraph-Tensorflow (ngraph-tf) enables TensorFlow to run with [Intel® nGraph™](https://github.com/NervanaSystems/ngraph), compiler and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend keeping this as is.

runtime engine, speeding up training and inference workloads on nGraph
supported hardware: CPU, GPU, and custom silicon like the [Intel® Nervana™ NNP](https://itpeernetwork.intel.com/inteldcisummit-artificial-intelligence/). It integrates seamlessly with Tensorflow, allowing developers the flexibility to switch amongst different hardware, by making minimum to no change to their code.

* [Build with Linux](#linux-instructions)
* [Build using OS X](#using-os-x)
* Using the stable [upstreamed](#using-the-stable-upstreamed-version) version
* [Debugging](#debugging)
* [Support](#support)
* [How to Contribute](#how-to-contribute)



## Linux instructions
There are 3 ways to install nGraph-tf.

| Option | Build TF from Source | Build nGraph from Source | Notes |
|:---:|:---:|:---:|:---: |
| [1](#option-1-build-ngraph-using-an-existing-tensorflow-installation) | No | Yes | |
| [2](#option-2-build-ngraph-using-tensorflow-source) | Yes | Yes | Builds unit tests. Recommended for contributing to nGraph-Tensorflow |
| [3](#option-3-build-tensorflow-source-with-ngraph) | Yes | No | nGraph enabled by default |

### Option 1: Use an existing TensorFlow v1.11.0-rc2 (or greater) installation
#### Create a python virtual environment

1. You need to instantiate a specific kind of `virtualenv` to
be able to proceed with the `ngraph-tf` bridge installation. For
systems with Python 3.n or Python 2.7, these commands are
You need to instantiate a specific kind of `virtualenv` to be able to proceed with the `ngraph-tf` installation. For Python 3.n or Python 2.7, do

virtualenv --system-site-packages -p python3 your_virtualenv
virtualenv --system-site-packages -p /usr/bin/python2 your_virtualenv
source your_virtualenv/bin/activate # bash, sh, ksh, or zsh

Typically the following python packages are also needed `numpy mock keras keras_applications`.

pip install -U numpy mock keras keras_applications

Note: Depending on the version of Python and the packages already installed on your system,the above list may vary.

#### Install bazel for building TensorFlow Source

The installation prerequisites are the same as described in the TensorFlow [prepare environment] for linux.

1. We use the standard build process called "bazel". The instructions were tested with [bazel version 0.16.0].

wget https://github.com/bazelbuild/bazel/releases/download/0.16.0/bazel-0.16.0-installer-linux-x86_64.sh
chmod +x bazel-0.16.0-installer-linux-x86_64.sh
./bazel-0.16.0-installer-linux-x86_64.sh --user

2. Add and source the ``bin`` path to your ``~/.bashrc`` file in order to call bazel from the installation we set up:

export PATH=$PATH:~/bin
source ~/.bashrc

### Option 1: Build nGraph using an existing TensorFlow installation

1. Create and activate a [python virtual environment](#create-a-python-virtual-environment)

2. Install TensorFlow v1.11.0-rc2. Note that this is a pre-release so you need
to use the following steps to install this:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now we are at 1.11, so may need to change all instances of 1.11-rc2 to 1.11

Expand All @@ -38,8 +62,7 @@ a variety of nGraph-enabled backends: CPU, GPU, and custom silicon like the

pip install -U tensorflow

3. Checkout `v0.6.1` from the `ngraph-tf` repo and build the bridge
as follows:
3. Checkout `v0.6.1` from the `ngraph-tf` repo and build it:

shresthamalik marked this conversation as resolved.
Show resolved Hide resolved
git clone https://github.com/NervanaSystems/ngraph-tf.git
cd ngraph-tf
Expand All @@ -51,34 +74,18 @@ a variety of nGraph-enabled backends: CPU, GPU, and custom silicon like the
make install
pip install -U python/dist/ngraph-0.6.1-py2.py3-none-linux_x86_64.whl

To enable nGraph, in your python scripts

### Option 2: Build nGraph bridge from source using TensorFlow source

To run unit tests, or if you are planning to contribute, install the nGraph
bridge using the TensorFlow source tree as follows:

#### Prepare the build environment

The installation prerequisites are the same as described in the TensorFlow
[prepare environment] for linux.

1. We use the standard build process which is a system called "bazel". These
instructions were tested with [bazel version 0.16.0].

wget https://github.com/bazelbuild/bazel/releases/download/0.16.0/bazel-0.16.0-installer-linux-x86_64.sh
chmod +x bazel-0.16.0-installer-linux-x86_64.sh
./bazel-0.16.0-installer-linux-x86_64.sh --user

2. Add and source the ``bin`` path to your ``~/.bashrc`` file in order to be
able to call bazel from the user's installation we set up:
import ngraph

### Option 2: Build nGraph using TensorFlow source

export PATH=$PATH:~/bin
source ~/.bashrc
To run unit tests, or if you are planning to contribute, install nGraph-tf
using the TensorFlow source tree as follows:

#### Installation

1. Once TensorFlow's dependencies are installed, clone the source of the
[tensorflow] repo to your machine.
1. Install [bazel](#install-bazel-for-building-tensorflow-source) and other TensorFlow dependencies. Now, clone the source of the [tensorflow] repo to your machine.

:warning: You need the following version of TensorFlow: `v1.11.0-rc2`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please update this to point to v1.11.0


Expand All @@ -88,18 +95,7 @@ The installation prerequisites are the same as described in the TensorFlow
git status
HEAD detached at v1.11.0-rc2
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update to v1.11.0


2. You must instantiate a specific kind of `virtualenv` to be able to proceed
with the `ngraph-tf` bridge installation. For systems with Python 3.n or
Python 2.7, these commands are

virtualenv --system-site-packages -p python3 your_virtualenv
virtualenv --system-site-packages -p /usr/bin/python2 your_virtualenv
source your_virtualenv/bin/activate # bash, sh, ksh, or zsh

Note: Depending on specific version of the Python and components already
installed on your system - the list of dependent Python components vary.
Typically the following components are needed: `numpy mock keras keras_application`.
Install them if your Python environment doesn't have them already.
2. Create and activate a [python virtual environment](#create-a-python-virtual-environment)

3. Now run `./configure` and choose `no` for the following when prompted to build TensorFlow.

Expand All @@ -110,17 +106,17 @@ The installation prerequisites are the same as described in the TensorFlow

nGraph support:

Do you wish to build TensorFlow with nGraph support? [y/N]: n
Do you wish to build TensorFlow with nGraph support? [y/N]: N
No nGraph support will be enabled for TensorFlow.

Since you are building nGraph using an existing TensorFlow build, you cannot respond with `y`
for the above step. This will result in conflicts as there will be two versions of
nGraph - one embedded within TensorFlow and the other you build and loaded.

If you want to use the nGraph embedded within TensorFlow, see the
following section on how to use the upstream version.
[following section](#option-3-build-tensorflow-source-with-ngraph).

Note that if you are running TensorFlow on a Skylake family processor then select
Note: If you are running TensorFlow on a Skylake family processor then select
`-march=broadwell` when prompted to specify the optimization flags:

Please specify optimization flags to use during compilation
Expand Down Expand Up @@ -149,12 +145,12 @@ The installation prerequisites are the same as described in the TensorFlow
git checkout v0.6.1


7. Next, build and install nGraph bridge.
7. Next, build and install nGraph-tf.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

step 6: Now clone the ngraph-tfrepo one level above -- in the *parent* directory of thetensorflow repo cloned in step 1
this requirement is probably no longer there.

:warning: Run the ngraph-tf build from within the `virtualenv`.

mkdir build
cd build
cmake -DUNIT_TEST_ENABLE=TRUE -DTF_SRC_DIR=<path to TensorFlow source directory> ..
cmake -DUNIT_TEST_ENABLE=TRUE -DTF_SRC_DIR=<absolute path to TensorFlow source directory> ..
make -j <your_processor_cores>
make install
pip install -U python/dist/<ngraph-0.6.1-py2.py3-none-linux_x86_64.whl>
Expand All @@ -165,61 +161,96 @@ the dependencies.
Once the build and installation steps are complete, you can start using TensorFlow
with nGraph backends.

Please add the following line to enable nGraph: `import ngraph`
To enable nGraph, in your python scripts

import ngraph

Note: The actual filename for the pip package may be different as it's version
dependent. Please check the `build/python/dist` directory for the actual pip wheel.

## Using the stable upstreamed version
You can run tests following the instructions [here](#running-tests).

nGraph is being added to the TensorFlow source tree the using pull requests from
time to time.
### Option 3: Build TensorFlow Source with nGraph

In order to build that version of nGraph, download the source tree as mentioned
above and select `Y` when prompted to build with nGraph.
nGraph is being added to the TensorFlow source tree. When built with this option, there is **no need to separately build `ngraph-tf` or use `pip` to install the ngraph module**. With this configuration, your TensorFlow model scripts will work with nGraph without any changes.

For this final option, there is **no need to separately build `ngraph-tf` or to
use `pip` to install the ngraph module**. With this configuration, your TensorFlow
model scripts will work without any changes.
#### Installation

Note: The version that is available in the upstreamed version of TensorFlow usually
lags the features and bug fixes available in the `master` branch of this repository.
1. Install [bazel](#install-bazel-for-building-tensorflow-source) and other TensorFlow dependencies. Now, clone the source of the [tensorflow] repo to your machine.

### Running tests
:warning: You need the following version of TensorFlow: `v1.11.0-rc2`

To run the C++ unit tests,
git clone https://github.com/tensorflow/tensorflow.git
cd tensorflow
git checkout v1.11.0-rc2
git status
HEAD detached at v1.11.0-rc2

2. Create and activate a [python virtual environment](#create-a-python-virtual-environment)

3. Now run `./configure` and choose the following when prompted

* Go to the build directory and run the following commands:
CUDA support:

Do you wish to build TensorFlow with CUDA support? [y/N]: N
No CUDA support will be enabled for TensorFlow.

nGraph support:

cd test
./gtest_ngtf
Do you wish to build TensorFlow with nGraph support? [y/N]: y
nGraph support will be enabled for TensorFlow.

You can run a few of your own DL models to validate the end-to-end
functionality. Also, you can use the `ngraph-tf/examples` directory and try to
run the following model with some MNIST data on your local machine:
Note that if you are running TensorFlow on a Skylake family processor then select
`-march=broadwell` when prompted to specify the optimization flags:

Please specify optimization flags to use during compilation
when bazel option "--config=opt" is specified
[Default is -march=native]: -march=broadwell

This is due to an issue in TensorFlow which is being actively worked on:
https://github.com/tensorflow/tensorflow/issues/17273

cd examples/mnist
python mnist_fprop_only.py --data_dir <input_data_location>
4. Prepare the pip package and the TensorFlow C++ library:

bazel build --config=opt //tensorflow/tools/pip_package:build_pip_package
bazel-bin/tensorflow/tools/pip_package/build_pip_package ./

5. Install the pip package, replacing the `tensorflow-1.*` with your
version of TensorFlow:

pip install -U ./tensorflow-1.*whl

Note: The version that is available with TensorFlow usually lags the features and bug fixes available in the `master` branch of this repository.

## Using OS X

The build and installation instructions are idential for Ubuntu 16.04 and OS X.

### Running tests

Export the appropriate paths to your build location; OS X uses the `DYLD_` prefix:
To [run tests](#running-tests), export the appropriate paths to your build location; OS X uses the `DYLD_` prefix:

export DYLD_LIBRARY_PATH=/bazel-out/darwin-py3-opt/bin/tensorflow:$DYLD_LIBRARY_PATH
export DYLD_LIBRARY_PATH=/build/ngraph/ngraph_dist/lib:$DYLD_LIBRARY_PATH

Then follow "Running tests" on Linux as described above.
### Running tests

## Debugging
To run the C++ unit tests,

See the instructions provided in the [diagnostics] directory.
* Go to the build directory and run the following commands:

https://github.com/NervanaSystems/ngraph-tf/blob/master/diagnostics/README.md
cd test
./gtest_ngtf

You can run a few of your own DL models to validate the end-to-end
functionality. Also, you can use the `ngraph-tf/examples` directory and try to
run the following model with some MNIST data on your local machine:

cd examples/mnist
python mnist_fprop_only.py --data_dir <input_data_location>

## Debugging

See the instructions provided in the [diagnostics](https://github.com/NervanaSystems/ngraph-tf/blob/master/diagnostics/README.md
) directory.

## Support

Expand Down Expand Up @@ -257,5 +288,5 @@ See the full documentation here: <http://ngraph.nervanasys.com/docs/latest>
[diagnostics]:diagnostics/README.md
[ops]:http://ngraph.nervanasys.com/docs/latest/ops/index.html
[nGraph]:https://github.com/NervanaSystems/ngraph
[ngraph-tf bridge]:https://github.com/NervanaSystems/ngraph-tf
[ngraph-tf]:https://github.com/NervanaSystems/ngraph-tf