Skip to content

Commit ad4e2e2

Browse files
anurlybayevanurlybayev
authored
Merge pull request #5 from CentML/update-readme
Update the README with latest instructions on how to build Habitat
2 parents bb124e4 + 3faa0c1 commit ad4e2e2

File tree

2 files changed

+152
-91
lines changed

2 files changed

+152
-91
lines changed

‎INSTALL.md‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎README.md‎

Lines changed: 152 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,157 @@
1-
# Habitat: A Runtime-Based Computational Performance Predictor for Deep Neural Network Training
1+
# Habitat
22

3-
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4885489.svg)](https://doi.org/10.5281/zenodo.4885489)
4-
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4876277.svg)](https://doi.org/10.5281/zenodo.4876277)
3+
[![License](https://img.shields.io/badge/license-Apache--2.0-green?style=flat)](https://github.com/CentML/habitat/blob/main/LICENSE)
54

6-
Habitat is a tool that predicts a deep neural network's training iteration
7-
execution time on a given GPU. It currently supports PyTorch. To learn more
8-
about how Habitat works, please see our [research
9-
paper](https://arxiv.org/abs/2102.00527).
105

116

12-
## Running From Source
7+
A Runtime-Based Computational Performance Predictor for Deep Neural Network Training
138

14-
Currently, the only way to run Habitat is to build it from source. You should
15-
use the Docker image provided in this repository to make sure that you can
16-
compile the code.
9+
- [Installation](#installation)
10+
- [Building from source](#build)
11+
- [Usage example](#getting-started)
12+
- [Development Environment Setup](#dev-setup)
13+
- [Release process](#release-process)
14+
- [Release history](#release-history)
15+
- [License](#license)
16+
- [Research paper](#paper)
17+
- [Contributing](#contributing)
1718

18-
1. Download the [Habitat pre-trained
19-
models](https://doi.org/10.5281/zenodo.4876277).
20-
2. Run `extract-models.sh` under `analyzer` to extract and install the
21-
pre-trained models.
22-
3. Run `setup.sh` under `docker/` to build the Habitat container image.
23-
4. Run `start.sh` to start a new container. By default, your home directory
24-
will be mounted inside the container under `~/home`.
25-
5. Once inside the container, run `install-dev.sh` under `analyzer/` to build
26-
and install the Habitat package.
27-
6. In your scripts, `import habitat` to get access to Habitat. See
28-
`experiments/run_experiment.py` for an example showing how to use Habitat.
19+
Habitat is a tool that predicts a deep neural network's training iteration execution time on a given GPU. It currently supports PyTorch. To learn more about how Habitat works, please see our [research paper](https://arxiv.org/abs/2102.00527).
2920

30-
**Note:** Habitat needs access to your GPU's performance counters, which
31-
requires special permissions if you are running with a recent driver (418.43 or
32-
later). If you encounter a `CUPTI_ERROR_INSUFFICIENT_PRIVILEGES` error when
33-
running Habitat, please follow the instructions
34-
[here](https://developer.nvidia.com/ERR_NVGPUCTRPERM)
35-
and in [issue #5](https://github.com/geoffxy/habitat/issues/5).
21+
<h2 id="installation">Installation</h2>
3622

23+
To run Habitat, you need:
24+
- [Python 3.6+](https://www.python.org/)
25+
- [Pytorch 1.1.0+](https://pytorch.org/)
26+
- A system equiped with an Nvidia GPU.
3727

38-
## License
28+
Currently, we have predictors for the following Nvidia GPUs:
29+
30+
| GPU | Generation | Memory | Mem. Type | SMs |
31+
| ---------- |:-----------:| ------:| :-------: | :-: |
32+
| P4000 | Pascal | 8 GB | GDDR5 | 14 |
33+
| P100 | Pascal | 16 GB | HBM2 | 56 |
34+
| V100 | Volta | 16 GB | HBM2 | 80 |
35+
| 2070 | Turing | 8 GB | GDDR6 | 36 |
36+
| 2080Ti | Turing | 11 GB | GDDR6 | 68 |
37+
| T4 | Turing | 16 GB | GDDR6 | 40 |
38+
| 3090 | Ampere | 24 GB | GDDR6X | 82 |
39+
40+
**NOTE:** Not implmented yet
41+
```zsh
42+
python3 -m pip install habitat
43+
python3 -c "import habitat"
44+
```
45+
46+
<h2 id="build">Building from source</h2>
47+
48+
Prerequsites:
49+
- A system equiped with an Nvidia GPU with properly configured CUDA
50+
- [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit-archive)
51+
- [cmake v3.17+](https://github.com/Kitware/CMake/releases)
52+
- [Habitat pre-trained models](https://zenodo.org/record/4876277)
53+
54+
```zsh
55+
git clone https://github.com/CentML/habitat.git && cd habitat
56+
git submodule init && git submodule update
57+
58+
# Download the pre-trained models
59+
cd analyzer
60+
curl -O https://zenodo.org/record/4876277/files/habitat-models.tar.gz\?download\=1
61+
62+
# Install the models
63+
./extract-models.sh
64+
```
65+
66+
**Note:** Habitat needs access to your GPU's performance counters, which requires special permissions if you are running with a recent driver (418.43 or later). If you encounter a `CUPTI_ERROR_INSUFFICIENT_PRIVILEGES` error when running Habitat, please follow the instructions [here](https://developer.nvidia.com/ERR_NVGPUCTRPERM) and in [issue #5](https://github.com/geoffxy/habitat/issues/5).
67+
68+
### Building with Docker
69+
70+
Habitat has been tested to work on the latest version of [NVIDIA NGC PyTorch containers](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/pytorch).
71+
72+
1. To build Habitat with Docker, first run the NGC container.
73+
```bash
74+
docker run --gpus all -it --rm nvcr.io/nvidia/pytorch:22.08-py3
75+
```
76+
2. Inside the container, clone the repository then build and install the Habitat Python package:
77+
```bash
78+
git clone --recursive https://github.com/centml/habitat
79+
./habitat/analyzer/install-dev.sh
80+
```
81+
3. Download and extract the pretrained models by following the steps in the previous section.
82+
83+
### Building without Docker
84+
85+
1. Install CUPTI
86+
87+
CUPTI is a profiling interface required by Habitat. Select the correct version of CUDA [here](https://developer.nvidia.com/cuda-toolkit-archive) and following the instructions to add NVIDIA's repository. Then, install CUPTI with:
88+
```bash
89+
sudo apt-get install cuda-cupti-11-x
90+
```
91+
where `11-x` represents the version of CUDA you have installed.
92+
93+
2. Install `CMake` 3.17+.
94+
95+
Follow these steps to download and install a precompiled version of CMake:
96+
```bash
97+
wget https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-linux-x86_64.sh
98+
chmod +x cmake-3.24.0-linux-x86_64.sh
99+
mkdir /opt/cmake
100+
sh cmake-3.24.0-linux-x86_64.sh --prefix=/opt/cmake --skip-license
101+
ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake
102+
```
103+
You can verify the version of CMake you installed with the following:
104+
```bash
105+
cmake --version
106+
```
107+
3. Build and install the Habitat Python package:
108+
```bash
109+
git clone https://github.com/centml/habitat
110+
./habitat/analyzer/install-dev.sh
111+
```
112+
4. Download and extract the pretrained models by following the steps in the previous section.
113+
114+
<h2 id="getting-started">Usage example</h2>
115+
116+
You can verify your Habitat installation by running the simple usage example:
117+
```python
118+
# example.py
119+
import habitat
120+
import torch
121+
import torchvision.models as models
122+
123+
# Define model and sample inputs
124+
model = models.resnet50().cuda()
125+
image = torch.rand(8, 3, 224, 224).cuda()
126+
127+
# Measure a single inference
128+
tracker = habitat.OperationTracker(device=habitat.Device.RTX2080Ti)
129+
with tracker.track():
130+
out = model(image)
131+
132+
trace = tracker.get_tracked_trace()
133+
print("Run time on source:", trace.run_time_ms)
134+
135+
# Perform prediction to a single target device
136+
pred = trace.to_device(habitat.Device.V100)
137+
print("Predicted time on V100:", pred.run_time_ms)
138+
```
139+
140+
```zsh
141+
python3 example.py
142+
```
143+
144+
See [experiments/run_experiment.py](https://github.com/CentML/habitat/tree/main/experiments) for other examples of Habitat usage.
145+
146+
<h2 id="dev-setup">Development Environment Setup</h2>
147+
148+
<h2 id="release-process">Release Process</h2>
149+
150+
<h2 id="release-history">Release History</h2>
151+
152+
See [Releases](https://github.com/UofT-EcoSystem/habitat/releases)
153+
154+
<h2 id="license">License</h2>
39155

40156
The code in this repository is licensed under the Apache 2.0 license (see
41157
`LICENSE` and `NOTICE`), with the exception of the files mentioned below.
@@ -56,15 +172,11 @@ corresponding `README` files and license files inside the subdirectories for
56172
more information.
57173

58174

59-
## Research Paper
175+
<h2 id="paper">Research Paper</h2>
60176

61-
Habitat began as a research project in the [EcoSystem
62-
Group](https://www.cs.toronto.edu/ecosystem) at the [University of
63-
Toronto](https://cs.toronto.edu). The accompanying research paper will appear
64-
in the proceedings of [USENIX
177+
Habitat began as a research project in the [EcoSystem Group](https://www.cs.toronto.edu/ecosystem) at the [University of Toronto](https://cs.toronto.edu). The accompanying research paper appeared in the proceedings of [USENIX
65178
ATC'21](https://www.usenix.org/conference/atc21/presentation/yu). If you are
66-
interested, you can read a preprint of the paper
67-
[here](https://arxiv.org/abs/2102.00527).
179+
interested, you can read a preprint of the paper [here](https://arxiv.org/abs/2102.00527).
68180

69181
If you use Habitat in your research, please consider citing our paper:
70182

@@ -79,3 +191,7 @@ If you use Habitat in your research, please consider citing our paper:
79191
year = {2021},
80192
}
81193
```
194+
<h2 id="contributing">Contributing</h2>
195+
196+
Check out [CONTRIBUTING.md](https://github.com/CentML/habitat/blob/main/CONTRIBUTING.md) for more information on how to help with Habitat.
197+

0 commit comments

Comments
 (0)