Mixed run sources
=================

The **Mixed** run-source mode combines data sets that cannot be described by
one global **Year** and **Instrument** selection. Use it, for example, to fit a
LEM run and a GPS run with one model, to compare measurements from different
years, or to use an explicit data-file path.

Mixed mode is currently intended for **Asymmetry** fits. It creates one
runnable MSR file containing all selected data sets and fits them
simultaneously.

Select the sources
------------------

#. Open the **Runs** tab.
#. Change the source selector from **Run(s)** to **Mixed**. The global **Year**
   and **Instrument** controls are hidden because every source identifies its
   own origin.
#. Enter the sources in **Mixed files**.

Each source can be written as ``year/instrument/run`` or as an explicit data
file or path. Instrument names are case-insensitive, but must identify an
instrument known to muSRFlow.

.. list-table:: Mixed-selection examples
   :header-rows: 1
   :widths: 42 58

   * - Input
     - Meaning
   * - ``2025/LEM/1014``
     - One LEM data set from 2025.
   * - ``2025/LEM/1014, 2024/GPS/0567``
     - Two independent data sets in one simultaneous fit.
   * - ``2025/LEM/1014+2025/LEM/1015``
     - One logical data set; run 1015 is written as ``ADDRUN``.
   * - ``2025/LEM/1014+2025/LEM/1015, /data/reference.root``
     - An ``ADDRUN`` data set and a second data set supplied by path.

A comma starts a new logical data set. A ``+`` adds another source to the
current data set through the MSR ``ADDRUN`` directive. Mixed mode deliberately
does not expand ranges or stepped sequences: write every source explicitly.
For homogeneous runs from one year and instrument, switch back to **Run(s)**
and use its range syntax instead.

Configure the fit
-----------------

#. Select **Asymmetry** as the fit type.
#. Choose histograms that are meaningful for every selected source.
#. Build the model and set initial values in the same way as for a normal fit.
#. Open **Parameters** and decide which model parameters are shared.

With two or more logical data sets, the parameter table shows a **Shared**
column:

* A checked parameter is represented once and fitted jointly across every
  data set.
* An unchecked parameter gets one row per data set. muSRFlow adds a stable
  source-derived suffix to each MSR parameter name so values from different
  years and instruments cannot collide.
* Unchecking an existing shared parameter seeds every independent copy with
  the shared row's current value. The copies can then be edited separately.

This is a simultaneous fit even when no parameters are shared. Mixed sources
do not currently use the independent-series **reuse / refit / skip** route.

Plot or fit
-----------

Press **Plot** to generate the mixed MSR and inspect all selected spectra, or
press **Fit** to generate it, run ``musrfit``, and then plot the fitted result.
The generated document contains:

* one ``RUN`` block for each comma-separated data set;
* ``ADDRUN`` lines for sources joined with ``+``;
* one map entry per model parameter and data set;
* a ``PLOT`` block whose ``runs`` line includes every generated RUN block.

Unlike an ordinary homogeneous multi-run fit, this route does not ask
``msr2data`` to expand a template. ``msr2data`` assumes one numeric run series
under one year and instrument, so muSRFlow resolves every mixed component and
builds the runnable multi-dataset MSR directly.

After a fit, fitted values flow back into the parameter table. The MSR Editor
shows the same runnable document; locking the editor makes its text
authoritative for the next Plot or Fit, as described in :doc:`msr-editor`.

Explicit files
--------------

An explicit source may be a file name or a full path. muSRFlow recognizes the
usual extensions and writes the corresponding MSR file format, including
``.root``, ``.bin``, ``.mdu``, ``.msr``, and ``.nxs``. The extension is not
written as part of the MSR ``RUN`` token, following musrfit file-name syntax.

On the desktop, the normal local-data checks and download fallback still apply
to resolvable instrument runs. An arbitrary explicit path must be accessible
from the environment in which the fitting tools run. In particular, a Windows
path used with the bundled WSL runtime must be visible through its ``/mnt/...``
path.

Import and shared links
-----------------------

Importing an MSR that contains multiple instruments, years, or explicit RUN
tokens restores the selection in **Mixed** mode when the sources can be
identified. A shared web link stores the mixed selection as ``MixedFiles``.
Search integrations may provide the equivalent ``RunFiles`` field. Do not
combine either field with ``RunNumbers`` in the same request.

Current limitations
-------------------

* A mixed selection with more than one logical data set supports
  **Asymmetry**, but not **Single hist**. Fit those data sets separately when a
  single-histogram model is required.
* Ranges such as ``1014-1020`` and stepped selections are not accepted in the
  Mixed field.
* The independent-series reuse/refit/skip workflow is not used for mixed
  sources; all data sets belong to one generated fit document.
* Automatic initial-value guessing from run headers is disabled because one
  global guess is not generally valid across unlike sources. Enter initial
  values in the parameter table.
* GUI t\ :sub:`0` and background override mapping is not yet available for
  mixed selections. The data-file defaults are used unless the generated MSR
  is adjusted in the expert editor.

When a source cannot be resolved, muSRFlow reports it as missing data rather
than as a failed fit. Correct the source, data location, or runtime-visible
path, then run Plot or Fit again.
