From cd28af61804cc84838243794d476c95e06715116 Mon Sep 17 00:00:00 2001 From: Critsium-xy Date: Wed, 22 Apr 2026 17:01:20 +0800 Subject: [PATCH 1/2] Move windows docx --- docs/index.rst | 2 +- docs/quick_start/easy_install.md | 2 +- docs/quick_start/windows_installer.md | 256 -------------------------- 3 files changed, 2 insertions(+), 258 deletions(-) delete mode 100644 docs/quick_start/windows_installer.md diff --git a/docs/index.rst b/docs/index.rst index a5209940347..dd0b5968c4c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,7 +26,6 @@ the developments and applications of novel machine-learning-assisted DFT methods :caption: Quick Start quick_start/easy_install - quick_start/windows_installer quick_start/hands_on quick_start/input quick_start/output @@ -45,6 +44,7 @@ the developments and applications of novel machine-learning-assisted DFT methods advanced/output_files/index advanced/interface/index advanced/input_files/index + advanced/windows_installer .. toctree:: :maxdepth: 2 diff --git a/docs/quick_start/easy_install.md b/docs/quick_start/easy_install.md index 90128a707b1..c9c33096691 100644 --- a/docs/quick_start/easy_install.md +++ b/docs/quick_start/easy_install.md @@ -1,6 +1,6 @@ # Easy Installation -This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that provisions WSL2 and installs ABACUS inside it automatically, see [Windows One-Click Installer](./windows_installer.md). +This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that provisions WSL2 and installs ABACUS inside it automatically, see [Windows One-Click Installer](./advanced/windows_installer.md). ## Get ABACUS source code diff --git a/docs/quick_start/windows_installer.md b/docs/quick_start/windows_installer.md deleted file mode 100644 index 7d4e3346760..00000000000 --- a/docs/quick_start/windows_installer.md +++ /dev/null @@ -1,256 +0,0 @@ -# Windows One-Click Installer (WSL2 + conda-forge) - -A lightweight installer that brings ABACUS to Windows via WSL2 and -conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling — -run `install-abacus.bat` once and type `abacus` from any Windows terminal. - -The scripts live in the repository under `tools/windows/`. This page is the -user-facing documentation for the same scripts. - -## How it works - -ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, -ELPA, FFTW, libxc, OpenBLAS, …) that is painful to build natively on Windows. -Instead of porting, this installer provisions a standard Linux environment -inside WSL2 and exposes it through thin Windows launchers. - -The pipeline, end to end: - -1. **`install-abacus.bat`** (runs on Windows, requires admin) - - Checks the Windows build (≥ 19041) and whether WSL is installed; if not, - runs `wsl --install --no-launch` and asks the user to reboot once. - - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. - - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL - registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This - is immune to UTF-16 parsing pitfalls and to Store appx leftovers that - can make `wsl -d -- true` falsely report success. - - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is - missing, then verifies the registry entry appeared. - - Invokes `provision.sh` inside the distribution, stripping any `\r` - bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line - endings don't break shell parsing. - - Writes two small launcher `.cmd` files and adds them to the user PATH - via PowerShell (avoiding `setx`'s 1024-character truncation). - -2. **`provision.sh`** (runs as root inside the WSL distribution) - - Optionally rewrites `/etc/apt/sources.list` to TUNA. - - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, - bzip2). - - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases - mirror) and installs it to `/opt/abacus-miniforge`. - - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA - conda-forge channel) — a single package pulls in the entire scientific - runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, - which is exactly what WSL2 provides. - - Writes two system-wide launchers, `/usr/local/bin/abacus` and - `/usr/local/bin/abacus-mpi`, that activate the env and exec the real - binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread - oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE - "allow run as root" environment variables and passes - `--allow-run-as-root` to `mpirun`, so the default WSL root user can - launch parallel jobs without creating a non-root user. - -3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) - - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. - - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` - so thread-count overrides set on the Windows side are visible inside WSL. - - Body is just: - ``` - wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* - ``` - `--cd "%CD%"` maps the current Windows directory (`C:\…\case`) to its - WSL path (`/mnt/c/…/case`), so users can `cd` into a case directory in - `cmd`/PowerShell/Terminal and just type `abacus`. - -4. **`uninstall-abacus.bat`** - - Reads `install-state.txt` (written by the installer) to learn whether - the Ubuntu-22.04 distribution was pre-existing or added by us. - - If it was added by us, prompts whether to `wsl --unregister` the entire - distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. - - If it was pre-existing, only the ABACUS files inside are removed. - - Cleans Windows-side launchers and removes the bin directory from the - user PATH. - - Does **not** touch WSL itself (runtime, Windows optional features, or - other distributions). See *Uninstallation* below for how to fully - remove WSL if you want to. - -## Requirements - -- Windows 10 build 19041 (2004) or newer, or any Windows 11. -- Administrator privileges for the first run (to enable WSL features). -- Virtualization enabled in BIOS/UEFI. -- ~2 GB free disk space (Ubuntu + conda env). -- Network access to GitHub and conda-forge, or to TUNA if you choose the - China mirror option. - -## Installation - -1. Clone or download this repository. -2. In `tools/windows/`, right-click `install-abacus.bat` → **Run as administrator**. -3. Answer the China-mirror prompt (`y` recommended inside Mainland China). -4. If this is the first time WSL is installed on the machine, the script - will ask you to reboot and run it again. -5. Wait for `[*] Provisioning ABACUS …` to finish (5–15 minutes on first - run; most of it is the conda-forge download). -6. When you see `Installation complete!`, **open a new terminal window** - (so the updated PATH takes effect) and verify: - ``` - abacus --version - ``` - -## Usage - -Serial run in any case directory: - -``` -cd path\to\my_case -abacus -``` - -Parallel run with 4 MPI ranks: - -``` -abacus-mpi -n 4 -``` - -Hybrid MPI + OpenMP (e.g. 4 MPI ranks × 2 threads each): - -``` -set OMP_NUM_THREADS=2 -abacus-mpi -n 4 -``` - -Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in -your Windows shell and the launcher will forward the value into WSL through -`WSLENV`. Unset, it defaults to 1 — a safe choice when running pure MPI. - -Interactive Linux shell (for advanced debugging, manually running -`mpirun`, inspecting logs, etc.): - -``` -wsl -d Ubuntu-22.04 -``` - -Inside the shell you can `conda activate abacus_env` to get access to -`mpirun`, `mpiexec`, and other tools from the conda environment. - -## Uninstallation - -### Standard: remove ABACUS only - -Run `uninstall-abacus.bat`. This handles the common case: - -- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers - inside WSL. -- If the installer added the `Ubuntu-22.04` distribution, asks whether you - also want to `wsl --unregister` it (pick `y` to reclaim the disk space, - `n` to keep the Linux environment for other uses). -- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from - your user PATH. - -This is enough for almost every user. WSL itself and any *other* WSL -distributions you have stay untouched — important because WSL is commonly -shared with Docker Desktop, VS Code Remote, and other toolchains. - -### Nuclear: remove WSL itself - -Only do this if you truly have no other use for WSL on this machine. -Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other -Linux distros you have, and so on. Run the following in an elevated -PowerShell: - -```powershell -# 1. Unregister every WSL distribution (this wipes all their files). -wsl --list --quiet | ForEach-Object { wsl --unregister $_.Trim() } - -# 2. Uninstall the WSL runtime itself (wsl.exe + the Linux kernel package). -# This is Microsoft's official command; it does not disable the Windows -# optional features and does not touch any distro appx packages. -wsl --uninstall - -# 3. Optionally remove leftover distribution appx packages from the Store -# (e.g. "Ubuntu 22.04 LTS"). `wsl --unregister` deletes the data only; -# the Store app that installs the distro is separate. -Get-AppxPackage *Ubuntu* | Remove-AppxPackage - -# 4. Optional: disable the Windows optional features (requires a reboot). -# Skip this step if anything else on the machine still uses Hyper-V -# virtualization (Docker Desktop, Windows Sandbox, Hyper-V VMs, ...). -dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart -dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart - -# 5. Remove user config if present. -Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue - -# 6. Reboot to finalize. -Restart-Computer -``` - -After the reboot `wsl.exe` no longer exists. If you also ran step 4, the -Hyper-V virtualization layer used by WSL2 is disabled. - -> On older Windows builds where `wsl --uninstall` is not available (WSL -> shipped via the in-box `wsl.exe` rather than the Store package), use -> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a -> fallback for step 2. - -## Performance notes - -- Files under `/mnt/c/...` are served through the 9P protocol and are - noticeably slower than native ext4. For heavy I/O (large SCF, MD - trajectories), run the case from inside the WSL filesystem: - ``` - wsl -d Ubuntu-22.04 - cp -r /mnt/c/path/to/case ~/case - cd ~/case - abacus - ``` -- The first `wsl` invocation after a boot triggers a 10–30 s VM cold start. -- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network - overhead between ranks — you get near-native parallel performance. - -## File layout - -``` -tools/windows/ -├── install-abacus.bat # Windows entry point (admin, interactive) -├── uninstall-abacus.bat # Clean removal, optionally including the distro -├── provision.sh # Linux-side installer (runs as root in WSL) -├── .gitattributes # Pin *.sh to LF, *.bat/*.cmd to CRLF -└── README.md # Mirror of this page, shipped with the scripts -``` - -Artifacts created at install time: - -``` -%LOCALAPPDATA%\ABACUS\ -├── bin\ -│ ├── abacus.cmd # Windows launcher (serial) -│ └── abacus-mpi.cmd # Windows launcher (MPI) -└── install-state.txt # Records whether we created the WSL distro - -Inside WSL (Ubuntu-22.04): -/opt/abacus-miniforge/ # Private Miniforge install -/opt/abacus-miniforge/envs/abacus_env/ # conda env holding abacus -/usr/local/bin/abacus, /usr/local/bin/abacus-mpi # Linux-side launchers -``` - -## Design choices and trade-offs - -- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's - MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going - through WSL2 lets us reuse the Linux binaries conda-forge already ships, - turning a multi-week porting problem into a 200-line shell script. -- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is - built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks - mismatches; pinning the version keeps the install reproducible. -- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** - Clean uninstall path, clear ownership, and doesn't interfere with a - user's personal conda install if they later add one inside the same - distribution. -- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from - ~10 min to ~1 min, but balloons the installer from a few KB of scripts - to 300–500 MB, requires CI infrastructure, and needs code signing to - avoid SmartScreen warnings. A scripted online installer is the - lowest-maintenance starting point; the pre-built rootfs path remains - open for a future v1. From 22991254bbc0ed4b96fbbb85a291666f0537c28d Mon Sep 17 00:00:00 2001 From: Critsium-xy Date: Wed, 22 Apr 2026 17:04:38 +0800 Subject: [PATCH 2/2] Add docs --- docs/advanced/windows_installer.md | 256 +++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/advanced/windows_installer.md diff --git a/docs/advanced/windows_installer.md b/docs/advanced/windows_installer.md new file mode 100644 index 00000000000..7d4e3346760 --- /dev/null +++ b/docs/advanced/windows_installer.md @@ -0,0 +1,256 @@ +# Windows One-Click Installer (WSL2 + conda-forge) + +A lightweight installer that brings ABACUS to Windows via WSL2 and +conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling — +run `install-abacus.bat` once and type `abacus` from any Windows terminal. + +The scripts live in the repository under `tools/windows/`. This page is the +user-facing documentation for the same scripts. + +## How it works + +ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, +ELPA, FFTW, libxc, OpenBLAS, …) that is painful to build natively on Windows. +Instead of porting, this installer provisions a standard Linux environment +inside WSL2 and exposes it through thin Windows launchers. + +The pipeline, end to end: + +1. **`install-abacus.bat`** (runs on Windows, requires admin) + - Checks the Windows build (≥ 19041) and whether WSL is installed; if not, + runs `wsl --install --no-launch` and asks the user to reboot once. + - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL + registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This + is immune to UTF-16 parsing pitfalls and to Store appx leftovers that + can make `wsl -d -- true` falsely report success. + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is + missing, then verifies the registry entry appeared. + - Invokes `provision.sh` inside the distribution, stripping any `\r` + bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line + endings don't break shell parsing. + - Writes two small launcher `.cmd` files and adds them to the user PATH + via PowerShell (avoiding `setx`'s 1024-character truncation). + +2. **`provision.sh`** (runs as root inside the WSL distribution) + - Optionally rewrites `/etc/apt/sources.list` to TUNA. + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, + bzip2). + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases + mirror) and installs it to `/opt/abacus-miniforge`. + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA + conda-forge channel) — a single package pulls in the entire scientific + runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, + which is exactly what WSL2 provides. + - Writes two system-wide launchers, `/usr/local/bin/abacus` and + `/usr/local/bin/abacus-mpi`, that activate the env and exec the real + binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread + oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE + "allow run as root" environment variables and passes + `--allow-run-as-root` to `mpirun`, so the default WSL root user can + launch parallel jobs without creating a non-root user. + +3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` + so thread-count overrides set on the Windows side are visible inside WSL. + - Body is just: + ``` + wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* + ``` + `--cd "%CD%"` maps the current Windows directory (`C:\…\case`) to its + WSL path (`/mnt/c/…/case`), so users can `cd` into a case directory in + `cmd`/PowerShell/Terminal and just type `abacus`. + +4. **`uninstall-abacus.bat`** + - Reads `install-state.txt` (written by the installer) to learn whether + the Ubuntu-22.04 distribution was pre-existing or added by us. + - If it was added by us, prompts whether to `wsl --unregister` the entire + distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. + - If it was pre-existing, only the ABACUS files inside are removed. + - Cleans Windows-side launchers and removes the bin directory from the + user PATH. + - Does **not** touch WSL itself (runtime, Windows optional features, or + other distributions). See *Uninstallation* below for how to fully + remove WSL if you want to. + +## Requirements + +- Windows 10 build 19041 (2004) or newer, or any Windows 11. +- Administrator privileges for the first run (to enable WSL features). +- Virtualization enabled in BIOS/UEFI. +- ~2 GB free disk space (Ubuntu + conda env). +- Network access to GitHub and conda-forge, or to TUNA if you choose the + China mirror option. + +## Installation + +1. Clone or download this repository. +2. In `tools/windows/`, right-click `install-abacus.bat` → **Run as administrator**. +3. Answer the China-mirror prompt (`y` recommended inside Mainland China). +4. If this is the first time WSL is installed on the machine, the script + will ask you to reboot and run it again. +5. Wait for `[*] Provisioning ABACUS …` to finish (5–15 minutes on first + run; most of it is the conda-forge download). +6. When you see `Installation complete!`, **open a new terminal window** + (so the updated PATH takes effect) and verify: + ``` + abacus --version + ``` + +## Usage + +Serial run in any case directory: + +``` +cd path\to\my_case +abacus +``` + +Parallel run with 4 MPI ranks: + +``` +abacus-mpi -n 4 +``` + +Hybrid MPI + OpenMP (e.g. 4 MPI ranks × 2 threads each): + +``` +set OMP_NUM_THREADS=2 +abacus-mpi -n 4 +``` + +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in +your Windows shell and the launcher will forward the value into WSL through +`WSLENV`. Unset, it defaults to 1 — a safe choice when running pure MPI. + +Interactive Linux shell (for advanced debugging, manually running +`mpirun`, inspecting logs, etc.): + +``` +wsl -d Ubuntu-22.04 +``` + +Inside the shell you can `conda activate abacus_env` to get access to +`mpirun`, `mpiexec`, and other tools from the conda environment. + +## Uninstallation + +### Standard: remove ABACUS only + +Run `uninstall-abacus.bat`. This handles the common case: + +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers + inside WSL. +- If the installer added the `Ubuntu-22.04` distribution, asks whether you + also want to `wsl --unregister` it (pick `y` to reclaim the disk space, + `n` to keep the Linux environment for other uses). +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from + your user PATH. + +This is enough for almost every user. WSL itself and any *other* WSL +distributions you have stay untouched — important because WSL is commonly +shared with Docker Desktop, VS Code Remote, and other toolchains. + +### Nuclear: remove WSL itself + +Only do this if you truly have no other use for WSL on this machine. +Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other +Linux distros you have, and so on. Run the following in an elevated +PowerShell: + +```powershell +# 1. Unregister every WSL distribution (this wipes all their files). +wsl --list --quiet | ForEach-Object { wsl --unregister $_.Trim() } + +# 2. Uninstall the WSL runtime itself (wsl.exe + the Linux kernel package). +# This is Microsoft's official command; it does not disable the Windows +# optional features and does not touch any distro appx packages. +wsl --uninstall + +# 3. Optionally remove leftover distribution appx packages from the Store +# (e.g. "Ubuntu 22.04 LTS"). `wsl --unregister` deletes the data only; +# the Store app that installs the distro is separate. +Get-AppxPackage *Ubuntu* | Remove-AppxPackage + +# 4. Optional: disable the Windows optional features (requires a reboot). +# Skip this step if anything else on the machine still uses Hyper-V +# virtualization (Docker Desktop, Windows Sandbox, Hyper-V VMs, ...). +dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart +dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart + +# 5. Remove user config if present. +Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue + +# 6. Reboot to finalize. +Restart-Computer +``` + +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the +Hyper-V virtualization layer used by WSL2 is disabled. + +> On older Windows builds where `wsl --uninstall` is not available (WSL +> shipped via the in-box `wsl.exe` rather than the Store package), use +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a +> fallback for step 2. + +## Performance notes + +- Files under `/mnt/c/...` are served through the 9P protocol and are + noticeably slower than native ext4. For heavy I/O (large SCF, MD + trajectories), run the case from inside the WSL filesystem: + ``` + wsl -d Ubuntu-22.04 + cp -r /mnt/c/path/to/case ~/case + cd ~/case + abacus + ``` +- The first `wsl` invocation after a boot triggers a 10–30 s VM cold start. +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network + overhead between ranks — you get near-native parallel performance. + +## File layout + +``` +tools/windows/ +├── install-abacus.bat # Windows entry point (admin, interactive) +├── uninstall-abacus.bat # Clean removal, optionally including the distro +├── provision.sh # Linux-side installer (runs as root in WSL) +├── .gitattributes # Pin *.sh to LF, *.bat/*.cmd to CRLF +└── README.md # Mirror of this page, shipped with the scripts +``` + +Artifacts created at install time: + +``` +%LOCALAPPDATA%\ABACUS\ +├── bin\ +│ ├── abacus.cmd # Windows launcher (serial) +│ └── abacus-mpi.cmd # Windows launcher (MPI) +└── install-state.txt # Records whether we created the WSL distro + +Inside WSL (Ubuntu-22.04): +/opt/abacus-miniforge/ # Private Miniforge install +/opt/abacus-miniforge/envs/abacus_env/ # conda env holding abacus +/usr/local/bin/abacus, /usr/local/bin/abacus-mpi # Linux-side launchers +``` + +## Design choices and trade-offs + +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's + MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going + through WSL2 lets us reuse the Linux binaries conda-forge already ships, + turning a multi-week porting problem into a 200-line shell script. +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is + built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks + mismatches; pinning the version keeps the install reproducible. +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** + Clean uninstall path, clear ownership, and doesn't interfere with a + user's personal conda install if they later add one inside the same + distribution. +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from + ~10 min to ~1 min, but balloons the installer from a few KB of scripts + to 300–500 MB, requires CI infrastructure, and needs code signing to + avoid SmartScreen warnings. A scripted online installer is the + lowest-maintenance starting point; the pre-built rootfs path remains + open for a future v1.