Overview
========

muSRFlow provides a modern interface over the classic µSR analysis tools. A
typical session selects the data, chooses a fit model, fits it, inspects the
result, and finally inspects how the fitted parameters vary run by run.

.. figure:: images/fit-workflow.*
   :alt: Four steps: choose the analysis, prepare the MSR, fit with musrfit, then review fitted values and plots. Plot skips the minimizer.
   :width: 100%

   The basic fit workflow. See :doc:`runs-fitting` for independent series
   and shared-parameter fits, and :doc:`msr-editor` for document ownership.

What you get
------------

* A single window with the full workflow in tabs:

  * **Runs** -- run selection, factorial fit range, fit model, fit options,
    and the Plot / FFT / RRF view settings.
  * **Parameters** -- the parameter table with starting values, steps,
    limits, and plot selection.
  * **Constraints** -- custom parameters and parameter constraints.
  * **t0 / Bg** -- expert timing and background controls.
  * **MSR Editor** -- the generated MSR document, with GUI-to-MSR and
    MSR-to-GUI synchronisation.
  * **Results** -- generated files, execution details, and the full command
    log.

* Two one-click workflow actions in the main toolbar:

  * **Fit** -- generate the MSR document and run the fit.
  * **Plot** -- generate the MSR document and display the spectra.

* Interactive parameter plots that show how every fitted parameter evolves
  across the selected runs.

* Configuration sharing: the current analysis settings can be encoded into a
  link and restored on another machine.

Under the hood
--------------

muSRFlow does not reimplement the physics. It writes MSR files that are fed
to the `musrfit <https://lmu.web.psi.ch/musrfit/>`_ package, and renders
spectra with ``musrview``:

* ``musrfit`` -- the muon-spectroscopy fitting engine. muSRFlow generates an
  MSR file from the GUI and runs ``musrfit`` on it. The fitted values (a
  ``par.dat`` parameter table) feed the parameter plots.
* ``musrview`` -- the reference data viewer. On the desktop it opens its own
  native window; in the browser edition the server produces a ROOT canvas
  that is drawn with JSROOT inside the page.
* ``msr2data`` -- converts a fitted MSR file into a parameter table
  (``par.dat``) that the parameter plot can read.
* ``dump_header`` -- reads run metadata used to resolve portable run names
  and to guess initial parameters.

Two editions
------------

* **Desktop (Electron)** runs the tools directly on your machine, manages its
  own data and working directories (set under **File / Preferences**), and
  can open and save MSR files from the File menu.
* **Web** runs the same interface in a browser. The data tree and the
  command-line tools live on the server, so file selection is limited to what
  the server exposes, and there is no local Preferences dialog.

Both editions share the same workflow and produce the same MSR documents.
The differences that matter day to day are collected in
:doc:`platforms`.

A first fit
-----------

#. In the **Runs** tab, choose the instrument and year and enter one or more
   run numbers.
#. Adjust the fit range and the fit model as needed.
#. Press **Fit**.
#. Open the **Parameters** tab to verify and adjust starting values, then
   press **Fit** again.
#. Use **Plot** any time to look at the spectra.
#. Select parameters and choose **Plot parameters...** to inspect how they
   vary across the run set (see :doc:`parameters-plots`).

The Quick Start button (``?``) at the right of the tab bar opens a short
guide that highlights the section relevant to the active tab. Its sections
are expanded into the chapters of this manual.
