A lightweight one-click 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.

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.
   • Prompts for an ABACUS version (blank = latest on conda-forge; an exact version like 3.7.4 is pinned; a match-spec like >=3.7,<3.8 is passed through to conda).
   • 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 installs 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.

• 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.

1. Clone or download this repository.
2. Right-click install-abacus.bat → Run as administrator.
3. Answer the China-mirror prompt (y recommended inside Mainland China). Then pick an ABACUS version when prompted (leave blank for the latest on conda-forge; for a pinned install, type an exact version such as 3.7.4).
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
   

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.

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.

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:

# 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.

• 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.

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              # This file

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

• 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.