ARC - Reference Documentation

ARC is a Linux‑only setup script that provisions a clean, CPU‑only PyTorch environment for the HLS for AI labs. It prefers conda and automatically falls back to venv when conda is unavailable or fails.

Design Goals

Reproducible student environments across Flip/Babylon and other Linux hosts.
CPU‑first PyTorch baseline for broad compatibility.
Guardrails to keep third‑party requirements from breaking the torch stack.
Sane toolchains: verify on venv path, install inside conda env when using conda.

File Layout

setup.sh - main entrypoint (run this)
requirements.txt - course extras; installed with constraints (won’t override torch)
.gitignore - ignores virtual envs, caches, build outputs

Installation

Clone the repository and run ARC:

bash

git clone https://github.com/Anthonykung/hls-for-ai-lab1-env.git
cd hls-for-ai-lab1-env
bash setup.sh

CLI

bash

bash setup.sh [OPTIONS]

Options:
  --conda                 Prefer conda (falls back to venv if conda path fails)
  --venv                  Force Python venv (no conda attempt)
  --python X.Y            Python version (default set in script, e.g., 3.11)
  --name <env-name>       Conda env name (default: arc_env)
  --venv-dir <path>       Venv directory (default: .venv)
  -h, --help              Show detailed help

Environment Variable Overrides

bash

ENV_MANAGER=conda bash setup.sh
ENV_MANAGER=venv  bash setup.sh

Safeguards & Constraints

Torch stack is authoritative: ARC installs CPU wheels first, then pins/constraints them.
requirements.txt is solved through pip-tools so it respects the pinned torch packages.
On venv path, ARC verifies host toolchains only.
On conda path, ARC installs toolchains inside the env from conda-forge.

Toolchain Minimums

make ≥ 4.3
gcc ≥ 11.5
g++ ≥ 11.5
cmake ≥ 3.26
pkg-config (GNU) ≥ 0.29.2 or pkgconf ≥ 1.7.0

Note: If your system is older and you hit C++ ABI errors, prefer the conda path so modern runtimes are included inside the env.

Examples

Prefer conda with Python 3.11:

bash

bash setup.sh --conda --python 3.11

Force venv to .env/:

bash

bash setup.sh --venv --venv-dir .env

Disable auto‑detect via env var:

bash

ENV_MANAGER=venv bash setup.sh

Verification Output (Sample)

Python: 3.11.x
Torch: 2.x.y
CUDA available (should be False): False
Numpy: 1.x.y
✅ CPU-only PyTorch confirmed.

Followed by toolchain versions.

Logs

install.log - latest run
install.log.1 - previous run

Cleanup / Reset

Conda

bash

conda deactivate 2>/dev/null || true
conda remove -n arc_env --all -y

Venv

bash

deactivate 2>/dev/null || true
rm -rf .venv

Re‑run bash setup.sh afterward.

FAQ

Why CPU‑only? Course baseline, consistent across hosts; GPU access is not guaranteed.

Will ARC modify my system compilers? No. Venv path only verifies. Conda path installs toolchains inside the env.

Can I add packages later? Yes - conda install <pkg> or pip install <pkg> depending on your manager. Avoid altering the torch stack unless necessary.

Where should I file issues? Include install.log when asking for help.