GeoMX 安装指南#

本指南将引导您完成 GeoMX 的安装过程，并解释附带的 shell 脚本中使用的环境变量的含义。

用预构建 Docker 镜像安装 GeoMX#

为了简化安装过程，我们强烈推荐使用我们预构建的 Docker 镜像，它们可以在 DockerHub 上获取：

# If run on CPUs
sudo docker run -it --rm --name geomx-cpu lizonghango00o1/geomx:cpu-only bash

# If run on GPUs with CUDA 8.0
sudo docker run -it --rm --name geomx-gpu lizonghango00o1/geomx:cu80 bash

# If run on GPUs with CUDA 10.1
sudo docker run -it --rm --name geomx-gpu lizonghango00o1/geomx:cu101 bash

这些命令会自动从 DockerHub 拉取所需的 Docker 镜像并启动 Docker 容器。我们可以在此容器中直接与 GeoMX 进行交互。

备注

如需获取更深入的关于使用 Docker / Nvidia-Docker 的指南，请参考 Docker 文档和 NVIDIA 容器工具集。

然后，我们可以使用 scripts 文件夹中提供的脚本文件来运行示例任务。例如：

# If run on CPUs
cd GeoMX/scripts/cpu && bash run_vanilla_hips.sh

# If run on GPUs
cd GeoMX/scripts/gpu && bash run_vanilla_hips.sh

警告

注意：如果您使用的是带有 cu80 和 cu101 标签的镜像，GeoMX 的首次初始化可能需要几分钟的时间。但是，后续的运行将会恢复正常，除非您重新编译了 GeoMX。这个初始化延迟是正常的，它也发生在 PyTorch 和 MXNET 等其他框架上。

从 Dockerfile 中自动构建 GeoMX#

另外，我们也可以使用 Dockerfile 生成自定义的 Docker 镜像。在 docker 文件夹中可以找到一些 Dockerfile 模板。

要创建一个基于 CPU 的 Docker 镜像，使用：

cd docker && sudo docker build -f build_on_cpu.dockerfile -t geomx:cpu-only .

要创建一个基于 GPU 的 Docker 镜像，以 CUDA 10.1 版本为例，使用：

cd docker && sudo docker build -f build_on_gpu.dockerfile -t geomx:cu101 .

警告

如果由于网络问题导致 Docker 镜像或 GeoMX 编译失败，您可以重试，或在 Docker 容器内编译 GeoMX。

从源代码编译 GeoMX#

虽然在主机上直接安装 GeoMX 是可行的，但由于可能存在的环境不兼容等问题，我们不建议使用这种方式安装。但如果您需要在宿主机上编译安装 GeoMX，请参考以下步骤。

  • 步骤 1：从 GitHub 克隆 GeoMX 代码仓库下载源代码：

git clone https://github.com/INET-RC/GeoMX.git

警告

如果因网络问题导致 git clone 失败，请尝试使用代理，如在仓库地址前添加 https://ghproxy.com/：

git clone https://ghproxy.com/https://github.com/INET-RC/GeoMX.git

  • 步骤 2：安装第三方依赖：

sudo apt update
sudo apt install -y build-essential cmake libopencv-dev libopenblas-dev libsnappy-dev autogen autoconf automake libtool

  • 步骤 3：创建一个名为 geomx 的 conda 环境，使用 Python 3.7，并安装必要的包：

conda create -n geomx python=3.7
conda activate geomx
# Run the following commands in the conda environment named geomx.
pip install --upgrade pip
pip install numpy==1.17.3 pandas opencv-python -i https://mirrors.aliyun.com/pypi/simple

警告

如果您没有安装 Anaconda3，或者 Anaconda3 版本过高，可能会导致创建 Python 3.7 的 conda 环境失败。为解决这个问题，您可以使用以下命令安装一个兼容的 Anaconda3 版本：

curl -k -so ~/anaconda.sh https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-py37_4.9.2-Linux-x86_64.sh
chmod +x ~/anaconda.sh
~/anaconda.sh -b -p /opt/conda
rm ~/anaconda.sh
echo "export PATH=/opt/conda/bin:\$PATH" >> ~/.bashrc
echo "export CONDA_AUTO_UPDATE_CONDA=false" >> ~/.bashrc
/opt/conda/bin/conda init bash

如果安装成功，当重新打开您的 shell 时，会看到以下输出：

(base) user@hostname:~$

  • 步骤 4：复制配置文件。根据您的偏好，将对应的配置文件复制到 GeoMX/config.mk。如果是在 CPU 上编译安装，请使用：

cd GeoMX && cp make/cpu_config.mk ./config.mk

如果需要在 GPU 上编译安装，请复制配置文件 make/gpu_config.mk。具体的配置指令请参考 cpu_config.mk 和 gpu_config.mk。

  • 步骤 5：编译源代码。这里我们使用所有的 CPU 逻辑核（通过 $(nproc) 自动获取）来更快地构建 GeoMX。但是，为了避免 CPU 过载，您可能需要根据机器当前的 CPU 负载率调小这个值。

make -j$(nproc)

警告

这一步可能会因为网络问题而失败。如果发生这种问题，稍后再重新运行该命令。一旦构建成功，您将看到一个新的文件夹 lib，其中包含库文件 libmxnet.so。

警告

在执行 make 时，我们可能会遇到一个错误称 “opencv2/opencv.hpp: 没有那个文件或目录”。如果发生这种问题，请按照 OpenCV 官方文档中的指示安装 OpenCV2。

如果您只是想快速试用 GeoMX 或不需要 OpenCV，您可以在 ./config.mk 文件中简单地将 USE_OPENCV = 0 来禁用它。

如果您正在使用我们提供的 Dockerfile 或预构建 Docker 镜像，那么 OpenCV2 已经被安装好了，您不需要担心这个错误。

  • 步骤 6：安装 GeoMX 到 Python

cd python && pip install -e .

其中，-e 参数是可选的。它等同于 --editable，意味着如果您编辑了源文件，这些更改将会反映在已安装的包中。

  • 步骤 7：测试 GeoMX 是否安装成功

import mxnet as mx
from mxnet import nd

# Use this if we build GeoMX with USE_CUDA = 0.
nd.zeros(1, ctx=mx.cpu())
# Use this if we build GeoMX with USE_CUDA = 1.
# nd.zeros(1, ctx=mx.gpu(0))

如果没有报错，就说明 GeoMX 安装成功了。

警告

如果您编译 GeoMX 时设置了 USE_CUDA = 1，但是执行 nd.zeros(1, ctx=mx.gpu(0)) 时长时间无响应，请不用担心。这种延迟通常是因为第一次访问 GPU 时的初始设置操作。我们需要做的只是耐心等待几分钟。

如果过长的时间一直没有响应，最好检查您的 GPU 驱动和 CUDA 版本，或者考虑重启您的系统。

如果您设置 USE_CUDA = 1 后编译出现错误，尝试将 CUDA 版本降级到 8.0 或 10.1。目前 GeoMX 没有兼容更高的 CUDA 版本。