First successful Windows installation: WSL2 + TUNA mirror / 首次 Windows 实机安装成功

[haoming-luo]

First successful Windows installation / 首次 Windows 实机安装成功

AgentFEM has now completed its first reported installation and finite-element
solve on a real Windows host through WSL2 + the TUNA mirror route. This
field note records the reusable path and the two recovery steps that may help
future users.

AgentFEM 已完成首次真实 Windows 主机上的安装与有限元求解。本次采用
WSL2 + TUNA 镜像通道，以下只保留可复用、已脱敏的经验。

Verified route / 已走通路径

Initial host state:

• Windows 10/11, x86-64;
• no existing WSL, conda, or mamba;
• Windows administrator approval was supplied through UAC when WSL was enabled.

The successful sequence was:

1. Enable WSL without downloading a default Linux distribution:

   wsl --install --no-distribution --no-launch

2. When wsl --install -d Ubuntu timed out while accessing GitHub-hosted
   metadata, download the Ubuntu 24.04 WSL image from TUNA and verify its
   SHA-256 against the published checksum:

   curl.exe -L -o ubuntu-24.04.4-wsl-amd64.wsl `
     https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/24.04.4/ubuntu-24.04.4-wsl-amd64.wsl
   
   wsl --import Ubuntu-24.04 <install-dir> .\ubuntu-24.04.4-wsl-amd64.wsl

3. Download the Linux x86-64 Miniforge installer from TUNA, install it inside
   WSL, and create the supported environment from one conda-forge mirror:

   mamba create -n agentfem-env --no-rc --override-channels \
     -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge \
     python=3.11 fenics-dolfinx=0.11 agentfem
   mamba activate agentfem-env
   agentfem doctor --json
   agentfem workspace --protect --json

The resulting stack used Python 3.11, DOLFINx 0.11, PETSc 3.25 and MPICH 5.0.
AgentFEM identified the route as Windows via WSL2/Linux, selected a compatible
MPI launcher, and protected projects under Windows
Documents\AgentFEMProjects.

Two useful findings / 两点经验

Mirror synchronization. During the first installation on 14 September
2026, TUNA briefly resolved AgentFEM 0.3.4 while 0.3.6 had just been released.
TUNA now carries 0.3.6. This was normal mirror propagation delay, not a lasting
version limitation.

First-solve compiler repair. The environment initially lacked a visible C
compiler, so FEniCSx could not JIT-compile a new UFL form. Installing the native
toolchain fixed the existing environment, after which the finite-element case
completed successfully:

sudo apt-get update
sudo apt-get install -y gcc g++
agentfem doctor

This repair does not alter project inputs or results. AgentFEM's corrected
runtime contract now detects solver readiness, includes the compiler in future
Complete Runtime milestones, and re-imports the final .wsl artifact into a
clean environment for a cold-cache solve before acceptance.

Current guidance

• Follow the installation guide.
• Keep projects in Documents\AgentFEMProjects rather than inside a disposable
  WSL distribution.
• Use one conda-forge source for the PETSc/MPI/FEniCSx stack; do not mix
  numerical package channels.
• Native Windows remains experimental; WSL2 is the supported Windows route.

Thank you to the first Windows tester for carrying this path from a clean
machine through installation, diagnosis, and a successful solve.