[Feature] Add Windows Installer for ABACUS

docs/index.rst

@@ -26,6 +26,7 @@ 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

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.
+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).
 
 ## Get ABACUS source code
 

docs/quick_start/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 <name> -- 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.

tools/windows/.gitattributes

@@ -0,0 +1,6 @@
+# Shell scripts must have LF line endings so bash inside WSL can parse them.
+*.sh text eol=lf
+
+# Batch files are Windows-only; keep CRLF.
+*.bat text eol=crlf
+*.cmd text eol=crlf