.. _windows-installation:

Windows installation
====================

Download the Windows package
----------------------------

Open the `muSRFlow Releases page
<https://gitea.psi.ch/salman/muSRFlow/releases>`_ and download
``muSRFlow-<version>-x64.exe`` plus its ``.sha256`` file. Verify the checksum,
then keep the installer available while enabling WSL below. The installer
contains the ROOT and musrfit runtime; do not download a separate Linux
runtime package for Windows.

The Windows installer includes muSRFlow, ROOT, and musrfit. Install WSL2
first; muSRFlow prepares its own Linux runtime on first launch. You do not
need Node.js, npm, Ubuntu, or a separate ROOT/musrfit installation.

Already installed muSRFlow? Read `Existing installations`_ as well: updating
the application does not update an already imported WSL runtime.

Before you start
----------------

* Use a **64-bit Intel/AMD PC**. The current package is x64.
* Windows 11 is recommended. Windows 10 requires build 19044 or newer for
  WSLg, which displays the musrview spectrum windows.
* Administrator access is needed to enable the Windows virtualization features.

See `Microsoft's WSL GUI requirements
<https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps>`_ for the
Windows prerequisites.

Install step by step
--------------------

1. **Install WSL.** Open **PowerShell as Administrator** and run:

   .. code-block:: powershell

      wsl --install --no-distribution

   **Restart Windows afterwards.** Skip this step if WSL is already installed.
   muSRFlow supplies its own distribution, so Ubuntu is not required.

2. **Update and check WSL.** In administrator PowerShell, run:

   .. code-block:: powershell

      wsl --update
      wsl --version

   Follow any restart instructions. The output should include WSL and WSLg.
   These commands are described in the `Microsoft WSL command reference
   <https://learn.microsoft.com/en-us/windows/wsl/basic-commands>`_.

3. **Install muSRFlow.** Double-click the Windows installer and complete setup.
   The runtime archive ``muSRFlow-runtime-rootfs.tar.gz`` is included; do not
   extract or import it manually for a normal installation.

4. **Launch muSRFlow** from the Start menu using your normal Windows account.
   First launch imports the runtime as ``muSRFlow-runtime`` and can take
   several minutes. Fit and Plot wait until preparation finishes. Afterwards,
   verify in PowerShell:

   .. code-block:: powershell

      wsl --list --verbose

   The list should contain ``muSRFlow-runtime`` with **VERSION 2**.
   ``Running`` and ``Stopped`` are both normal when idle. The runtime is
   stored under ``%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime`` for this account.

5. **Choose work and data folders before fitting.** Create folders such as:

   .. code-block:: text

      C:\Users\<your-name>\muSRFlow\work
      C:\Users\<your-name>\muSRFlow\data

   In **File / Preferences**, select them as **Work directory** and
   **Data directory**. Leave **musrfit binaries** and **musrfit startup XML**
   on automatic detection, then save. Enter normal Windows paths; muSRFlow
   translates them for WSL.

   Use a work folder outside the application installation directory. The
   default ``.`` can resolve to the installation folder and place your
   results among files managed by the installer.

6. **Try Plot, then Fit.** Select a known instrument, year, and run. Click
   **Plot** and confirm that the spectrum window opens. Missing run data
   can be downloaded from ``musruser.psi.ch`` after confirmation when the
   server is reachable. Then click **Fit**, check that the parameter table
   updates, and inspect the generated files in your work directory.

.. _windows-existing-installations:

Existing installations
----------------------

1. Preserve any MSR/data/result files currently stored inside the muSRFlow
   installation folder: move them to a separate work folder before upgrading.
2. Close muSRFlow and install the refreshed Windows application.
3. If your runtime was imported from an older bundle, add the missing Boost
   headers from PowerShell:

   .. code-block:: powershell

      wsl -d muSRFlow-runtime -- dnf -y install boost-devel

   This needs access to the distribution's package repositories. ROOT uses
   these headers when loading musrview plotting classes. Fresh runtimes
   from the corrected installer already include them.
4. Reopen muSRFlow, select your work directory in Preferences, and retry Plot
   and Fit.

Reinstalling the application preserves an existing ``muSRFlow-runtime``
distribution, so the application update alone does not add those headers.
The command above repairs it in place; do not unregister the distribution
as part of this update. The Linux **Install runtime...** preference is not
used on Windows.

For WSL startup, runtime-library, or spectrum-window problems, continue with
the Windows section of :doc:`troubleshooting`.
