304 lines
20 KiB
HTML
304 lines
20 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<html class="writer-html5" lang="en" data-content_root="./">
|
|
<head>
|
|
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<title>Windows installation — muSRFlow User Manual</title>
|
|
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
|
|
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=d11f710b" />
|
|
|
|
|
|
<script src="_static/jquery.js?v=5d32c60e"></script>
|
|
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
|
|
<script src="_static/documentation_options.js?v=8085e645"></script>
|
|
<script src="_static/doctools.js?v=9bcbadda"></script>
|
|
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
|
|
<script src="_static/js/theme.js"></script>
|
|
<link rel="index" title="Index" href="genindex.html" />
|
|
<link rel="search" title="Search" href="search.html" />
|
|
<link rel="next" title="Linux installation" href="install-linux.html" />
|
|
<link rel="prev" title="Getting started" href="getting-started.html" />
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav">
|
|
<div class="wy-grid-for-nav">
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search" >
|
|
|
|
|
|
|
|
<a href="index.html" class="icon icon-home">
|
|
muSRFlow
|
|
</a>
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
|
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting started</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">Windows installation</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#before-you-start">Before you start</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#install-step-by-step">Install step by step</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#existing-installations">Existing installations</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#required-feature-is-not-installed">Required feature is not installed</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#cannot-find-wsl-exe">Cannot find wsl.exe</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#cannot-load-libcore-so">Cannot load libCore.so</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#missing-boost-version-hpp-or-plotting-crash">Missing boost/version.hpp or plotting crash</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#no-spectrum-window-appears">No spectrum window appears</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#reporting-a-problem">Reporting a problem</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="install-linux.html">Linux installation</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="runs-fitting.html">Runs and fitting</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="parameters-plots.html">Parameters and parameter plots</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="constraints.html">Constraints</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="t0-background.html">t0 / background</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="msr-editor.html">MSR editor</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="results-diagnostics.html">Results and diagnostics</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="configuration-sharing.html">Configuration sharing</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="preferences.html">Preferences</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="platforms.html">Web and desktop editions</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="keyboard-shortcuts.html">Keyboard shortcuts</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">muSRFlow</a>
|
|
</nav>
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="Page navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
|
|
<li class="breadcrumb-item active">Windows installation</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
<a href="_sources/install-windows.rst.txt" rel="nofollow"> View page source</a>
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<section id="windows-installation">
|
|
<span id="id1"></span><h1>Windows installation<a class="headerlink" href="#windows-installation" title="Link to this heading"></a></h1>
|
|
<p>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.</p>
|
|
<p>Already installed muSRFlow? Read <a class="reference internal" href="#existing-installations">Existing installations</a> as well: updating
|
|
the application does not update an already imported WSL runtime.</p>
|
|
<section id="before-you-start">
|
|
<h2>Before you start<a class="headerlink" href="#before-you-start" title="Link to this heading"></a></h2>
|
|
<ul class="simple">
|
|
<li><p>Use a <strong>64-bit Intel/AMD PC</strong>. The current package is x64.</p></li>
|
|
<li><p>Windows 11 is recommended. Windows 10 requires build 19044 or newer for
|
|
WSLg, which displays the musrview spectrum windows.</p></li>
|
|
<li><p>Administrator access is needed to enable the Windows virtualization features.</p></li>
|
|
<li><p>Obtain the Windows installer, named <code class="docutils literal notranslate"><span class="pre">muSRFlow-<version>-x64.exe</span></code>, from
|
|
the project’s <a class="reference external" href="https://gitea.psi.ch/salman/muSRFlow/releases">Releases</a>
|
|
or the <strong>musrflow-windows</strong> package in
|
|
<a class="reference external" href="https://gitea.psi.ch/salman/muSRFlow/packages">Packages</a>. Verify its
|
|
SHA-256 checksum against the accompanying <code class="docutils literal notranslate"><span class="pre">.sha256</span></code> file. The Windows
|
|
installer includes the bundled runtime (<code class="docutils literal notranslate"><span class="pre">musrfit</span></code>, <code class="docutils literal notranslate"><span class="pre">musrt0</span></code>, <code class="docutils literal notranslate"><span class="pre">musrview</span></code>,
|
|
<code class="docutils literal notranslate"><span class="pre">msr2data</span></code>, <code class="docutils literal notranslate"><span class="pre">dump_header</span></code>, <code class="docutils literal notranslate"><span class="pre">root-config</span></code>) for use inside WSL2; only
|
|
markers are placed in the app resources.</p></li>
|
|
<li><p>For a test build that has not been published yet, download the
|
|
<strong>musrflow-windows-x64</strong> artifact from a successful <strong>Build Windows
|
|
installer</strong> workflow run and extract the installer.</p></li>
|
|
</ul>
|
|
<p><strong>Avoid old rc.5 installers.</strong> Early builds lack the WSL fixes. The current
|
|
runner-built installer includes them and has passed Windows installation,
|
|
runtime setup, data download, Fit/Plot, and multi-run smoke tests.</p>
|
|
<p>See <a class="reference external" href="https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps">Microsoft’s WSL GUI requirements</a> for the
|
|
Windows prerequisites.</p>
|
|
</section>
|
|
<section id="install-step-by-step">
|
|
<h2>Install step by step<a class="headerlink" href="#install-step-by-step" title="Link to this heading"></a></h2>
|
|
<ol class="arabic">
|
|
<li><p><strong>Install WSL.</strong> Open <strong>PowerShell as Administrator</strong> and run:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">wsl</span> <span class="p">-</span><span class="n">-install</span> <span class="p">-</span><span class="n">-no-distribution</span>
|
|
</pre></div>
|
|
</div>
|
|
<p><strong>Restart Windows afterwards.</strong> Skip this step if WSL is already installed.
|
|
muSRFlow supplies its own distribution, so Ubuntu is not required.</p>
|
|
</li>
|
|
<li><p><strong>Update and check WSL.</strong> In administrator PowerShell, run:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">wsl</span> <span class="p">-</span><span class="n">-update</span>
|
|
<span class="n">wsl</span> <span class="p">-</span><span class="n">-version</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Follow any restart instructions. The output should include WSL and WSLg.
|
|
These commands are described in the <a class="reference external" href="https://learn.microsoft.com/en-us/windows/wsl/basic-commands">Microsoft WSL command reference</a>.</p>
|
|
</li>
|
|
<li><p><strong>Install muSRFlow.</strong> Double-click the Windows installer and complete setup.
|
|
The runtime archive <code class="docutils literal notranslate"><span class="pre">muSRFlow-runtime-rootfs.tar.gz</span></code> is included; do not
|
|
extract or import it manually for a normal installation.</p></li>
|
|
<li><p><strong>Launch muSRFlow</strong> from the Start menu using your normal Windows account.
|
|
First launch imports the runtime as <code class="docutils literal notranslate"><span class="pre">muSRFlow-runtime</span></code> and can take
|
|
several minutes. Fit and Plot wait until preparation finishes. Afterwards,
|
|
verify in PowerShell:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">wsl</span> <span class="p">-</span><span class="n">-list</span> <span class="p">-</span><span class="n">-verbose</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The list should contain <code class="docutils literal notranslate"><span class="pre">muSRFlow-runtime</span></code> with <strong>VERSION 2</strong>.
|
|
<code class="docutils literal notranslate"><span class="pre">Running</span></code> and <code class="docutils literal notranslate"><span class="pre">Stopped</span></code> are both normal when idle. The runtime is
|
|
stored under <code class="docutils literal notranslate"><span class="pre">%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime</span></code> for this account.</p>
|
|
</li>
|
|
<li><p><strong>Choose work and data folders before fitting.</strong> Create folders such as:</p>
|
|
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>C:\Users\<your-name>\muSRFlow\work
|
|
C:\Users\<your-name>\muSRFlow\data
|
|
</pre></div>
|
|
</div>
|
|
<p>In <strong>File / Preferences</strong>, select them as <strong>Work directory</strong> and
|
|
<strong>Data directory</strong>. Leave <strong>musrfit binaries</strong> and <strong>musrfit startup XML</strong>
|
|
on automatic detection, then save. Enter normal Windows paths; muSRFlow
|
|
translates them for WSL.</p>
|
|
<p>Use a work folder outside the application installation directory. The
|
|
default <code class="docutils literal notranslate"><span class="pre">.</span></code> can resolve to the installation folder and place your
|
|
results among files managed by the installer.</p>
|
|
</li>
|
|
<li><p><strong>Try Plot, then Fit.</strong> Select a known instrument, year, and run. Click
|
|
<strong>Plot</strong> and confirm that the spectrum window opens. Missing run data
|
|
can be downloaded from <code class="docutils literal notranslate"><span class="pre">musruser.psi.ch</span></code> after confirmation when the
|
|
server is reachable. Then click <strong>Fit</strong>, check that the parameter table
|
|
updates, and inspect the generated files in your work directory.</p></li>
|
|
</ol>
|
|
</section>
|
|
<section id="existing-installations">
|
|
<h2>Existing installations<a class="headerlink" href="#existing-installations" title="Link to this heading"></a></h2>
|
|
<ol class="arabic">
|
|
<li><p>Preserve any MSR/data/result files currently stored inside the muSRFlow
|
|
installation folder: move them to a separate work folder before upgrading.</p></li>
|
|
<li><p>Close muSRFlow and install the refreshed Windows application.</p></li>
|
|
<li><p>If your runtime was imported from an older bundle, add the missing Boost
|
|
headers from PowerShell:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">wsl</span> <span class="n">-d</span> <span class="n">muSRFlow-runtime</span> <span class="p">--</span> <span class="n">dnf</span> <span class="n">-y</span> <span class="n">install</span> <span class="n">boost-devel</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>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.</p>
|
|
</li>
|
|
<li><p>Reopen muSRFlow, select your work directory in Preferences, and retry Plot
|
|
and Fit.</p></li>
|
|
</ol>
|
|
<p>Reinstalling the application preserves an existing <code class="docutils literal notranslate"><span class="pre">muSRFlow-runtime</span></code>
|
|
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 <strong>Install runtime…</strong> preference is not
|
|
used on Windows.</p>
|
|
</section>
|
|
<section id="troubleshooting">
|
|
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Link to this heading"></a></h2>
|
|
<section id="required-feature-is-not-installed">
|
|
<h3>Required feature is not installed<a class="headerlink" href="#required-feature-is-not-installed" title="Link to this heading"></a></h3>
|
|
<p>For <code class="docutils literal notranslate"><span class="pre">HCS_E_SERVICE_NOT_AVAILABLE</span></code> during runtime preparation, Windows
|
|
could not create the WSL virtual machine. In <strong>administrator PowerShell</strong>:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">dism</span><span class="p">.</span><span class="n">exe</span> <span class="p">/</span><span class="n">online</span> <span class="p">/</span><span class="nb">enable-feature</span> <span class="p">/</span><span class="n">featurename</span><span class="p">:</span><span class="n">VirtualMachinePlatform</span> <span class="p">/</span><span class="n">all</span> <span class="p">/</span><span class="n">norestart</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Restart Windows. Check <strong>Task Manager / Performance / CPU</strong> for
|
|
<strong>Virtualization: Enabled</strong>; if disabled, enable hardware virtualization in
|
|
BIOS/UEFI. If Windows itself is a virtual machine, its host must expose nested
|
|
virtualization. If the error persists, check the boot setting:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">bcdedit</span> <span class="p">/</span><span class="n">enum</span> <span class="p">|</span> <span class="n">findstr</span> <span class="n">-i</span> <span class="n">hypervisorlaunchtype</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Only if it reports <code class="docutils literal notranslate"><span class="pre">Off</span></code>, enable it and restart:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">bcdedit</span> <span class="p">/</span><span class="nb">set </span><span class="n">hypervisorlaunchtype</span> <span class="n">Auto</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>See <a class="reference external" href="https://learn.microsoft.com/en-us/windows/wsl/troubleshooting">Microsoft’s WSL troubleshooting guide</a>.</p>
|
|
</section>
|
|
<section id="cannot-find-wsl-exe">
|
|
<h3>Cannot find wsl.exe<a class="headerlink" href="#cannot-find-wsl-exe" title="Link to this heading"></a></h3>
|
|
<p>For <code class="docutils literal notranslate"><span class="pre">spawn</span> <span class="pre">wsl.exe</span> <span class="pre">ENOENT</span></code>, first check that <code class="docutils literal notranslate"><span class="pre">wsl</span> <span class="pre">--version</span></code> works in
|
|
PowerShell. If it does, install the refreshed muSRFlow build: early rc.5
|
|
builds incorrectly replaced the Windows executable search path. Also check
|
|
that the selected work directory exists and is writable.</p>
|
|
</section>
|
|
<section id="cannot-load-libcore-so">
|
|
<h3>Cannot load libCore.so<a class="headerlink" href="#cannot-load-libcore-so" title="Link to this heading"></a></h3>
|
|
<p>Install the refreshed muSRFlow build. It passes the ROOT library directory
|
|
inside WSL for every bundled command. Setting a Windows <code class="docutils literal notranslate"><span class="pre">ROOTSYS</span></code> or
|
|
<code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> is not a substitute for this launcher fix.</p>
|
|
</section>
|
|
<section id="missing-boost-version-hpp-or-plotting-crash">
|
|
<h3>Missing boost/version.hpp or plotting crash<a class="headerlink" href="#missing-boost-version-hpp-or-plotting-crash" title="Link to this heading"></a></h3>
|
|
<p>Follow <a class="reference internal" href="#existing-installations">Existing installations</a> to install <code class="docutils literal notranslate"><span class="pre">boost-devel</span></code> in an older
|
|
runtime. The corrected runtime includes it. If plotting still crashes,
|
|
include the full command output when reporting the problem.</p>
|
|
</section>
|
|
<section id="no-spectrum-window-appears">
|
|
<h3>No spectrum window appears<a class="headerlink" href="#no-spectrum-window-appears" title="Link to this heading"></a></h3>
|
|
<p>Confirm that <code class="docutils literal notranslate"><span class="pre">wsl</span> <span class="pre">--version</span></code> lists WSLg, update WSL, and inspect the
|
|
muSRFlow run log. Successful runtime import or a successful fit alone does
|
|
not verify interactive graphics support.</p>
|
|
</section>
|
|
<section id="reporting-a-problem">
|
|
<h3>Reporting a problem<a class="headerlink" href="#reporting-a-problem" title="Link to this heading"></a></h3>
|
|
<p>Include the muSRFlow version, full run log, and the output of:</p>
|
|
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="n">wsl</span> <span class="p">-</span><span class="n">-version</span>
|
|
<span class="n">wsl</span> <span class="p">-</span><span class="n">-status</span>
|
|
<span class="n">wsl</span> <span class="p">-</span><span class="n">-list</span> <span class="p">-</span><span class="n">-verbose</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The corrected runtime has completed a real fit and generated a PNG in a
|
|
Linux container. Interactive Windows/WSLg plotting still needs validation
|
|
on the target PC.</p>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
|
<a href="getting-started.html" class="btn btn-neutral float-left" title="Getting started" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
|
<a href="install-linux.html" class="btn btn-neutral float-right" title="Linux installation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
|
</div>
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>© Copyright 2026 Zaher Salman.</p>
|
|
</div>
|
|
|
|
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
|
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
|
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
|
|
</footer>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</div>
|
|
<script>
|
|
jQuery(function () {
|
|
SphinxRtdTheme.Navigation.enable(true);
|
|
});
|
|
</script>
|
|
|
|
</body>
|
|
</html> |