diff --git a/README.md b/README.md index 2ed5883..5742a84 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,65 @@ # muSRFlow -muSRFlow is a desktop and web workflow for creating, editing, fitting, -plotting, and inspecting musrfit MSR files. It wraps the `musrfit`, -`musrview`, `msr2data`, and `dump_header` command-line tools, and provides -interactive plotting of the fitted parameters across runs. +muSRFlow makes fitting muSR spectra easier: create and edit MSR models, fit +single runs or run series, inspect spectra, and plot fitted parameters. +It is available as a desktop application and a web application. + +Current release candidate: **1.0.0-rc.5**. + +## Installation + +**Start with the guide for your platform.** Packaged desktop applications do +not require Node.js or npm. + +| Platform | Instructions | ROOT and musrfit | +| --- | --- | --- | +| **Windows** | **[Install muSRFlow on Windows](docs/source/install-windows.rst)** | Included in the installer; WSL2 must be enabled first. | +| **Linux** | **[Install muSRFlow on Linux](docs/source/install-linux.rst)** | Use a local installation or install the separate runtime. | +| **Web** | Open your site's muSRFlow URL in a browser. | Runs on the server; no local installation. | + +**Already using Windows?** Read the [existing-installation update steps](docs/source/install-windows.rst#existing-installations). +Older runtimes need the Boost-header update as well as the refreshed application. +The Windows guide also covers WSL startup errors, `wsl.exe ENOENT`, and missing +`libCore.so`. Native macOS packages and Flatpak packages are not available yet. + +Before your first desktop fit, choose a **Work directory** and **Data directory** +in **File -> Preferences**. Keep your MSRs and results outside the application +installation folder. ## User Manual -The end-user manual is built with [Sphinx](https://www.sphinx-doc.org/) from -`docs/source` (reStructuredText). The built HTML and PDF live under -`docs/_build`. Rebuild it with: +- [Getting started](docs/source/getting-started.rst) +- [Manual contents and workflow chapters](docs/source/index.rst) +- [PDF manual](docs/_build/latex/muSRFlow.pdf) +- [HTML manual](docs/_build/html/index.html) (open locally in a browser) +- [Troubleshooting](docs/source/troubleshooting.rst) + +## Development and Packaging + +These instructions are for working on the source code or producing installers. +For installation on a user's computer, use the platform guides above. + +With Node.js and npm installed, run from the repository: ```bash -cd docs -make html # HTML in docs/_build/html -make latexpdf # PDF at docs/_build/latex/muSRFlow.pdf -``` - -## Desktop Development - -Install [Node.js](https://nodejs.org/) and npm, then run: - -```bash -npm install +npm ci npm start ``` -Dependencies only need to be installed once. Later sessions can be started with -`npm start`. +- [Build desktop packages and prepare releases](docs/DESKTOP_DEPLOYMENT.md) +- [Build the ROOT + musrfit runtime](packaging/runtime/README.md) +- [Windows WSL runtime packaging](packaging/wsl2/README.md) +- [Roadmap and remaining work](TODO.md) +- [Release notes](CHANGELOG.md) -## Desktop Packages - -The desktop app is at version `1.0.0-rc.5` (release candidate). Linux RPM -and AppImage release packages can be produced with: +The manual uses Sphinx. Rebuild its HTML and PDF with: ```bash -npm run dist:rpm -npm run dist:appimage +cd docs +make html +make latexpdf ``` -Each command also builds a matching standalone ROOT + musrfit runtime -(`musrflow-runtime` rpm / AppImage); use `npm run dist:runtime` to build only -the runtime artifacts. See [`docs/DESKTOP_DEPLOYMENT.md`](docs/DESKTOP_DEPLOYMENT.md) -for build, runtime, and release requirements. - -### Windows installation - -The Windows x64 installer includes ROOT and musrfit in a WSL2 runtime. -Install WSL first, then run `muSRFlow--x64.exe`; muSRFlow prepares -its bundled runtime automatically on first launch. Node.js, npm, and a separate -musrfit installation are not needed on the target PC. - -Follow the [step-by-step Windows installation guide](docs/DESKTOP_DEPLOYMENT.md#installing-on-windows) -for WSL setup, folder preferences, and the first Plot/Fit check. Windows -packaging instructions are in [packaging/wsl2/README.md](packaging/wsl2/README.md). - -The remaining work before 1.0 and the prioritized improvements are tracked in -[`TODO.md`](TODO.md). Per-release notes are in -[`CHANGELOG.md`](CHANGELOG.md). - ## Web Deployment The browser application consists of `index.html`, `quick-start.html`, `ZGUI.css`, diff --git a/TODO.md b/TODO.md index 44695d9..76c336f 100644 --- a/TODO.md +++ b/TODO.md @@ -1,10 +1,11 @@ # muSRFlow Roadmap and TODO -Last reviewed: 2026-09-23. Current version: `1.0.0-rc.5`. +Current version: `1.0.0-rc.5`. Roadmap reviewed: 2026-09-23; documentation +and obsolete checklist references cleaned up: 2026-10-28. -The `1.0` target is a stable set of documented workflows, not complete parity -with every historical CGI option. Work is grouped below by release gate and by -the larger workflow features needed for routine analysis. +The `1.0` target is a stable set of documented, regression-tested workflows. +Work is grouped below by release gate and by the larger workflow features +needed for routine analysis. Historical delivery details are in `CHANGELOG.md`. ## 1. Version 1.0 release path @@ -62,8 +63,6 @@ history, manual run files, compound `ADDRUN`, and multiple fit ranges. unexpectedly by the `musrfit -t` behavior. (`runMSRFileLocal` omits `-t` when the MSR carries an explicit title; `tests/electron-msr-title.test.js` covers the regression.) -- [x] Audit `CGI_PARITY_CHECKLIST.md` against the current implementation and - remove stale gap descriptions. - [x] Implement the first scan-detection and built-in plot-template tasks from section 2. @@ -140,31 +139,19 @@ Deferred past `1.0` (explicitly documented as out of scope): - opt-in web usage collection (config + outcomes as JSONL) to build a corpus for training fitting models — design in `docs/WEB_USAGE_COLLECTION.md`, not yet implemented. -- Low priority: reorder the parameter catalogue so physical parameters (`Asy`, - `Frq`, `Lam`, `Sgm`/`Sig`, ...) precede phase (`Phi`) and detector counts - (`No`/`NBg`) in the dropdown and thus in generated FITPARAMETER blocks. - Preferred approach: a global parameter-priority list applied inside - `cfgConstraints()` when building `funSel`, leaving each `theoryBlk` signature - text untouched. (Reordering the names inside `theoryBlk` would also work but - changes emitted THEORY text; `No`/`NBg` already sort last because they are - appended only in SingleHist mode.) -The legacy CGI parity audit (formerly `CGI_PARITY_CHECKLIST.md`) is closed: the -shared Electron/web codebase deliberately replaces the static CGI rather than -mirroring it, and its intentional differences are documented under -"Intentional Differences". Only the following optional legacy-CGI conveniences -remain for evaluation after `1.0` (none block a supported workflow today): -- header/log metadata extraction (`TITLE`/temperature/field/energy used as GUI - defaults or result context, beyond the `_par.dat` scan metadata already used - by the parameter plot); -- legacy plotted-data ASCII/`gzip` spectrum dump alongside the ROOT/JSROOT - plots; -- the `LEM (PPC)`/`ROOT-PPC` legacy filename format; -- the asymmetric positive-MINOS error field in the parameter table; -- fixed Y PLOT limits as an editor-synchronized display option; -- a full musrfit command/output viewer (floating console on the web, native - child window in Electron); -- a durable job manifest with retry/reopen for reproducibility. +#### Optional workflow enhancements after 1.0 + +These are product improvements to evaluate, not gaps against the old CGI. +Header-based initial guesses, scan metadata, and the modeless Run log already +exist; extend them only where a concrete analysis workflow needs more. + +- [ ] Export plotted spectra as ASCII, optionally compressed, alongside the + existing ROOT/JSROOT plots. +- [ ] Evaluate support for archived LEM PPC/ROOT-PPC data if users need it. +- [ ] Expose asymmetric positive MINOS errors in the parameter table. +- [ ] Synchronize fixed Y plot limits between the editor and GUI. +- [ ] Add a durable job manifest with retry/reopen for reproducibility. ### `1.0.0-rc.1`: hardening @@ -472,8 +459,9 @@ plot, editor, synchronization, and result-collection behavior. (delivered across `beta.3`/`beta.4`). 2. The `1.0.0-rc.1` hardening gates are complete (preload bridge, CGI hardening, package and clean-web-deploy validation). -3. Focus the remaining pre-`1.0` work on `beta.5` workflow completeness and then - `1.0.0-rc.2` user validation. +3. Validate the current release candidate with real analyses on Electron and + the web, including clean installation and upgrade checks on Linux and + Windows/WSLg. Resolve workflow regressions before the stable release. 4. The model-expression tree is deferred past 1.0 (see `beta.4`); the current flat-component generation and the synchronization layer are the supported `1.0` model and are protected by fixtures. diff --git a/docs/DESKTOP_DEPLOYMENT.md b/docs/DESKTOP_DEPLOYMENT.md index 1ca6ea0..30780e8 100644 --- a/docs/DESKTOP_DEPLOYMENT.md +++ b/docs/DESKTOP_DEPLOYMENT.md @@ -1,220 +1,106 @@ -# muSRFlow desktop deployment +# Desktop Packaging and Releases -The first public beta is version `0.9.0-beta.1`. +This guide is for maintainers building installers and preparing releases. +**Installing muSRFlow on a user's computer? Start here:** -## Recommended Linux packages +- [Windows installation, updates, and troubleshooting](source/install-windows.rst) +- [Linux installation and runtime selection](source/install-linux.rst) -For PSI/Linux desktops, build an **RPM** first. muSRFlow intentionally launches -host-installed `musrfit`, `musrview`, `msr2data`, and `dump_header`, and it must -read normal experiment-data mounts and user-selected work directories. An RPM -therefore matches the application model better than a sandboxed Flatpak. - -An **AppImage** target is provided as a fallback for systems where RPM package -requirements differ between distributions. Flatpak can be revisited later if -we decide how host musrfit executables and data mounts should cross the sandbox. +Application version comes from `package.json`; the current release candidate +is `1.0.0-rc.5`. Target PCs do not need the developer tools described below. ## Build host -A release build requires Node.js/npm and network access the first time -`electron-builder` is downloaded. Application dependencies should be installed -from the lock file first: +Install Node.js/npm and the dependencies from the lock file: ```bash npm ci ``` -Run the Electron-side tests and build an x86_64 RPM: +Package builds run the Electron tests. The first build needs network access +for Electron and electron-builder downloads. Runtime source builds need Docker +or Podman; see the [runtime build guide](../packaging/runtime/README.md). + +## Linux packages ```bash -npm run dist:rpm +npm run dist:rpm # application RPM and runtime artifacts +npm run dist:appimage # application AppImage and runtime artifacts +npm run dist:linux # both application formats and runtime artifacts ``` -Build the portable AppImage instead: +Each command packages the lean application and the matching separate runtime +artifact(s), plus the runtime download bundle. Build the scientific runtime +first with `packaging/runtime/build.sh` if `runtime/` is not ready. -```bash -npm run dist:appimage -``` +| Artifact | Filename or directory | +| --- | --- | +| Application RPM | `dist/musrflow--x86_64.rpm` | +| Application AppImage | `dist/muSRFlow--x86_64.AppImage` | +| Runtime RPM | `dist/musrflow-runtime--x86_64.rpm` | +| Runtime AppImage | `dist/musrflow-runtime--x86_64.AppImage` | +| Offline runtime bundle | `dist/runtime-downloads/`, with `runtime-download.json`, archive, and checksum | -Or build both: - -```bash -npm run dist:linux -``` - -Artifacts are written to `dist/` and include the package version in their file -name. Each of these commands also builds the matching standalone runtime -artifact (`musrflow-runtime--x86_64.rpm` and/or -`muSRFlow-runtime--x86_64.AppImage`) plus a checksummed download bundle -under `dist/runtime-downloads/`. `npm run dist:runtime` builds only the runtime -artifacts. `npm run dist:runtime:archive` builds just the plain download archive -and its JSON descriptor without needing the RPM/AppImage packaging tools. - -## Target PC requirements - -The packaged Electron application includes Electron and its JavaScript -runtime; target PCs do **not** need Node.js or npm. - -The musrfit toolchain is not bundled in the Linux app package. The target PC -can either provide it system-wide: - -```text -musrfit -musrview -msr2data -dump_header -``` - -or install the standalone runtime that muSRFlow ships: the `musrflow-runtime` -rpm, or the portable `muSRFlow-runtime` AppImage run with `--install`. Both -place ROOT and musrfit in `/opt/musrflow/runtime`. muSRFlow looks in the -configured **musrfit binaries** directory, a bundled runtime, -`/opt/musrflow/runtime`, `/usr/local/bin`, and `/usr/bin`. The user -must also have access to the experiment data tree configured under -**File -> Preferences -> Data directory** and write access to the configured -**Work directory**. - -After installing on a new PC, the minimum smoke test is: - -1. Start muSRFlow and check **Help -> About muSRFlow** for the expected version. -2. Set Data and Work directories under **File -> Preferences**. -3. Open one known run and confirm header-based frequency initialization. -4. Run Plot, then Fit, and verify that `musrview`/`musrfit` start successfully. -5. Open a parameter plot and refresh it after another fit. - -## Installing an RPM - -Use the native package manager where possible, for example: - -```bash -sudo dnf install ./dist/muSRFlow-1.0.0-rc.1-x86_64.rpm -``` - -On RPM distributions with different package naming conventions, use the -AppImage if the RPM dependency resolver rejects otherwise available Electron -libraries. - -## Running the AppImage - -```bash -chmod +x dist/muSRFlow-1.0.0-rc.1-x86_64.AppImage -./dist/muSRFlow-1.0.0-rc.1-x86_64.AppImage -``` - -## Installing the standalone runtime - -On a machine without a system musrfit, install the ROOT + musrfit runtime that -muSRFlow ships. Either install the rpm: - -```bash -sudo dnf install ./dist/musrflow-runtime-1.0.0-rc.1-x86_64.rpm -``` - -or run the portable runtime AppImage, which copies the same tree into -`/opt/musrflow/runtime`: - -```bash -chmod +x dist/muSRFlow-runtime-1.0.0-rc.1-x86_64.AppImage -./dist/muSRFlow-runtime-1.0.0-rc.1-x86_64.AppImage --install -``` - -Pass an optional directory to `--install` for a user-local prefix, and set -`MUSRFLOW_RUNTIME_ROOT` to point muSRFlow at it. Without a runtime the app falls -back to the host `musrfit` installation as before. - -The plain runtime download can also be checked with its SHA-256 sidecar and -extracted into a fresh user-writable directory, without administrator access or -FUSE. Set `MUSRFLOW_RUNTIME_ROOT` to the extracted `runtime/` directory. See the -[runtime packaging guide](../packaging/runtime/README.md#download-archive) for -the archive layout and descriptor format. On Linux, **File -> Preferences -> -Install runtime...** installs a downloaded bundle after confirmation and selects -its verified tools. **Check tools** tests the saved tool selection. In-app online -downloads and missing-tool startup prompts will follow separately; no runtime -is downloaded automatically. - -## Installing on Windows - -The Windows package is for **64-bit Intel/AMD PCs**. Windows 11 is recommended; -Windows 10 needs build 19044 or newer for WSLg, which displays the `musrview` -plot windows. See [Microsoft's WSL GUI requirements](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps). - -The installer includes ROOT and musrfit inside a private WSL2 distribution. -You do not need Node.js, npm, Ubuntu, or a separate musrfit installation. - -1. **Install WSL.** Open PowerShell as Administrator and run: - - ```powershell - wsl --install --no-distribution - ``` - - Restart Windows afterwards. If WSL is already installed, skip this step. - `--no-distribution` leaves the Linux distribution installation to muSRFlow. - -2. **Update and check WSL.** In administrator PowerShell, run: - - ```powershell - wsl --update - wsl --version - ``` - - Follow any restart instructions. The version output should include WSL - and WSLg. Microsoft's [WSL command reference](https://learn.microsoft.com/en-us/windows/wsl/basic-commands) - describes these commands. - -3. **Install muSRFlow.** Copy `muSRFlow--x64.exe` from the release - artifacts to the Windows PC and double-click it. For the current release - candidate, the build output is `dist/muSRFlow-1.0.0-rc.5-x64.exe`. - The runtime archive `muSRFlow-runtime-rootfs.tar.gz` is included in the - installer; you do not need to extract or import it manually. - -4. **Launch muSRFlow** from the Start menu using your normal Windows account. - The first launch imports the runtime as `muSRFlow-runtime`. Preparation - can take several minutes; Fit and Plot wait for it to finish. After setup, - check in PowerShell: - - ```powershell - wsl --list --verbose - ``` - - The list should contain `muSRFlow-runtime` with **VERSION 2**. Either - `Running` or `Stopped` is normal when idle. The imported runtime is stored - under `%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime` for this Windows account. - -5. **Configure your folders.** Create writable folders, for example - `C:\Users\\muSRFlow\work` and - `C:\Users\\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. Use normal - Windows paths in Preferences; muSRFlow translates them for WSL. - -6. **Test Plot and Fit.** Select a known instrument, year, and run, then click - **Plot**. If the data are missing locally, muSRFlow offers to download them - from `musruser.psi.ch` when the server is reachable. Confirm that the - spectrum window opens, then run **Fit** and check that the parameter table - updates. Results are written to the selected Windows work directory. - -If runtime preparation fails, check that WSL is installed and updated, restart -muSRFlow, and retry the action. If the runtime is ready but no spectrum window -opens, check WSLg using `wsl --version` and inspect the application command log. -The [WSL runtime guide](../packaging/wsl2/README.md) describes manual import for -debugging. The Linux **Install runtime...** preference is not used on Windows. - -The setup flow is covered by automated tests with simulated WSL commands; -installation and graphical plotting still need validation on a Windows PC. +`npm run dist:runtime` builds only runtime artifacts. +`npm run dist:runtime:archive` builds just the plain runtime download bundle +without the RPM/AppImage packaging tools. The AppImage runtime builder needs +the electron-builder AppImage cache; see the runtime guide for prerequisites. ## Building the Windows installer -On the build host, install application dependencies with `npm ci`, prepare -the Linux `runtime/` tree, then build its WSL root filesystem and the installer: +Prepare the validated Linux `runtime/` tree, then run: ```bash bash packaging/wsl2/build-wsl2.sh npm run dist:win ``` -The rootfs builder requires Docker or Podman. `dist:win` packages the existing -`packaging/wsl2/out/muSRFlow-runtime-rootfs.tar.gz`; it does not rebuild that -archive. Output is `dist/muSRFlow--x64.exe`. See the -[WSL packaging guide](../packaging/wsl2/README.md#packaging) for details. +The rootfs builder uses Docker or Podman and includes the distribution libraries +and Boost headers needed for plotting. It checks executable startup and ROOT +plotting-header loading before exporting +`packaging/wsl2/out/muSRFlow-runtime-rootfs.tar.gz`. + +`dist:win` packages the existing archive; it does not rebuild it. The result is +`dist/muSRFlow--x64.exe`, including both the app and the WSL2 runtime. +See [WSL packaging](../packaging/wsl2/README.md) for implementation details. + +**Existing Windows installations keep their imported runtime.** Link users to +[the Windows update instructions](source/install-windows.rst#existing-installations) +when distributing a runtime-related fix; reinstalling the app alone does not +update that distribution. + +## Release validation + +1. Run `npm test` with the required scientific tools available. Record any + environment-dependent checks that could not be exercised. +2. Install each package on its target OS. Check the version in **Help -> About**. +3. Follow the platform installation guide, including runtime setup and separate + work/data directories. +4. Exercise Plot, Fit, FFT, series/global fitting, parameter plotting, and MSR + editing with known data. Confirm parameter feedback and result files. +5. Test upgrades of existing installations as well as a fresh installation. + Windows testing must include an interactive WSLg spectrum window. + +Linux-container tests have exercised the Windows runtime's tools, a real fit, +and PNG generation. Those tests do not replace interactive Windows testing. + +## Installation links retained for older references + +### Installing on Windows + +The complete user guide is now [Windows installation](source/install-windows.rst). + +### Installing an RPM + +See [Linux application installation](source/install-linux.rst#install-the-application). + +### Running the AppImage + +See [Linux application installation](source/install-linux.rst#install-the-application). + +### Installing the standalone runtime + +See [Linux runtime setup](source/install-linux.rst#set-up-root-and-musrfit). ## Configuration link scheme @@ -248,23 +134,18 @@ run controls, running the plot when `action=plot` is present. Electron reports it through `app.getVersion()` and the About dialog. `package-lock.json` should carry the same version. -For the next release candidate or final release, keep `package.json`, -`package-lock.json`, `tests/release-packaging.test.js`, and `CHANGELOG.md` in -step. For example: +For a version change, update `package.json`, `package-lock.json`, +`tests/release-packaging.test.js`, and `CHANGELOG.md` together. Run the tests, +rebuild the manuals and installers, and commit before tagging the release. +Check the remaining release gates in [TODO.md](../TODO.md) before tagging 1.0. -```bash -npm version 1.0.0-rc.1 --no-git-tag-version -npm test -git commit -am "Prepare muSRFlow 1.0.0-rc.1" -git tag v1.0.0-rc.1 -``` - -For `1.0.0`, update the version only after the release candidate has been -exercised on the actual target Linux installations. +`npm run checksums` produces MD5/SHA-256 sidecars for top-level RPM and AppImage +artifacts. It does not cover Windows installers. For a Windows release, generate +and publish a SHA-256 checksum for the actual installer as well. Runtime download +bundles include their own SHA-256 sidecar and descriptor. ## Application icon -The repository currently does not contain a packaged application icon. The -RPM/AppImage can be built and tested without one, but a final muSRFlow icon -should be added before the 1.0 release and referenced from the electron-builder -Linux configuration. +Linux packages use `assets/musrflow-icon.png` through the electron-builder +configuration in `package.json`. Windows packaging currently uses the default +Electron icon; a Windows-specific icon remains a packaging improvement. diff --git a/docs/_build/html/_sources/getting-started.rst.txt b/docs/_build/html/_sources/getting-started.rst.txt index 2ed5526..7265b3c 100644 --- a/docs/_build/html/_sources/getting-started.rst.txt +++ b/docs/_build/html/_sources/getting-started.rst.txt @@ -1,138 +1,65 @@ Getting started =============== -Prerequisites -------------- +Choose your edition +------------------- -muSRFlow wraps external ``musrfit`` tools. How they are supplied depends on -the edition: +* **Windows desktop:** follow :doc:`install-windows`. ROOT and musrfit are + included in a WSL2 runtime. The guide covers first installation, existing + runtime updates, and Windows-specific errors. +* **Linux desktop:** follow :doc:`install-linux`. Use an existing musrfit + installation or install the separate runtime through Preferences. +* **Web:** open your site's muSRFlow URL, for example + ``http://musruser.psi.ch/muSRFlow/``. The server runs the tools; there is + nothing to install on your computer. -* Linux desktop: use a local musrfit installation or install the separate - ROOT + musrfit runtime. Select the tools through **File / Preferences**. -* Windows desktop: the installer includes ROOT and musrfit in a WSL2 runtime. - Install WSL first, following :ref:`windows-installation` below. -* Web: the tools are installed on the server that hosts the CGI runner. - -Packaged desktop applications do not require Node.js or npm on the target -PC. The browser edition needs no local installation at all. +Packaged desktop applications do not require Node.js or npm. .. _desktop-installation: -Development and Linux packages ------------------------------- +Desktop installation +-------------------- -From a checkout, with `Node.js `_ and npm installed: +The complete instructions are in :doc:`install-windows` and +:doc:`install-linux`. Choose work and data folders in **File / Preferences** +before your first analysis. Keep work files outside the application +installation directory. -.. code-block:: console - - $ npm install - $ npm start - -`npm install` is only needed once; later sessions start with `npm start`. - -Release packages (Linux RPM and AppImage) are produced with: - -.. code-block:: console - - $ npm run dist:rpm - $ npm run dist:appimage - -Each command also builds the matching standalone ROOT + musrfit runtime -artifact (``musrflow-runtime`` rpm / AppImage); ``npm run dist:runtime`` builds -only the runtime. The build and runtime requirements are described in -``docs/DESKTOP_DEPLOYMENT.md``. - -.. _windows-installation: +.. _getting-started-windows-installation: Windows installation -------------------- -Use a 64-bit Intel/AMD Windows PC. Windows 11 is recommended; Windows 10 -requires build 19044 or newer for WSLg, which displays the ``musrview`` -windows. See `Microsoft's WSL GUI requirements -`_. - -1. Open **PowerShell as Administrator** and install WSL: - - .. code-block:: powershell - - wsl --install --no-distribution - - Restart Windows afterwards. Skip this step if WSL is already installed. - You do not need Ubuntu: muSRFlow supplies its own distribution. - -2. Update WSL and check its components in administrator PowerShell: - - .. code-block:: powershell - - wsl --update - wsl --version - - Follow any restart instructions. The output should include WSL and WSLg. - See the `Microsoft WSL command reference - `_. - -3. Copy the release installer ``muSRFlow--x64.exe`` to Windows and - double-click it. It includes ``muSRFlow-runtime-rootfs.tar.gz``; there is - no separate ROOT or musrfit installation or manual archive import. - -4. Launch muSRFlow from the Start menu using your normal Windows account. - The first launch prepares the runtime, which can take several minutes. - Fit and Plot wait until preparation finishes. Afterwards, verify: - - .. code-block:: powershell - - wsl --list --verbose - - The list should contain ``muSRFlow-runtime`` with **VERSION 2**. - ``Running`` and ``Stopped`` are both normal when idle. - -5. Create writable work and data folders, for example - ``C:\Users\\muSRFlow\work`` and - ``C:\Users\\muSRFlow\data``. Choose them in - **File / Preferences**. Leave **musrfit binaries** and - **musrfit startup XML** on automatic detection, then save. - Enter Windows paths; muSRFlow translates them for WSL. - -6. Select a known instrument, year, and run, then press **Plot**. If data - are missing, muSRFlow offers to download them from ``musruser.psi.ch`` - when the server is reachable. Confirm the spectrum window opens, then - try **Fit** and check that the parameter table updates. Results stay in - your Windows work directory. - -If setup fails, check WSL, restart muSRFlow, and retry. If plotting fails -after setup, check that ``wsl --version`` includes WSLg and inspect the -command log. The Linux **Install runtime...** preference does not apply to -Windows. Installation and graphical plotting still need validation on a -Windows PC; automated setup tests use simulated WSL commands. +The Windows instructions have their own chapter: :doc:`install-windows`. +It also contains the update steps for older WSL runtimes. Running the desktop app ----------------------- -When the window opens, the **Runs** tab is active and the current year is -already selected. Enter run numbers, choose a model, and press **Fit**. The -first fit writes the working files next to your MSR document and results -appear in the **Results** tab. +When the window opens, the **Runs** tab is active. Choose the instrument, +year, and run numbers, check the model, and press **Plot** to inspect the +spectrum. Press **Fit** to fit it and refresh the parameter table. Generated +files go to the selected work directory; the **Results** tab and run log +show the outcome. Opening the web edition ----------------------- -Point your browser at the deployment URL (e.g. -``http://musruser.psi.ch/muSRFlow/``). Instrument options and run numbers are -the ones the server data tree supports. There is nothing to install; the -parameter table is also served from the same data tree. +Open the deployment URL in your browser. Instrument options and available +run data depend on that site's server configuration. Fit and Plot run on +the server; output files can be opened from the result links. The Quick Start guide --------------------- The ``?`` button at the right of the tab bar opens a short, tab-aware guide. On the desktop it opens in an independent window; in the browser it opens a -modeless dialog next to the main window. Each of its sections corresponds to -one tab and is expanded into a chapter of this manual. +modeless dialog next to the main window. The full workflow chapters follow +the installation guides in this manual. Support ------- -For questions and bug reports contact Zaher Salman -``_. Issue tracking is linked from the project -repository. \ No newline at end of file +For questions and bug reports, include the version and run log and contact +`Zaher Salman `_. See :doc:`troubleshooting` +for common workflow problems. diff --git a/docs/_build/html/_sources/index.rst.txt b/docs/_build/html/_sources/index.rst.txt index 41463d2..3e79b4c 100644 --- a/docs/_build/html/_sources/index.rst.txt +++ b/docs/_build/html/_sources/index.rst.txt @@ -7,6 +7,9 @@ application and as a browser application, and both editions wrap the same set of command-line tools (``musrfit``, ``musrview``, ``msr2data``, and ``dump_header``). +Start with :doc:`install-windows` or :doc:`install-linux` for desktop setup. +For the browser edition, see :doc:`getting-started`. + These pages describe the end-user workflow. They are organised around the main window tabs, mirroring the Quick Start help that is built into the application (the ``?`` button). @@ -17,6 +20,8 @@ application (the ``?`` button). overview getting-started + install-windows + install-linux runs-fitting parameters-plots constraints @@ -33,6 +38,6 @@ application (the ``?`` button). If anything in this manual does not match the behaviour you see, contact `Zaher Salman `_. -Separate repository documents cover desk build and packaging +Separate repository documents cover desktop builds and packaging (``docs/DESKTOP_DEPLOYMENT.md``) and the web-server/CGI deployment (``cgi/README.md``); this manual concentrates on using the application. \ No newline at end of file diff --git a/docs/_build/html/_sources/install-linux.rst.txt b/docs/_build/html/_sources/install-linux.rst.txt new file mode 100644 index 0000000..bbb6ffe --- /dev/null +++ b/docs/_build/html/_sources/install-linux.rst.txt @@ -0,0 +1,135 @@ +.. _linux-installation: + +Linux installation +================== + +Install the muSRFlow application, then select a working ROOT + musrfit +installation. **The Linux application package does not include the scientific +runtime.** You can use an existing installation or install the separate +runtime through Preferences. Node.js and npm are not needed on the target PC. + +The current application packages are for x86_64 Linux. Examples below use +``1.0.0-rc.5``; substitute the version of the package you obtained. Run the +commands from the folder containing the downloaded files. + +Install the application +----------------------- + +Choose one application format. + +RPM +~~~ + +On an RPM-based distribution with dnf: + +.. code-block:: bash + + sudo dnf install ./musrflow-1.0.0-rc.5-x86_64.rpm + musrflow + +On other RPM systems, use the distribution's package manager. The application +RPM filename starts with lowercase ``musrflow``. + +AppImage +~~~~~~~~ + +.. code-block:: bash + + chmod +x muSRFlow-1.0.0-rc.5-x86_64.AppImage + ./muSRFlow-1.0.0-rc.5-x86_64.AppImage + +The application AppImage filename starts with ``muSRFlow``. It requires a +compatible Linux desktop and AppImage/FUSE support. If it cannot start, +check the terminal output or use the RPM on a supported RPM distribution. + +Set up ROOT and musrfit +----------------------- + +Use an existing installation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open **File / Preferences**. Leave **musrfit binaries** on automatic detection +for a standard installation, or choose the directory containing ``musrfit``, +``musrview``, ``msr2data``, ``musrt0``, and ``dump_header``. Save your settings, +then use **Check tools** to verify the saved selection. + +Install the separate runtime from a local bundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Obtain the runtime bundle for your architecture. Keep + ``runtime-download.json`` and its matching ``musrflow-runtime-*.tar.gz`` + archive in the same folder. You do not need to unpack it. +2. Open **File / Preferences / Install runtime...** and select + ``runtime-download.json``. +3. Review the versions and destination, then select **Install and use**. + muSRFlow validates the archive, installs it in your personal application + data directory, and selects its tools. +4. Use **Check tools** to confirm the selected runtime starts. + +This installation does not require administrator access. Runtime downloads +are not automatic: obtain the bundle separately before opening the installer. +A compatible Linux system and desktop/display services are still required. + +Alternative: system runtime RPM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + sudo dnf install ./musrflow-runtime-1.0.0-rc.5-x86_64.rpm + +This installs the runtime into ``/opt/musrflow/runtime``, which muSRFlow +recognizes automatically when no explicit tool directory takes precedence. + +Alternative: runtime AppImage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a user-writable runtime location: + +.. code-block:: bash + + chmod +x musrflow-runtime-1.0.0-rc.5-x86_64.AppImage + ./musrflow-runtime-1.0.0-rc.5-x86_64.AppImage --install "$HOME/.local/share/musrflow/runtime" + +Launch the application with the installed runtime selected: + +.. code-block:: bash + + MUSRFLOW_RUNTIME_ROOT="$HOME/.local/share/musrflow/runtime" musrflow + +For the application AppImage, replace ``musrflow`` in that command with its +path. Leave **musrfit binaries** on automatic detection so the selected +runtime is used. Without a custom destination, the runtime AppImage installs +to ``/opt/musrflow/runtime`` and needs permission to write there. Its filename +is lowercase ``musrflow-runtime``, unlike the application AppImage. + +Choose folders and test +----------------------- + +1. In **File / Preferences**, choose a writable **Work directory** outside + the application installation folder, for example ``~/muSRFlow/work``. + Use **Browse...** to select it. +2. Set **Data directory** to the root of your instrument data tree, or to a + writable folder such as ``~/muSRFlow/data`` for downloaded runs. +3. Leave **musrfit startup XML** on automatic detection unless you have a + specific installation configuration, then save. +4. Select a known instrument, year, and run. Click **Plot**, then **Fit**. + Confirm the spectrum opens, fitted parameters update, and output files + appear in your work directory. Missing runs can be downloaded from + ``musruser.psi.ch`` after confirmation when the server is reachable. + +Updating and troubleshooting +---------------------------- + +* Upgrade the application RPM with your package manager, or replace the + application AppImage. The separate runtime is not updated by an app upgrade. +* Preserve work files outside the application/runtime installation directories. +* For missing tools or shared libraries, run **Check tools** and inspect the + reported executable paths. A configured binaries directory overrides + automatic detection; clear an obsolete selection or choose the correct one. +* If fitting works but no spectrum window opens, inspect the run log and + confirm your desktop session can display native musrview windows. +* If data are missing, check the instrument, year, run number, and data root. + Downloaded files use the selected writable data root or the personal + fallback folder reported in Preferences. + +Include the application version and run log when reporting a problem. diff --git a/docs/_build/html/_sources/install-windows.rst.txt b/docs/_build/html/_sources/install-windows.rst.txt new file mode 100644 index 0000000..5b19c3d --- /dev/null +++ b/docs/_build/html/_sources/install-windows.rst.txt @@ -0,0 +1,193 @@ +.. _windows-installation: + +Windows installation +==================== + +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. +* Obtain the Windows installer, named ``muSRFlow--x64.exe``. The + current release candidate is ``1.0.0-rc.5``. + +**Use the refreshed Windows build.** Earlier rc.5 installers have the same +filename but lack the WSL fixes. Obtain a build containing commit ``a6981c4`` +or later. In the development workspace, the verified replacement is +``dist/windows-runtime-fix/muSRFlow-1.0.0-rc.5-x64.exe``; this is a local build +output, not a public download address. + +See `Microsoft's WSL GUI requirements +`_ 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 + `_. + +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\\muSRFlow\work + C:\Users\\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. + +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. + +Troubleshooting +--------------- + +Required feature is not installed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For ``HCS_E_SERVICE_NOT_AVAILABLE`` during runtime preparation, Windows +could not create the WSL virtual machine. In **administrator PowerShell**: + +.. code-block:: powershell + + dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart + +Restart Windows. Check **Task Manager / Performance / CPU** for +**Virtualization: Enabled**; 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: + +.. code-block:: powershell + + bcdedit /enum | findstr -i hypervisorlaunchtype + +Only if it reports ``Off``, enable it and restart: + +.. code-block:: powershell + + bcdedit /set hypervisorlaunchtype Auto + +See `Microsoft's WSL troubleshooting guide +`_. + +Cannot find wsl.exe +~~~~~~~~~~~~~~~~~~~ + +For ``spawn wsl.exe ENOENT``, first check that ``wsl --version`` 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. + +Cannot load libCore.so +~~~~~~~~~~~~~~~~~~~~~~ + +Install the refreshed muSRFlow build. It passes the ROOT library directory +inside WSL for every bundled command. Setting a Windows ``ROOTSYS`` or +``LD_LIBRARY_PATH`` is not a substitute for this launcher fix. + +Missing boost/version.hpp or plotting crash +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow `Existing installations`_ to install ``boost-devel`` in an older +runtime. The corrected runtime includes it. If plotting still crashes, +include the full command output when reporting the problem. + +No spectrum window appears +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Confirm that ``wsl --version`` lists WSLg, update WSL, and inspect the +muSRFlow run log. Successful runtime import or a successful fit alone does +not verify interactive graphics support. + +Reporting a problem +~~~~~~~~~~~~~~~~~~~ + +Include the muSRFlow version, full run log, and the output of: + +.. code-block:: powershell + + wsl --version + wsl --status + wsl --list --verbose + +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. diff --git a/docs/_build/html/_sources/platforms.rst.txt b/docs/_build/html/_sources/platforms.rst.txt index 13f80df..ad051d3 100644 --- a/docs/_build/html/_sources/platforms.rst.txt +++ b/docs/_build/html/_sources/platforms.rst.txt @@ -38,28 +38,17 @@ the command-line tools live. Bundled ROOT and musrfit ------------------------ -Packaged desktop builds can use a self-contained ROOT + musrfit runtime, so a -separate musrfit installation is not required on the machine. The runtime may -be bundled inside the application or, on Linux, installed separately (the -``musrflow-runtime`` rpm or the portable ``muSRFlow-runtime`` AppImage, both -defaulting to ``/opt/musrflow/runtime``). When a runtime is found muSRFlow runs -those tools with ``ROOTSYS``, ``MUSRFITPATH``, and ``LD_LIBRARY_PATH`` pointed -at it; a directory set in **Preferences / musrfit binaries** still takes -precedence, and on builds without a runtime the system installation is used -exactly as before. The runtime is built with ``packaging/runtime/build.sh`` and -packaged with ``packaging/runtime/build-runtime-rpm.sh`` / -``build-runtime-appimage.sh`` (see ``packaging/runtime/README.md``). +On Linux, the application and scientific runtime are separate. Use an +existing ROOT + musrfit installation, install an offline runtime bundle in +Preferences, or install the system runtime RPM/AppImage. An explicitly +selected binaries directory takes precedence over automatic detection. +See :doc:`install-linux` for installation and tool checks. -On Windows the bundled runtime runs inside a WSL2 distribution that muSRFlow -ships: the tools are invoked through ``wsl.exe`` and file paths are translated -between the Windows and WSL forms, so inputs and outputs stay on the Windows -side. The rootfs is built with ``packaging/wsl2/build-wsl2.sh`` and imported -once per user (see ``packaging/wsl2/README.md``). - -Follow :ref:`windows-installation` for the WSL setup, Windows installer, -folder preferences, and first Plot/Fit check. The Windows installer includes -``muSRFlow-runtime-rootfs.tar.gz`` and imports it automatically; the separate -Linux runtime archive and **Install runtime...** preference do not apply. +On Windows, the application installer includes the runtime. It runs inside +a WSL2 distribution named ``muSRFlow-runtime``. Tools are invoked through +``wsl.exe``, with paths translated so inputs and outputs stay on the Windows +side. The separate Linux runtime installer does not apply to Windows. +See :doc:`install-windows` for WSL setup, installation, updates, and fixes. The workflow chapters of this manual apply to both editions. Where a step is specific to one edition (handling files, Preferences), the text says so diff --git a/docs/_build/html/_sources/preferences.rst.txt b/docs/_build/html/_sources/preferences.rst.txt index e74055a..ef7fdfd 100644 --- a/docs/_build/html/_sources/preferences.rst.txt +++ b/docs/_build/html/_sources/preferences.rst.txt @@ -7,7 +7,9 @@ configuration and never exposes this dialog. Work directory Where generated files, MSR documents, and result artifacts are written. - Defaults to the current directory (``.``). + Defaults to the current directory (``.``), which can be the application + installation folder. Choose a separate writable work folder before fitting + so application upgrades do not affect your results. Data directory The root of the instrument data tree (for example @@ -44,6 +46,12 @@ musrfit binaries sessions, while the web edition takes its tools from the server and never exposes this field. +Runtime installation and checks (Linux) + **Check tools** checks the saved tool selection. **Install runtime...** + installs a local runtime bundle after confirmation and selects its tools. + See :doc:`install-linux` for the required files and installation steps. + Windows uses its bundled WSL runtime instead; see :doc:`install-windows`. + musrfit threads The number of OpenMP threads passed to a local ``musrfit`` run (``-u``). Leave it blank to let musrfit use every available core. Set a lower diff --git a/docs/_build/html/_sources/troubleshooting.rst.txt b/docs/_build/html/_sources/troubleshooting.rst.txt index 003d840..b58fc0e 100644 --- a/docs/_build/html/_sources/troubleshooting.rst.txt +++ b/docs/_build/html/_sources/troubleshooting.rst.txt @@ -1,6 +1,10 @@ Troubleshooting =============== +For Windows setup, WSL startup errors, missing ROOT libraries, and older +runtime updates, see :doc:`install-windows`. For Linux package/runtime setup, +see :doc:`install-linux`. The sections below cover analysis workflows. + Fit or plot will not start -------------------------- diff --git a/docs/_build/html/configuration-sharing.html b/docs/_build/html/configuration-sharing.html index 1361ed0..b2338cb 100644 --- a/docs/_build/html/configuration-sharing.html +++ b/docs/_build/html/configuration-sharing.html @@ -46,6 +46,8 @@
  • Overview
  • Getting started
  • +
  • Windows installation
  • +
  • Linux installation
  • Runs and fitting
  • Parameters and parameter plots
  • Constraints
  • diff --git a/docs/_build/html/constraints.html b/docs/_build/html/constraints.html index 1feac5c..6e38cbc 100644 --- a/docs/_build/html/constraints.html +++ b/docs/_build/html/constraints.html @@ -46,6 +46,8 @@
    • Overview
    • Getting started
    • +
    • Windows installation
    • +
    • Linux installation
    • Runs and fitting
    • Parameters and parameter plots
    • Constraints
        diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html index 83ab803..8c9db15 100644 --- a/docs/_build/html/genindex.html +++ b/docs/_build/html/genindex.html @@ -43,6 +43,8 @@
        • Overview
        • Getting started
        • +
        • Windows installation
        • +
        • Linux installation
        • Runs and fitting
        • Parameters and parameter plots
        • Constraints
        • diff --git a/docs/_build/html/getting-started.html b/docs/_build/html/getting-started.html index 660797d..e53e708 100644 --- a/docs/_build/html/getting-started.html +++ b/docs/_build/html/getting-started.html @@ -19,7 +19,7 @@ - + @@ -46,8 +46,8 @@
          • Overview
          • Getting started
          • +
          • Windows installation
          • +
          • Linux installation
          • Runs and fitting
          • Parameters and parameter plots
          • Constraints
          • @@ -95,115 +97,58 @@

            Getting started

            -
            -

            Prerequisites

            -

            muSRFlow wraps external musrfit tools. How they are supplied depends on -the edition:

            +
            +

            Choose your edition

              -
            • Linux desktop: use a local musrfit installation or install the separate -ROOT + musrfit runtime. Select the tools through File / Preferences.

            • -
            • Windows desktop: the installer includes ROOT and musrfit in a WSL2 runtime. -Install WSL first, following Windows installation below.

            • -
            • Web: the tools are installed on the server that hosts the CGI runner.

            • +
            • Windows desktop: follow Windows installation. ROOT and musrfit are +included in a WSL2 runtime. The guide covers first installation, existing +runtime updates, and Windows-specific errors.

            • +
            • Linux desktop: follow Linux installation. Use an existing musrfit +installation or install the separate runtime through Preferences.

            • +
            • Web: open your site’s muSRFlow URL, for example +http://musruser.psi.ch/muSRFlow/. The server runs the tools; there is +nothing to install on your computer.

            -

            Packaged desktop applications do not require Node.js or npm on the target -PC. The browser edition needs no local installation at all.

            +

            Packaged desktop applications do not require Node.js or npm.

            -
            -

            Development and Linux packages

            -

            From a checkout, with Node.js and npm installed:

            -
            $ npm install
            -$ npm start
            -
            -
            -

            npm install is only needed once; later sessions start with npm start.

            -

            Release packages (Linux RPM and AppImage) are produced with:

            -
            $ npm run dist:rpm
            -$ npm run dist:appimage
            -
            -
            -

            Each command also builds the matching standalone ROOT + musrfit runtime -artifact (musrflow-runtime rpm / AppImage); npm run dist:runtime builds -only the runtime. The build and runtime requirements are described in -docs/DESKTOP_DEPLOYMENT.md.

            +
            +

            Desktop installation

            +

            The complete instructions are in Windows installation and +Linux installation. Choose work and data folders in File / Preferences +before your first analysis. Keep work files outside the application +installation directory.

            -

            Windows installation

            -

            Use a 64-bit Intel/AMD Windows PC. Windows 11 is recommended; Windows 10 -requires build 19044 or newer for WSLg, which displays the musrview -windows. See Microsoft’s WSL GUI requirements.

            -
              -
            1. Open PowerShell as Administrator and install WSL:

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

              Restart Windows afterwards. Skip this step if WSL is already installed. -You do not need Ubuntu: muSRFlow supplies its own distribution.

              -
            2. -
            3. Update WSL and check its components in administrator PowerShell:

              -
              wsl --update
              -wsl --version
              -
              -
              -

              Follow any restart instructions. The output should include WSL and WSLg. -See the Microsoft WSL command reference.

              -
            4. -
            5. Copy the release installer muSRFlow-<version>-x64.exe to Windows and -double-click it. It includes muSRFlow-runtime-rootfs.tar.gz; there is -no separate ROOT or musrfit installation or manual archive import.

            6. -
            7. Launch muSRFlow from the Start menu using your normal Windows account. -The first launch prepares the runtime, which can take several minutes. -Fit and Plot wait until preparation finishes. Afterwards, verify:

              -
              wsl --list --verbose
              -
              -
              -

              The list should contain muSRFlow-runtime with VERSION 2. -Running and Stopped are both normal when idle.

              -
            8. -
            9. Create writable work and data folders, for example -C:\Users\<your-name>\muSRFlow\work and -C:\Users\<your-name>\muSRFlow\data. Choose them in -File / Preferences. Leave musrfit binaries and -musrfit startup XML on automatic detection, then save. -Enter Windows paths; muSRFlow translates them for WSL.

            10. -
            11. Select a known instrument, year, and run, then press Plot. If data -are missing, muSRFlow offers to download them from musruser.psi.ch -when the server is reachable. Confirm the spectrum window opens, then -try Fit and check that the parameter table updates. Results stay in -your Windows work directory.

            12. -
            -

            If setup fails, check WSL, restart muSRFlow, and retry. If plotting fails -after setup, check that wsl --version includes WSLg and inspect the -command log. The Linux Install runtime… preference does not apply to -Windows. Installation and graphical plotting still need validation on a -Windows PC; automated setup tests use simulated WSL commands.

            +

            Windows installation

            +

            The Windows instructions have their own chapter: Windows installation. +It also contains the update steps for older WSL runtimes.

            Running the desktop app

            -

            When the window opens, the Runs tab is active and the current year is -already selected. Enter run numbers, choose a model, and press Fit. The -first fit writes the working files next to your MSR document and results -appear in the Results tab.

            +

            When the window opens, the Runs tab is active. Choose the instrument, +year, and run numbers, check the model, and press Plot to inspect the +spectrum. Press Fit to fit it and refresh the parameter table. Generated +files go to the selected work directory; the Results tab and run log +show the outcome.

            Opening the web edition

            -

            Point your browser at the deployment URL (e.g. -http://musruser.psi.ch/muSRFlow/). Instrument options and run numbers are -the ones the server data tree supports. There is nothing to install; the -parameter table is also served from the same data tree.

            +

            Open the deployment URL in your browser. Instrument options and available +run data depend on that site’s server configuration. Fit and Plot run on +the server; output files can be opened from the result links.

            The Quick Start guide

            The ? button at the right of the tab bar opens a short, tab-aware guide. On the desktop it opens in an independent window; in the browser it opens a -modeless dialog next to the main window. Each of its sections corresponds to -one tab and is expanded into a chapter of this manual.

            +modeless dialog next to the main window. The full workflow chapters follow +the installation guides in this manual.

            Support

            -

            For questions and bug reports contact Zaher Salman -mailto:zaher.salman@psi.ch. Issue tracking is linked from the project -repository.

            +

            For questions and bug reports, include the version and run log and contact +Zaher Salman. See Troubleshooting +for common workflow problems.

            @@ -212,7 +157,7 @@ repository.

            diff --git a/docs/_build/html/install-linux.html b/docs/_build/html/install-linux.html new file mode 100644 index 0000000..3dea0c6 --- /dev/null +++ b/docs/_build/html/install-linux.html @@ -0,0 +1,256 @@ + + + + + + + + + Linux installation — muSRFlow User Manual + + + + + + + + + + + + + + + + + +
            + + +
            + +
            +
            +
            + +
            +
            +
            +
            + +
            +

            Linux installation

            +

            Install the muSRFlow application, then select a working ROOT + musrfit +installation. The Linux application package does not include the scientific +runtime. You can use an existing installation or install the separate +runtime through Preferences. Node.js and npm are not needed on the target PC.

            +

            The current application packages are for x86_64 Linux. Examples below use +1.0.0-rc.5; substitute the version of the package you obtained. Run the +commands from the folder containing the downloaded files.

            +
            +

            Install the application

            +

            Choose one application format.

            +
            +

            RPM

            +

            On an RPM-based distribution with dnf:

            +
            sudo dnf install ./musrflow-1.0.0-rc.5-x86_64.rpm
            +musrflow
            +
            +
            +

            On other RPM systems, use the distribution’s package manager. The application +RPM filename starts with lowercase musrflow.

            +
            +
            +

            AppImage

            +
            chmod +x muSRFlow-1.0.0-rc.5-x86_64.AppImage
            +./muSRFlow-1.0.0-rc.5-x86_64.AppImage
            +
            +
            +

            The application AppImage filename starts with muSRFlow. It requires a +compatible Linux desktop and AppImage/FUSE support. If it cannot start, +check the terminal output or use the RPM on a supported RPM distribution.

            +
            +
            +
            +

            Set up ROOT and musrfit

            +
            +

            Use an existing installation

            +

            Open File / Preferences. Leave musrfit binaries on automatic detection +for a standard installation, or choose the directory containing musrfit, +musrview, msr2data, musrt0, and dump_header. Save your settings, +then use Check tools to verify the saved selection.

            +
            +
            +

            Install the separate runtime from a local bundle

            +
              +
            1. Obtain the runtime bundle for your architecture. Keep +runtime-download.json and its matching musrflow-runtime-*.tar.gz +archive in the same folder. You do not need to unpack it.

            2. +
            3. Open File / Preferences / Install runtime… and select +runtime-download.json.

            4. +
            5. Review the versions and destination, then select Install and use. +muSRFlow validates the archive, installs it in your personal application +data directory, and selects its tools.

            6. +
            7. Use Check tools to confirm the selected runtime starts.

            8. +
            +

            This installation does not require administrator access. Runtime downloads +are not automatic: obtain the bundle separately before opening the installer. +A compatible Linux system and desktop/display services are still required.

            +
            +
            +

            Alternative: system runtime RPM

            +
            sudo dnf install ./musrflow-runtime-1.0.0-rc.5-x86_64.rpm
            +
            +
            +

            This installs the runtime into /opt/musrflow/runtime, which muSRFlow +recognizes automatically when no explicit tool directory takes precedence.

            +
            +
            +

            Alternative: runtime AppImage

            +

            For a user-writable runtime location:

            +
            chmod +x musrflow-runtime-1.0.0-rc.5-x86_64.AppImage
            +./musrflow-runtime-1.0.0-rc.5-x86_64.AppImage --install "$HOME/.local/share/musrflow/runtime"
            +
            +
            +

            Launch the application with the installed runtime selected:

            +
            MUSRFLOW_RUNTIME_ROOT="$HOME/.local/share/musrflow/runtime" musrflow
            +
            +
            +

            For the application AppImage, replace musrflow in that command with its +path. Leave musrfit binaries on automatic detection so the selected +runtime is used. Without a custom destination, the runtime AppImage installs +to /opt/musrflow/runtime and needs permission to write there. Its filename +is lowercase musrflow-runtime, unlike the application AppImage.

            +
            +
            +
            +

            Choose folders and test

            +
              +
            1. In File / Preferences, choose a writable Work directory outside +the application installation folder, for example ~/muSRFlow/work. +Use Browse… to select it.

            2. +
            3. Set Data directory to the root of your instrument data tree, or to a +writable folder such as ~/muSRFlow/data for downloaded runs.

            4. +
            5. Leave musrfit startup XML on automatic detection unless you have a +specific installation configuration, then save.

            6. +
            7. Select a known instrument, year, and run. Click Plot, then Fit. +Confirm the spectrum opens, fitted parameters update, and output files +appear in your work directory. Missing runs can be downloaded from +musruser.psi.ch after confirmation when the server is reachable.

            8. +
            +
            +
            +

            Updating and troubleshooting

            +
              +
            • Upgrade the application RPM with your package manager, or replace the +application AppImage. The separate runtime is not updated by an app upgrade.

            • +
            • Preserve work files outside the application/runtime installation directories.

            • +
            • For missing tools or shared libraries, run Check tools and inspect the +reported executable paths. A configured binaries directory overrides +automatic detection; clear an obsolete selection or choose the correct one.

            • +
            • If fitting works but no spectrum window opens, inspect the run log and +confirm your desktop session can display native musrview windows.

            • +
            • If data are missing, check the instrument, year, run number, and data root. +Downloaded files use the selected writable data root or the personal +fallback folder reported in Preferences.

            • +
            +

            Include the application version and run log when reporting a problem.

            +
            +
            + + +
            +
            + +
            +
            +
            +
            + + + + \ No newline at end of file diff --git a/docs/_build/html/install-windows.html b/docs/_build/html/install-windows.html new file mode 100644 index 0000000..3bf2e77 --- /dev/null +++ b/docs/_build/html/install-windows.html @@ -0,0 +1,297 @@ + + + + + + + + + Windows installation — muSRFlow User Manual + + + + + + + + + + + + + + + + + +
            + + +
            + +
            +
            +
            + +
            +
            +
            +
            + +
            +

            Windows installation

            +

            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.

            • +
            • Obtain the Windows installer, named muSRFlow-<version>-x64.exe. The +current release candidate is 1.0.0-rc.5.

            • +
            +

            Use the refreshed Windows build. Earlier rc.5 installers have the same +filename but lack the WSL fixes. Obtain a build containing commit a6981c4 +or later. In the development workspace, the verified replacement is +dist/windows-runtime-fix/muSRFlow-1.0.0-rc.5-x64.exe; this is a local build +output, not a public download address.

            +

            See Microsoft’s WSL GUI requirements for the +Windows prerequisites.

            +
            +
            +

            Install step by step

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

              +
              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. +
            3. Update and check WSL. In administrator PowerShell, run:

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

              +
            4. +
            5. 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.

            6. +
            7. 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:

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

              +
            8. +
            9. Choose work and data folders before fitting. Create folders such as:

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

              +
            10. +
            11. 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.

            12. +
            +
            +
            +

            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. +
            3. Close muSRFlow and install the refreshed Windows application.

            4. +
            5. If your runtime was imported from an older bundle, add the missing Boost +headers from 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.

              +
            6. +
            7. Reopen muSRFlow, select your work directory in Preferences, and retry Plot +and Fit.

            8. +
            +

            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.

            +
            +
            +

            Troubleshooting

            +
            +

            Required feature is not installed

            +

            For HCS_E_SERVICE_NOT_AVAILABLE during runtime preparation, Windows +could not create the WSL virtual machine. In administrator PowerShell:

            +
            dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
            +
            +
            +

            Restart Windows. Check Task Manager / Performance / CPU for +Virtualization: Enabled; 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:

            +
            bcdedit /enum | findstr -i hypervisorlaunchtype
            +
            +
            +

            Only if it reports Off, enable it and restart:

            +
            bcdedit /set hypervisorlaunchtype Auto
            +
            +
            +

            See Microsoft’s WSL troubleshooting guide.

            +
            +
            +

            Cannot find wsl.exe

            +

            For spawn wsl.exe ENOENT, first check that wsl --version 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.

            +
            +
            +

            Cannot load libCore.so

            +

            Install the refreshed muSRFlow build. It passes the ROOT library directory +inside WSL for every bundled command. Setting a Windows ROOTSYS or +LD_LIBRARY_PATH is not a substitute for this launcher fix.

            +
            +
            +

            Missing boost/version.hpp or plotting crash

            +

            Follow Existing installations to install boost-devel in an older +runtime. The corrected runtime includes it. If plotting still crashes, +include the full command output when reporting the problem.

            +
            +
            +

            No spectrum window appears

            +

            Confirm that wsl --version lists WSLg, update WSL, and inspect the +muSRFlow run log. Successful runtime import or a successful fit alone does +not verify interactive graphics support.

            +
            +
            +

            Reporting a problem

            +

            Include the muSRFlow version, full run log, and the output of:

            +
            wsl --version
            +wsl --status
            +wsl --list --verbose
            +
            +
            +

            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.

            +
            +
            +
            + + +
            +
            + +
            +
            +
            +
            + + + + \ No newline at end of file diff --git a/docs/_build/html/keyboard-shortcuts.html b/docs/_build/html/keyboard-shortcuts.html index 207c5ca..aa37be5 100644 --- a/docs/_build/html/keyboard-shortcuts.html +++ b/docs/_build/html/keyboard-shortcuts.html @@ -46,6 +46,8 @@
            • Overview
            • Getting started
            • +
            • Windows installation
            • +
            • Linux installation
            • Runs and fitting
            • Parameters and parameter plots
            • Constraints
            • diff --git a/docs/_build/html/msr-editor.html b/docs/_build/html/msr-editor.html index 4b4683d..c376d13 100644 --- a/docs/_build/html/msr-editor.html +++ b/docs/_build/html/msr-editor.html @@ -46,6 +46,8 @@
            • Getting started
            • +
            • Windows installation
            • +
            • Linux installation
            • Runs and fitting
            • Parameters and parameter plots
            • Constraints
            • diff --git a/docs/_build/html/parameters-plots.html b/docs/_build/html/parameters-plots.html index 9f689a5..c8dcd80 100644 --- a/docs/_build/html/parameters-plots.html +++ b/docs/_build/html/parameters-plots.html @@ -46,6 +46,8 @@
              • Overview
              • Getting started
              • +
              • Windows installation
              • +
              • Linux installation
              • Runs and fitting
              • Parameters and parameter plots
                • The parameter table
                    diff --git a/docs/_build/html/platforms.html b/docs/_build/html/platforms.html index 7fc26c8..b6a020c 100644 --- a/docs/_build/html/platforms.html +++ b/docs/_build/html/platforms.html @@ -46,6 +46,8 @@
                    • Overview
                    • Getting started
                    • +
                    • Windows installation
                    • +
                    • Linux installation
                    • Runs and fitting
                    • Parameters and parameter plots
                    • Constraints
                    • @@ -139,26 +141,16 @@ JSROOT in the page.

                      Bundled ROOT and musrfit

                      -

                      Packaged desktop builds can use a self-contained ROOT + musrfit runtime, so a -separate musrfit installation is not required on the machine. The runtime may -be bundled inside the application or, on Linux, installed separately (the -musrflow-runtime rpm or the portable muSRFlow-runtime AppImage, both -defaulting to /opt/musrflow/runtime). When a runtime is found muSRFlow runs -those tools with ROOTSYS, MUSRFITPATH, and LD_LIBRARY_PATH pointed -at it; a directory set in Preferences / musrfit binaries still takes -precedence, and on builds without a runtime the system installation is used -exactly as before. The runtime is built with packaging/runtime/build.sh and -packaged with packaging/runtime/build-runtime-rpm.sh / -build-runtime-appimage.sh (see packaging/runtime/README.md).

                      -

                      On Windows the bundled runtime runs inside a WSL2 distribution that muSRFlow -ships: the tools are invoked through wsl.exe and file paths are translated -between the Windows and WSL forms, so inputs and outputs stay on the Windows -side. The rootfs is built with packaging/wsl2/build-wsl2.sh and imported -once per user (see packaging/wsl2/README.md).

                      -

                      Follow Windows installation for the WSL setup, Windows installer, -folder preferences, and first Plot/Fit check. The Windows installer includes -muSRFlow-runtime-rootfs.tar.gz and imports it automatically; the separate -Linux runtime archive and Install runtime… preference do not apply.

                      +

                      On Linux, the application and scientific runtime are separate. Use an +existing ROOT + musrfit installation, install an offline runtime bundle in +Preferences, or install the system runtime RPM/AppImage. An explicitly +selected binaries directory takes precedence over automatic detection. +See Linux installation for installation and tool checks.

                      +

                      On Windows, the application installer includes the runtime. It runs inside +a WSL2 distribution named muSRFlow-runtime. Tools are invoked through +wsl.exe, with paths translated so inputs and outputs stay on the Windows +side. The separate Linux runtime installer does not apply to Windows. +See Windows installation for WSL setup, installation, updates, and fixes.

                      The workflow chapters of this manual apply to both editions. Where a step is specific to one edition (handling files, Preferences), the text says so explicitly.

                      diff --git a/docs/_build/html/preferences.html b/docs/_build/html/preferences.html index 54e55f0..d03e95f 100644 --- a/docs/_build/html/preferences.html +++ b/docs/_build/html/preferences.html @@ -46,6 +46,8 @@
                      • Overview
                      • Getting started
                      • +
                      • Windows installation
                      • +
                      • Linux installation
                      • Runs and fitting
                      • Parameters and parameter plots
                      • Constraints
                      • @@ -91,7 +93,9 @@ configuration and never exposes this dialog.

                        Work directory

                        Where generated files, MSR documents, and result artifacts are written. -Defaults to the current directory (.).

                        +Defaults to the current directory (.), which can be the application +installation folder. Choose a separate writable work folder before fitting +so application upgrades do not affect your results.

                        Data directory

                        The root of the instrument data tree (for example /psi.ch/group/lmu/public/data). Run paths are resolved under it.

                        @@ -123,6 +127,11 @@ given to them. The setting is a desktop feature: it is remembered across sessions, while the web edition takes its tools from the server and never exposes this field.

                        +
                        Runtime installation and checks (Linux)

                        Check tools checks the saved tool selection. Install runtime… +installs a local runtime bundle after confirmation and selects its tools. +See Linux installation for the required files and installation steps. +Windows uses its bundled WSL runtime instead; see Windows installation.

                        +
                        musrfit threads

                        The number of OpenMP threads passed to a local musrfit run (-u). Leave it blank to let musrfit use every available core. Set a lower number to keep a fit from saturating a shared workstation or login node. diff --git a/docs/_build/html/results-diagnostics.html b/docs/_build/html/results-diagnostics.html index bd5bf62..4024286 100644 --- a/docs/_build/html/results-diagnostics.html +++ b/docs/_build/html/results-diagnostics.html @@ -46,6 +46,8 @@

                        • Overview
                        • Getting started
                        • +
                        • Windows installation
                        • +
                        • Linux installation
                        • Runs and fitting
                        • Parameters and parameter plots
                        • Constraints
                        • diff --git a/docs/_build/html/runs-fitting.html b/docs/_build/html/runs-fitting.html index ebee29a..d7ed1d2 100644 --- a/docs/_build/html/runs-fitting.html +++ b/docs/_build/html/runs-fitting.html @@ -20,7 +20,7 @@ - + @@ -46,6 +46,8 @@
                          • Overview
                          • Getting started
                          • +
                          • Windows installation
                          • +
                          • Linux installation
                          • Runs and fitting
                            • Run selection
                            • Fit range
                            • @@ -317,7 +319,7 @@ replace it – see