2441 lines
229 KiB
HTML
2441 lines
229 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>User manual — musrfit 1.6.0 documentation</title>
|
||
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
<script type="text/javascript" src="_static/language_data.js"></script>
|
||
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Documentation of user libs (user functions)" href="user-libs.html" />
|
||
<link rel="prev" title="Tutorial for musrfit" href="tutorial.html" />
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="user-libs.html" title="Documentation of user libs (user functions)"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="tutorial.html" title="Tutorial for musrfit"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">musrfit 1.6.0 documentation</a> »</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="user-manual">
|
||
<span id="index-0"></span><span id="id1"></span><h1>User manual<a class="headerlink" href="#user-manual" title="Permalink to this headline">¶</a></h1>
|
||
<div class="section" id="introduction">
|
||
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrfit</span></code> is a software tool for analyzing time-differential μSR data. The program suite is <a class="reference external" href="http://www.gnu.org/philosophy/free-sw.html">free software</a> and licensed under the <a class="reference external" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU GPL version 2</a> or any later version (at your option). It is implemented in <code class="docutils literal notranslate"><span class="pre">C++</span></code>/ROOT and uses the <a class="reference external" href="http://seal.web.cern.ch/seal/MathLibs/Minuit2/html/index.html">MINUIT2</a> libraries developed at <a class="reference external" href="http://www.cern.ch/">CERN</a> for fitting data. Installation instructions for GNU/Linux, MS Windows, and macOS can be found under <a class="reference internal" href="setup-standard.html#musrfit-setup"><span class="std std-ref">musrfit setup</span></a>. Recent changes of the program can be followed on the git, either <a class="reference external" href="https://bitbucket.org/muonspin/musrfit">bitbucket</a> or <a class="reference external" href="https://gitlab.psi.ch/nemu/musrfit">gitlab</a>.</p>
|
||
</div>
|
||
<div class="section" id="available-executables-configuration-files-and-their-basic-usage">
|
||
<h2>Available Executables, Configuration Files and their Basic Usage<a class="headerlink" href="#available-executables-configuration-files-and-their-basic-usage" title="Permalink to this headline">¶</a></h2>
|
||
<p>The philosophy is that users, based on their abilities or preferences, can work on the command line are in a more GUI based setting. Here, the command line based tools will be described. The GUI based parts are described in the <a class="reference internal" href="musredit.html#musredit-sec"><span class="std std-ref">musredit</span></a>.</p>
|
||
<div class="section" id="musrfit">
|
||
<span id="index-1"></span><span id="id2"></span><h3>musrfit<a class="headerlink" href="#musrfit" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrfit</span></code> is the actual fitting program. It defines the FCN routine passed to <code class="docutils literal notranslate"><span class="pre">MINUIT2</span></code> and performs <span class="math notranslate nohighlight">\(\chi^2\)</span> or log-max-likelihood fitting. If called from within a shell it accepts several parameters:</p>
|
||
<dl class="simple">
|
||
<dt><strong><msr-file></strong></dt><dd><p>filename of the msr input file defining all the details needed for performing a fit to a specified set of data. This is the only mandatory parameter.</p>
|
||
</dd>
|
||
<dt><strong>-k, - -keep-mn2-output</strong></dt><dd><p>selects the option for keeping the output of <code class="docutils literal notranslate"><span class="pre">MINUIT2</span></code> including the correlation coefficients between different parameters and renaming the files <code class="docutils literal notranslate"><span class="pre">MINUIT2.OUTPUT</span></code> and <code class="docutils literal notranslate"><span class="pre">MINUIT2.root</span></code> to <code class="docutils literal notranslate"><span class="pre"><msr_file_without_extension>-mn2.output</span></code> and <code class="docutils literal notranslate"><span class="pre"><msr_file_without_extension>-mn2.root</span></code>, respectively, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre"><msr_file></span></code> = <code class="docutils literal notranslate"><span class="pre">8472.msr</span></code> will result in <code class="docutils literal notranslate"><span class="pre">8472-mn2.output</span></code>, <code class="docutils literal notranslate"><span class="pre">8472-mn2.root</span></code>.</p>
|
||
</dd>
|
||
<dt><strong>-c, - -chisq-only</strong></dt><dd><p>Instead of fitting the model, <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> calculates <span class="math notranslate nohighlight">\(\chi^2\)</span> or max. log-likelihood, maxLH, only once and sends the result to the standard output if called with this option. This is <em>e.g.</em> useful for the adjustment of the initial values of the fit parameters.</p>
|
||
</dd>
|
||
<dt><strong>-t, - -title-from-data-file</strong></dt><dd><p>If this option is given <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> will replace the title in the <code class="docutils literal notranslate"><span class="pre"><msr_file></span></code> by the run title in the data file of the first run appearing in a RUN block. In case there is no run title in the data file no substitution is done.</p>
|
||
</dd>
|
||
<dt><strong>-e, - -estimateN0</strong></dt><dd><p>estimate <span class="math notranslate nohighlight">\(N_0\)</span> for single histogram fits.</p>
|
||
</dd>
|
||
<dt><strong>-p, - -per-run-block-chisq</strong></dt><dd><p>will write per run block chisq/maxLH into the msr-file.</p>
|
||
</dd>
|
||
<dt><strong>- -dump <type></strong></dt><dd><p>is writing a data file with the fit data and the theory; <type> can be ascii (data in columns) or root (data in ROOT histograms).</p>
|
||
</dd>
|
||
<dt><strong>- -timeout <timeout_tag></strong></dt><dd><p>overwrites the predefined timeout of 3600 sec. <timeout_tag> <span class="math notranslate nohighlight">\(\leq\)</span> 0 means the timeout facility is not enabled. <timeout_tag> > 0, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">nn</span></code> will set the timeout to <code class="docutils literal notranslate"><span class="pre">nn</span></code> (sec). If during a fit this timeout is reached, <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> will terminate. This is used to prevent orphan <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> processes to jam the system.</p>
|
||
</dd>
|
||
<dt><strong>- -help</strong></dt><dd><p>displays a small help notice in the shell explaining the basic usage of the program.</p>
|
||
</dd>
|
||
<dt><strong>- -version</strong></dt><dd><p>prints the version number of <code class="docutils literal notranslate"><span class="pre">musrfit</span></code></p>
|
||
</dd>
|
||
</dl>
|
||
<p>If called with a msr input file, <em>e.g.</em></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrfit <span class="m">8472</span>.msr
|
||
</pre></div>
|
||
</div>
|
||
<p>the fit described in the input file will be executed and the results will be written to a mlog output file, in the example <code class="docutils literal notranslate"><span class="pre">8472.mlog</span></code>. When the fitting has terminated the msr file and the mlog file are swapped, so that the resultant parameter values can be found in the msr file and the mlog file contains a copy of the input file. The format of the mlog file is the same as that of the msr file. For a detailed description of the msr file format refer to the <a class="reference internal" href="#msr-file-format"><span class="std std-ref">corresponding section</span></a>.</p>
|
||
<p>Another example:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrfit -c -e 8472_tf_histo.msr
|
||
</pre></div>
|
||
</div>
|
||
<p>This will calculate the chisq/maxLH of the run 8472 after estimating the <span class="math notranslate nohighlight">\(N_0\)</span>.</p>
|
||
</div>
|
||
<div class="section" id="musrview">
|
||
<span id="index-2"></span><span id="id3"></span><h3>musrview<a class="headerlink" href="#musrview" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrview</span></code> is an interactive graphical user interface for the presentation of the analyzed data and the corresponding fits. If called from within a shell it accepts the following parameters:</p>
|
||
<dl class="simple">
|
||
<dt><strong><msr_file></strong></dt><dd><p>name of the msr input or output file to be displayed. This is the only mandatory parameter.</p>
|
||
</dd>
|
||
<dt><strong>- -help</strong></dt><dd><p>displays a small help notice in the shell explaining the basic usage of the program.</p>
|
||
</dd>
|
||
<dt><strong>- -version</strong></dt><dd><p>prints the version number of <code class="docutils literal notranslate"><span class="pre">musrview</span></code>.</p>
|
||
</dd>
|
||
<dt><strong>-f, - -fourier</strong></dt><dd><p>will directly present the Fourier transform of the <msr_file> with Fourier options as defined in the <msr_file>.</p>
|
||
</dd>
|
||
<dt><strong>-a, - -avg</strong></dt><dd><p>will directly present the averaged data/Fourier of the <msr_file>.</p>
|
||
</dd>
|
||
<dt><strong>- -<graphic_format_extension></strong></dt><dd><p>will produce a graphics output file without starting a ROOT session. The filename is based on the name of the <msr_file>, <em>e.g.</em> 8472.msr will result in 8472_0.png.
|
||
Supported values for <code class="docutils literal notranslate"><span class="pre"><graphic_format_extension></span></code> are <em>eps</em>, <em>pdf</em>, <em>gif</em>, <em>jpg</em>, <em>png</em>, <em>svg</em>, <em>xpm</em>, and, <em>root</em>.</p>
|
||
</dd>
|
||
<dt><strong>- -ascii</strong></dt><dd><p>will generate an ascii dump of the data and theory as plotted.</p>
|
||
</dd>
|
||
<dt><strong>- -timeout <timeout></strong></dt><dd><p><timeout> given in seconds after which <code class="docutils literal notranslate"><span class="pre">musrview</span></code> terminates. If <timeout> <span class="math notranslate nohighlight">\(\leq\)</span> 0, no timeout will take place. Default for <timeout> is 0.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If called with a msr file and the <code class="docutils literal notranslate"><span class="pre">--<graphic_format_extension></span></code> option, <em>e.g.</em></p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ musrview 8472.msr --jpg
|
||
</pre></div>
|
||
</div>
|
||
<p>for each PLOT block in the the msr file a file <code class="docutils literal notranslate"><span class="pre">8472_X.jpg</span></code> is produced where <code class="docutils literal notranslate"><span class="pre">X</span></code> counts the PLOT blocks starting from zero.</p>
|
||
<p>If called only with a msr file, <em>e.g.</em></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrview <span class="m">8472</span>.msr
|
||
</pre></div>
|
||
</div>
|
||
<p>a ROOT canvas is drawn; it contains all experimental data and fits specified in the PLOT block of the msr file. For a description of the various plotting types refer to the <a class="reference internal" href="#msr-file-format"><span class="std std-ref">corresponding section</span></a>.</p>
|
||
<p>Another example:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrview 8472_tf_histo.msr -f -a
|
||
</pre></div>
|
||
</div>
|
||
<p>will show the averaged Fourier transform of the data of run 8472.</p>
|
||
<p>Within the drawn canvas all standard actions applicable to ROOT canvases might be performed. In the menu bar the Musrfit menu can be found. From there some musrfit-specific actions might be taken:</p>
|
||
<dl class="simple">
|
||
<dt><strong>Fourier</strong></dt><dd><p>performs the Fourier transformation of the <em>selected data</em> and shows the result.</p>
|
||
</dd>
|
||
<dt><strong>Difference</strong></dt><dd><p>shows the difference between the selected data and the fit.</p>
|
||
</dd>
|
||
<dt><strong>Average</strong></dt><dd><p>toggle between the current view and the averaged data view. Useful if the averaged Fourier power spectrum of lots of detectors shall be shown.</p>
|
||
</dd>
|
||
<dt><strong>Export Data</strong></dt><dd><p>saves the selected data in a simple multi-column ASCII file.</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="section" id="musrview-key-shortcuts">
|
||
<span id="index-3"></span><h4>musrview key-shortcuts<a class="headerlink" href="#musrview-key-shortcuts" title="Permalink to this headline">¶</a></h4>
|
||
<p>Additionally, some functions can be accessed using <em>key-shortcuts</em>:</p>
|
||
<dl class="simple">
|
||
<dt><strong>q</strong></dt><dd><p>quits musrview.</p>
|
||
</dd>
|
||
<dt><strong>d</strong></dt><dd><p>shows the difference between the selected data and the fit.</p>
|
||
</dd>
|
||
<dt><strong>f</strong></dt><dd><p>performs the Fourier transformation of the selected data and shows the result.</p>
|
||
</dd>
|
||
<dt><strong>a</strong></dt><dd><p>show the average of the presented data, <em>e.g.</em> the averaged Fourier power spectra of various detectors.</p>
|
||
</dd>
|
||
<dt><strong>u</strong></dt><dd><p>reset the plotting range to the area given in the msr file (“un-zoom”).</p>
|
||
</dd>
|
||
<dt><strong>c</strong></dt><dd><p>toggles between normal and cross-hair cursor.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="musrft">
|
||
<span id="index-4"></span><span id="id4"></span><h3>musrFT<a class="headerlink" href="#musrft" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrFT</span></code> is an interactive graphical user interface for the presentation of Fourier transforms of <em>raw</em> μSR histograms. It’s purpose is to get a quick overview for high TF-field data, as found <em>e.g.</em> at the HAL-9500 instrument at PSI. It Fourier transforms the raw histogram data, i.e. <span class="math notranslate nohighlight">\(N(t)\)</span> rather than <span class="math notranslate nohighlight">\(A(t)\)</span>, and hence shows the lifetime contribution of the muon decay. This is no problem for large enough fields, but will be a <em>severe</em> problem at very low fields. <code class="docutils literal notranslate"><span class="pre">musrFT</span></code> is still in its early stage and should be considered a beta-version.</p>
|
||
<p>If called from within a shell it accepts the following parameters:</p>
|
||
<dl class="simple">
|
||
<dt><strong>Input Files</strong></dt><dd><dl class="simple">
|
||
<dt><strong><msr_files></strong></dt><dd><p>msr-file name(s). These msr-files are used for the Fourier transform. It can be a list of msr-files, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">musrFT</span> <span class="pre">3110.msr</span> <span class="pre">3111.msr</span></code></p>
|
||
</dd>
|
||
<dt><strong>-df, - -data-file <data-file></strong></dt><dd><p>This allows to feed only μSR data file(s) to perform the Fourier transform. Since the extended <msr-file> information are missing, they will need to be provided by to options, or <code class="docutils literal notranslate"><span class="pre">musrFT</span></code> tries to guess, based on <a class="reference internal" href="#musrfit-startup"><span class="std std-ref">musrfit_startup.xml</span></a> settings.</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
<dt><strong>Options</strong></dt><dd><dl class="simple">
|
||
<dt><strong>- -help</strong></dt><dd><p>display a help and exit.</p>
|
||
</dd>
|
||
<dt><strong>- -version</strong></dt><dd><p>output version information and exit.</p>
|
||
</dd>
|
||
<dt><strong>-g, - -graphic-format <graphic-format-extension></strong></dt><dd><p>will produce a graphic-output-file without starting a root session. The name is based either on the <msr-file> or the <data-file>, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">3310.msr</span> <span class="pre">-></span> <span class="pre">3310_0.png</span></code>. Supported graphic-format-extension: <em>eps</em>, <em>pdf</em>, <em>gif</em>, <em>jpg</em>, <em>png</em>, <em>svg</em>, <em>xpm</em>, and <em>root</em>.</p>
|
||
</dd>
|
||
<dt><strong>- -dump <fln></strong></dt><dd><p>rather than starting a root session and showing Fourier graphs of the data, it will output the Fourier data in an ascii file <fln>.</p>
|
||
</dd>
|
||
<dt><strong>-br, - -background-range <start> <end></strong></dt><dd><p>background interval used to estimate the background to be subtracted before the Fourier transform. <start>, <end> to be given in bins.</p>
|
||
</dd>
|
||
<dt><strong>-bg, - -background</strong></dt><dd><p>gives the background explicit for each histogram.</p>
|
||
</dd>
|
||
<dt><strong>-fo, - -fourier-option <fopt></strong></dt><dd><p><fopt> can be ‘<em>real</em>’, ‘<em>imag</em>’, ‘<em>real+imag</em>’, ‘<em>power</em>’, or ‘<em>phase</em>’. If this is not defined (neither on the command line nor in the <a class="reference internal" href="#musrfit-startup"><span class="std std-ref">musrfit_startup.xml</span></a>) ‘<em>power</em>’ will be used.</p>
|
||
</dd>
|
||
<dt><strong>-ap, - -apodization <val></strong></dt><dd><p><val> can be either ‘<em>none</em>’, ‘<em>weak</em>’, ‘<em>medium</em>’, ‘<em>strong</em>’. Default will be ‘<em>none</em>’.</p>
|
||
</dd>
|
||
<dt><strong>-fp, - -fourier-power <N></strong></dt><dd><p><N> being the Fourier power, i.e. <code class="docutils literal notranslate"><span class="pre">2^<N></span></code> used for zero padding. Default is -1, i.e. <em>no</em> zero padding will be performed.</p>
|
||
</dd>
|
||
<dt><strong>-u, - -units <units></strong></dt><dd><p><units> is used to define the abscissa of the Fourier transform. One may choose between the fields (<em>Gauss</em>) or (<em>Tesla</em>), the frequency (<em>MHz</em>), and the angular-frequency domain (<em>Mc/s</em>). Default will be ‘<em>MHz</em>’.</p>
|
||
</dd>
|
||
<dt><strong>-ph, - -phase <val></strong></dt><dd><p>defines the initial phase <val>. This only is of concern for ‘<em>real</em>’, ‘<em>imag</em>’, and ‘<em>real+imag</em>’. Default will be 0.0.</p>
|
||
</dd>
|
||
<dt><strong>-fr, - -fourier-range <start> <end></strong></dt><dd><p>Fourier range. <start>, <end> are interpreted in the units given. Default will be -1.0 for both which means, take the full Fourier range.</p>
|
||
</dd>
|
||
<dt><strong>-tr, - -time-range <start> <end></strong></dt><dd><p>time domain range to be used for Fourier transform. <start>, <end> are to be given in (μs). If nothing is provided, the full time range found in the data file(s) will be used.</p>
|
||
</dd>
|
||
<dt><strong>- -histo <list></strong></dt><dd><p>give the <list> of histograms to be used for the Fourier transform. <em>E.g.</em> <code class="docutils literal notranslate"><span class="pre">musrFT</span> <span class="pre">-df</span> <span class="pre">lem15_his_01234.root</span> <span class="pre">--histo</span> <span class="pre">1</span> <span class="pre">3</span></code>, will only be needed together with the option <code class="docutils literal notranslate"><span class="pre">--data-file</span></code>. If multiple data files are given, <list> will apply to all data-files given. If <code class="docutils literal notranslate"><span class="pre">--histo</span></code> is not given, <em>all</em> histos of a data file will be used. <list> can be anything like: 2 3 6, or 2-17, or 1-6 9, etc.</p>
|
||
</dd>
|
||
<dt><strong>-a, - -average</strong></dt><dd><p>show the average of all <strong>ALL</strong> Fourier transformed data.</p>
|
||
</dd>
|
||
<dt><strong>-ad, - -average-per-data-set</strong></dt><dd><p>show the average of <strong>per-data-set</strong> Fourier transformed data.</p>
|
||
</dd>
|
||
<dt><strong>- -t0 <list></strong></dt><dd><p>A list of t0’s can be provided. This in conjunction with <code class="docutils literal notranslate"><span class="pre">--data-file</span></code> and <code class="docutils literal notranslate"><span class="pre">--fourier-option</span> <span class="pre">real</span></code> allows to get the proper initial phase if t0’s are known. If a single t0 for multiple histos is given, it is assume, that this t0 is common to <em>all</em> histos. Example: <code class="docutils literal notranslate"><span class="pre">musrFT</span> <span class="pre">-df</span> <span class="pre">lem15_his_01234.root</span> <span class="pre">-fo</span> <span class="pre">real</span> <span class="pre">--t0</span> <span class="pre">2750</span> <span class="pre">--histo</span> <span class="pre">1</span> <span class="pre">3</span></code>.</p>
|
||
</dd>
|
||
<dt><strong>-pa, - -packing <N></strong></dt><dd><p>if <N> (an integer), the time domain data will first be packed/rebinned by <N>.</p>
|
||
</dd>
|
||
<dt><strong>- -title <title></strong></dt><dd><p>give a global title for the plot.</p>
|
||
</dd>
|
||
<dt><strong>- -create-msr-file <fln></strong></dt><dd><p>creates a msr-file based on the command line options provided. This will help on the way to a full fitting model.</p>
|
||
</dd>
|
||
<dt><strong>-lc, - -lifetimecorrection <fudge></strong></dt><dd><p>try to eliminate the muon life time decay. Only makes sense for low transverse fields. <fudge> is a tweaking factor (scaling factor for the estimated t0) and should be kept around 1.0.</p>
|
||
</dd>
|
||
<dt><strong>- -timeout <timeout></strong></dt><dd><p><timeout> given in seconds after which <code class="docutils literal notranslate"><span class="pre">musrFT</span></code> terminates. If <timeout> <span class="math notranslate nohighlight">\(\leq\)</span> 0, no timeout will take place. Default <timeout> is 3600 sec.</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<p><strong>Example 1</strong></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrFT -df tdc_hifi_2014_00153.mdu --title <span class="s2">"MnSi"</span> -tr <span class="m">0</span> <span class="m">10</span> -fr <span class="m">7</span>.0 <span class="m">7</span>.6 -u Tesla --histo <span class="m">2</span>-17 -a
|
||
</pre></div>
|
||
</div>
|
||
<p>will take time range from t=0..10 μs, will show the Fourier transform in units of Tesla from B=7.0..7.6 Tesla of the detectors 2-17. Rather than showing the 16 individual Fourier transforms, the average of all Fourier spectra will be shown. t0’s will be guessed by the maximum of the time domain histogram (assuming a prompt peak!!).</p>
|
||
<p><strong>Example 2</strong></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrFT -df tdc_hifi_2014_00153.mdu -tr <span class="m">0</span> <span class="m">10</span> -fr <span class="m">7</span>.0 <span class="m">7</span>.6 -u Tesla --histo <span class="m">2</span>-17 --title <span class="s2">"MnSi average, T=50K, B=7.5T"</span> -a -g pdf
|
||
</pre></div>
|
||
</div>
|
||
<p>as <strong>Example 1</strong> but rather than showing an interactive GUI, the output will be dumped into a pdf-file. The file name will be <code class="docutils literal notranslate"><span class="pre">tdc_hifi_2014_00153.pdf</span></code>.</p>
|
||
<p><strong>Example 3</strong></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrFT -df tdc_hifi_2014_00153.mdu -tr <span class="m">0</span> <span class="m">10</span> -fr <span class="m">7</span>.0 <span class="m">7</span>.6 -u Tesla --histo <span class="m">2</span>-17 --title <span class="s2">"MnSi average, T=50K, B=7.5T"</span> -a --dump MnSi.dat
|
||
</pre></div>
|
||
</div>
|
||
<p>as <strong>Example 1</strong> but rather than showing an interactive GUI, the output will be dumped into the ascii file <code class="docutils literal notranslate"><span class="pre">MnSi.dat</span></code>.</p>
|
||
<p>Within the drawn canvas all standard actions applicable to ROOT canvases might be performed. In the menu bar the <code class="docutils literal notranslate"><span class="pre">MusrFT</span></code> menu can be found. From there some <code class="docutils literal notranslate"><span class="pre">musrFT</span></code>-specific actions might be taken</p>
|
||
<dl class="simple">
|
||
<dt><strong>Fourier</strong></dt><dd><p>allows to switch between different Fourier transform representations ‘<em>Power</em>’, ‘<em>Real</em>’, …</p>
|
||
</dd>
|
||
<dt><strong>Average</strong></dt><dd><p>toggle between the current view and the averaged data view.</p>
|
||
</dd>
|
||
<dt><strong>Average per Data Set</strong></dt><dd><p>toggle between the current view and the per data set average view.</p>
|
||
</dd>
|
||
<dt><strong>Export Data</strong></dt><dd><p>saves the selected data in a simple multi-column ASCII file.</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="section" id="musrft-key-shortcuts">
|
||
<span id="index-5"></span><h4>musrFT key-shortcuts<a class="headerlink" href="#musrft-key-shortcuts" title="Permalink to this headline">¶</a></h4>
|
||
<p>Additionally, some functions can be accessed using key-shortcuts:</p>
|
||
<dl class="simple">
|
||
<dt><strong>q</strong></dt><dd><p>quits musrFT.</p>
|
||
</dd>
|
||
<dt><strong>a</strong></dt><dd><p>toggle between average of the presented data and single Fourier histos, <em>e.g.</em> the averaged Fourier power spectra of various detectors.</p>
|
||
</dd>
|
||
<dt><strong>d</strong></dt><dd><p>toggle between average per data set and single Fourier histos, <em>e.g.</em> the averaged Fourier power spectra of various detectors for the different data sets given.</p>
|
||
</dd>
|
||
<dt><strong>u</strong></dt><dd><p>reset the plotting range to the area given in the msr-file or the form the command line (“unzoom”).</p>
|
||
</dd>
|
||
<dt><strong>c</strong></dt><dd><p>toggles between normal and crosshair cursor.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="musrt0">
|
||
<span id="index-6"></span><span id="id5"></span><h3>musrt0<a class="headerlink" href="#musrt0" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrt0</span></code> is a user interface allowing to determine t0 and the time windows of data and background needed to be specified in the RUN blocks of the msr file. It can be operated either as an interactive program or in a non-interactive mode. In the non-interactive mode it accepts the following parameters:</p>
|
||
<dl class="simple">
|
||
<dt><strong><msr_file></strong></dt><dd><p>name of an msr file.</p>
|
||
</dd>
|
||
<dt><strong>-g, - -getT0FromPromptPeak [<firstGoodBinOffset>]</strong></dt><dd><p>tries to estimate t0 from the prompt peak (maximum entry) in each histogram and writes the corresponding values to the t0 lines in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN blocks</span></a> of the msr file. If an optional number <firstGoodBinOffset> is given, the lower limit of the data range will be set to t0 + <firstGoodBinOffset>.</p>
|
||
</dd>
|
||
<dt><strong>- -timeout <timeout></strong></dt><dd><p><timeout> given in seconds after which musrview terminates. If <timeout> <span class="math notranslate nohighlight">\(\leq\)</span> 0, no timeout will take place. Default for <timeout> is 0.</p>
|
||
</dd>
|
||
<dt><strong>- -help</strong></dt><dd><p>displays a small help notice in the shell explaining the basic usage of the program.</p>
|
||
</dd>
|
||
<dt><strong>- -version</strong></dt><dd><p>prints the version number of musrt0.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>The interactive mode of <code class="docutils literal notranslate"><span class="pre">musrt0</span></code> is started if the program is called with a sole msr-file argument, <em>e.g.</em></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ musrt0 <span class="m">8472</span>.msr
|
||
</pre></div>
|
||
</div>
|
||
<p>Then a ROOT canvas depicting the histogram of the data set mentioned first in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN blocks</span></a> block is drawn in different colors:</p>
|
||
<img alt="_images/musrt0.png" src="_images/musrt0.png" />
|
||
<p>The colors of the data points represent the choice of the time windows of data (blue) and background (red), as well as t0 (green line). In order to change these ranges the mouse cross-hair is moved to a channel of choice and one of the following keys is pressed:</p>
|
||
<dl class="simple">
|
||
<dt><strong>q</strong></dt><dd><p>close the currently open histogram and opens the next (see also below) .</p>
|
||
</dd>
|
||
<dt><strong>Q</strong></dt><dd><p>quit <code class="docutils literal notranslate"><span class="pre">musrt0</span></code> without writing into the msr file.</p>
|
||
</dd>
|
||
<dt><strong>z</strong></dt><dd><p>zoom into the region about the t0.</p>
|
||
</dd>
|
||
<dt><strong>u</strong></dt><dd><p>unzoom to the full range.</p>
|
||
</dd>
|
||
<dt><strong>t</strong></dt><dd><p>set t0 bin position.</p>
|
||
</dd>
|
||
<dt><strong>T</strong></dt><dd><p>automatically set t0, <em>i.e.</em> jump to the maximum of the histogram.</p>
|
||
</dd>
|
||
<dt><strong>b</strong></dt><dd><p>set the lower limit of the background range bin.</p>
|
||
</dd>
|
||
<dt><strong>B</strong></dt><dd><p>set the upper limit of the background range bin.</p>
|
||
</dd>
|
||
<dt><strong>d</strong></dt><dd><p>set the lower limit of the data range bin.</p>
|
||
</dd>
|
||
<dt><strong>D</strong></dt><dd><p>set the upper limit of the data range bin.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>When all channels have been set correctly for the first histogram, pressing of the key <strong>q</strong> opens the subsequent histogram listed in a <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> and the respective channels can be updated there. This procedure is repeated until all histograms given in the RUN blocks are processed.</p>
|
||
<p>Using the key <strong>Q</strong>, <code class="docutils literal notranslate"><span class="pre">musrt0</span></code> can be interrupted. No changes to the msr file are applied in this case.</p>
|
||
<p>Closing a window by clicking the X button (close icon) is equivalent to pressing <strong>Q</strong>, <em>i.e.</em> <code class="docutils literal notranslate"><span class="pre">musrt0</span></code> is simply terminated.</p>
|
||
</div>
|
||
<div class="section" id="msr2msr">
|
||
<span id="index-7"></span><h3>msr2msr<a class="headerlink" href="#msr2msr" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">msr2msr</span></code> is a small utility for converting existing WKM msr files into musrfit msr files. It accepts the following parameters:</p>
|
||
<dl class="simple">
|
||
<dt><strong><msr_file_in></strong></dt><dd><p>input WKM msr file (mandatory first parameter).</p>
|
||
</dd>
|
||
<dt><strong><msr_file_out></strong></dt><dd><p>converted output musrfit msr file (mandatory second parameter).</p>
|
||
</dd>
|
||
<dt><strong>- -help</strong></dt><dd><p>displays a small help notice in the shell explaining the basic usage of the program.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>A typical example then looks like:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ msr2msr <span class="m">8472</span>-WKM.msr <span class="m">8472</span>-musrfit.msr
|
||
</pre></div>
|
||
</div>
|
||
<p>If the input file has already the <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> msr file structure, the output file will be just a copy of the input file.</p>
|
||
</div>
|
||
<div class="section" id="msr2data">
|
||
<h3>msr2data<a class="headerlink" href="#msr2data" title="Permalink to this headline">¶</a></h3>
|
||
<p>For details concerning <code class="docutils literal notranslate"><span class="pre">msr2data</span></code> see the section <a class="reference internal" href="msr2data.html#msr2data"><span class="std std-ref">msr2data</span></a>.</p>
|
||
</div>
|
||
<div class="section" id="any2many">
|
||
<span id="index-8"></span><span id="id6"></span><h3>any2many<a class="headerlink" href="#any2many" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">any2many</span></code> is a μSR data file converter. Currently different facilities (PSI, TRIUMF, ISIS, J-PARC) are saving their μSR data files in different formats, or even worse some instruments are using other μSR data formats than others. The aim of <code class="docutils literal notranslate"><span class="pre">any2many</span></code> is that these files can be converted into each other. Of course only a subset of header information can be converted.</p>
|
||
<p>Currently <code class="docutils literal notranslate"><span class="pre">any2many</span></code> can convert the following μSR data file formats:</p>
|
||
<dl class="simple">
|
||
<dt><strong>input formats</strong></dt><dd><p><em>MusrRoot</em>, <em>PSI-BIN</em> (PSI bulk), <em>ROOT</em> (PSI LEM), <em>MUD</em> (TRIUMF), <em>NeXus</em> IDF1 and <em>NeXus</em> IDF2 (ISIS), <em>PSI-MDU</em> (PSI bulk internal only), <em>WKM</em> (outdated ascii file format).</p>
|
||
</dd>
|
||
<dt><strong>output formats</strong></dt><dd><p><em>MusrRoot</em>, <em>PSI-BIN</em>, <em>ROOT</em>, <em>MUD</em>, <em>NeXus1-HDF4</em>, <em>NeXus1-HDF5</em>, <em>NeXus1-XML</em>, <em>NeXus2-HDF4</em>, <em>NeXus2-HDF5</em>, <em>NeXus2-XML</em>, <em>WKM</em>, <em>ASCII</em></p>
|
||
</dd>
|
||
</dl>
|
||
<p>Since the goal was to create a very flexible converter tool, it has ample of options which will listed below, followed by many examples showing how to use it. The options:</p>
|
||
<dl class="simple">
|
||
<dt><strong>-f <filenameList-input></strong></dt><dd><p>where <filenameList-input> is a space separated list of file names (not starting with a ‘-‘), <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0111.root</span> <span class="pre">2010/lem10_his_0113.root</span></code>.</p>
|
||
</dd>
|
||
<dt><strong>-o <outputFileName></strong></dt><dd><p>this option allows to given an output-file-name for the converted file. This option only makes sense if <filenameList-input> is a single input-file-name!</p>
|
||
</dd>
|
||
<dt><strong>-r <runList-input></strong></dt><dd><p>where <runList-input> is a list of run numbers separated by spaces of the form: <run1> <run2> <run3> etc., or a sequence of runs <runStart>-<runEnd>, <em>e.g.</em> 111-123. This option cannot be combined with -f and vice versa.</p>
|
||
</dd>
|
||
<dt><strong>-t <in-template> <out-template></strong></dt><dd><p>where <in-/out-template> are templates to generate real file names from run numbers. The following template tags can be used: <code class="docutils literal notranslate"><span class="pre">[yy]</span></code> for year, and <code class="docutils literal notranslate"><span class="pre">[rrrr]</span></code> for the run number. If the run number tag is used, the number of ‘r’ will give the number of digits used with leading zeros, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">[rrrrrr]</span></code> and run 123 will result in 000123. Similarly <code class="docutils literal notranslate"><span class="pre">[yyyy]</span></code> will result in something like 1999, whereas <code class="docutils literal notranslate"><span class="pre">[yy]</span></code> into something like 99. For more details best check the examples below.</p>
|
||
</dd>
|
||
<dt><strong>-c <in-Format> <out-Format></strong></dt><dd><p>this is used to tell <code class="docutils literal notranslate"><span class="pre">any2many</span></code> what is the input-file-format and into which output-file-format the data shall be converted. The possible input-/output-file-formats are listed above.</p>
|
||
</dd>
|
||
<dt><strong>-h</strong></dt><dd><p>This option is for MusrRoot input files only! Select the the histo groups to be exported. is a space separated list of the histo group, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">-h</span> <span class="pre">0,</span> <span class="pre">20</span></code> will try to export the histo 0 (NPP) and 20 (PPC). A histo-group is defined via the RedGreen offset in the MusrRoot file format. It is used <em>e.g.</em> in red/green mode measurements. If this option is omitted in a conversion from MusrRoot to something, the first group will be exported only!</p>
|
||
</dd>
|
||
<dt><strong>-p <output-path></strong></dt><dd><p>where <output-path> is the output path for the converted files. If no <output-path> is given, the current directory will be used, unless the option <strong>-s</strong> is used.</p>
|
||
</dd>
|
||
<dt><strong>-y <year></strong></dt><dd><p>here a <year> in the form <code class="docutils literal notranslate"><span class="pre">yy</span></code> or <code class="docutils literal notranslate"><span class="pre">yyyy</span></code> can be given. If this is the case, any automatic file name generation which needs a year will use this given one.</p>
|
||
</dd>
|
||
<dt><strong>-s</strong></dt><dd><p>with this option the output data file will be sent to the stdout. It is intended to be used together with web applications.</p>
|
||
</dd>
|
||
<dt><strong>-rebin <n></strong></dt><dd><p>where <n> is the number of bins to be packed/rebinned.</p>
|
||
</dd>
|
||
<dt><strong>-z [g|b] <compressed></strong></dt><dd><p>where <compressed> is the output file name (without extension) of the compressed data collection, and ‘g’ will result in <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code>, and ‘b’ in <code class="docutils literal notranslate"><span class="pre">.tar.bz2</span></code> files.</p>
|
||
</dd>
|
||
<dt><strong>–help</strong></dt><dd><p>displays a help notice in the shell explaining the basic usage of the program.</p>
|
||
</dd>
|
||
<dt><strong>–version</strong></dt><dd><p>shows the current version of <code class="docutils literal notranslate"><span class="pre">any2many</span></code>.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If the template option <cite>-t</cite> is absent, the output file name will be generated according to the input data file name (not possible with <runList-input>), and the output data format.</p>
|
||
<p>Here now a couple of examples which should help to understand the switches.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -f <span class="m">2010</span>/lem10_his_0123.root -c ROOT ASCII -rebin <span class="m">25</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Will take the <em>LEM ROOT</em> file <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0123.root</span></code> rebin it by 25 and convert it to <em>ASCII</em>. The output file name will be <code class="docutils literal notranslate"><span class="pre">lem10_his_0123.ascii</span></code>, and the file will be saved in the current directory. The data in <code class="docutils literal notranslate"><span class="pre">lem10_his_0123.ascii</span></code> are written in columns.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -f <span class="m">2010</span>/lem10_his_0123.root -c ROOT NEXUS2-HDF5 -o <span class="m">2010</span>/lem10_his_0123_v2.nxs
|
||
</pre></div>
|
||
</div>
|
||
<p>Will take the <em>LEM ROOT</em> file <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0123.root</span></code> and convert it to <em>NeXus</em> IDF V2. The output file name will be <code class="docutils literal notranslate"><span class="pre">lem10_his_0123_v2.nxs</span></code>, and will be saved in the current directory.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -r <span class="m">123</span> <span class="m">137</span> -c PSI-BIN MUD -t d<span class="o">[</span>yyyy<span class="o">]</span>/deltat_tdc_gps_<span class="o">[</span>rrrr<span class="o">]</span>.bin <span class="o">[</span>rrrrrr<span class="o">]</span>.msr -y <span class="m">2001</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Will take the run 123 and 137, will generate the input file names: <code class="docutils literal notranslate"><span class="pre">d2001/deltat_tdc_gps_0123.bin</span></code> and <code class="docutils literal notranslate"><span class="pre">d2001/deltat_tdc_gps_0137.bin</span></code>, read these files, and convert them to the output files with names <code class="docutils literal notranslate"><span class="pre">000123.msr`</span> <span class="pre">and</span> <span class="pre">`000137.msr</span></code>, respectively.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -r <span class="m">100</span>-117 -c PSI-MDU ASCII -t d<span class="o">[</span>yyyy<span class="o">]</span>/deltat_tdc_alc_<span class="o">[</span>rrrr<span class="o">]</span>.mdu <span class="o">[</span>rrr<span class="o">]</span>.ascii -y <span class="m">2011</span> -s
|
||
</pre></div>
|
||
</div>
|
||
<p>Will take the runs 100 through 117 and convert the <em>PSI-MDU</em> input files to <em>ASCII</em> output and instead of saving them into a file, they will be spit to the standard output.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -r <span class="m">100</span>-117 -c NEXUS ROOT -t d<span class="o">[</span>yyyy<span class="o">]</span>/psi_gps_<span class="o">[</span>rrrr<span class="o">]</span>.NXS psi_<span class="o">[</span>yyyy<span class="o">]</span>_gps_<span class="o">[</span>rrrr<span class="o">]</span>.root -z b psi_gps_run_100to117
|
||
</pre></div>
|
||
</div>
|
||
<p>Will take the runs 100 through 117 and convert the <em>NeXus</em> input files to <em>ROOT</em> output. Afterwards these new files will be collected in a compressed archive <code class="docutils literal notranslate"><span class="pre">psi_gps_run_100to117.tar.bz2</span></code>.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ any2many -f <span class="m">2010</span>/lem10_his_0123.root <span class="m">2010</span>/lem10_his_0012.root -c ROOT ROOT -rebin <span class="m">25</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Will read the two files <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0123.root</span></code> and <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0012.root</span></code>, rebin them with 25 and export them as <em>LEM ROOT</em> files with adding rebin25 to the name, <em>e.g.</em> <code class="docutils literal notranslate"><span class="pre">2010/lem10_his_0123_rebin25.root</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="dump-header">
|
||
<span id="index-9"></span><h3>dump_header<a class="headerlink" href="#dump-header" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">dump_header</span></code> is a little program which tries to read a μSR data file and sends the relevant information (required header info, start of the histos, etc.) to the standard output. Currently the following μSR data file formats are supported: <em>MusrROOT</em>, <em>ROOT</em> (old LEM format), <em>PSI-BIN</em>, <em>PSI-MDU</em>, <em>NeXus</em> (IDF1 and IDF2), <em>MUD</em>, and <em>WKM</em>.</p>
|
||
<dl class="simple">
|
||
<dt><strong>-rn, - -runNo <runNo></strong></dt><dd><p>run number of the header to be dumped.</p>
|
||
</dd>
|
||
<dt><strong>-fn, - -fileName <fileName></strong></dt><dd><p>muSR data file name.</p>
|
||
</dd>
|
||
<dt><strong>-ff, - -fileFormat <fileFormat></strong></dt><dd><p>where <fileFormat> is one of the above listed ones.</p>
|
||
</dd>
|
||
<dt><strong>-y, - -year <year></strong></dt><dd><p><year> has to be a 4 digit value, <em>e.g.</em> 2005, if provided it is used to generate the file name for the given <runNo>, otherwise the current year is used. If a file name is given, this option has no effect.</p>
|
||
</dd>
|
||
<dt><strong>-s, –summary</strong></dt><dd><p>this option is used for LE-μSR data sets only. It will, additionally to the header information, print the summary file content.</p>
|
||
</dd>
|
||
<dt><strong>–psi-bulk <opt></strong></dt><dd><p>where <opt> consists of two items: (i) pta or tdc, (ii) the instrument name, <em>i.e.</em> gps, ltf, dolly, gpd, or hifi. This is needed in combination with the file formats <em>PSI-BIN</em> and <em>PSI-MDU</em> when providing a run number.</p>
|
||
</dd>
|
||
<dt><strong>-h, –help</strong></dt><dd><p>will show a short help.</p>
|
||
</dd>
|
||
<dt><strong>-v, –version</strong></dt><dd><p>will print the current version.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>Examples:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ dump_header -fn tdc_hifi_2015_00123.mdu -y <span class="m">2015</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>will dump the header information for the run 123 of the HAL-9500 instrument of the year 2015.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ dump_header -rn <span class="m">123</span> -ff PSI-MDU --psi-bulk tdc hifi -y <span class="m">2015</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>the same as the previous example, except that the file name is constructed via the number and the additionally provided information.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ dump_header -rn <span class="m">3456</span> -s
|
||
</pre></div>
|
||
</div>
|
||
<p>Will dump the LEM header information of run 3456 including the content of the run summary file.</p>
|
||
</div>
|
||
<div class="section" id="musrfit-startup-xml">
|
||
<span id="musrfit-startup"></span><span id="index-10"></span><h3>musrfit_startup.xml<a class="headerlink" href="#musrfit-startup-xml" title="Permalink to this headline">¶</a></h3>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrfit_startup.xml</span></code> is a configuration file located at <code class="docutils literal notranslate"><span class="pre">$HOME\.musrfit</span></code>. In this file the following XML tags are allowed to define settings:</p>
|
||
<dl>
|
||
<dt><strong><data_path>PATH_TO_DATA</data_path></strong></dt><dd><p>add the new path <code class="docutils literal notranslate"><span class="pre">PATH_TO_DATA</span></code> where <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> and <code class="docutils literal notranslate"><span class="pre">musrview</span></code> will search for data files.</p>
|
||
</dd>
|
||
<dt><strong><write_per_run_block_chisq>y/n</write_per_run_block_chisq></strong></dt><dd><p>if enabled <span class="math notranslate nohighlight">\(\chi^2\)</span> for each <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> will be written to the <a class="reference internal" href="#msr-statistic-block"><span class="std std-ref">STATISTIC block</span></a> of the resulting msr file. Additionally,
|
||
in case a <span class="math notranslate nohighlight">\(\chi^2\)</span> single-histogram fit is done, also <a class="reference external" href="http://en.wikipedia.org/wiki/Pearson's_chi-square_test">Pearson’s</a> <span class="math notranslate nohighlight">\(\chi^2\)</span> will be added.</p>
|
||
</dd>
|
||
<dt><strong><fourier_settings></fourier_settings></strong></dt><dd><p>set the default parameters for the Fourier transform in <code class="docutils literal notranslate"><span class="pre">musrview</span></code>. For further details refer to the description of the <a class="reference internal" href="#msr-fourier-block"><span class="std std-ref">FOURIER block</span></a> in the msr file.</p>
|
||
<dl class="simple">
|
||
<dt><strong><units>UNITS</units></strong></dt><dd><p>specify the units of the frequency or field-domain. Valid units are <em>Gauss</em>, <em>MHz</em> and <em>Mc/s</em> (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
<dt><strong><fourier_power>n</fourier_power></strong></dt><dd><p>specify the number of points <span class="math notranslate nohighlight">\(2^n (n < 21)\)</span> to be used for the Fourier transform (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
<dt><strong><apodization>APOD</apodization></strong></dt><dd><p>set the default apodization method. Valid apodizations are <em>none</em>, <em>weak</em>, <em>medium</em>, and <em>strong</em> (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
<dt><strong><plot>PLOT</plot></strong></dt><dd><p>specify which part of the Fourier transform is plotted by default. You can choose between <em>real</em>, <em>imag</em>, <em>real_and_imag</em>, <em>power</em>, and <em>phase</em> (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
<dt><strong><phase>PH</phase></strong></dt><dd><p>set the initial phase shift PH (in degrees) of the data to be Fourier transformed (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
<dt><strong><phase_increment>PHINCR</phase_increment></strong></dt><dd><p>change the default value of the phase increment (in degrees) used for the phase optimization to PHINCR (inside a <fourier_settings> environment).</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
<dt><strong><root_settings></root_settings></strong></dt><dd><p>change the default ROOT settings.</p>
|
||
<dl>
|
||
<dt><strong><marker_list></marker_list></strong></dt><dd><p>specify the order in which <code class="docutils literal notranslate"><span class="pre">musrview</span></code> should use markers when plotting data (inside a <root_settings> environment).</p>
|
||
<dl class="simple">
|
||
<dt><strong><marker>X</marker></strong></dt><dd><p>use the ROOT marker number X (inside a <marker_list> environment).</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
<dt><strong><color_list></color_list></strong></dt><dd><p>specify the order in which <code class="docutils literal notranslate"><span class="pre">musrview</span></code> should use colors when plotting data (inside a <root_settings> environment).</p>
|
||
<dl class="simple">
|
||
<dt><strong><color>R,G,B</color></strong></dt><dd><p>use the RGB coded color (inside a <color_list> environment).</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<p>An example would look like:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
|
||
<span class="nt"><musrfit</span> <span class="na">xmlns=</span><span class="s">"https://intranet.psi.ch/MUSR/MusrFit"</span><span class="nt">></span>
|
||
<span class="nt"><data_path></span>/mnt/data/nemu/his<span class="nt"></data_path></span>
|
||
<span class="nt"><write_per_run_block_chisq></span>y<span class="nt"></write_per_run_block_chisq></span>
|
||
<span class="nt"><fourier_settings></span>
|
||
<span class="nt"><units></span>Gauss<span class="nt"></units></span>
|
||
<span class="nt"><fourier_power></span>0<span class="nt"></fourier_power></span>
|
||
<span class="nt"><apodization></span>none<span class="nt"></apodization></span>
|
||
<span class="nt"><plot></span>real_and_imag<span class="nt"></plot></span>
|
||
<span class="nt"><phase></span>0.0<span class="nt"></phase></span>
|
||
<span class="nt"><phase_increment></span>1.0<span class="nt"></phase_increment></span>
|
||
<span class="nt"></fourier_settings></span>
|
||
<span class="nt"><root_settings></span>
|
||
<span class="nt"><marker_list></span>
|
||
<span class="c"><!-- Root marker numbers --></span>
|
||
<span class="nt"><marker></span>24<span class="nt"></marker></span>
|
||
<span class="nt"><marker></span>25<span class="nt"></marker></span>
|
||
<span class="nt"><marker></span>26<span class="nt"></marker></span>
|
||
<span class="nt"><marker></span>27<span class="nt"></marker></span>
|
||
<span class="nt"></marker_list></span>
|
||
<span class="nt"><color_list></span>
|
||
<span class="c"><!-- Color as RGB coded string --></span>
|
||
<span class="nt"><color></span>0,0,0<span class="nt"></color></span>
|
||
<span class="nt"><color></span>255,0,0<span class="nt"></color></span>
|
||
<span class="nt"><color></span>0,255,0<span class="nt"></color></span>
|
||
<span class="nt"><color></span>0,0,255<span class="nt"></color></span>
|
||
<span class="nt"></color_list></span>
|
||
<span class="nt"></root_settings></span>
|
||
<span class="nt"></musrfit></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="description-of-the-msr-file-format">
|
||
<span id="msr-file-format"></span><span id="index-11"></span><h2>Description of the msr File Format<a class="headerlink" href="#description-of-the-msr-file-format" title="Permalink to this headline">¶</a></h2>
|
||
<p>The programs are using an input file to control their action. This input file has the extension <code class="docutils literal notranslate"><span class="pre">.msr</span></code> (msr file). The msr file is built up from different blocks. Each block starts with a keyword and is, with the exception of the title, terminated by an empty line. Comments start with the character <code class="docutils literal notranslate"><span class="pre">#</span></code>. The various input blocks are described below.</p>
|
||
<div class="section" id="the-title">
|
||
<span id="msr-title-block"></span><span id="index-12"></span><h3>The Title<a class="headerlink" href="#the-title" title="Permalink to this headline">¶</a></h3>
|
||
<p>The first line of the msr file is the title line. Unlike all the other input blocks, it does not start with a block keyword. It is just a simple text line, in which any information can be placed. The title text will be used in the graphical representation of the data as a headline.</p>
|
||
</div>
|
||
<div class="section" id="the-fitparameter-block">
|
||
<span id="msr-fitparameter-block"></span><span id="index-13"></span><h3>The FITPARAMETER Block<a class="headerlink" href="#the-fitparameter-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The FITPARAMETER block is used to define the fit parameters in a MINUIT typical style. There are various possible parameter definitions which are listed here:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mf">1.</span> <span class="o"><</span><span class="n">no</span><span class="o">></span> <span class="o"><</span><span class="n">name</span><span class="o">></span> <span class="o"><</span><span class="n">value</span><span class="o">></span> <span class="o"><</span><span class="n">step</span><span class="o">></span>
|
||
<span class="mf">2.</span> <span class="o"><</span><span class="n">no</span><span class="o">></span> <span class="o"><</span><span class="n">name</span><span class="o">></span> <span class="o"><</span><span class="n">value</span><span class="o">></span> <span class="o"><</span><span class="n">step</span><span class="o">></span> <span class="o"><</span><span class="n">lower_boundary</span><span class="o">></span> <span class="o"><</span><span class="n">upper_boundary</span><span class="o">></span>
|
||
<span class="mf">3.</span> <span class="o"><</span><span class="n">no</span><span class="o">></span> <span class="o"><</span><span class="n">name</span><span class="o">></span> <span class="o"><</span><span class="n">value</span><span class="o">></span> <span class="o"><</span><span class="n">step</span><span class="o">></span> <span class="o"><</span><span class="n">pos_error</span><span class="o">></span> <span class="o"><</span><span class="n">lower_boundary</span><span class="o">></span> <span class="o"><</span><span class="n">upper_boundary</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <no> is the parameter number, <name> is the parameter name <a class="footnote-reference brackets" href="#f1" id="id7">1</a>, <value> is the initial guess of the parameter, <step> the inital step width, <lower/upper_boundary> is the lower/upper boundary for the parameter <a class="footnote-reference brackets" href="#f2" id="id8">2</a>.</p>
|
||
<p>In the output file, <value> will be the MINUIT fit value, <step> will contain the error estimate (or the negative error estimate if MINOS was successfully used), <pos_error> will have the value <em>none</em> if MINOS has not been used, otherwise it will show the positive error estimate.</p>
|
||
<p>A typical example looks like this:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FITPARAMETER</span>
|
||
<span class="c1"># No Name Value Step Pos_Error Boundaries</span>
|
||
<span class="mi">1</span> <span class="n">alpha</span> <span class="mi">1</span> <span class="mf">0.02</span> <span class="n">none</span> <span class="mi">0</span> <span class="mf">1.8</span>
|
||
<span class="mi">2</span> <span class="n">asy</span> <span class="mf">0.1042</span> <span class="mf">0.004713</span> <span class="n">none</span> <span class="mi">0</span> <span class="mf">0.33</span>
|
||
<span class="mi">3</span> <span class="n">phase</span> <span class="mi">15</span> <span class="mf">1.0</span> <span class="n">none</span>
|
||
<span class="mi">4</span> <span class="n">freq</span> <span class="mf">0.9</span> <span class="mf">0.0379</span> <span class="n">none</span>
|
||
<span class="mi">5</span> <span class="n">rate</span> <span class="mf">0.03</span> <span class="mf">0.00579</span> <span class="n">none</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>There is also the possibility to constrain the parameters to semi-defined intervals (like par > a or par < b). The syntax is as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FITPARAMETER</span>
|
||
<span class="c1"># No Name Value Step Pos_Error Boundaries</span>
|
||
<span class="c1"># Specify only a lower boundary for the parameter</span>
|
||
<span class="mi">1</span> <span class="n">Asy1</span> <span class="mf">0.04501</span> <span class="o">-</span><span class="mf">0.00208</span> <span class="mf">0.00211</span> <span class="mi">0</span> <span class="n">none</span>
|
||
|
||
<span class="c1"># Specify only an upper boundary for the parameter</span>
|
||
<span class="mi">2</span> <span class="n">Rate1</span> <span class="mf">0.14245</span> <span class="o">-</span><span class="mf">0.02501</span> <span class="mf">0.02279</span> <span class="n">none</span> <span class="mi">10</span>
|
||
|
||
<span class="c1"># Specify lower and upper boundaries for the parameter</span>
|
||
<span class="mi">3</span> <span class="n">Asy2</span> <span class="mf">0.14501</span> <span class="o">-</span><span class="mf">0.00208</span> <span class="mf">0.00211</span> <span class="mi">0</span> <span class="mf">0.33</span>
|
||
|
||
<span class="c1"># Do not specify boundaries at all</span>
|
||
<span class="mi">4</span> <span class="n">Field2</span> <span class="mf">343.212</span> <span class="o">-</span><span class="mf">2.27960</span> <span class="mf">2.27885</span>
|
||
<span class="mi">5</span> <span class="n">Rate2</span> <span class="mf">0.42045</span> <span class="o">-</span><span class="mf">0.02501</span> <span class="mf">0.02279</span> <span class="n">none</span> <span class="n">none</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="rubric">Notes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="f1"><span class="brackets"><a class="fn-backref" href="#id7">1</a></span></dt>
|
||
<dd><p>A standard string without whitespace.</p>
|
||
</dd>
|
||
<dt class="label" id="f2"><span class="brackets"><a class="fn-backref" href="#id8">2</a></span></dt>
|
||
<dd><p>According to the MINUIT manual this should be avoided whenever possible!</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="the-theory-block">
|
||
<span id="msr-theory-block"></span><span id="index-14"></span><h3>The THEORY Block<a class="headerlink" href="#the-theory-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The THEORY block is used to define the fit function. There is a set of predefined functions available. It is also possible to use externally defined functions. How to use them will be explained afterwards, here only the predefined functions are described.</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 4%" />
|
||
<col style="width: 2%" />
|
||
<col style="width: 14%" />
|
||
<col style="width: 77%" />
|
||
<col style="width: 3%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>name</p></th>
|
||
<th class="head"><p>abbr.</p></th>
|
||
<th class="head"><p>parameters</p></th>
|
||
<th class="head"><p>mathematical expression</p></th>
|
||
<th class="head"><p>notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>const</p></td>
|
||
<td><p>c</p></td>
|
||
<td><p>const(1)</p></td>
|
||
<td><p>const</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>asymmetry</p></td>
|
||
<td><p>a</p></td>
|
||
<td><p>A(1)</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(A\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>simplExpo</p></td>
|
||
<td><p>se</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\exp(-\lambda t)\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>generExpo</p></td>
|
||
<td><p>ge</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1}) \beta(1)\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\exp\left[-(\lambda t)^\beta\right]\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>simpleGss</p></td>
|
||
<td><p>sg</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\exp\left[-\frac{1}{2} (\sigma t)^2\right]\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>statGssKT</p></td>
|
||
<td><p>stg</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\frac{1}{3} + \frac{2}{3} \left[ 1 - (\sigma t)^2\right] \exp\left[-\frac{1}{2} (\sigma t)^2\right]\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>statGssKTLF</p></td>
|
||
<td><p>sgktlf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(G_{\rm G}^{\rm LF}(t) = 1-\frac{2\sigma^2}{(2\pi\nu)^2} \left[ 1-\exp\left(- \frac{1}{2}\sigma^2t^2\right)\cos(2\pi\nu t)\right]\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ \frac{2\sigma^4}{(2\pi\nu)^3} \int_0^t \exp\left(- \frac{1}{2}\sigma^2\tau^2\right) \sigma(2\pi\nu\tau) d\tau\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n1" id="id9">3</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>dynGssKTLF</p></td>
|
||
<td><p>dgktlf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\Gamma\)</span> (MHz)</p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\frac{1}{2\pi i} \int_{\gamma+i\infty}^{\gamma-i\infty} \frac{f_{\rm G}(s+\Gamma)}{1-\Gamma f_{\rm G}(s+\Gamma)} \exp(s t) ds\)</span>,</dt><dd><p>where <span class="math notranslate nohighlight">\(f_{\rm G}(s) = \int_0^\infty G_{\rm G}^{\rm LF}(t) \exp(-s t) dt\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n2" id="id10">4</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>statExpKT</p></td>
|
||
<td><p>sekt</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\frac{1}{3} + \frac{2}{3} \left[ 1 - \lambda t\right] \exp(-\lambda t)\)</span></p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#n3" id="id11">5</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>statExpKTLF</p></td>
|
||
<td><p>sektlf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(a (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(1 - \frac{a}{2\pi\nu} j_1(2\pi\nu t) \exp(-a t)\)</span></dt><dd><p><span class="math notranslate nohighlight">\(- \left(\frac{a}{2\pi\nu}\right)^2 \left[j_0(2\pi\nu t)\exp(-a t)-1\right]\)</span>
|
||
<span class="math notranslate nohighlight">\(- a \left[1+\left(\frac{a}{2\pi\nu}\right)^2\right] \int_0^t \exp(-a\tau) j_0(2\pi\nu\tau) d\tau = G_{\rm L}^{\rm LF}(t)\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n4" id="id12">6</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>dynExpKTLF</p></td>
|
||
<td><p>dektlf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(a (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\Gamma\)</span> (MHz)</p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\frac{1}{2\pi i} \int_{\gamma+i\infty}^{\gamma-i\infty} \frac{f_{\rm L}(s+\Gamma)}{1-\Gamma f_{\rm L}(s+\Gamma)} \exp(s t) ds\)</span>,</dt><dd><p>where <span class="math notranslate nohighlight">\(f_{\rm L}(s) = \int_0^\infty G_{\rm L}^{\rm LF}(t) \exp(-s t) dt\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n5" id="id13">7</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>combiLGKT</p></td>
|
||
<td><p>lgkt</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\frac{1}{3} + \frac{2}{3} (1 - \sigma^2 t^2 -\lambda t) \exp\left(-\frac{\sigma^2 t^2}{2}-\lambda t\right)\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>strKT</p></td>
|
||
<td><p>skt</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1}),~\beta(1)\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\frac{1}{3} + \frac{2}{3} \left[ 1 - (\sigma t)^\beta\right] \exp\left[-(\sigma t)^\beta / \beta \right]\)</span></p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#n6" id="id14">8</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>spinGlass</p></td>
|
||
<td><p>spg</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\gamma (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(q (1)\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\frac{1}{3} \exp\left(-\sqrt{\Omega t}\right) +\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ \frac{2}{3} \left(1 - \frac{q\lambda^2 t^2}{\sqrt{\Omega t+ q\lambda^2 t^2}}\right) \exp(-\sqrt{\Omega t + q \lambda^2 t^2})\)</span>,
|
||
<span class="math notranslate nohighlight">\(\Omega t = \frac{4 \lambda^2 (1-q) t}{\gamma}\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>rdAnisoHf</p></td>
|
||
<td><p>rahf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\lambda (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\frac{1}{6} (1-\nu t/2) \exp(-\nu t/2) +\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ \frac{1}{3} (1 - \nu t/4) \exp(-\frac{\nu t + 2.44949 \lambda t}{4})\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n7" id="id15">9</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>TFieldCos</p></td>
|
||
<td><p>tf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz)</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\cos\left(2\pi\nu t + \frac{\pi \varphi}{180}\right)\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>internFld</p></td>
|
||
<td><p>if</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\alpha (1), \varphi (^\circ)\)</span>, <span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\lambda_{\rm T} (\mu \mathrm{s}^{-1})\)</span>,<span class="math notranslate nohighlight">\(\lambda_{\rm L} (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\alpha \cos\left(2\pi\nu t + \frac{\pi \varphi}{180}\right) \exp(-\lambda_{\rm T}t) +\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ (1-\alpha) \exp(-\lambda_{\rm L} t)\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Bessel</p></td>
|
||
<td><p>b</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz)</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(j_0\left(2\pi\nu t + \frac{\pi \varphi}{180}\right)\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>internbsl</p></td>
|
||
<td><p>ib</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\alpha (1), \varphi (^\circ)\)</span>, <span class="math notranslate nohighlight">\(\nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\lambda_{\rm T} (\mu \mathrm{s}^{-1})\)</span>,<span class="math notranslate nohighlight">\(\lambda_{\rm L} (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\alpha j_0\left(2\pi\nu t + \frac{\pi \varphi}{180}\right) \exp(-\lambda_{\rm T}t) +\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ (1-\alpha) \exp(-\lambda_{\rm L} t)\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>internFldGK</p></td>
|
||
<td><p>ifgk</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\alpha (1), \nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\lambda (\mu\mathrm{s}^{-1}), \beta (1)\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\alpha\left[\cos(2\pi\nu t)-\frac{\sigma^2 t}{2\pi\nu}\sin(2\pi\nu t)\right]\exp(-\sigma^2 t^2/2)+\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ (1-\alpha) \exp(-(\lambda t)^\beta)\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n8" id="id16">10</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>internFldLL</p></td>
|
||
<td><p>ifll</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\alpha (1), \nu\)</span> (MHz), <span class="math notranslate nohighlight">\(a (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\lambda (\mu\mathrm{s}^{-1}), \beta (1)\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\alpha\left[\cos(2\pi\nu t)-\frac{a}{2\pi\nu}\sin(2\pi\nu t)\right]\exp(-a t)+\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ (1-\alpha) \exp(-(\lambda t)^\beta)\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n9" id="id17">11</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>abragam</p></td>
|
||
<td><p>ab</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sigma (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\gamma\)</span> (MHz)</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\exp\left[-\frac{\sigma^2}{\gamma^2} (e^{-\gamma t} - 1 + \gamma t)\right]\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>skewedGss</p></td>
|
||
<td><p>skg</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz) <span class="math notranslate nohighlight">\(\sigma_{+} (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\sigma_{-} (\mu \mathrm{s}^{-1})\)</span></p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\frac{\sigma_{-}}{\sigma_{+}+\sigma_{-}} \exp\left[\frac{\sigma_{-}^2 t^2}{2}\right] \left\{\cos(2\pi\nu t + \frac{\pi\varphi}{180}) + \sin(2\pi\nu t + \frac{\pi\varphi}{180}) \mathrm{Erfi}\left(\frac{\sigma_{-} t}{\sqrt{2}}\right)\right\} +\)</span></dt><dd><p><span class="math notranslate nohighlight">\(+ \frac{\sigma_{+}}{\sigma_{+}+\sigma_{-}} \exp\left[\frac{\sigma_{+}^2 t^2}{2}\right] \left\{\cos(2\pi\nu t + \frac{\pi\varphi}{180}) - \sin(2\pi\nu t + \frac{\pi\varphi}{180}) \mathrm{Erfi}\left(\frac{\sigma_{+} t}{\sqrt{2}}\right)\right\}\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p><a class="footnote-reference brackets" href="#n10" id="id18">12</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>staticNKZF</p></td>
|
||
<td><p>snkzf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\Delta_0 (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(R_b = \Delta_{\rm GbG}/\Delta_0 (1)\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\frac{1}{3} + \frac{2}{3}\left(\frac{1}{1+R_b^2\Delta_0^2 t^2}\right)^{3/2} \left(1 - \frac{\Delta_0^2 t^2}{1+R_b^2\Delta_0^2 t^2}\right) \exp\left[-\frac{\Delta_0^2 t^2}{2(1+R_b^2\Delta_0^2 t^2)}\right]\)</span></p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#n11" id="id19">13</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>staticNKTF</p></td>
|
||
<td><p>snktf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\Delta_0 (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(R_b = \Delta_{\rm GbG}/\Delta_0 (1)\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sqrt{\frac{1}{1+R_b^2 \Delta_0^2 t^2}} \exp\left[-\frac{\Delta_0^2 t^2}{2(1+R_b^2 \Delta_0^2 t^2)}\right] \cos(2\pi\nu t + \varphi)\)</span></p></td>
|
||
<td><p>see [13]</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>dynamicNKZF</p></td>
|
||
<td><p>dnkzf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\Delta_0 (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(R_b = \Delta_{\rm GbG}/\Delta_0 (1)\)</span>, <span class="math notranslate nohighlight">\(\nu_c\)</span> (MHz)</p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\sqrt{\frac{1}{1+4 R_b^2 \Delta_0^2 \Theta(t)}} \exp\left[-\frac{2\Delta_0^2 \Theta(t)}{1+4 R_b^2 \Delta_0^2 \Theta(t)}\right]\)</span>,</dt><dd><p><span class="math notranslate nohighlight">\(\Theta(t) = \frac{\exp(-\nu_c t) -1 -\nu_c t}{\nu_c^2}\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p>see [13]</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>dynamicNKTF</p></td>
|
||
<td><p>dnktf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz), <span class="math notranslate nohighlight">\(\Delta_0 (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(R_b = \Delta_{\rm GbG}/\Delta_0 (1)\)</span>, <span class="math notranslate nohighlight">\(\nu_c\)</span> (MHz)</p></td>
|
||
<td><dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(\sqrt{\frac{1}{1+2 R_b^2 \Delta_0^2 \Theta(t)}} \exp\left[-\frac{\Delta_0^2 \Theta(t)}{1+2 R_b^2 \Delta_0^2 \Theta(t)}\right] \cos(2\pi\nu t + \varphi)\)</span>,</dt><dd><p><span class="math notranslate nohighlight">\(\Theta(t) = \frac{\exp(-\nu_c t) -1 -\nu_c t}{\nu_c^2}\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
<td><p>see [13]</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>muMinusExpTF</p></td>
|
||
<td><p>mmsetf</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(N_0 (1), \tau (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(A (1), \lambda (\mu \mathrm{s}^{-1})\)</span>, <span class="math notranslate nohighlight">\(\varphi (^\circ), \nu\)</span> (MHz)</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(N_0 \exp(-t/\tau) \left[ 1 + A \exp(-\lambda t) \cos(2 \pi \nu t + \varphi) \right]\)</span></p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#n12" id="id20">14</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>polynom</p></td>
|
||
<td><p>p</p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(t_0 ([t]), a_0 (1)\)</span>, <span class="math notranslate nohighlight">\(a_1 (t), \ldots, a_n (1)\)</span></p></td>
|
||
<td><p><span class="math notranslate nohighlight">\(\sum_{k=0}^n a_k (t-t_0)^k\)</span></p></td>
|
||
<td></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="rubric">Notes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="n1"><span class="brackets"><a class="fn-backref" href="#id9">3</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://link.aps.org/doi/10.1103/PhysRevB.20.850">R.S. Hayano</a> <em>et al.</em>, Phys. Rev. B <strong>20</strong>, 850 (1979). – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n2"><span class="brackets"><a class="fn-backref" href="#id10">4</a></span></dt>
|
||
<dd><p>R.S. Hayano <em>et al.</em>, Phys. Rev. B <strong>20</strong>, 850 (1979).,
|
||
<a class="reference external" href="http://dx.doi.org/10.1088/0953-8984/4/18/020">P. Dalmas de Réotier</a> and A. Yaouanc, J. Phys.: Condens. Matter <strong>4</strong>, 4533 (1992).,
|
||
<a class="reference external" href="http://link.aps.org/doi/10.1103/PhysRevB.50.10039">A. Keren</a>, Phys. Rev. B <strong>50</strong>, 10039 (1994). – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n3"><span class="brackets"><a class="fn-backref" href="#id11">5</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://link.aps.org/doi/10.1103/PhysRevB.31.546">Y.J. Uemura</a> <em>et al.</em>, Phys. Rev. B <strong>31</strong>, 546 (1985). – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n4"><span class="brackets"><a class="fn-backref" href="#id12">6</a></span></dt>
|
||
<dd><p>Y.J. Uemura <em>et al.</em>, Phys. Rev. B <strong>31</strong>, 546 (1985). – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n5"><span class="brackets"><a class="fn-backref" href="#id13">7</a></span></dt>
|
||
<dd><p>R.S. Hayano <em>et al.</em>, Phys. Rev. B <strong>20</strong>, 850 (1979)., P. Dalmas de Réotier and A. Yaouanc, J. Phys.: Condens. Matter <strong>4</strong>, 4533 (1992). – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n6"><span class="brackets"><a class="fn-backref" href="#id14">8</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://dx.doi.org/10.1088/0953-8984/9/5/018">M.R. Crook</a> and R. Cywinski, J. Phys.: Condens. Matter <strong>9</strong> 1149 (1997).</p>
|
||
</dd>
|
||
<dt class="label" id="n7"><span class="brackets"><a class="fn-backref" href="#id15">9</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://link.aps.org/doi/10.1103/PhysRevB.34.4467">R.E. Turner</a> and D.R. Harshman, Phys. Rev. B <strong>34</strong>, 4467 (1986).</p>
|
||
</dd>
|
||
<dt class="label" id="n8"><span class="brackets"><a class="fn-backref" href="#id16">10</a></span></dt>
|
||
<dd><p><a class="reference external" href="https://doi.org/10.1016/0375-9601(91)90959-C">E.I. Kornilov</a> and V.Yu. Pomjakushin, Physics Letters A <strong>153</strong>, 364, (1991).
|
||
In the original work, <span class="math notranslate nohighlight">\(\alpha=2/3,\, \lambda=0,\, \beta=1\)</span>. If you find values strongly deviating from these values you should question your analysis approach.</p>
|
||
</dd>
|
||
<dt class="label" id="n9"><span class="brackets"><a class="fn-backref" href="#id17">11</a></span></dt>
|
||
<dd><p><a class="reference external" href="https://doi.org/10.1016/S0921-4526(00)00337-9">M.I. Larkin</a> <em>et al.</em>, Physica B: Condensed Matter <strong>289-290</strong>, 153 (2000).
|
||
In the original work, <span class="math notranslate nohighlight">\(\alpha=2/3,\, \lambda=0,\, \beta=1\)</span>. If you find values strongly deviating from these values you should question your analysis approach.</p>
|
||
</dd>
|
||
<dt class="label" id="n10"><span class="brackets"><a class="fn-backref" href="#id18">12</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://lmu.web.psi.ch/musrfit/memos/skewedGaussian.pdf">see memo</a> – <strong>not</strong> DKS ready.</p>
|
||
</dd>
|
||
<dt class="label" id="n11"><span class="brackets"><a class="fn-backref" href="#id19">13</a></span></dt>
|
||
<dd><p><a class="reference external" href="http://link.aps.org/doi/10.1103/PhysRevB.56.2352">D.R. Noakes</a> and G.M. Kalvius, Phys. Rev. B <strong>56</strong>, 2352 (1997);
|
||
A. Yaouanc and P. Dalmas de Réotier “Muon Spin Rotation, Relaxation, and Resonance” Oxford Scientific Publication;
|
||
simplifying the original formulae by eliminating <span class="math notranslate nohighlight">\(\Delta_{\rm eff}\)</span> via the identity
|
||
<span class="math notranslate nohighlight">\(\Delta_{\rm eff}^2 = (1+R_b^2)\Delta_0\)</span>.</p>
|
||
</dd>
|
||
<dt class="label" id="n12"><span class="brackets"><a class="fn-backref" href="#id20">14</a></span></dt>
|
||
<dd><p>This function is explicit for <span class="math notranslate nohighlight">\(\mu^-\)</span>! Do not try to use it for <span class="math notranslate nohighlight">\(\mu^+\)</span>!</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="section" id="maps">
|
||
<span id="msr-map-intro"></span><h4>Maps<a class="headerlink" href="#maps" title="Permalink to this headline">¶</a></h4>
|
||
<p>There are two situations where the theory function needs an additional switch/map allowing a compact and flexible handling of the fit.</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Typically your spectrometer has a couple of detectors. Hence, in a TF experiment all these detectors will have at least a different initial phase.
|
||
Maps allow exactly to deal with this difficulty.</p></li>
|
||
<li><p>In case different runs are fitted simultaneously, it is very often necessary that for a given theory function, some parameters are run-dependent.
|
||
An example could be a temperature scan, where the parameters (asymmetry, depolarization rates, etc.) will depend on the temperature.</p></li>
|
||
</ol>
|
||
<p>In order to handle such situations, a mapping of parameters in the THEORY block is possible. That means, instead of a parameter number,
|
||
the mapping of the parameter is given. The definition of the mapping block is part of the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> and will be described there.
|
||
For example</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">THEORY</span>
|
||
<span class="n">asymmetry</span> <span class="mi">2</span>
|
||
<span class="n">simplExpo</span> <span class="mi">3</span>
|
||
<span class="n">TFieldCos</span> <span class="n">map1</span> <span class="mi">5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>means that the phase parameter of <code class="docutils literal notranslate"><span class="pre">TFieldCos</span></code> will be mapped to <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>, and hence every detector will have its individual phase.</p>
|
||
</div>
|
||
<div class="section" id="functions">
|
||
<h4>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h4>
|
||
<p>Yet another useful feature is the possibility to define functions in the <a class="reference internal" href="#msr-functions-block"><span class="std std-ref">FUNCTIONS block</span></a>.
|
||
Within the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a> these functions can be addressed as funX, where ‘X’ is the function number, <em>e.g.</em> fun2.
|
||
Whereas the theory is operating on the parameters and the time, functions currently can <em>only</em> operate on the parameters.</p>
|
||
</div>
|
||
<div class="section" id="user-functions">
|
||
<span id="msr-theory-block-user-functions"></span><h4>User Functions<a class="headerlink" href="#user-functions" title="Permalink to this headline">¶</a></h4>
|
||
<p>In the case complicated and not predefined functions are needed to fit data, <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> offers the possibility to implement external functions
|
||
and introduce them to <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> through the ROOT dictionary mechanism. The detailed rules these user-defined functions have to obey will be discussed
|
||
in the according <a class="reference internal" href="#id38"><span class="std std-ref">section</span></a>. Here only the syntax for the msr file is provided. To call a user function in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a> the
|
||
keyword <code class="docutils literal notranslate"><span class="pre">userFcn</span></code> is used. It is followed by the name of the shared library which holds the C++ class where the function is implemented and the name of
|
||
the class. Finally, all parameters are given in the order needed by the class. Of course it is also possible to use mapped parameters or functions
|
||
instead of specifying the parameters directly.</p>
|
||
<p>A THEORY block including a user function may then look like</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">THEORY</span>
|
||
<span class="n">asymmetry</span> <span class="mi">1</span>
|
||
<span class="n">userFcn</span> <span class="n">libMyLibrary</span><span class="o">.</span><span class="n">so</span> <span class="n">TMyFunction</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="n">map1</span> <span class="n">fun1</span>
|
||
<span class="o">+</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-functions-block">
|
||
<span id="msr-functions-block"></span><span id="index-15"></span><h3>The FUNCTIONS Block<a class="headerlink" href="#the-functions-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>Here some auxiliary functions can be defined. These functions can currently <em>only</em> operate on the defined parameters. They can be used in the
|
||
<a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a> and for one specific case in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>. Supported is the use of basic arithmetic:</p>
|
||
<dl class="simple">
|
||
<dt><span class="math notranslate nohighlight">\(+\)</span></dt><dd><p>Addition</p>
|
||
</dd>
|
||
<dt><span class="math notranslate nohighlight">\(-\)</span></dt><dd><p>Subtraction</p>
|
||
</dd>
|
||
<dt><span class="math notranslate nohighlight">\(*\)</span></dt><dd><p>Multiplication</p>
|
||
</dd>
|
||
<dt><span class="math notranslate nohighlight">\(/\)</span></dt><dd><p>Division</p>
|
||
</dd>
|
||
<dt><span class="math notranslate nohighlight">\(()\)</span></dt><dd><p>The standard use of parentheses</p>
|
||
</dd>
|
||
</dl>
|
||
<p>The following functions are built-in and can be used in a function definition: <strong>cos(), sin(), tan(), acos(), asin(), atan(), cosh(), sinh(), tanh(),
|
||
acosh(), asinh(), atanh(), exp(), log(), ln(), sqrt(), pow(base, exponent)</strong>.</p>
|
||
<p>Furthermore, some constants are predefined and might also be used:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>gamma_mu</strong> = <span class="math notranslate nohighlight">\(\gamma_\mu/(2\pi) = 0.0135538817~\mathrm{MHz/G}\)</span></p></li>
|
||
<li><p><strong>pi</strong> = <span class="math notranslate nohighlight">\(\pi = 3.14159265358979323846\)</span></p></li>
|
||
</ul>
|
||
<p>The fit parameters are accessed either directly through parX, where ‘X’ is the number of the parameter in the <a class="reference internal" href="#msr-fitparameter-block"><span class="std std-ref">FITPARAMETER block</span></a>,
|
||
<em>e.g.</em> <em>par5</em> or through a mapping with mapY, where ‘Y’ specifies the mapping number in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> as explained below.</p>
|
||
<p>The defined functions are denoted as funX, where ‘X’ is the function number, <em>i.e.</em> fun1, fun2, etc. and have to be placed separately on one
|
||
line each. Afterwards they can be used in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>.</p>
|
||
<p>It follows an example to illustrate the usage of functions in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>. The total asymmetry of a signal
|
||
consisting of two parts should be a fit parameter. The fraction of each of the parts will then be expressed as a function of the total asymmetry.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FITPARAMETER</span>
|
||
<span class="c1"># No Name Value Step Pos_Error Boundaries</span>
|
||
<span class="mi">1</span> <span class="n">alpha</span> <span class="mi">1</span> <span class="mf">0.02</span> <span class="n">none</span> <span class="mi">0</span> <span class="mf">1.8</span>
|
||
<span class="mi">2</span> <span class="n">phase</span> <span class="mi">15</span> <span class="mf">1.0</span> <span class="n">none</span>
|
||
<span class="mi">3</span> <span class="n">asy</span> <span class="mf">0.2542</span> <span class="mf">0.004713</span> <span class="n">none</span> <span class="mi">0</span> <span class="mf">0.33</span>
|
||
<span class="mi">4</span> <span class="n">rate1</span> <span class="mi">15</span> <span class="mf">1.0</span> <span class="n">none</span> <span class="mi">0</span> <span class="n">none</span>
|
||
<span class="mi">5</span> <span class="n">frac1</span> <span class="mf">0.33</span> <span class="mf">0.0379</span> <span class="n">none</span> <span class="mi">0</span> <span class="mi">1</span>
|
||
<span class="mi">6</span> <span class="n">rate2</span> <span class="mf">0.13</span> <span class="mf">0.00579</span> <span class="n">none</span> <span class="mi">0</span> <span class="mi">10</span>
|
||
|
||
<span class="c1">###############################################################</span>
|
||
<span class="n">THEORY</span>
|
||
<span class="n">asymmetry</span> <span class="n">fun1</span>
|
||
<span class="n">simplExpo</span> <span class="mi">4</span> <span class="p">(</span><span class="n">rate</span><span class="p">)</span>
|
||
<span class="o">+</span>
|
||
<span class="n">asymmetry</span> <span class="n">fun2</span>
|
||
<span class="n">simplExpo</span> <span class="mi">6</span> <span class="p">(</span><span class="n">rate</span><span class="p">)</span>
|
||
|
||
<span class="c1">###############################################################</span>
|
||
<span class="n">FUNCTIONS</span>
|
||
<span class="n">fun1</span> <span class="o">=</span> <span class="n">par3</span> <span class="o">*</span> <span class="n">par5</span>
|
||
<span class="n">fun2</span> <span class="o">=</span> <span class="n">par3</span> <span class="o">*</span> <span class="p">(</span> <span class="mf">1.0</span> <span class="o">-</span> <span class="n">par5</span> <span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-global-block">
|
||
<span id="msr-global-block"></span><span id="index-16"></span><h3>The GLOBAL Block<a class="headerlink" href="#the-global-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The GLOBAL block is used to collect data which otherwise need to be specified in every single run entry of the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>.
|
||
Therefore, this block is only present to potentially shorten the msr file and to ease the handling for the user. The logic will by like that:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>check if the property is found in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>.</p></li>
|
||
<li><p>if <em>not</em> present in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>, check whether it is present in the GLOBAL block.</p></li>
|
||
<li><p>if still not found, try the data file.</p></li>
|
||
<li><p>if still not found, either try to estimate it, or fire an error message.</p></li>
|
||
</ol>
|
||
<p>This means that an entry present in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> will overwrite a setting from the GLOBAL block.</p>
|
||
<p>Currently the supported GLOBAL block entries are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">fittype</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">data</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">t0</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">addt0</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">fit</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">rrf_freq</span></code> for fittype 1, 3</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">rrf_packing</span></code> for fittype 1, 3</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">rrf_phase</span></code> for fittype 1, 3</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">packing</span></code> for fittype 0, 2, 4, 5</p></li>
|
||
</ul>
|
||
<p>For a detailed discussion of these entries see the section <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>.</p>
|
||
<p>The single histo RRF fit and asymmetry RRF fit related entries (fittype 1 and 3 only) have the following syntax:</p>
|
||
<dl>
|
||
<dt><strong>rrf_freq</strong></dt><dd><p>Defines the RRF frequency. The exact syntax is rrf_freq <value> <unit> where <value> is the value, and <unit> can be <em>MHz</em>, <em>Mc</em>, and <em>T</em>. An example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rrf_freq</span> <span class="mf">7.2</span> <span class="n">T</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><strong>rrf_packing</strong></dt><dd><p>for fittype 1 and fittype 3 rather than giving packing, rrf_packing <pack> has to be provided, <em>e.g.</em></p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rrf_packing</span> <span class="mi">150</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><strong>rrf_phase</strong></dt><dd><p>an optional additional RRF phase can be provided (if not provided, the RRF phase will be 0.0).
|
||
Syntax: rrf_phase <phase>, where the value <phase> is given in degree. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rrf_phase</span> <span class="mi">45</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<p>An example snippet with, and without GLOBAL section.</p>
|
||
<p>With GLOBAL block:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
|
||
<span class="c1">###############################################################</span>
|
||
<span class="n">GLOBAL</span>
|
||
<span class="n">fittype</span> <span class="mi">0</span> <span class="p">(</span><span class="n">single</span> <span class="n">histogram</span> <span class="n">fit</span><span class="p">)</span>
|
||
<span class="n">fit</span> <span class="mf">0.0005</span> <span class="mi">10</span>
|
||
<span class="n">packing</span> <span class="mi">5</span>
|
||
|
||
<span class="c1">###############################################################</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="nb">map</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span>
|
||
<span class="n">norm</span> <span class="mi">8</span>
|
||
<span class="n">backgr</span><span class="o">.</span><span class="n">fit</span> <span class="mi">9</span>
|
||
<span class="n">forward</span> <span class="mi">2</span>
|
||
<span class="n">data</span> <span class="mi">20120</span> <span class="mi">409500</span>
|
||
<span class="n">t0</span> <span class="mf">20108.0</span>
|
||
<span class="c1">#--------------------------------------------------------------</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="nb">map</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span>
|
||
<span class="n">norm</span> <span class="mi">13</span>
|
||
<span class="n">backgr</span><span class="o">.</span><span class="n">fit</span> <span class="mi">14</span>
|
||
<span class="n">forward</span> <span class="mi">3</span>
|
||
<span class="n">data</span> <span class="mi">20111</span> <span class="mi">409500</span>
|
||
<span class="n">t0</span> <span class="mf">20088.0</span>
|
||
<span class="c1">#--------------------------------------------------------------</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Without GLOBAL block:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
|
||
<span class="c1">###############################################################</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="n">fittype</span> <span class="mi">0</span> <span class="p">(</span><span class="n">single</span> <span class="n">histogram</span> <span class="n">fit</span><span class="p">)</span>
|
||
<span class="nb">map</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span>
|
||
<span class="n">norm</span> <span class="mi">8</span>
|
||
<span class="n">backgr</span><span class="o">.</span><span class="n">fit</span> <span class="mi">9</span>
|
||
<span class="n">forward</span> <span class="mi">2</span>
|
||
<span class="n">data</span> <span class="mi">20120</span> <span class="mi">409500</span>
|
||
<span class="n">t0</span> <span class="mf">20108.0</span>
|
||
<span class="n">fit</span> <span class="mf">0.0005</span> <span class="mi">10</span>
|
||
<span class="n">packing</span> <span class="mi">5</span>
|
||
<span class="c1">#--------------------------------------------------------------</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="n">fittype</span> <span class="mi">0</span> <span class="p">(</span><span class="n">single</span> <span class="n">histogram</span> <span class="n">fit</span><span class="p">)</span>
|
||
<span class="nb">map</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span>
|
||
<span class="n">norm</span> <span class="mi">13</span>
|
||
<span class="n">backgr</span><span class="o">.</span><span class="n">fit</span> <span class="mi">14</span>
|
||
<span class="n">forward</span> <span class="mi">3</span>
|
||
<span class="n">data</span> <span class="mi">20111</span> <span class="mi">409500</span>
|
||
<span class="n">t0</span> <span class="mf">20088.0</span>
|
||
<span class="n">fit</span> <span class="mf">0.0005</span> <span class="mi">10</span>
|
||
<span class="n">packing</span> <span class="mi">5</span>
|
||
<span class="c1">#--------------------------------------------------------------</span>
|
||
<span class="n">RUN</span> <span class="n">data</span><span class="o">/</span><span class="n">tdc_hifi_2014_00153</span> <span class="n">PIE3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">MDU</span> <span class="p">(</span><span class="n">name</span> <span class="n">beamline</span> <span class="n">institute</span> <span class="n">data</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="nb">format</span><span class="p">)</span>
|
||
<span class="n">fittype</span> <span class="mi">0</span> <span class="p">(</span><span class="n">single</span> <span class="n">histogram</span> <span class="n">fit</span><span class="p">)</span>
|
||
<span class="o">...</span> <span class="ow">and</span> <span class="n">many</span> <span class="n">more</span> <span class="n">detectors</span> <span class="n">here</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-run-block">
|
||
<span id="msr-run-block"></span><span id="index-17"></span><h3>The RUN Block<a class="headerlink" href="#the-run-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The RUN block is used to collect the data needed for a particular run to be fitted. This includes the run name, fit type, data format, etc.
|
||
The RUN block is slightly differently organized than the other blocks. The information is collected via labels followed by the information.
|
||
Each run to be fitted has its <em>own</em> RUN block. A RUN block starts with a run-file line which has the structure</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">RUN</span> <span class="o"><</span><span class="n">run_file_name</span><span class="o">></span> <span class="o"><</span><span class="n">beamline</span><span class="o">></span> <span class="o"><</span><span class="n">facility</span><span class="o">></span> <span class="o"><</span><span class="n">file_format</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 14%" />
|
||
<col style="width: 86%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>RUN-block tag</p></th>
|
||
<th class="head"><p>comment</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><run_file_name></p></td>
|
||
<td><p>sub path and file name without extension</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><beamline></p></td>
|
||
<td><p>name of the beamline where the data were taken, <em>e.g.</em> MUE4. Used to generate a default path.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><facility></p></td>
|
||
<td><p>name of the facility where the data were recorded, <em>e.g.</em> PSI. Used to generate a default path.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><file_format></p></td>
|
||
<td><p>file format: MUSR-ROOT, NEXUS, ROOT-NPP, ROOT-PPC, PSI-BIN, PSI-MDU, WKM, MUD, MDU-ASCII, ASCII, DB</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The tokens following the RUN statement are used to identify the run, the potential location where the run might be found,
|
||
and the file format in which the run data has been saved. In order to understand the meaning of all the above tokens,
|
||
a short digression is needed.</p>
|
||
<p>Where is musrfit looking for data files? There is a specific order how this is done:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Check if the file is found in the current directory</p></li>
|
||
<li><p>Check if the path (or multiple paths) was (were) given in the <a class="reference internal" href="#musrfit-startup"><span class="std std-ref">XML startup file</span></a>.</p></li>
|
||
<li><p>Check if there is a system variable <code class="docutils literal notranslate"><span class="pre">MUSRFULLDATAPATH</span></code>. This system variable can contain multiple search paths separated by colons, <em>e.g.</em></p></li>
|
||
</ol>
|
||
<blockquote>
|
||
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">export</span> <span class="nv">MUSRFULLDATAPATH</span><span class="o">=</span>/mnt/data/nemu/wkm/:/mnt/data/nemu/his/:/afs/psi.ch/user/s/smith/
|
||
</pre></div>
|
||
</div>
|
||
</div></blockquote>
|
||
<ol class="arabic" start="4">
|
||
<li><p>Construct the search path from the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN-block</span></a> information in the following way: Based on the RUN line in the RUN block, default paths will be generated, <em>e.g.</em> for</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">RUN</span> <span class="mi">2007</span><span class="o">/</span><span class="n">lem07_his_2018</span> <span class="n">MUE4</span> <span class="n">PSI</span> <span class="n">ROOT</span><span class="o">-</span><span class="n">NPP</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>the generated search path will look like</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">musrFullDataPathToken</span><span class="o">/</span><span class="n">DATA</span><span class="o">/</span><span class="n">Facility</span><span class="o">/</span><span class="n">Beamline</span><span class="o">/</span><span class="n">runName</span><span class="o">.</span><span class="n">ext</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">musrFullDataPathToken</span></code> is extracted from the <code class="docutils literal notranslate"><span class="pre">MUSRFULLDATAPATH</span></code> token by token, for the above example this might lead to the path</p>
|
||
</li>
|
||
</ol>
|
||
<blockquote>
|
||
<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">afs</span><span class="o">/</span><span class="n">psi</span><span class="o">.</span><span class="n">ch</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">s</span><span class="o">/</span><span class="n">smith</span><span class="o">/</span><span class="n">DATA</span><span class="o">/</span><span class="n">PSI</span><span class="o">/</span><span class="n">MUE4</span><span class="o">/</span><span class="mi">2007</span><span class="o">/</span><span class="n">lem07_his_2018</span><span class="o">.</span><span class="n">root</span>
|
||
</pre></div>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>Here are some valid examples for the first line of a RUN block:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">RUN</span> <span class="mi">2007</span><span class="o">/</span><span class="n">lem07_his_2018</span> <span class="n">MUE4</span> <span class="n">PSI</span> <span class="n">ROOT</span><span class="o">-</span><span class="n">NPP</span>
|
||
<span class="n">RUN</span> <span class="mi">2007</span><span class="o">/</span><span class="n">lem07_2018_rb1_npp</span> <span class="n">MUE4</span> <span class="n">PSI</span> <span class="n">WKM</span>
|
||
<span class="n">RUN</span> <span class="n">d2007</span><span class="o">/</span><span class="n">deltat_pta_gps_2650</span> <span class="n">PIM3</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">BIN</span>
|
||
<span class="n">RUN</span> <span class="n">d2010</span><span class="o">/</span><span class="n">tdc</span><span class="o">/</span><span class="n">deltat_tdc_gpd_8472</span> <span class="n">MUE1</span> <span class="n">PSI</span> <span class="n">PSI</span><span class="o">-</span><span class="n">BIN</span>
|
||
<span class="n">RUN</span> <span class="n">beautiful</span><span class="o">-</span><span class="n">data</span> <span class="n">MUE4</span> <span class="n">PSI</span> <span class="n">DB</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>After this short digression back to the RUN-block description.</p>
|
||
<p>In order to describe the operations needed for fitting and plotting, quite some information are needed. These information are following the RUN statement and are listed below. Depending on the fit type these information vary and hence it is indicated for which fit/plot type the information is applicable</p>
|
||
<span id="index-18"></span><dl id="msr-addrun">
|
||
<dt><strong>ADDRUN <run_file_name> <beamline> <facility> <file_format></strong> (optional)</dt><dd><p>If an ADDRUN is just following after a RUN statement, these runs will be added. More than one ADDRUN statements are possible, <em>i.e.</em> adding up as many runs as wished. It is also possible to add runs with different file formats. If the t0’s are given in the data files, the ADDRUN statement is all what is needed, otherwise just add the t0’s with the addt0 statement.</p>
|
||
<p>For a <a class="reference internal" href="#single-histogram-fit"><span class="std std-ref">Single Histogram Fit</span></a> or a <a class="reference internal" href="#negative-muon-musr-fit"><span class="std std-ref">MuMinus Fit</span></a> it will be</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">addt0</span> <span class="n">t0AddRun1</span>
|
||
<span class="n">addt0</span> <span class="n">t0AddRun2</span>
|
||
<span class="n">etc</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For an <a class="reference internal" href="#asymmetry-fit"><span class="std std-ref">Asymmetry Fit</span></a> this reads</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">addt0</span> <span class="n">t0AddRun1Forward</span> <span class="n">t0AddRun1Backward</span>
|
||
<span class="n">addt0</span> <span class="n">t0AddRun2Forward</span> <span class="n">t0AddRun2Backward</span>
|
||
<span class="n">etc</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>How will the background and data ranges be handled in this situation? First, the ADDRUN’s will be shifted in time such that all the t0’s have the same channel/bin number. Subsequently, the runs will be added. The background/data range is applied to this summed up new histogram.</p>
|
||
<p>ADDRUN is <em>not</em> available for the fit type <a class="reference internal" href="#non-musr-fit"><span class="std std-ref">Non-muSR Fit</span></a>.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-19"></span><dl id="msr-fittype">
|
||
<dt><strong>fittype</strong> (required if not already defined in the GLOBAL block)</dt><dd><p>This tag is used to indicate which type of fit is wished. The supported fit types are:</p>
|
||
<dl class="simple">
|
||
<dt><strong>0</strong></dt><dd><p>Single Histogram Fit</p>
|
||
</dd>
|
||
<dt><strong>1</strong></dt><dd><p>Single Histogram RRF Fit (only for online analysis)</p>
|
||
</dd>
|
||
<dt><strong>2</strong></dt><dd><p>Asymmetry Fit</p>
|
||
</dd>
|
||
<dt><strong>3</strong></dt><dd><p>Asymmetry RRF Fit (only for online analysis)</p>
|
||
</dd>
|
||
<dt><strong>4</strong></dt><dd><p>MuMinus Fit. This is a single histogram fit especially for negative muon μSR</p>
|
||
</dd>
|
||
<dt><strong>5</strong></dt><dd><p>beta-NMR Asymmetry Fit</p>
|
||
</dd>
|
||
<dt><strong>8</strong></dt><dd><p>Non-μSR Fit</p>
|
||
</dd>
|
||
</dl>
|
||
<p>The description of these fit types can be found in the <a class="reference internal" href="#fit-types"><span class="std std-ref">corresponding section</span></a>. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fittype</span> <span class="mi">0</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-20"></span><dl id="msr-alpha-beta">
|
||
<dt><strong>alpha, beta</strong> (fit type 2, 3, 5)</dt><dd><p>These parameters are used to correct the asymmetry for different detector efficiencies, solid angles and initial asymmetries. They are defined as <span class="math notranslate nohighlight">\(\alpha = N_{0,b}/N_{0,f}\)</span> and <span class="math notranslate nohighlight">\(\beta = A_{0,b}/A_{0,f}\)</span>. If the parameters are not specified in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>, for each one the value of 1 is assumed (for fittype 5, alpha is estimated from the ratio of <span class="math notranslate nohighlight">\(\sum_i \left( N_{\mathrm{bp}}(i)+N_{\mathrm{bm}}(i) \right)\)</span> and <span class="math notranslate nohighlight">\(\sum_i \left( N_{\mathrm{fp}}(i)+N_{\mathrm{fm}}(i) \right)\)</span>). Example for alpha with fit parameter number 1:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">alpha</span> <span class="mi">1</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-21"></span><dl id="msr-norm">
|
||
<dt><strong>norm</strong> (fit type 0)</dt><dd><p>Number of the fit parameter that represents the normalization constant <span class="math notranslate nohighlight">\(N_0\)</span> of the histogram; the value of this parameter is given either per nanosecond or per bin (see <a class="reference internal" href="#msr-commands-block"><span class="std std-ref">below</span></a>).
|
||
It is possible to substitute the parameter number by a function here (and only here in a RUN block), for instance to relate <span class="math notranslate nohighlight">\(N_0\)</span>’s of different histograms through an <span class="math notranslate nohighlight">\(\alpha\)</span>
|
||
parameter. Example for a <code class="docutils literal notranslate"><span class="pre">norm</span></code> defined by fit parameter number 12:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">norm</span> <span class="mi">12</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Example for a <code class="docutils literal notranslate"><span class="pre">norm</span></code> defined via function number 3:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">norm</span> <span class="n">fun3</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-22"></span><dl class="simple" id="msr-backgr-fit">
|
||
<dt><strong>backgr.fit</strong> (fit type 0)</dt><dd><p>Parameter number specifying the constant background in a histogram. Its value is given either per nanosecond or per bin (see <a class="reference internal" href="#msr-commands-block"><span class="std std-ref">below</span></a>). If this keyword is present,
|
||
any information on a background line are ignored.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-23"></span><dl class="simple" id="msr-lifetime">
|
||
<dt><strong>lifetime</strong> (fit type 0)</dt><dd><p>Fit parameter representing the lifetime of the muon. If it is not specified the value <span class="math notranslate nohighlight">\(\tau_\mu=2.197019~ \mu\mathrm{s}\)</span> is used in the calculations.</p>
|
||
</dd>
|
||
<dt><strong>lifetimecorrection</strong> (fit type 0) <em>obsolete</em></dt><dd><p>Does not accept any arguments. If present, the output in <code class="docutils literal notranslate"><span class="pre">musrview</span></code> is corrected for the exponential decay of the muon. This item is <em>obsolete</em> in the RUN block
|
||
and will be transferred to the <a class="reference internal" href="#msr-plot-block"><span class="std std-ref">PLOT block</span></a>, which allows switching between histogram view and asymmetry view much quicker.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-24"></span><dl class="simple" id="msr-map">
|
||
<dt><strong>map</strong></dt><dd><p>On this line the mapping of run-dependent parameters is done. Parameter numbers given here may be accessed through map1, map2, etc. in the
|
||
<a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY</span></a> and <a class="reference internal" href="#msr-functions-block"><span class="std std-ref">FUNCTIONS</span></a> blocks (see also <a class="reference internal" href="#msr-map-intro"><span class="std std-ref">maps</span></a>). The first ten maps
|
||
are always present and have the value 0 if not used; however, the total number of maps is not restricted!</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-25"></span><dl id="msr-forward">
|
||
<dt><strong>forward</strong> (fit type 0, 1, 4)</dt><dd><p>Number of the histogram in the data file to be processed. If histograms shall be grouped, all the numbers which shall be grouped. Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">forward</span> <span class="mi">3</span> <span class="c1"># no grouping, take histogram number 3</span>
|
||
<span class="n">forward</span> <span class="mi">1</span> <span class="mi">2</span> <span class="c1"># group histogram number 1 and 2</span>
|
||
<span class="n">forward</span> <span class="mi">1</span><span class="o">-</span><span class="mi">10</span> <span class="mi">12</span> <span class="c1"># group histograms with numbers from 1 to 10 and additionally histogram 12</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-26"></span><dl id="msr-forward-backward">
|
||
<dt><strong>forward, backward</strong> (fit types 2, 3)</dt><dd><p>Numbers of the histograms in the data file that should be taken to calculate the asymmetry. If histograms shall be grouped, all the numbers which shall be grouped. Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># build forward/backward asymmetry with histogram 1 and 3</span>
|
||
<span class="n">forward</span> <span class="mi">1</span>
|
||
<span class="n">backward</span> <span class="mi">3</span>
|
||
<span class="c1"># build forward/backward asymmetry with groupings 1+2+3 and 7+8+9</span>
|
||
<span class="n">forward</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span>
|
||
<span class="n">backward</span> <span class="mi">7</span> <span class="mi">8</span> <span class="mi">9</span>
|
||
<span class="c1"># build forward/backward asymmetry with groupings 1+2+3 and 7+8+9 (alternative notation)</span>
|
||
<span class="n">forward</span> <span class="mi">1</span><span class="o">-</span><span class="mi">3</span>
|
||
<span class="n">backward</span> <span class="mi">7</span><span class="o">-</span><span class="mi">9</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><strong>forward, backward</strong> (fit type 5)</dt><dd><p>Numbers of the histograms in the data file that should be taken to calculate the asymmetry. Two forward and backward histograms should be given indicationg positive and negative helicities. The asymmetry from opposite helicities will be subtracted. Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># build forward/backward asymmetry with histogram 1 and 3 then subtract asymmetry built with histograms 2 and 4</span>
|
||
<span class="n">forward</span> <span class="mi">1</span> <span class="mi">2</span>
|
||
<span class="n">backward</span> <span class="mi">3</span> <span class="mi">4</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-27"></span><dl class="simple" id="msr-backgr-fix">
|
||
<dt><strong>backgr.fix</strong> (fit types 0, 1, 2, 3, 5)</dt><dd><p>A fixed constant background in counts per nanosecond or per bin (see <a class="reference internal" href="#msr-commands-block"><span class="std std-ref">below</span></a>) may be given at this point.
|
||
The background is specified for all histograms in the order <span class="math notranslate nohighlight">\(B_f B_b [B_r B_l]\)</span>. If this keyword is present, <em>any</em> information on a <code class="docutils literal notranslate"><span class="pre">background</span></code> line is ignored.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-28"></span><dl id="msr-background-single-histo">
|
||
<dt><strong>background</strong> (fit type 0, 1)</dt><dd><p>The numbers of the first and the last channel of an interval from which the constant background should be calculated are specified here.
|
||
In case histograms are being grouped, the specified channels are interpreted with respect to the first histogram. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">background</span> <span class="mi">100</span> <span class="mi">18000</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-29"></span><dl id="msr-background-asymmetry">
|
||
<dt><strong>background</strong> (fit types 2, 3, 5)</dt><dd><p>The numbers of the first and the last channel of an interval from which the constant background should be calculated are specified here.
|
||
For all the histograms this is done together in the following order: <span class="math notranslate nohighlight">\(k_{f,\rm first} k_{f,\rm last} k_{b,\rm first} k_{b, \rm last} [k_{r,\rm first} k_{r,\rm last} k_{l,\rm first} k_{l,\rm last}]\)</span>.
|
||
In case histograms are being grouped, the specified channels are interpreted with respect to the first histograms. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">background</span> <span class="mi">61</span> <span class="mi">184</span> <span class="mi">57</span> <span class="mi">145</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-30"></span><dl id="msr-data-single-histo">
|
||
<dt><strong>data</strong> (fit type 0, 1, 4)</dt><dd><p>The numbers of the first and the last channel of an interval from which the data is taken are specified here.
|
||
In case histograms are being grouped, the specified channels are interpreted with respect to the first histogram.
|
||
Typically these channels are referred to as <code class="docutils literal notranslate"><span class="pre">first</span> <span class="pre">good</span> <span class="pre">bin</span></code> / <code class="docutils literal notranslate"><span class="pre">last</span> <span class="pre">good</span> <span class="pre">bin</span></code> (fgb/lgb). Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data</span> <span class="mi">165</span> <span class="mi">7965</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-31"></span><dl id="msr-data-asymmetry">
|
||
<dt><strong>data</strong> (fit type 2, 3, 5)</dt><dd><p>The numbers of the first and the last channel of an interval from which the data is taken are specified here.
|
||
Typically these channels are referred to as first good bin / last good bin (fgb/lgb). For all the histograms this is
|
||
done together in the following order: <span class="math notranslate nohighlight">\(k_{f,\rm first} k_{f,\rm last} k_{b,\rm first} k_{b, \rm last} [k_{r,\rm first} k_{r,\rm last} k_{l,\rm first} k_{l,\rm last}]\)</span>.
|
||
In case histograms are being grouped, the specified channels are interpreted with respect to the first histograms. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data</span> <span class="mi">207</span> <span class="mi">7994</span> <span class="mi">167</span> <span class="mi">8009</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-32"></span><dl id="msr-t0-single-histo">
|
||
<dt><strong>t0</strong> (fit type 0, 1, 4)</dt><dd><p>The number of the time-zero channel of the histogram. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t0</span> <span class="mi">3419</span> <span class="c1"># t0 channel = 3419</span>
|
||
<span class="n">t0</span> <span class="mi">3419</span> <span class="mi">3434</span> <span class="c1"># t0 channels for groupings: forward f1 f2. 3419 t0 for f1, 3434 t0 for f2.</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-33"></span><dl id="msr-t0-asymmetry">
|
||
<dt><strong>t0</strong> (fit type 2, 3, 5)</dt><dd><p>The numbers of time-zero channels of the histograms in the order <span class="math notranslate nohighlight">\(t_{0,f} t_{0,b}\)</span>. For fit type 5, the time-zero is the channel of the start of beam pulse. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t0</span> <span class="mi">3419</span> <span class="mi">3418</span> <span class="c1"># t0 channels: forward (3419), backward (3418)</span>
|
||
<span class="n">t0</span> <span class="mi">3419</span> <span class="mi">3418</span> <span class="mi">3417</span> <span class="mi">3416</span> <span class="c1"># t0 channels (assuming forward f1 f2, backward b1 b2): forward (3419, f1), backward (3418, b1); forward (3417, f2), backward (3416, b2)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-34"></span><dl class="simple" id="msr-addt0-single-histo">
|
||
<dt><strong>addt0</strong> (fit type 0, 1, 4)</dt><dd><p>The number of the time-zero channel of the histogram. If grouping of histograms is present (see <a class="reference internal" href="#msr-forward"><span class="std std-ref">forward</span></a>) the
|
||
same syntax as for <a class="reference internal" href="#msr-t0-single-histo"><span class="std std-ref">t0</span></a> applies. If one addt0 is given, the total number of addt0’s needs to be equal to
|
||
the total number of <a class="reference internal" href="#msr-addrun"><span class="std std-ref">ADDRUN</span></a>’s!</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-35"></span><dl class="simple" id="msr-addt0-asymmetry">
|
||
<dt><strong>addt0</strong> (fit type 2, 3, 5)</dt><dd><p>The numbers of time-zero channels of the histograms in the order <span class="math notranslate nohighlight">\(t_{0,f} t_{0,b} [t_{0,r} t_{0,l}]\)</span>.
|
||
If grouping of histograms is present (see <a class="reference internal" href="#msr-forward-backward"><span class="std std-ref">forward</span></a>) the same syntax as for <a class="reference internal" href="#msr-t0-asymmetry"><span class="std std-ref">t0</span></a> applies.
|
||
If one addt0 is given, the total number of addt0’s needs to be equal to the total number of <a class="reference internal" href="#msr-addrun"><span class="std std-ref">ADDRUN</span></a>’s!</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-36"></span><dl class="simple" id="msr-xy-data">
|
||
<dt><strong>xy-data</strong> (fit type 8)</dt><dd><p>Specification of the data from an ASCII or DB file which should be used as <em>x</em> and <em>y</em> data (in this order).
|
||
For a simple ASCII file the column numbers are used, in the case of a DB file one can either specify the variable
|
||
numbers or the name of the variables as given in the DB header.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-37"></span><dl id="msr-fit">
|
||
<dt><strong>fit</strong></dt><dd><p>The range of data that should be considered when the fitting is done. For the μSR fit types 0, 1, 2, 3, and 4 the
|
||
starting and end times are given in micro-seconds. For the non-μSR fit type 8 the starting and end points of the
|
||
fitting range are given in the units of the <em>x</em> data.</p>
|
||
<p><strong>In case the fit range specified here is larger than the data range (in any direction), the data range will be used as fit range.</strong></p>
|
||
<p>An example for a μSR fit:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fit</span> <span class="mf">0.1</span> <span class="mf">8.5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Which means that the fitting window will span from 0.1 to 8.5 micro-seconds.</p>
|
||
<p>Another possibility for the μSR fits is to give the fit range in bins, rather than time. The syntax is then:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fit</span> <span class="n">fgb</span><span class="o">+<</span><span class="n">n0</span><span class="o">></span> <span class="n">lgb</span><span class="o">-<</span><span class="n">n1</span><span class="o">></span><span class="p">,</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">fgb</span></code> and <code class="docutils literal notranslate"><span class="pre">lgb</span></code> are label tags which refer to the ‘first good bin’ and the ‘last good bin’ defined
|
||
either in the <a class="reference internal" href="#msr-data-single-histo"><span class="std std-ref">data</span></a> tag of the run block, data file, are estimated based on T0.
|
||
<code class="docutils literal notranslate"><span class="pre"><n0></span></code> and <code class="docutils literal notranslate"><span class="pre"><n1></span></code> are offsets (given in bins) allowing to change the fit window compared to the data window.
|
||
An example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fit</span> <span class="n">fgb</span><span class="o">+</span><span class="mi">150</span> <span class="n">lgb</span><span class="o">-</span><span class="mi">1332</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-38"></span><dl class="simple" id="msr-packing">
|
||
<dt><strong>packing</strong></dt><dd><p>Number of data channels to be binned together. For the non-μSR fit type 8 the binning is supposed to be 1.
|
||
For the single histogram RRF fit (fittype 1) and asymmetry RRF fit (fittype 3) this parameter is meaningless.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="the-commands-block">
|
||
<span id="msr-commands-block"></span><span id="index-39"></span><h3>The COMMANDS Block<a class="headerlink" href="#the-commands-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The COMMANDS block is used to specify the commands which are passed from <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> to <code class="docutils literal notranslate"><span class="pre">MINUIT2</span></code>. The supported commands
|
||
after the <code class="docutils literal notranslate"><span class="pre">COMMANDS</span></code> keyword are listed in the two tables below (<a class="reference internal" href="#minuit2-command-overview"><span class="std std-ref">Minuit2 Command Overview</span></a> and <a class="reference internal" href="#dks-command-overview"><span class="std std-ref">DKS Command Overview</span></a>)
|
||
and further described in <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a>.</p>
|
||
<div class="section" id="minuit2-command-overview">
|
||
<span id="index-40"></span><span id="id21"></span><h4>Minuit2 Command Overview<a class="headerlink" href="#minuit2-command-overview" title="Permalink to this headline">¶</a></h4>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 20%" />
|
||
<col style="width: 37%" />
|
||
<col style="width: 42%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p><strong>Cmd</strong></p></th>
|
||
<th class="head"><p>brief description</p></th>
|
||
<th class="head"><p>Reference</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><strong>STRATEGY</strong></p></td>
|
||
<td><p>0 (low), 1 (default), and 2 (high)</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id22">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>MIGRAD</strong></p></td>
|
||
<td><p>This is the best minimizer for
|
||
nearly all functions.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id23">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>SIMPLEX</strong></p></td>
|
||
<td><p>This genuine multidimensional
|
||
minimization routine is usually
|
||
much slower than MIGRAD.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id24">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>MINIMIZE</strong></p></td>
|
||
<td><p>This is equivalent to MIGRAD,
|
||
except that if MIGRAD fails, it
|
||
reverts to SIMPLEX and then calls
|
||
MIGRAD again.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id25">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>MINOS</strong></p></td>
|
||
<td><p>Calculate parameter errors taking
|
||
into account both parameter
|
||
correlations and non-linearities.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id26">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>HESSE</strong></p></td>
|
||
<td><p>Calculates an error matrix.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id27">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>SAVE</strong></p></td>
|
||
<td><p>Writes the <code class="docutils literal notranslate"><span class="pre">MINUIT2.OUTPUT</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">MINUIT2.root</span></code> files which
|
||
contained detailed information
|
||
about the fit, like the
|
||
<code class="docutils literal notranslate"><span class="pre">COVARIANCE</span> <span class="pre">MATRIX</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">CORRELATION</span> <span class="pre">COEFFICIENTS</span></code>, etc.</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>SET BATCH</strong></p></td>
|
||
<td><p>Obsolate. Only present for
|
||
backward compatibilty.</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>END RETURN</strong></p></td>
|
||
<td><p>Obsolete. Only present for
|
||
backward compatibility.</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>MAX_LIKELIHOOD</strong></p></td>
|
||
<td><p>If present, use max. log likelihood
|
||
rather than the default
|
||
<span class="math notranslate nohighlight">\(\chi^2\)</span>.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>PRINT_LEVEL</strong></p></td>
|
||
<td><p>Prints more or less messages to the
|
||
stdout. Allowed values: 0-3</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id28">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>SCAN</strong></p></td>
|
||
<td><p>A command line based option, which
|
||
allows to scan <span class="math notranslate nohighlight">\(\chi^2\)</span> by
|
||
vary a single parameter.
|
||
<code class="docutils literal notranslate"><span class="pre">SCAN</span></code> needs to be followed by
|
||
the command <code class="docutils literal notranslate"><span class="pre">MNPLOT</span></code>.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id29">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>CONTOURS</strong></p></td>
|
||
<td><p>A command line based option. It
|
||
allows to plot the contour of
|
||
parX vs parY.
|
||
<code class="docutils literal notranslate"><span class="pre">CONTOURS</span></code> needs to be followed
|
||
by the command <code class="docutils literal notranslate"><span class="pre">MNPLOT</span></code>.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f3" id="id30">15</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>MNPLOT</strong></p></td>
|
||
<td><p>Helper command for the commands
|
||
<code class="docutils literal notranslate"><span class="pre">SCAN</span></code> and <code class="docutils literal notranslate"><span class="pre">CONTOURS</span></code>.</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>FIX</strong></p></td>
|
||
<td><p>Allows to fix parameters on the
|
||
command level. It can help to guide
|
||
a complicated fit (e.g. muonium
|
||
<span class="math notranslate nohighlight">\(\mu^+\)</span>.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>RELEASE</strong></p></td>
|
||
<td><p>Allows to release parameters on the
|
||
command level which have been fixed
|
||
before. It can help to guide
|
||
a complicated fit (e.g. muonium
|
||
<span class="math notranslate nohighlight">\(\mu^+\)</span>.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>RESTORE</strong></p></td>
|
||
<td><p>Releases <strong>all</strong> fixed parameters.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>FIT_RANGE</strong></p></td>
|
||
<td><p>Allows to change the fit range on
|
||
the command level. This might be
|
||
helpful in conjunction with
|
||
multiple signals in the spectrum.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>SCALE_N0_BKG</strong></p></td>
|
||
<td><p>For histogram fits only.
|
||
If set true (default), it will
|
||
scale <span class="math notranslate nohighlight">\(N_0\)</span> to 1/ns,
|
||
Otherwise <span class="math notranslate nohighlight">\(N_0\)</span> is given in
|
||
counts.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>SECTOR</strong></p></td>
|
||
<td><p>Allows to output <span class="math notranslate nohighlight">\(\chi^2\)</span> or
|
||
maxLH values for a sub-range of the
|
||
fitted time range.
|
||
Used for statistical analysis only.</p></td>
|
||
<td><p>see <a class="reference internal" href="#musrfit-command-block-details"><span class="std std-ref">musrfit Command Block Details</span></a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="rubric">Minuit2 Command Notes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="f3"><span class="brackets">15</span><span class="fn-backref">(<a href="#id22">1</a>,<a href="#id23">2</a>,<a href="#id24">3</a>,<a href="#id25">4</a>,<a href="#id26">5</a>,<a href="#id27">6</a>,<a href="#id28">7</a>,<a href="#id29">8</a>,<a href="#id30">9</a>)</span></dt>
|
||
<dd><p>see <a class="reference external" href="https://root.cern.ch/root/htmldoc/guides/minuit2/Minuit2.html">MINUIT2 users guide</a></p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="dks-command-overview">
|
||
<span id="index-41"></span><span id="id31"></span><h4>DKS Command Overview<a class="headerlink" href="#dks-command-overview" title="Permalink to this headline">¶</a></h4>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 28%" />
|
||
<col style="width: 53%" />
|
||
<col style="width: 19%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p><strong>DKS Extension</strong></p></th>
|
||
<th class="head"><p>brief description</p></th>
|
||
<th class="head"><p>Reference</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><strong>OpenMP</strong></p></td>
|
||
<td><p>Invoke OpenMP if allowed by the OS.
|
||
Currently macOS does <em>not</em> support
|
||
OpenMP out of the box. All Linux
|
||
flavours do so.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f4" id="id32">16</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>CUDA</strong></p></td>
|
||
<td><p>For properly setup Nvidia graphic
|
||
cards (e.g. Tesla K40c).
|
||
Allows to off-load the minimization
|
||
to the GPU. Speedups of up to 50
|
||
are possible!</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f5" id="id33">17</a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>OpenCL-CPU</strong></p></td>
|
||
<td><p>Invoke OpenCL on the CPU if the
|
||
OS supports it. This might be useful
|
||
for macOS.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f6" id="id34">18</a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>OpenCL-GPU</strong></p></td>
|
||
<td><p>Invoke OpenCL on the GPU if the
|
||
OS supports it. This might be useful
|
||
for macOS and for systems having a
|
||
powerful AMD graphics card in place.</p></td>
|
||
<td><p><a class="footnote-reference brackets" href="#f6" id="id35">18</a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="rubric">DKS Command Notes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="f4"><span class="brackets"><a class="fn-backref" href="#id32">16</a></span></dt>
|
||
<dd><p>Standard <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> as well as DKS support <a class="reference external" href="https://www.openmp.org/">OpenMP</a>.
|
||
It allows to use all your threads of your CPU(s) during the minimization.</p>
|
||
</dd>
|
||
<dt class="label" id="f5"><span class="brackets"><a class="fn-backref" href="#id33">17</a></span></dt>
|
||
<dd><p>This is only supported for the <code class="docutils literal notranslate"><span class="pre">DKS</span></code> version of <code class="docutils literal notranslate"><span class="pre">musrfit</span></code>. For details about
|
||
<code class="docutils literal notranslate"><span class="pre">CUDA</span></code> see <a class="reference external" href="https://developer.nvidia.com/cuda-zone">NVIDIA</a>.</p>
|
||
</dd>
|
||
<dt class="label" id="f6"><span class="brackets">18</span><span class="fn-backref">(<a href="#id34">1</a>,<a href="#id35">2</a>)</span></dt>
|
||
<dd><p>This is only supported for the <code class="docutils literal notranslate"><span class="pre">DKS</span></code> version of <code class="docutils literal notranslate"><span class="pre">musrfit</span></code>. For details about
|
||
<code class="docutils literal notranslate"><span class="pre">OpenCL</span></code> see <a class="reference external" href="https://www.khronos.org/opencl/">the Khronos Group</a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="musrfit-command-block-details">
|
||
<span id="index-42"></span><span id="id36"></span><h4><code class="docutils literal notranslate"><span class="pre">musrfit</span></code> Command Block Details<a class="headerlink" href="#musrfit-command-block-details" title="Permalink to this headline">¶</a></h4>
|
||
<p>A standard COMMANDS block then looks like this:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Additional to the commands listed above also the command <strong>MAX_LIKELIHOOD</strong> is valid. This keyword can be placed anywhere in
|
||
the block and switches from the default <span class="math notranslate nohighlight">\(\chi^2\)</span> minimization to the log likelihood maximization which can be advantageous
|
||
if one is dealing with low-statistics data.</p>
|
||
<p>Furthermore, it is possible to call the <code class="docutils literal notranslate"><span class="pre">MINUIT2</span></code> methods <strong>SCAN</strong> and <strong>CONTOURS</strong> together with <strong>MNPLOT</strong>.
|
||
Exemplary invocations are as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">SCAN</span> <span class="mi">7</span>
|
||
<span class="n">MNPLOT</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>or</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">CONTOURS</span> <span class="mi">8</span> <span class="mi">9</span>
|
||
<span class="n">MNPLOT</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Sometimes it is necessary to guide <code class="docutils literal notranslate"><span class="pre">MINUIT2</span></code> to the global optimum. For this purpose it is useful to have the commands
|
||
<strong>FIX <list_of_param_to_be_fixed></strong>, <strong>RELEASE <list_of_param_to_be_fixed></strong>, and <strong>RESTORE</strong> at hand. <strong><list_of_param_to_be_fixed></strong>
|
||
is a list of the parameters to be fixed/released. It is a space- or comma-separated list of either parameter numbers and/or parameter names.
|
||
<strong>RESTORE</strong> releases all the fixed parameters. A typical example could look like:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">FIX</span> <span class="n">Freq1</span><span class="p">,</span> <span class="n">Freq2</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">RESTORE</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It is important to understand that before <strong>MINOS</strong> is called, all the fixed parameters need to be released and another minimizer
|
||
command (<strong>MINIMIZE</strong>, <strong>MIGRAD</strong>, or <strong>SIMPLEX</strong>) needs to be in place, otherwise musrfit will assume that the still fixed parameters
|
||
have to be handled as constant parameters, <em>i.e.</em> setting the <step> value of the parameter to zero.</p>
|
||
<p>For even more complex fitting the additional command <strong>FIT_RANGE [RESET | t</strong><sub>start</sub> <strong>t</strong><sub>end</sub> <strong>| t</strong><sub>s1</sub> <strong>t</strong><sub>e1</sub>
|
||
<strong>t</strong><sub>s2</sub> <strong>t</strong><sub>e2</sub> <strong>… t</strong><sub>sn</sub> <strong>t</strong><sub>en</sub> <strong>]</strong> is provided. It allows to change the fit range during different iterations.
|
||
The command <strong>FIT_RANGE t</strong><sub>start</sub> <strong>t</strong><sub>end</sub> changes the current fit range for all the runs present in the msr file.
|
||
<strong>FIT_RANGE RESET</strong> will restore to the original fit ranges as provided in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>. If for each run of the
|
||
msr file an individual fit range should be used, the third option applies. Here <strong>n</strong> has to correspond to the number of runs in the RUN block.</p>
|
||
<p>As for the run block, there is a 2<sup>nd</sup> flavor how the <strong>FIT_RANGE</strong> can be changed, namely giving the fit range in bins,
|
||
<em>i.e.</em> <strong>FIT_RANGE [ RESET | fgb+<n0> lgb-<n1> | fgb+<n00> lgb-<n01> fgb+<n10> lgb-<n11> … fgb+<nN0> lgb-<nN1> ]</strong> where <strong>N</strong> is the number of available run blocks.
|
||
The idea is inline with the above syntax and the syntax describe for the fit range (fit) of the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>.</p>
|
||
<p>A typical example could look like:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">FIT_RANGE</span> <span class="mf">0.0</span> <span class="mf">0.8</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">FIT_RANGE</span> <span class="n">RESET</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>or</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">FIT_RANGE</span> <span class="n">fgb</span><span class="o">+</span><span class="mi">15</span> <span class="n">lgb</span><span class="o">-</span><span class="mi">1332</span> <span class="n">fgb</span><span class="o">+</span><span class="mi">17</span> <span class="n">lgb</span><span class="o">-</span><span class="mi">1330</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">FIT_RANGE</span> <span class="n">RESET</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The command <strong>SCALE_N0_BKG TRUE | FALSE</strong> is only used in conjunction with single-histogram fits.
|
||
The default is <strong>SCALE_N0_BKG TRUE</strong> which will result in a scaling of <em>N(t)</em> such that it is given in ns<sup>-1</sup>, whereas with <strong>SCALE_N0_BKG FALSE</strong>
|
||
<em>no scaling</em> is performed and <em>N(t)</em> will be given in bin<sup>-1</sup>. If the command is not present at all, it will be interpreted as if <strong>SCALE_N0_BKG TRUE</strong> was present.</p>
|
||
<p>For “debug” purposes it is possible to force MINUIT2 to print out additional information. The COMMAND block command is <strong>PRINT_LEVEL <n></strong>,
|
||
where <strong><n></strong> can have the values 0,1,2, or 3. A typical example could look like:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">MIGRAD</span>
|
||
<span class="n">SAVE</span>
|
||
<span class="n">PRINT_LEVEL</span> <span class="mi">2</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Here the MINOS command will print out lot of additional information to the standard output. Notice there are 2 SAVE commands here. This will write the result of
|
||
MIGRAD to the MINUIT2.OUTPUT file and at the end append the MINOS results to this file.</p>
|
||
<p>The command <strong>SECTOR <list-of-sector-times></strong>, where <code class="docutils literal notranslate"><span class="pre"><list-of-sector-times></span></code> is a list of time values (space or comma separated) which have to range between the fit-start-time and the fit-end-time, allows to report <span class="math notranslate nohighlight">\(\chi^2\)</span> and maxLH values for sub-intervals of the given fit-range. Its only purpose is for a statistical analysis of complicated fits. The results will be written to the <code class="docutils literal notranslate"><span class="pre">MINUIT2.OUTPUT</span></code> file.</p>
|
||
<p>An example might look like this (assuming a fit-range from 0.005 to 10 us):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMMANDS</span>
|
||
<span class="n">MINIMIZE</span>
|
||
<span class="n">MINOS</span>
|
||
<span class="n">SECTOR</span> <span class="mf">5.0</span><span class="p">,</span> <span class="mf">7.5</span><span class="p">,</span> <span class="mf">9.0</span>
|
||
<span class="n">SAVE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><em>Note:</em> If a fit is invoked, the sector command results will only be written to file, if the fit <em>has converged</em>!</p>
|
||
</div>
|
||
<div class="section" id="dks-extensions-of-the-commands-block-enabling-gpu-and-general-opencl-support">
|
||
<span id="msr-commands-block-dks"></span><span id="index-43"></span><h4>DKS extensions of the COMMANDS block enabling GPU and general OpenCL support<a class="headerlink" href="#dks-extensions-of-the-commands-block-enabling-gpu-and-general-opencl-support" title="Permalink to this headline">¶</a></h4>
|
||
<p>In case you are running the musrfit / DKS version, there are a couple commands which allow you to control the way how the fit shall be performed. These commands are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 12%" />
|
||
<col style="width: 88%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Command</p></th>
|
||
<th class="head"><p>Purpose</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><strong>OpenMP</strong></p></td>
|
||
<td><p>tries to run multi-threading via OpenMP if available</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>CUDA</strong></p></td>
|
||
<td><p>tries to run the fit on a NVIDIA card as <em>e.g.</em> the Tesla K40c</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><strong>OpenCL-CPU</strong></p></td>
|
||
<td><p>tries to run multi-threading via OpenCL on the CPU. This is useful for macOS</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><strong>OpenCL-GPU</strong></p></td>
|
||
<td><p>tries to run multi-threading via OpenCL on the GPU. This is used for AMD cards, but also works for NVIDIA</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p><strong>OpenMP</strong> is the default if none of these tags are found in the COMMANDS block.</p>
|
||
<p>In case the defined THEORY is <em>not</em> ready to run on the accelerator, <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> will fall back to the default behavior.
|
||
In the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY table</span></a> all the functions which are currently <em>not</em> GPU ready are labeled by “not DKS ready” in the reference column or corresponding footnote.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-fourier-block">
|
||
<span id="msr-fourier-block"></span><span id="index-44"></span><h3>The FOURIER Block<a class="headerlink" href="#the-fourier-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>If a Fourier transform is carried out the results are plotted within <code class="docutils literal notranslate"><span class="pre">musrview</span></code>. As input data the actual data <em>shown</em> in <code class="docutils literal notranslate"><span class="pre">musrview</span></code> is used,
|
||
<em>i.e.</em> the currently time range shown in <code class="docutils literal notranslate"><span class="pre">musrview</span></code>! In the FOURIER block of the msr file all necessary parameters for calculating and presenting
|
||
the Fourier transform of the data specified in the <a class="reference internal" href="#msr-plot-block"><span class="std std-ref">PLOT block</span></a> is given. If the FOURIER block is not present in the msr file,
|
||
either the parameters set in the <a class="reference internal" href="#musrfit-startup"><span class="std std-ref">XML startup</span></a> file or the system defaults are taken when the Fourier transform is performed.
|
||
The block starts with the <em>FOURIER</em> keyword and may contain the following entries on the successive lines:</p>
|
||
<span id="index-45"></span><dl class="simple" id="msr-fourier-block-units">
|
||
<dt><strong>units</strong></dt><dd><p>Here is specified in which domain the Fourier-transformed data is presented. One may choose between the fields (<em>Gauss</em>) or (<em>Tesla</em>), the frequency (<em>MHz</em>), and the angular-frequency domain (<em>Mc/s</em>).</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-46"></span><dl class="simple" id="msr-fourier-block-fourier-power">
|
||
<dt><strong>fourier_power</strong></dt><dd><p>It is possible (but not necessary) to set the number of data points used for the Fourier transform here. As argument the exponent <em>n<21</em> of a power of 2 is accepted.
|
||
The number of data points is then 2<sup>n</sup>. <strong>Attention:</strong> If the number of points given here is bigger than the actual number of available data points,
|
||
the input data vector is filled with zeros until the number of requested points is reached (<em>zero padding</em>)!</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-47"></span><dl class="simple" id="msr-fourier-block-dc-corrected">
|
||
<dt><strong>dc-corrected</strong></dt><dd><p>a flag to remove a potential DC-offset of the signal. Allowed entries are <code class="docutils literal notranslate"><span class="pre">dc-corrected</span> <span class="pre">true</span> <span class="pre">|</span> <span class="pre">1</span> <span class="pre">|</span> <span class="pre">false</span> <span class="pre">|</span> <span class="pre">0</span></code>.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-48"></span><dl id="msr-fourier-block-apodization">
|
||
<dt><strong>apodization</strong></dt><dd><p>Here is decided if the data should be apodized before the Fourier transform is performed and if yes, which apodization should be used (for further details about apodization of
|
||
μSR data refer to the <a class="reference external" href="https://open.library.ubc.ca/cIRcle/collections/ubctheses/831/items/1.0085550">PhD thesis of T.M. Riseman (UBC)</a>). The argument to be put after the
|
||
keyword is therefore one of the following: <strong>NONE, WEAK, MEDIUM</strong> or <strong>STRONG</strong>. If the data should be apodized, they are manipulated as follows: each data value is multiplied by the function</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[\sum_{k=0}^4 c_k \left(\frac{i}{n}\right)^{2k},\]</div>
|
||
<p>where <em>i</em> is the data-point index and <em>n</em> is the total number of data points. The coefficients <em>c</em><sub>j</sub> for the different apodizations are given by:</p>
|
||
<dl class="simple">
|
||
<dt><strong>WEAK</strong></dt><dd><p><span class="math notranslate nohighlight">\(c_0 = 1.0,\, c_1 = -1.319391,\, c_2 = 0.703484,\, c_3=c_4=0.0\)</span></p>
|
||
</dd>
|
||
<dt><strong>MEDIUM</strong></dt><dd><p><span class="math notranslate nohighlight">\(c_0 = 1.0,\, c_1 = -1.831292,\, c_2 = 0.983734,\, c_3=c_4=0.0\)</span></p>
|
||
</dd>
|
||
<dt><strong>STRONG</strong></dt><dd><p><span class="math notranslate nohighlight">\(c_0 = 1.0,\, c_1 = -2.708894,\, c_2 = 2.953575,\, c_3=-1.599128,\, c_4=0.399782\)</span></p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-49"></span><dl id="msr-fourier-block-plot">
|
||
<dt><strong>plot</strong></dt><dd><p>At this point it is possible to set the part of the Fourier-transformed data which should be plotted by default if the Fourier transform is done by pressing the <em>f</em>-key in <code class="docutils literal notranslate"><span class="pre">musrview</span></code>.
|
||
The argument may be one of the following:</p>
|
||
<dl class="simple">
|
||
<dt><strong>real</strong></dt><dd><p>The real part of the (complex) Fourier transform is plotted.</p>
|
||
</dd>
|
||
<dt><strong>imag</strong></dt><dd><p>The imaginary part of the Fourier transform is plotted.</p>
|
||
</dd>
|
||
<dt><strong>real_and_imag</strong></dt><dd><p>Both the real and the imaginary parts of the Fourier transform are shown.</p>
|
||
</dd>
|
||
<dt><strong>power</strong></dt><dd><p>The absolute value of the Fourier transform is depicted.</p>
|
||
</dd>
|
||
<dt><strong>phase</strong></dt><dd><p>The phase of the Fourier transform is plotted.</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-50"></span><dl id="msr-fourier-block-phase">
|
||
<dt><strong>phase</strong></dt><dd><p>If a real Fourier shall be plotted, it is necessary to adopt the phases of the different detectors. The number of potentially provided phases can be either <strong>one</strong>, which means that this phase will be applied to <em>all</em> Fourier spectra,
|
||
or the number of phases have to correspond to the number of runs in the plot block.</p>
|
||
<p>Currently there are three options:</p>
|
||
<ol class="arabic">
|
||
<li><p>The phases for each run/detector are given explicitly, <em>i.e.</em></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>phase val0 sep val1 sep ... sep valN
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">val0</span></code>, <code class="docutils literal notranslate"><span class="pre">val1</span></code>, etc. are explicitly given phases (<em>i.e.</em> doubles), and <code class="docutils literal notranslate"><span class="pre">sep</span></code> is one of the following allowed separators: <code class="docutils literal notranslate"><span class="pre">space</span></code>, <code class="docutils literal notranslate"><span class="pre">,</span></code>, <code class="docutils literal notranslate"><span class="pre">;</span></code>, or <code class="docutils literal notranslate"><span class="pre">tab</span></code>.
|
||
For example</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>phase -3.2, <span class="m">175</span>.9
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The phases for each run/detector are given as phase parameter from the <a class="reference internal" href="#msr-fitparameter-block"><span class="std std-ref">FITPARAMETER block</span></a>, <em>e.g.</em> par3, which would
|
||
take the value of parameter number 3. More explicitly</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>phase parX0 sep parX1 sep ... sep parXN
|
||
</pre></div>
|
||
</div>
|
||
<p>where the same rules applies as for explicit phase values. An example could look like this</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>phase par7, par12, par17, par22, par27, par32, par37, par42, par47, par52, par57, par62, par67, par72, par77, par82
|
||
</pre></div>
|
||
</div>
|
||
<p>One might prefer to express the phases in respect to a reference counter, <em>e.g.</em> the forward counter is the reference counter phase (fcp) whereas
|
||
the backward counter phase (bcp) is expressed as bcp = fcp + relative_bcp. If the fitting is done along these lines, the phases in the Fourier
|
||
block can be expressed the following way</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>phase parRX0 sep parX1 sep ... sep parXN
|
||
</pre></div>
|
||
</div>
|
||
<p>which means that <code class="docutils literal notranslate"><span class="pre">X0</span></code> is the reference phase, and all the other phases are relative phases in respect to <code class="docutils literal notranslate"><span class="pre">X0</span></code>, <em>i.e.</em> the absolut phase of
|
||
<code class="docutils literal notranslate"><span class="pre">Xj</span></code> would be the summ of the values of <code class="docutils literal notranslate"><span class="pre">parX0</span></code> and <code class="docutils literal notranslate"><span class="pre">parXj</span></code> etc. The reference phase in the list is marked by <code class="docutils literal notranslate"><span class="pre">parR</span></code> rather than <code class="docutils literal notranslate"><span class="pre">par</span></code>.
|
||
Obviously only <em>one</em> reference phase can be defined!</p>
|
||
</li>
|
||
<li><p>Often the phases in the parameter block follow a clear list structure. This allows to write the Fourier phase parameters in a more compact form</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>phase par(X0, offset, #param)
|
||
</pre></div>
|
||
</div>
|
||
<p>with <code class="docutils literal notranslate"><span class="pre">X0</span></code> the first phase parameter index, <code class="docutils literal notranslate"><span class="pre">offset</span></code> being the offset to the next phase parameter, and <code class="docutils literal notranslate"><span class="pre">#param</span></code> being the number of phase parameters to be used.
|
||
This means that the previous example can be compacted to</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>phase par(7, 5, 16)
|
||
</pre></div>
|
||
</div>
|
||
<p>As in the phase parameter list examples before, also here a reference phase with relative phases might be wished. Differently to the phase parameter
|
||
list example, the first parameter number will be the reference phase. The compact notation here is</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>phase parR(X0, offest, #param)
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-51"></span><dl class="simple" id="msr-fourier-block-range-for-phase-correction">
|
||
<dt><strong>range_for_phase_correction</strong></dt><dd><p>An interval in Fourier space given in units as define with the ‘units’ tag, or the tag ‘all’ in which case the range given under ‘range’ will be used.
|
||
The given interval will be used for an automatic phasing of the real Fourier transform. This will allow to add real Fourier spectra coherently.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-52"></span><dl class="simple" id="msr-fourier-block-range">
|
||
<dt><strong>range</strong></dt><dd><p>The plotting range is set here. The interval is specified through its start and end points given in the <em>units</em> set after the <strong>units</strong> tag.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>Altogether, a possible FOURIER block might look like that:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FOURIER</span>
|
||
<span class="n">units</span> <span class="n">Mc</span><span class="o">/</span><span class="n">s</span>
|
||
<span class="n">fourier_power</span> <span class="mi">12</span>
|
||
<span class="n">apodization</span> <span class="n">NONE</span>
|
||
<span class="n">plot</span> <span class="n">real_and_imag</span>
|
||
<span class="n">phase</span> <span class="n">par5</span><span class="p">,</span> <span class="n">par8</span>
|
||
<span class="nb">range</span> <span class="mf">0.0</span> <span class="mf">17.03</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-plot-block">
|
||
<span id="msr-plot-block"></span><span id="index-53"></span><h3>The PLOT Block<a class="headerlink" href="#the-plot-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The PLOT block is intended to collect all the information needed for the graphical presentation of the data and fits using <code class="docutils literal notranslate"><span class="pre">musrview</span></code>.
|
||
The PLOT keyword at the beginning of the block is followed by a number which indicates the plot type. The plot types have to match the <a class="reference internal" href="#fit-types"><span class="std std-ref">fit types</span></a>.
|
||
Additionally, it is possible to provide information using the following keywords:</p>
|
||
<span id="index-54"></span><dl class="simple" id="msr-plot-block-lifetimecorrection">
|
||
<dt><strong>lifetimecorrection</strong></dt><dd><p>Does not accept any arguments. If present, the output in <code class="docutils literal notranslate"><span class="pre">musrview</span></code> is corrected for the exponential decay of the muon. Only relevant for (type 0).</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-55"></span><dl class="simple" id="msr-plot-block-runs">
|
||
<dt><strong>runs</strong></dt><dd><p>The numbers of the runs to be plotted have to be put here. The runs are numbered according to their appearance in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>.
|
||
The numbers is either a space separated list of numbers, an interval <em>e.g.</em> 1-16, or a combination of both.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-56"></span><dl id="msr-plot-block-range">
|
||
<dt><strong>range</strong></dt><dd><p>Here it is possible to define the plotting range explicitly. Depending on the plot type the following settings are allowed where the times are given in
|
||
micro-seconds and the <em>N</em> in counts (types 0-4) or in counts/nsec (type 0, 1):</p>
|
||
<dl class="simple">
|
||
<dt>fit type 0-4 <em>without</em> lifetimecorrection:</dt><dd><p><em>t</em><sub>min</sub> <em>t</em><sub>max</sub> [ <em>N</em><sub>min</sub> <em>N</em><sub>max</sub> ]</p>
|
||
</dd>
|
||
<dt>fit type 0-3 <em>with</em> lifetimecorrection:</dt><dd><p><em>t</em><sub>min</sub> <em>t</em><sub>max</sub> [ <em>A</em><sub>min</sub> <em>A</em><sub>max</sub> ]</p>
|
||
</dd>
|
||
<dt>fit type 8:</dt><dd><p><em>x</em><sub>min</sub> <em>x</em><sub>max</sub> [ <em>y</em><sub>min</sub> <em>y</em><sub>max</sub> ]</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-57"></span><dl id="msr-plot-block-sub-ranges">
|
||
<dt><strong>sub_ranges</strong></dt><dd><p>Here it is possible to define the plotting range for each run individually. For the different plot types the command has the structure:</p>
|
||
<dl class="simple">
|
||
<dt>fit type 0-4 <em>without</em> lifetimecorrection:</dt><dd><p><em>t</em><sup>1</sup><sub>min</sub> <em>t</em><sup>1</sup><sub>max</sub> <em>t</em><sup>2</sup><sub>min</sub> <em>t</em><sup>2</sup><sub>max</sub> … <em>t</em><sup>n</sup><sub>min</sub> <em>t</em><sup>n</sup><sub>max</sub> [ <em>N</em><sub>min</sub> <em>N</em> <sub>max</sub> ] (n = the number of runs to be plotted)</p>
|
||
</dd>
|
||
<dt>fit type 0-3 <em>with</em> lifetimecorrection:</dt><dd><p><em>t</em><sup>1</sup><sub>min</sub> <em>t</em><sup>1</sup><sub>max</sub> <em>t</em><sup>2</sup><sub>min</sub> <em>t</em><sup>2</sup><sub>max</sub> … <em>t</em><sup>n</sup><sub>min</sub> <em>t</em><sup>n</sup><sub>max</sub> [ <em>A</em><sub>min</sub> <em>A</em> <sub>max</sub> ] (n = the number of runs to be plotted)</p>
|
||
</dd>
|
||
<dt>fit type 8:</dt><dd><p><em>not yet implemented</em></p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-58"></span><dl class="simple" id="msr-plot-block-use-fit-ranges">
|
||
<dt><strong>use_fit_ranges</strong> [ <em>y</em><sub>min</sub> <em>y</em><sub>max</sub> ]</dt><dd><p>The fit ranges of the individual runs are used to present the data. Optionally, an ordinate range can be provided.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-59"></span><dl class="simple" id="msr-plot-block-view-packing">
|
||
<dt><strong>view_packing</strong></dt><dd><p>The data are presented in the packing given here rather than the binning used for the fit. <strong>WARNING:</strong> This is a global option and applies to all PLOT-blocks.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-60"></span><dl class="simple" id="msr-plot-block-logx">
|
||
<dt><strong>logx</strong></dt><dd><p>Will present the time axis in a logarithmic scale. <em>So far no checking of negative and zero-valued data is performed, hence expect interesting output!</em></p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-61"></span><dl class="simple" id="msr-plot-block-logy">
|
||
<dt><strong>logy</strong></dt><dd><p>Will present the axis of ordinates in a logarithmic scale. <em>So far no checking of negative and zero-valued data is performed, hence expect interesting output!</em></p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-62"></span><dl class="simple" id="msr-plot-block-rrf-packing">
|
||
<dt><strong>rrf_packing</strong> value</dt><dd><p>In the rotating-reference-frame (RRF) representation, this will be the value for the packing. <strong>WARNING:</strong> For the time being, this is a global option and applies to all PLOT blocks.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-63"></span><dl class="simple" id="msr-plot-block-rrf-freq">
|
||
<dt><strong>rrf_freq</strong> value unit</dt><dd><p>This entry provides the RRF “frequency” given by the value and the unit which can be: <em>kHz</em>, <em>MHz</em>, <em>Mc/s</em>, <em>G</em>, or <em>T</em>.</p>
|
||
</dd>
|
||
</dl>
|
||
<span id="index-64"></span><dl class="simple" id="msr-plot-block-rrf-phase">
|
||
<dt><strong>rrf_phase</strong> value</dt><dd><p>A phase of the RRF can be provided, either as a value in degrees, or as a parX, <em>e.g.</em> par4, where ‘X’ is supposed to be the phase parameter number in the <a class="reference internal" href="#msr-fitparameter-block"><span class="std std-ref">FITPARAMETER block</span></a>.</p>
|
||
</dd>
|
||
<dt><strong>Notes:</strong></dt><dd><ul class="simple">
|
||
<li><p>If no plot range is given at all, the fit range of the first run also serves as time window for the plot.</p></li>
|
||
<li><p>In the case no information on the axis of ordinates is available, the plotting range is chosen so that all data can be presented.</p></li>
|
||
<li><p>It is possible to define multiple PLOT blocks. Each PLOT block generates its own ROOT canvas.</p></li>
|
||
</ul>
|
||
</dd>
|
||
</dl>
|
||
<p>A typical PLOT block could look like</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">###############################################################</span>
|
||
<span class="n">PLOT</span> <span class="mi">0</span> <span class="p">(</span><span class="n">single</span> <span class="n">histo</span> <span class="n">plot</span><span class="p">)</span>
|
||
<span class="n">lifetimecorrection</span>
|
||
<span class="n">runs</span> <span class="mi">1</span><span class="o">-</span><span class="mi">16</span>
|
||
<span class="nb">range</span> <span class="mi">0</span> <span class="mf">9.07</span> <span class="o">-</span><span class="mf">0.5</span> <span class="mf">0.5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A few comments concerning the rotating reference frame (rrf) plot option: the idea of the rrf is to transform a high frequency
|
||
μSR spectrum into a low frequency spectrum. This is essentially done by multiplying the original asymmetry
|
||
<span class="math notranslate nohighlight">\(A(t)\)</span> by <span class="math notranslate nohighlight">\(\cos(\omega_{\rm rrf} t + \phi_{\rm rrf})\)</span>. This leads to two frequency shifted copies of the original
|
||
<span class="math notranslate nohighlight">\(A(t)\)</span>, one shifted downwards in frequency by <span class="math notranslate nohighlight">\(\omega_{\rm rrf}\)</span> (the wanted one) and one upwards (the unwanted one).
|
||
In order to get rid of the upward shifted spectrum, the <strong>rrf_packing</strong> is used, we just over-bin the high frequency copy.
|
||
The theory, however, is filtered via <a class="reference external" href="https://en.wikipedia.org/wiki/Kaiser_window">Kaiser filter</a>. Here a short example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">###############################################################</span>
|
||
<span class="n">PLOT</span> <span class="mi">1</span> <span class="p">(</span><span class="n">single</span> <span class="n">histo</span> <span class="n">RRF</span> <span class="n">plot</span><span class="p">)</span>
|
||
<span class="n">runs</span> <span class="mi">1</span>
|
||
<span class="nb">range</span> <span class="mi">0</span> <span class="mi">10</span> <span class="o">-</span><span class="mf">0.3</span> <span class="mf">0.3</span>
|
||
<span class="n">rrf_freq</span> <span class="mi">13900</span> <span class="n">G</span>
|
||
<span class="n">rrf_packing</span> <span class="mi">75</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-statistic-block">
|
||
<span id="msr-statistic-block"></span><span id="index-65"></span><h3>The STATISTIC Block<a class="headerlink" href="#the-statistic-block" title="Permalink to this headline">¶</a></h3>
|
||
<p>The STATISTIC block is the last block of a msr file. It contains some information on the fit: the date and time as well as
|
||
the absolute and normalized values of <span class="math notranslate nohighlight">\(\chi^2\)</span> and the number of degrees of freedom in the fit.
|
||
If enabled in the <a class="reference internal" href="#musrfit-startup"><span class="std std-ref">XML file</span></a> for <span class="math notranslate nohighlight">\(\chi^2\)</span>-single-histogram fits also <a class="reference external" href="http://en.wikipedia.org/wiki/Pearson's_chi-square_test">Pearson’s</a>
|
||
<span class="math notranslate nohighlight">\(\chi^2\)</span> will be written to the STATISTIC block.</p>
|
||
<p><em>These information only have a meaning if the fitting procedure has been executed at least once and the fit has converged!</em></p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="fit-types">
|
||
<span id="index-66"></span><span id="id37"></span><h2>Fit Types<a class="headerlink" href="#fit-types" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="single-histogram-fit-fit-type-0">
|
||
<span id="single-histogram-fit"></span><span id="index-67"></span><h3>Single Histogram Fit (fit type 0)<a class="headerlink" href="#single-histogram-fit-fit-type-0" title="Permalink to this headline">¶</a></h3>
|
||
<p>The single-histogram fit (fit type 0) is used to fit a function directly to the raw data using</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[N(t) = N_0 e^{-t/\tau_\mu} [ 1 + A(t) ] + N_{\rm bkg}\]</div>
|
||
<dl class="simple">
|
||
<dt>The parameters are given by:</dt><dd><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(N(t)\)</span>: rebinned decay histograms</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_0\)</span>: normalization constant of the histogram (RUN block: <a class="reference internal" href="#msr-norm"><span class="std std-ref">norm</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(\tau_\mu\)</span>: lifetime of the muon (RUN block: <a class="reference internal" href="#msr-lifetime"><span class="std std-ref">lifetime</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\rm bkg}\)</span>: constant background (RUN block: <a class="reference internal" href="#msr-backgr-fit"><span class="std std-ref">backgr.fit</span></a>, <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a>, or <a class="reference internal" href="#msr-background-single-histo"><span class="std std-ref">background</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(A(t)\)</span>: decay asymmetry/depolarization function as given in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>)</p></li>
|
||
</ul>
|
||
</dd>
|
||
</dl>
|
||
<p>In the plot type 0 without <code class="docutils literal notranslate"><span class="pre">lifetimecorrection</span></code> the rebinned histogram and the function <em>N(t)</em> written above are presented.
|
||
If the option lifetimecorrection is <em>set</em> in the PLOT block the asymmetry is plotted:</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[A(t) = \frac{N(t) - N_{\rm bkg}}{N_0} e^{+t/\tau_\mu} - 1\]</div>
|
||
</div>
|
||
<div class="section" id="single-histogram-rrf-fit-fit-type-1">
|
||
<span id="single-histogram-rrf-fit"></span><span id="index-68"></span><h3>Single Histogram RRF Fit (fit type 1)<a class="headerlink" href="#single-histogram-rrf-fit-fit-type-1" title="Permalink to this headline">¶</a></h3>
|
||
<p>The single-histogram RRF fit (fit type 1) is used to fit the rotating reference frame asymmetry <span class="math notranslate nohighlight">\(A_{\rm rrf}(t)\)</span> extracted from the raw data.
|
||
The currently implemented version will fail at low fields/frequencies (for about < 1 Tesla). The same is true, if multiple frequencies with large
|
||
enough separation are present, <em>e.g.</em> when dealing with muonium. <span class="math notranslate nohighlight">\(A_{\rm rrf}(t)\)</span> is estimated the following way (for more details see the
|
||
RRF memo (<musrfit>/doc/memos/rrf/rrf-notes.pdf)):</p>
|
||
<blockquote>
|
||
<div><ol class="arabic simple">
|
||
<li><p>define the background <span class="math notranslate nohighlight">\(N_{\rm bkg}\)</span>, and subtract it from the raw histogram.</p></li>
|
||
<li><p>calculate the property <span class="math notranslate nohighlight">\(M(t) = [N(t)-N_{\rm bkg}] \exp(+t/\tau)\)</span>.</p></li>
|
||
<li><p>estimate <span class="math notranslate nohighlight">\(N_0\)</span>. This is the most tricky part. From this calculate <span class="math notranslate nohighlight">\(A(t) = M(t)/N_0 -1\)</span>.</p></li>
|
||
<li><p>now the RRF transformation takes place: <span class="math notranslate nohighlight">\(A_{\rm rrf}(t) = 2 \cos(\omega_{\rm rrf} t + \phi_{\rm rrf}) A(t)\)</span>.
|
||
In Fourier space this is leading to <span class="math notranslate nohighlight">\([A(\omega-\omega_{\rm rrf})+A(\omega+\omega_{\rm rrf})]\)</span>.</p></li>
|
||
<li><p>in order to get rid if the <span class="math notranslate nohighlight">\(A(\omega+\omega_{\rm rrf})\)</span> component, <span class="math notranslate nohighlight">\(A_{\rm rrf}(t)\)</span> is over-binned
|
||
by the <a class="reference internal" href="#msr-plot-block-rrf-packing"><span class="std std-ref">rrf_packing</span></a>. This results in a signal <span class="math notranslate nohighlight">\(\langle A_{\rm rrf}(t) \rangle_{p}\)</span>
|
||
which ideally is <span class="math notranslate nohighlight">\(A(t)\)</span> shifted down in frequency by <span class="math notranslate nohighlight">\(\omega_{\rm rrf}\)</span>.</p></li>
|
||
</ol>
|
||
</div></blockquote>
|
||
<p>The single histogram RRF fit was introduced for online analysis <strong>only</strong>. It is leading to many uncontrolled effects like ghost lines due to imperfection
|
||
of the <span class="math notranslate nohighlight">\(N_0\)</span> estimate, line shape distortion due to dispersive filtering originating from the packing, back folding problems if
|
||
<span class="math notranslate nohighlight">\(\omega_{\rm rrf}\)</span> is not properly chosen, the error estimates on the fitted parameters is substantially worse, <em>etc.</em>
|
||
<strong>In summary: if you not urgently need it: do not use it! There are better ways to deal with the analysis of high frequency data!</strong>
|
||
For more details see the rrf-memo found in the source code under <musrfit>/doc/memo/rrf/rrf-notes.pdf or <a class="reference external" href="http://dx.doi.org/10.7566/JPSCP.21.011051">Musrfit–Real Time Parameter Fitting Using GPUs</a></p>
|
||
</div>
|
||
<div class="section" id="asymmetry-fit-fit-type-2">
|
||
<span id="asymmetry-fit"></span><span id="index-69"></span><h3>Asymmetry Fit (fit type 2)<a class="headerlink" href="#asymmetry-fit-fit-type-2" title="Permalink to this headline">¶</a></h3>
|
||
<p>For an asymmetry fit (fit type 2) two histograms are needed. These are given by the <a class="reference internal" href="#msr-forward-backward"><span class="std std-ref">forward</span></a> and <a class="reference internal" href="#msr-forward-backward"><span class="std std-ref">backward</span></a> keywords
|
||
in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>. Additionally, the parameters <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">alpha</span></a> and <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">beta</span></a> which relate the detector
|
||
efficiencies, solid angles and initial asymmetries of the two detectors can be supplied. The constant background for the two histograms is either given by
|
||
<a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background-determined intervals</span></a> or specified through <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN-block</span></a>.</p>
|
||
<p>The experimental asymmetry <span class="math notranslate nohighlight">\(a(k)\)</span> then is inferred from the two histograms:</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[a(k)=\frac{\left[N_{\mathrm{f}}(k)-B_{\mathrm{f}}\right]-\left[N_{\mathrm{b}}(k)-B_{\mathrm{b}}\right]}{\left[N_{\mathrm{f}}(k)-B_{\mathrm{f}}\right]+\left[N_{\mathrm{b}}(k)-B_{\mathrm{b}}\right]},\]</div>
|
||
<p>with</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{f}}(k)\)</span>: counts in the <strong>forward</strong> histogram channel <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{b}}(k)\)</span>: counts in the <strong>backward</strong> histogram channel <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p>:math:` B_{mathrm{f}}`: constant background in the <strong>forward</strong> histogram (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
<li><p>:math:` B_{mathrm{b}}`: constant background in the <strong>backward</strong> histogram (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>This theoretical asymmetry <span class="math notranslate nohighlight">\(a(t)\)</span> is used to fit the function</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[a(t)=\frac{(\alpha\beta +1)A(t)-(\alpha -1)}{(\alpha +1)-(\alpha\beta -1)A(t)},\]</div>
|
||
<p>where</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(\alpha\)</span>: accounts for the different detector efficiencies and solid angles (RUN block: <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">alpha</span></a>).</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(\beta\)</span>: accounts for the different detector asymmetries (RUN block: <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">beta</span></a>).</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(A(t)\)</span>: is the depolarization function as given in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>.</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>For the graphical representation in plot type 2 the equation above is rearranged to get <span class="math notranslate nohighlight">\(A(t)\)</span>:</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[A(t)=\frac{(\alpha -1)+(\alpha +1)a(t)}{(\alpha\beta +1)+(\alpha\beta -1)a(t)}=\frac{\alpha\left[N_{\mathrm{f}}(t)-B_{\mathrm{f}}\right]-\left[N_{\mathrm{b}}(t)-B_{\mathrm{b}}\right]}{\alpha\beta\left[N_{\mathrm{f}}(t)-B_{\mathrm{f}}\right]+\left[N_{\mathrm{b}}(t)-B_{\mathrm{b}}\right]}\]</div>
|
||
<p>and plotted together with the function given in the THEORY block.</p>
|
||
</div>
|
||
<div class="section" id="asymmetry-rrf-fit-fit-type-3">
|
||
<span id="asymmetry-rrf-fit"></span><span id="index-70"></span><h3>Asymmetry RRF Fit (fit type 3)<a class="headerlink" href="#asymmetry-rrf-fit-fit-type-3" title="Permalink to this headline">¶</a></h3>
|
||
<p>For asymmetry RRF Fit (fit type 3) two histograms are needed. In a first step, the unbinned asymmetry is formed as described for the asymmetry fit.
|
||
Afterwards the RRF transformation is carried out, <em>i.e.</em> point 4. and 5. as sketched in the single histogramm RRF fit. The same reservations as for
|
||
the single histogram RRF fit apply: <strong>if you not urgently need it: do not use it! There are better ways to deal with the analysis of high frequency data!</strong></p>
|
||
</div>
|
||
<div class="section" id="negative-muon-mgrsr-fit-fit-type-4">
|
||
<span id="negative-muon-musr-fit"></span><span id="index-71"></span><h3>Negative Muon μSR Fit (fit type 4)<a class="headerlink" href="#negative-muon-mgrsr-fit-fit-type-4" title="Permalink to this headline">¶</a></h3>
|
||
<p>The negative muon μSR fit (fit type 4) is used for single histogram fits of MuMinus, <em>i.e.</em></p>
|
||
<div class="math notranslate nohighlight">
|
||
\[N(t) = \sum_i N_i\,\mathrm{e}^{-t/\tau_i} \left[ 1 + A_i(t)\right] + N_{\rm bkg}(t)\]</div>
|
||
<p>where <span class="math notranslate nohighlight">\(i\)</span> runs over the different lifetime channels of <span class="math notranslate nohighlight">\(\mu^{-}\)</span>, and</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(N_i\)</span>: counts of lifetime channel <span class="math notranslate nohighlight">\(i\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(\tau_i\)</span>: lifetime of lifetime channel <span class="math notranslate nohighlight">\(i\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(A_i(t)\)</span>: depolarization function of lifetime channel <span class="math notranslate nohighlight">\(i\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\rm bkg}(t)\)</span>: <span class="math notranslate nohighlight">\(N_{\rm bkg}(t)= N_{\rm bkg,0} + \sum_k N_{\rm bkg,k} \cos(k \omega_{\rm cyclotron} t)\)</span> the background</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>Since MuMinus is quite generic, the full functional depends has to be written in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY Block</span></a>.</p>
|
||
</div>
|
||
<div class="section" id="beta-nmr-asymmetry-fit-fit-type-5">
|
||
<span id="bnmr-asymmetry-fit"></span><span id="index-72"></span><h3>beta-NMR Asymmetry Fit (fit type 5)<a class="headerlink" href="#beta-nmr-asymmetry-fit-fit-type-5" title="Permalink to this headline">¶</a></h3>
|
||
<p>Four histograms are needed for a beta-NMR asymmetry fit (fit type 5), two for positive helecity and two for negative. These are given by the <a class="reference internal" href="#msr-forward-backward"><span class="std std-ref">forward</span></a> and <a class="reference internal" href="#msr-forward-backward"><span class="std std-ref">backward</span></a> keywords
|
||
in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>. Additionally, the parameters <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">alpha</span></a> and <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">beta</span></a> which relate the detector
|
||
efficiencies, solid angles and initial asymmetries of the two detectors can be supplied. The constant background for the two histograms is either given by
|
||
<a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background-determined intervals</span></a> or specified through <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN-block</span></a>.</p>
|
||
<p>The experimental asymmetry <span class="math notranslate nohighlight">\(a(k)\)</span> is then calculated from the four histograms:</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[a(k)=\frac{\left[N_{\mathrm{fp}}(k)-B_{\mathrm{fp}}\right]-\left[N_{\mathrm{bp}}(k)-B_{\mathrm{bp}}\right]}{\left[N_{\mathrm{fp}}(k)-B_{\mathrm{fp}}\right]+\left[N_{\mathrm{bp}}(k)-B_{\mathrm{bp}}\right]}
|
||
- \frac{\left[N_{\mathrm{fm}}(k)-B_{\mathrm{fm}}\right]-\left[N_{\mathrm{bm}}(k)-B_{\mathrm{bm}}\right]}{\left[N_{\mathrm{fm}}(k)-B_{\mathrm{fm}}\right]+\left[N_{\mathrm{bm}}(k)-B_{\mathrm{bm}}\right]},\]</div>
|
||
<p>with</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{fp}}(k)\)</span>: counts in the <strong>forward</strong> histogram channel with positive helicity <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{bp}}(k)\)</span>: counts in the <strong>backward</strong> histogram channel with positive helicity <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(B_{\mathrm{fp}}\)</span>: constant background in the <strong>forward</strong> histogram with positive helicity (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(B_{\mathrm{bp}}\)</span>: constant background in the <strong>backward</strong> histogram with positive helicity (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{fm}}(k)\)</span>: counts in the <strong>forward</strong> histogram channel with negative helicity <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(N_{\mathrm{bm}}(k)\)</span>: counts in the <strong>backward</strong> histogram channel with negative helicity <span class="math notranslate nohighlight">\(k\)</span></p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(B_{\mathrm{fm}}\)</span>: constant background in the <strong>forward</strong> histogram with negative helicity (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(B_{\mathrm{bm}}\)</span>: constant background in the <strong>backward</strong> histogram with negative helicity (RUN block: <a class="reference internal" href="#msr-backgr-fix"><span class="std std-ref">backgr.fix</span></a> or <a class="reference internal" href="#msr-background-asymmetry"><span class="std std-ref">background</span></a>)</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>This theoretical asymmetry <span class="math notranslate nohighlight">\(a(t)\)</span> is used to fit the function</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[a(t)=\frac{(\alpha\beta +1)A(t)-(\alpha -1)}{(\alpha +1)-(\alpha\beta -1)A(t)} - \frac{(\alpha -1)-(\alpha\beta 1)A(t)}{(\alpha +1)+(\alpha\beta -1)Am(t)},\]</div>
|
||
<p>where</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p><span class="math notranslate nohighlight">\(\alpha\)</span>: accounts for the different detector efficiencies and solid angles (RUN block: <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">alpha</span></a>).</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(\beta\)</span>: accounts for the different detector asymmetries (RUN block: <a class="reference internal" href="#msr-alpha-beta"><span class="std std-ref">beta</span></a>).</p></li>
|
||
<li><p><span class="math notranslate nohighlight">\(A(t)\)</span>: is the depolarization function as given in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>.</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>For the graphical representation in plot type 5 the equation above is rearranged to get <span class="math notranslate nohighlight">\(A(t)\)</span>:</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[\begin{split}A(t) &= \frac{(\alpha -1)+(\alpha +1)a(t)}{(\alpha\beta+1)+(\alpha\beta -1)a(t)}-\frac{(\alpha +1)a(t)-(\alpha-1)}{(\alpha\beta +1)+(1-\alpha\beta)a(t)} \\
|
||
&= \frac{\alpha\left[N_{\mathrm{fp}}(t)-B_{\mathrm{fp}}\right]-\left[N_{\mathrm{bp}}(t)-B_{\mathrm{bp}}\right]}{\alpha\beta\left[N_{\mathrm{fp}}(t)-B_{\mathrm{fp}}\right]+\left[N_{\mathrm{bp}}(t)-B_{\mathrm{bp}}\right]} -\frac{\alpha\left[N_{\mathrm{fm}}(t)-B_{\mathrm{fm}}\right]-\left[N_{\mathrm{bm}}(t)-B_{\mathrm{bm}}\right]}{\alpha\beta\left[N_{\mathrm{fm}}(t)-B_{\mathrm{fm}}\right]+\left[N_{\mathrm{bm}}(t)-B_{\mathrm{bm}}\right]}\end{split}\]</div>
|
||
<p>and plotted together with the function given in the THEORY block.</p>
|
||
</div>
|
||
<div class="section" id="non-mgrsr-fit-fit-type-8">
|
||
<span id="non-musr-fit"></span><span id="index-73"></span><h3>Non-μSR Fit (fit type 8)<a class="headerlink" href="#non-mgrsr-fit-fit-type-8" title="Permalink to this headline">¶</a></h3>
|
||
<p>In the case of a non-μSR fit (fit type 8) the fitting function is</p>
|
||
<div class="math notranslate nohighlight">
|
||
\[y = f(x),\]</div>
|
||
<p>where <span class="math notranslate nohighlight">\(x, y\)</span> are given by <a class="reference internal" href="#msr-xy-data"><span class="std std-ref">xy-data</span></a> in the <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a>, and <span class="math notranslate nohighlight">\(f(x)\)</span> is the function defined in the <a class="reference internal" href="#msr-theory-block"><span class="std std-ref">THEORY block</span></a>.</p>
|
||
<p>The same applies for the plot with plot type 8.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="id38">
|
||
<span id="index-74"></span><span id="id39"></span><h2>User Functions<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h2>
|
||
<p><code class="docutils literal notranslate"><span class="pre">musrfit</span></code> offers the possibility to plug-in user-defined functions implemented in <code class="docutils literal notranslate"><span class="pre">C++</span></code> classes to the fitting and plotting routines.
|
||
In order to do so, basically two things are needed:</p>
|
||
<blockquote>
|
||
<div><ol class="arabic simple">
|
||
<li><p>a shared library containing the compiled class with the defined function.</p></li>
|
||
<li><p>a <a class="reference external" href="https://root.cern.ch/interacting-shared-libraries-rootcling">ROOT dictionary</a> that contains information about the functions in the shared library.</p></li>
|
||
</ol>
|
||
</div></blockquote>
|
||
<p>There are two possible ways to implement user functions and both will be explained below:</p>
|
||
<blockquote>
|
||
<div><ol class="arabic simple">
|
||
<li><p>a user function <em>without</em> global user-function-object access</p></li>
|
||
<li><p>a user function <em>with</em> global user-function-object access</p></li>
|
||
</ol>
|
||
</div></blockquote>
|
||
<p>Since the first is simpler this will be explained using an explicit example, before it is discussed why the second option is needed and how it can be used.</p>
|
||
<div class="section" id="user-function-without-global-user-function-object-access">
|
||
<span id="user-functions-without-global-part"></span><span id="index-75"></span><h3>User Function without global user-function-object access<a class="headerlink" href="#user-function-without-global-user-function-object-access" title="Permalink to this headline">¶</a></h3>
|
||
<p>In the following it is explained in detail how the implementation of a user function is done using the simple example of <span class="math notranslate nohighlight">\(f_a(x) = \sin(a x)/(a x)\)</span>,
|
||
where the parameter <span class="math notranslate nohighlight">\(a\)</span> should be determined by the fit. Although not necessary for this simple example, the source code is split into two parts,
|
||
namely a header file <code class="docutils literal notranslate"><span class="pre">TMyFunction.h</span></code> containing the class declaration and a second file <code class="docutils literal notranslate"><span class="pre">TMyFunction.cpp</span></code> including the function implementation
|
||
(the name of these files is your choice!).</p>
|
||
<p>To plug in the class to <code class="docutils literal notranslate"><span class="pre">musrfit</span></code>, it is necessary that the class derives from the base class <strong>PUserFcnBase</strong> defined in the header file <code class="docutils literal notranslate"><span class="pre">PUserFcnBase.h</span></code> (which is a part of <code class="docutils literal notranslate"><span class="pre">musrfit</span></code>).
|
||
In this abstract base class a function operator is defined that takes two arguments: the point where the function should be evaluated and a reference to a vector with all parameters of the function.</p>
|
||
<p>Therefore, the user’s header file could look like the following:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/***************************************************************************</span>
|
||
|
||
<span class="cm">TMyFunction.h</span>
|
||
|
||
<span class="cm">***************************************************************************/</span>
|
||
|
||
<span class="cp">#include</span> <span class="cpf">"PUserFcnBase.h"</span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><cassert></span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><cmath></span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><vector></span><span class="cp"></span>
|
||
|
||
<span class="k">using</span> <span class="k">namespace</span> <span class="n">std</span><span class="p">;</span>
|
||
|
||
<span class="k">class</span> <span class="nc">TMyFunction</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PUserFcnBase</span> <span class="p">{</span>
|
||
|
||
<span class="k">public</span><span class="o">:</span>
|
||
<span class="c1">// default constructor and destructor</span>
|
||
<span class="n">TMyFunction</span><span class="p">(){}</span>
|
||
<span class="o">~</span><span class="n">TMyFunction</span><span class="p">(){}</span>
|
||
|
||
<span class="c1">// global user-function-access functions, here without any functionality</span>
|
||
<span class="n">Bool_t</span> <span class="n">NeedGlobalPart</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">false</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="kt">void</span> <span class="n">SetGlobalPart</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">void</span><span class="o">*></span> <span class="o">&</span><span class="n">globalPart</span><span class="p">,</span> <span class="n">UInt_t</span> <span class="n">idx</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
|
||
<span class="n">Bool_t</span> <span class="n">GlobalPartIsValid</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> <span class="p">}</span>
|
||
|
||
<span class="c1">// function operator</span>
|
||
<span class="n">Double_t</span> <span class="k">operator</span><span class="p">()(</span><span class="n">Double_t</span><span class="p">,</span> <span class="k">const</span> <span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">>&</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
||
|
||
<span class="c1">// definition of the class for the ROOT dictionary</span>
|
||
<span class="n">ClassDef</span><span class="p">(</span><span class="n">TMyFunction</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="p">};</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the header file above the constructor (destructor) of the class is empty. This is not necessary, any code that should be executed when the
|
||
<a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> is read and the class object is created (destroyed) may be implemented in the constructor (destructor).
|
||
Another peculiarity is the <code class="docutils literal notranslate"><span class="pre">ClassDef</span></code> statement at the end of the class definition. It is needed for the ROOT dictionary generation
|
||
and has as arguments the class name and a revision number.</p>
|
||
<p>Please also be aware of the const-ness of the operator(). For an introductory discussion on that topic look for example <a class="reference external" href="http://en.wikipedia.org/wiki/Const_correctness">Const_correctness</a> and the links herein.</p>
|
||
<p>The actual implementation of the user function is done in the second source file. In this example it only contains the definition of the function operator() declared in the header file and might look like:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/***************************************************************************</span>
|
||
|
||
<span class="cm">TMyFunction.cpp</span>
|
||
|
||
<span class="cm">***************************************************************************/</span>
|
||
|
||
<span class="cp">#include</span> <span class="cpf">"TMyFunction.h"</span><span class="cp"></span>
|
||
|
||
<span class="n">ClassImp</span><span class="p">(</span><span class="n">TMyFunction</span><span class="p">)</span> <span class="c1">// for the ROOT dictionary</span>
|
||
|
||
<span class="n">Double_t</span> <span class="n">TMyFunction</span><span class="o">::</span><span class="k">operator</span><span class="p">()(</span><span class="n">Double_t</span> <span class="n">x</span><span class="p">,</span> <span class="k">const</span> <span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">></span> <span class="o">&</span><span class="n">par</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
|
||
<span class="n">assert</span><span class="p">(</span><span class="n">par</span><span class="p">.</span><span class="n">size</span><span class="p">()</span><span class="o">==</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// make sure the number of parameters handed to the function is correct</span>
|
||
|
||
<span class="k">const</span> <span class="n">Double_t</span> <span class="n">eps</span> <span class="o">=</span> <span class="mf">1.0e-5</span><span class="p">;</span>
|
||
<span class="n">Double_t</span> <span class="nf">arg</span><span class="p">(</span><span class="n">par</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">*</span><span class="n">x</span><span class="p">);</span>
|
||
|
||
<span class="k">if</span><span class="p">(</span><span class="n">arg</span> <span class="o"><</span> <span class="n">eps</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="mf">1.0</span><span class="p">;</span>
|
||
<span class="k">return</span> <span class="nf">sin</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span><span class="o">/</span><span class="n">arg</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Also this file contains a special statement for the ROOT dictionary generation (<code class="docutils literal notranslate"><span class="pre">ClassImp</span></code>), which is placed before the definition of the function.
|
||
If functions of more than one class are defined in the file, the <code class="docutils literal notranslate"><span class="pre">ClassImp</span></code> statements for the other classes follow right after the first one.</p>
|
||
<p>What is further needed for the <code class="docutils literal notranslate"><span class="pre">ROOT</span></code> dictionary is a so-called LinkDef file which again contains the class names of all classes that should be accessible
|
||
through the dictionary and has the following structure, where the “LinkDef.h” (or “linkdef.h” or “Linkdef.h”) at the end of the file name is mandatory:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/***************************************************************************</span>
|
||
|
||
<span class="cm">TMyLibraryLinkDef.h</span>
|
||
|
||
<span class="cm">***************************************************************************/</span>
|
||
|
||
<span class="cp">#ifdef __CINT__</span>
|
||
|
||
<span class="cp">#pragma link off all globals;</span>
|
||
<span class="cp">#pragma link off all classes;</span>
|
||
<span class="cp">#pragma link off all functions;</span>
|
||
|
||
<span class="cp">#pragma link C++ class TMyFunction+;</span>
|
||
|
||
<span class="cp">#endif </span><span class="c1">//__CINT__</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For compiling and linking it is wise to use a Makefile as for example the attached <a class="reference download internal" download="" href="_downloads/c06f924ba301a43e83dbbdfcfaf54ada/Makefile.TMyLibrary"><code class="xref download docutils literal notranslate"><span class="pre">Makefile.TMyLibrary</span></code></a>. It assumes standard <code class="docutils literal notranslate"><span class="pre">ROOT</span></code> and <code class="docutils literal notranslate"><span class="pre">musrfit</span></code>
|
||
installations and defines rules for the generation of the shared library <strong>libTMyLibrary.so</strong> including the class and the ROOT dictionary. In order
|
||
to get the library built and installed on the standard ROOT path just call:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make -f Makefile.TMyLibrary
|
||
$ make -f Makefile.TMyLibrary install
|
||
</pre></div>
|
||
</div>
|
||
<p>In case of a custom installation some paths in the Makefile might have to be adopted. For further information about the ROOT dictionary mechanism please
|
||
refer to the <a class="reference external" href="https://root.cern.ch/interacting-shared-libraries-rootcling">documentation</a>.</p>
|
||
<p>After installing the shared library the defined user function might be used in musrfit as described <a class="reference internal" href="#msr-theory-block-user-functions"><span class="std std-ref">above</span></a>.</p>
|
||
<p>Finally, please be aware of the <a class="reference internal" href="#user-function-important"><span class="std std-ref">remark</span></a> at the end of this section.</p>
|
||
</div>
|
||
<div class="section" id="user-function-with-global-user-function-object-access">
|
||
<span id="user-functions-with-global-part"></span><span id="index-76"></span><h3>User Function with global user-function-object access<a class="headerlink" href="#user-function-with-global-user-function-object-access" title="Permalink to this headline">¶</a></h3>
|
||
<p>Before explaining how to use global objects within user functions, it will be shortly explained where is the problem and why this might be a sensible approach.
|
||
In <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> each <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN block</span></a> (histogram, asymmetry, …) is owning its own theory-function tree. An example is shown in the figure below.
|
||
The bluish nodes are default musrfit functions, whereas the red nodes represent user functions (here labeled by <code class="docutils literal notranslate"><span class="pre">uF1</span></code> and <code class="docutils literal notranslate"><span class="pre">uF2</span></code>). Without global user-function
|
||
object, these nodes are independent entities. This means if the msr file contains <em>n</em> run blocks, the user function <code class="docutils literal notranslate"><span class="pre">uF1</span></code> will be called <em>n</em> times for each step
|
||
in the calculation. If the user function is performing CPU-demanding calculations this is rather inefficient.</p>
|
||
<img alt="_images/theory-tree-with-user-fcn.svg" src="_images/theory-tree-with-user-fcn.svg" /><p>Therefore, it is possible to associate to each user function (<code class="docutils literal notranslate"><span class="pre">uFx</span></code>) a global user-function object (<code class="docutils literal notranslate"><span class="pre">g_uFx</span></code>). The idea is the following: If <code class="docutils literal notranslate"><span class="pre">uFx</span></code> needs to
|
||
perform very time-consuming calculations (<em>e.g.</em> calculate an Abrikosov vortex lattice or the nonlocal response of a superconductor in the Meissner state) this
|
||
can be transferred to the global user-function object (<code class="docutils literal notranslate"><span class="pre">g_uFx</span></code>) and hence the time-consuming calculation is only performed once per cycle (compared to <em>n</em> times
|
||
without <code class="docutils literal notranslate"><span class="pre">g_uFx</span></code>), thus speeding up the fit.</p>
|
||
<p>After explaining the purpose of the global user-function-object approach, some explanations how to interface it follow here. Since the interface is very close to
|
||
the <a class="reference internal" href="#user-functions-without-global-part"><span class="std std-ref">user function without global objects</span></a>, only the additionally necessary overhead is explained here.</p>
|
||
<p>The user’s header file could look like the following:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/***************************************************************************</span>
|
||
|
||
<span class="cm">TMyFunction.h</span>
|
||
|
||
<span class="cm">***************************************************************************/</span>
|
||
|
||
<span class="cp">#include</span> <span class="cpf">"PUserFcnBase.h"</span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><cassert></span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><cmath></span><span class="cp"></span>
|
||
<span class="cp">#include</span> <span class="cpf"><vector></span><span class="cp"></span>
|
||
|
||
<span class="k">using</span> <span class="k">namespace</span> <span class="n">std</span><span class="p">;</span>
|
||
|
||
<span class="k">class</span> <span class="nc">TMyGlobalFunction</span> <span class="p">{</span>
|
||
|
||
<span class="k">public</span><span class="o">:</span>
|
||
<span class="c1">// default constructor and destructor</span>
|
||
<span class="n">TMyGlobalFunction</span><span class="p">(){}</span>
|
||
<span class="o">~</span><span class="n">TMyGlobalFunction</span><span class="p">(){}</span>
|
||
|
||
<span class="n">Bool_t</span> <span class="n">IsValid</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">fValid</span><span class="p">;</span> <span class="p">}</span>
|
||
|
||
<span class="c1">// the following function will check if something needs to be calculated, which</span>
|
||
<span class="c1">// is the case if param != fPrevParam</span>
|
||
<span class="kt">void</span> <span class="n">CalcSomethingCPUExpensive</span><span class="p">(</span><span class="k">const</span> <span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">></span> <span class="o">&</span><span class="n">param</span><span class="p">);</span>
|
||
|
||
<span class="c1">// this routine will return the calculated values, e.g. B(z,E) for TMyFunction::operator()()</span>
|
||
<span class="c1">// (...) here sketches only that some parameters are likley to be fed</span>
|
||
<span class="n">Double_t</span> <span class="nf">GetWhatIsNeeded</span><span class="p">(...);</span>
|
||
|
||
<span class="k">private</span><span class="o">:</span>
|
||
<span class="n">Bool_t</span> <span class="n">fValid</span><span class="p">;</span>
|
||
<span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">></span> <span class="n">fPrevParam</span><span class="p">;</span>
|
||
|
||
<span class="c1">// definition of the class for the ROOT-dictionary</span>
|
||
<span class="n">ClassDef</span><span class="p">(</span><span class="n">TMyGlobalFunction</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="p">};</span>
|
||
|
||
<span class="k">class</span> <span class="nc">TMyFunction</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PUserFcnBase</span> <span class="p">{</span>
|
||
|
||
<span class="k">public</span><span class="o">:</span>
|
||
<span class="c1">// default constructor and destructor</span>
|
||
<span class="n">TMyFunction</span><span class="p">(){}</span>
|
||
<span class="o">~</span><span class="n">TMyFunction</span><span class="p">(){}</span>
|
||
|
||
<span class="c1">// global user-function-access functions, here with some functionality</span>
|
||
<span class="n">Bool_t</span> <span class="n">NeedGlobalPart</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> <span class="p">}</span>
|
||
<span class="kt">void</span> <span class="n">SetGlobalPart</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">void</span><span class="o">*></span> <span class="o">&</span><span class="n">globalPart</span><span class="p">,</span> <span class="n">UInt_t</span> <span class="n">idx</span><span class="p">);</span>
|
||
<span class="n">Bool_t</span> <span class="nf">GlobalPartIsValid</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
|
||
|
||
<span class="c1">// function operator</span>
|
||
<span class="n">Double_t</span> <span class="nf">operator</span><span class="p">()(</span><span class="n">Double_t</span><span class="p">,</span> <span class="k">const</span> <span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">>&</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
||
|
||
<span class="k">private</span><span class="o">:</span>
|
||
<span class="n">Bool_t</span> <span class="n">fValid</span><span class="p">;</span>
|
||
<span class="n">Bool_t</span> <span class="n">fInvokedGlobal</span><span class="p">;</span>
|
||
<span class="n">Int_t</span> <span class="n">fIdxGlobal</span><span class="p">;</span>
|
||
<span class="n">TMyGlobalFunction</span> <span class="o">*</span> <span class="n">fGlobalUserFcn</span><span class="p">;</span>
|
||
|
||
<span class="c1">// definition of the class for the ROOT dictionary</span>
|
||
<span class="n">ClassDef</span><span class="p">(</span><span class="n">TMyFunction</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="p">};</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Compared to the <a class="reference internal" href="#user-functions-without-global-part"><span class="std std-ref">user function without global objects</span></a>, here the <code class="docutils literal notranslate"><span class="pre">NeedGlobalPart()</span></code> method returns true
|
||
meaning that a global user-function object will be needed. Furthermore, the methods <code class="docutils literal notranslate"><span class="pre">SetGlobalPart(vector<void*></span> <span class="pre">&globalPart,</span> <span class="pre">UInt_t</span> <span class="pre">idx)</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">GlobalPartIsValid()</span></code> now need to be implemented. The method <code class="docutils literal notranslate"><span class="pre">SetGlobalPart(vector<void*></span> <span class="pre">&globalPart,</span> <span class="pre">UInt_t</span> <span class="pre">idx)</span></code> is used to link the
|
||
<code class="docutils literal notranslate"><span class="pre">fGlobalUserFcn</span></code> to the global user object. This routine will look like:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="n">TMyFunction</span><span class="o">::</span><span class="n">SetGlobalPart</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">void</span> <span class="o">*></span> <span class="o">&</span><span class="n">globalPart</span><span class="p">,</span> <span class="n">UInt_t</span> <span class="n">idx</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="n">fIdxGlobal</span> <span class="o">=</span> <span class="k">static_cast</span><span class="o"><</span><span class="n">Int_t</span><span class="o">></span><span class="p">(</span><span class="n">idx</span><span class="p">);</span>
|
||
|
||
<span class="k">if</span> <span class="p">((</span><span class="n">Int_t</span><span class="p">)</span><span class="n">globalPart</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o"><=</span> <span class="n">fIdxGlobal</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// global user function not present, invoke it</span>
|
||
<span class="n">fGlobalUserFcn</span> <span class="o">=</span> <span class="k">new</span> <span class="n">TMyGlobalFunction</span><span class="p">();</span>
|
||
<span class="k">if</span> <span class="p">(</span><span class="n">fGlobalUserFcn</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// global user function object couldn't be invoked -> error</span>
|
||
<span class="n">fValid</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
|
||
<span class="n">cerr</span> <span class="o"><<</span> <span class="n">endl</span> <span class="o"><<</span> <span class="s">">> TMyFunction::SetGlobalPart(): **ERROR** Couldn't invoke global user function object, sorry ..."</span> <span class="o"><<</span> <span class="n">endl</span><span class="p">;</span>
|
||
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="c1">// global user function object could be invoked -> resize to global user function vector and keep the pointer to the corresponding object</span>
|
||
<span class="n">globalPart</span><span class="p">.</span><span class="n">resize</span><span class="p">(</span><span class="n">fIdxGlobal</span><span class="o">+</span><span class="mi">1</span><span class="p">);</span>
|
||
<span class="n">globalPart</span><span class="p">[</span><span class="n">fIdxGlobal</span><span class="p">]</span> <span class="o">=</span> <span class="k">dynamic_cast</span><span class="o"><</span><span class="n">TMyGlobalFunction</span><span class="o">*></span><span class="p">(</span><span class="n">fGlobalUserFcn</span><span class="p">);</span>
|
||
<span class="n">fValid</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
|
||
<span class="n">fInvokedGlobal</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="c1">// global user function already present hence just retrieve a pointer to it</span>
|
||
<span class="n">fValid</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
|
||
<span class="n">fGlobalUserFcn</span> <span class="o">=</span> <span class="p">(</span><span class="n">TMyGlobalFunction</span><span class="o">*</span><span class="p">)</span><span class="n">globalPart</span><span class="p">[</span><span class="n">fIdxGlobal</span><span class="p">];</span>
|
||
<span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>What it does is the following: it first checks if the object is already present in the global user-function-object vector and if not creates it. If it is already present,
|
||
the pointer to the global object vector is just kept (see figure above).</p>
|
||
<p>A sketch of the method <code class="docutils literal notranslate"><span class="pre">operator()(Double_t,</span> <span class="pre">const</span> <span class="pre">vector&)</span> <span class="pre">const</span></code> will then look like (pseudo-code snippet):</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Double_t</span> <span class="n">TMyFunction</span><span class="o">::</span><span class="k">operator</span><span class="p">()(</span><span class="n">Double_t</span> <span class="n">t</span><span class="p">,</span> <span class="k">const</span> <span class="n">vector</span><span class="o"><</span><span class="n">Double_t</span><span class="o">></span> <span class="o">&</span><span class="n">param</span><span class="p">)</span> <span class="k">const</span>
|
||
<span class="p">{</span>
|
||
<span class="n">Double_t</span> <span class="n">result</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">;</span>
|
||
|
||
<span class="c1">// do something, checking, etc.</span>
|
||
<span class="p">...</span>
|
||
|
||
<span class="c1">// call the global user function object (which will calculate something</span>
|
||
<span class="c1">// if param has changed). Hence it will only be done once in a iteration,</span>
|
||
<span class="c1">// and therefore only once for all run blocks.</span>
|
||
<span class="n">fGlobalUserFcn</span><span class="o">-></span><span class="n">CalcSomethingCPUExpensive</span><span class="p">(</span><span class="n">param</span><span class="p">);</span>
|
||
|
||
<span class="c1">// extract the needed values from the global object</span>
|
||
<span class="n">value</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="o">=</span> <span class="n">fGlobalUserFcn</span><span class="o">-></span><span class="n">GetWhatIsNeeded</span><span class="p">(...);</span>
|
||
|
||
<span class="c1">// use 'value(s)' to do some run block specific calculations (not/less CPU demanding)</span>
|
||
<span class="p">...</span>
|
||
|
||
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This way the efficiency of the user function can be increased by almost a factor of <em>n</em> (where <em>n</em> is the number of <a class="reference internal" href="#msr-run-block"><span class="std std-ref">RUN blocks</span></a>).</p>
|
||
<div class="admonition note" id="user-function-important">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> has been built with parallelization support (default for <code class="docutils literal notranslate"><span class="pre">GCC</span></code> > 4.2) it should be taken care of the thread safety of the <strong>user-function operator()</strong>.
|
||
During the function optimization of <code class="docutils literal notranslate"><span class="pre">musrfit</span></code> the operator() is called once for any given set of parameters in order to allow the safe execution of any calculation.
|
||
Within the <a class="reference internal" href="#single-histogram-fit"><span class="std std-ref">single-histogram</span></a> and <a class="reference internal" href="#asymmetry-fit"><span class="std std-ref">asymmetry</span></a> fits the calculation of <span class="math notranslate nohighlight">\(\chi^2\)</span> or the maximum log-likelihood is
|
||
parallelized and the operator() is expected to evaluate to reasonable values for a fixed set of parameters (but changing <em>t</em>) beginning with the second function call.
|
||
In case this cannot be ensured, the parallelization can be disabled by <em>–disable-omp</em> on the configure level of the program installation.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="technical-description-of-the-musrfit-framework">
|
||
<span id="technical-musrfit"></span><span id="index-77"></span><h2>Technical Description of the musrfit framework<a class="headerlink" href="#technical-description-of-the-musrfit-framework" title="Permalink to this headline">¶</a></h2>
|
||
<p>A technical description of the musrfit framework can be found on its own <a class="reference external" href="http://lmu.web.psi.ch/musrfit/technical/index.html">docu</a>.</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">User manual</a><ul>
|
||
<li><a class="reference internal" href="#introduction">Introduction</a></li>
|
||
<li><a class="reference internal" href="#available-executables-configuration-files-and-their-basic-usage">Available Executables, Configuration Files and their Basic Usage</a><ul>
|
||
<li><a class="reference internal" href="#musrfit">musrfit</a></li>
|
||
<li><a class="reference internal" href="#musrview">musrview</a></li>
|
||
<li><a class="reference internal" href="#musrft">musrFT</a></li>
|
||
<li><a class="reference internal" href="#musrt0">musrt0</a></li>
|
||
<li><a class="reference internal" href="#msr2msr">msr2msr</a></li>
|
||
<li><a class="reference internal" href="#msr2data">msr2data</a></li>
|
||
<li><a class="reference internal" href="#any2many">any2many</a></li>
|
||
<li><a class="reference internal" href="#dump-header">dump_header</a></li>
|
||
<li><a class="reference internal" href="#musrfit-startup-xml">musrfit_startup.xml</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#description-of-the-msr-file-format">Description of the msr File Format</a><ul>
|
||
<li><a class="reference internal" href="#the-title">The Title</a></li>
|
||
<li><a class="reference internal" href="#the-fitparameter-block">The FITPARAMETER Block</a></li>
|
||
<li><a class="reference internal" href="#the-theory-block">The THEORY Block</a></li>
|
||
<li><a class="reference internal" href="#the-functions-block">The FUNCTIONS Block</a></li>
|
||
<li><a class="reference internal" href="#the-global-block">The GLOBAL Block</a></li>
|
||
<li><a class="reference internal" href="#the-run-block">The RUN Block</a></li>
|
||
<li><a class="reference internal" href="#the-commands-block">The COMMANDS Block</a></li>
|
||
<li><a class="reference internal" href="#the-fourier-block">The FOURIER Block</a></li>
|
||
<li><a class="reference internal" href="#the-plot-block">The PLOT Block</a></li>
|
||
<li><a class="reference internal" href="#the-statistic-block">The STATISTIC Block</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#fit-types">Fit Types</a><ul>
|
||
<li><a class="reference internal" href="#single-histogram-fit-fit-type-0">Single Histogram Fit (fit type 0)</a></li>
|
||
<li><a class="reference internal" href="#single-histogram-rrf-fit-fit-type-1">Single Histogram RRF Fit (fit type 1)</a></li>
|
||
<li><a class="reference internal" href="#asymmetry-fit-fit-type-2">Asymmetry Fit (fit type 2)</a></li>
|
||
<li><a class="reference internal" href="#asymmetry-rrf-fit-fit-type-3">Asymmetry RRF Fit (fit type 3)</a></li>
|
||
<li><a class="reference internal" href="#negative-muon-mgrsr-fit-fit-type-4">Negative Muon μSR Fit (fit type 4)</a></li>
|
||
<li><a class="reference internal" href="#beta-nmr-asymmetry-fit-fit-type-5">beta-NMR Asymmetry Fit (fit type 5)</a></li>
|
||
<li><a class="reference internal" href="#non-mgrsr-fit-fit-type-8">Non-μSR Fit (fit type 8)</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#id38">User Functions</a><ul>
|
||
<li><a class="reference internal" href="#user-function-without-global-user-function-object-access">User Function without global user-function-object access</a></li>
|
||
<li><a class="reference internal" href="#user-function-with-global-user-function-object-access">User Function with global user-function-object access</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#technical-description-of-the-musrfit-framework">Technical Description of the musrfit framework</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="tutorial.html"
|
||
title="previous chapter">Tutorial for <code class="docutils literal notranslate"><span class="pre">musrfit</span></code></a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="user-libs.html"
|
||
title="next chapter">Documentation of user libs (user functions)</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="_sources/user-manual.rst.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
</div>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">$('#searchbox').show(0);</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="user-libs.html" title="Documentation of user libs (user functions)"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="tutorial.html" title="Tutorial for musrfit"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">musrfit 1.6.0 documentation</a> »</li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2020, Andreas Suter.
|
||
Last updated on May 14, 2020.
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.2.2.
|
||
</div>
|
||
</body>
|
||
</html> |