Files
muSRFlow/README.md

4.2 KiB

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.

User Manual

The end-user manual is built with Sphinx from docs/source (reStructuredText). The built HTML and PDF live under docs/_build. Rebuild it with:

cd docs
make html     # HTML in docs/_build/html
make latexpdf # PDF at docs/_build/latex/muSRFlow.pdf

Desktop Development

Install Node.js and npm, then run:

npm install
npm start

Dependencies only need to be installed once. Later sessions can be started with npm start.

Desktop Packages

The desktop app is at version 1.0.0-rc.1 (release candidate). Linux RPM and AppImage release packages can be produced with:

npm run dist:rpm
npm run dist:appimage

See docs/DESKTOP_DEPLOYMENT.md for build, runtime, and release requirements.

The remaining work before 1.0 and the prioritized improvements are tracked in TODO.md. Per-release notes are in CHANGELOG.md.

Web Deployment

The browser application consists of index.html, quick-start.html, ZGUI.css, muSRFitweb.js, muSRFitRoot.js, muSRFitParameterPlot.js, and muSRFitlib.js. The web plot window uses JSROOT to draw the ROOT files produced by musrview --root. Its server-side runner is documented in cgi/README.md.

Install both the browser files and CGI endpoint. The script targets the default Apache paths and hands the files to the web server's owner:

sudo ./scripts/deploy-web.sh

The web-only owner (apache/www-data/httpd) is auto-detected when the deployed tree is not already owned by the invoking user, so the script also runs unprivileged against a developer-owned web tree (skip that case's sudo). Override the targets and owner as needed with MUSRFLOW_WEB_TARGET, MUSRFLOW_CGI_TARGET, MUSRFLOW_STARTUP_XML_TARGET, MUSRFLOW_WEB_OWNER, and MUSRFLOW_WEB_GROUP.

The installed musrfit_startup.xml is rewritten when the machine's data tree lives under a non-PSI root: set MUSRFLOW_DATA_ROOT (e.g. /mnt/fake) and the <data_path> roots in the installed copy are rewritten to it so the portable RUN-name resolver matches the local data layout. The repository source file is never modified.

The server-side data root is configured separately: the CGI reads MUSRFIT_DATA_ROOT (default /psi.ch/group/lmu/public/data) and reports it to the browser through its health endpoint. When MUSRFLOW_DATA_ROOT is used, set MUSRFIT_DATA_ROOT to the same value so the path the browser shows and the security boundary agree with the rewritten startup-XML roots. See cgi/README.md for the full list of CGI environment variables.

Code Organization

The project splits platform code from shared logic so that a change is made once instead of duplicated across the desktop and web runtimes:

  • muSRFitlib.js — shared, platform-agnostic logic (MSR generation/parsing, series-fit planning and merge, fit-statistic parsing, shared-configuration protocol, command/parameter formatting). This is the canonical home for any logic that both runtimes need.
  • muSRFitelec.js — Electron-specific code (filesystem and IPC access, local process execution, local transaction adapter).
  • muSRFitweb.js — web-specific code (CGI transport, browser clipboard, drag-and-drop windows).

As a rule, the adapters supply only platform-specific primitives (filesystem, process, clipboard, HTTP) while muSRFitlib.js owns the logic. Pure transformations such as displayCommand, seriesRunDirectiveIdentity, and normalizeParameterDataHeaderLines live in muSRFitlib.js. The CGI endpoint writes files and runs external executables on the server; generated artifacts are served back over HTTP.

Contact

Zaher Salman zaher.salman@psi.ch

License

Copyright (C) 2026 Zaher Salman. muSRFlow is distributed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). See LICENSE for the full license text.