Add unstable changes for c789908

unstable/API_Reference.html

@@ -1781,7 +1781,7 @@ <h2><a class="toc-backref" href="#id50" role="doc-backlink"><code class="docutil
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Citing.html

@@ -117,7 +117,7 @@ <h1>Citing Horace<a class="headerlink" href="#citing-horace" title="Permalink to
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Contributing.html

@@ -139,7 +139,7 @@ <h2>Contributing code<a class="headerlink" href="#contributing-code" title="Perm
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Developers.html

@@ -126,7 +126,7 @@ <h1>For Developers<a class="headerlink" href="#for-developers" title="Permalink
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Example_scripts.html

@@ -53,6 +53,7 @@
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/basic_usage.html">Basic Usage</a></li>
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/corrections.html">Corrections</a></li>
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/data_corrections.html">Data Corrections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="example_scripts/dnd_vs_sqw.html">dnd vs sqw: the difference</a></li>
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/gpo_fitting_spinw.html">GPO fitting SpinW</a></li>
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/horace_whole_course_full_script.html">Horace course</a></li>
 <li class="toctree-l2"><a class="reference internal" href="example_scripts/sample_misalignment.html">Sample Misalignment</a></li>
@@ -111,6 +112,7 @@ <h1>Example Scripts<a class="headerlink" href="#example-scripts" title="Permalin
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/basic_usage.html">Basic Usage</a></li>
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/corrections.html">Corrections</a></li>
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/data_corrections.html">Data Corrections</a></li>
+<li class="toctree-l1"><a class="reference internal" href="example_scripts/dnd_vs_sqw.html">dnd vs sqw: the difference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/gpo_fitting_spinw.html">GPO fitting SpinW</a></li>
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/horace_whole_course_full_script.html">Horace course</a></li>
 <li class="toctree-l1"><a class="reference internal" href="example_scripts/sample_misalignment.html">Sample Misalignment</a></li>
@@ -135,7 +137,7 @@ <h1>Example Scripts<a class="headerlink" href="#example-scripts" title="Permalin
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/General_disclaimer.html

@@ -97,7 +97,7 @@ <h1>General disclaimer<a class="headerlink" href="#general-disclaimer" title="Pe
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Horace_manual.html

@@ -149,7 +149,7 @@ <h1>Horace Manual<a class="headerlink" href="#horace-manual" title="Permalink to
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/How_to_cite_Horace.html

@@ -110,7 +110,7 @@ <h1>How to cite Horace<a class="headerlink" href="#how-to-cite-horace" title="Pe
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Introduction.html

@@ -125,7 +125,7 @@ <h1>Introduction and Setup<a class="headerlink" href="#introduction-and-setup" t
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Papers_citing_Horace.html

@@ -227,7 +227,7 @@ <h2>2018<a class="headerlink" href="#id9" title="Permalink to this heading"><
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Previous_versions.html

@@ -105,7 +105,7 @@ <h1>Previous Versions<a class="headerlink" href="#previous-versions" title="Perm
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/Unsorted.html

@@ -152,7 +152,7 @@ <h1>Unsorted Manual Pages<a class="headerlink" href="#unsorted-manual-pages" tit
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/User_guide.html

@@ -191,7 +191,7 @@ <h1>User’s Guide<a class="headerlink" href="#user-s-guide" title="Permalink to
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/_sources/example_scripts/dnd_vs_sqw.rst.txt

@@ -0,0 +1,213 @@
+dnd vs sqw: the difference
+##########################
+
+This tutorial was originally a script designed to illustrate and explain the
+different key data types -- ``sqw`` and ``dnd`` (the ``d0d``, ``d1d`, ...
+family). -- in Horace, and why they are important.
+
+`Whole script`_ available here.
+
+The key difference is that ``sqw`` objects contain the exact data for each
+measurement (pixels) while ``dnd`` objects simply contain the histogrammed
+(binned) accumulation of these data.
+
+For more information on the differences between ``dnd`` and ``sqw``, :ref:`see
+here <manual/FAQ:What is the difference between sqw and dnd objects>`.
+
+.. code-block:: matlab
+
+   %Take two cuts:
+   sqw_file='/mnt/data/Science/URu2Si2/data/sqw/Ei81_20K.sqw';
+
+   proj = line_proj([1, 0, 0], [0, 1, 0]);
+
+   csqw=cut(sqw_file, proj, [-0.5, 0.5], [-4, 0.04, -2], [-0.05, 0.05], [0, 0.8, 60]);
+
+   %identical to above, except extra argument at the end
+   cdnd=cut(sqw_file, proj, [-0.5, 0.5], [-4, 0.04, -2], [-0.05, 0.05], [0, 0.8, 60], '-nopix');
+
+   plot(compact(csqw));
+   lz 0 10;
+   keep_figure;
+
+   plot(compact(cdnd));
+   lz 0 10;
+   keep_figure;
+
+::
+
+   Taking cut from data in file /mnt/data/Science/URu2Si2/data/sqw/Ei81_20K.sqw...
+   Step 1 of 1; Have read data for 5579774 pixels -- now processing data... -----> retained 1121852 pixels
+   Taking cut from data in file /mnt/data/Science/URu2Si2/data/sqw/Ei81_20K.sqw...
+   Step 1 of 1; Have read data for 5579774 pixels -- now processing data... -----> retained 1121852 pixels
+
+.. figure:: ../images/dnd_vs_sqw_fig1.jpg
+   :align: center
+   :width: 500
+
+.. figure:: ../images/dnd_vs_sqw_fig2.jpg
+   :align: center
+   :width: 500
+
+
+The plots look (are!) identical. So what's the difference? Double click on them
+in the Workspace part of the Matlab window. You can see that the ``csqw`` object
+has a lot more information associated with it.
+
+General principle
+=================
+
+Use ``dnd`` if you are just looking at the data - it takes up less computer
+memory, which is a good thing.
+
+If you want to ``fit`` or ``simulate`` the data and you are only simulating a
+basic function (i.e. using ``func_eval``, ``multifit_func``, etc) that does not
+depend on all 4 coordinates of Q and E, then use a ``dnd``.
+
+Example:
+
+.. code-block:: matlab
+
+   cgaussdnd=func_eval(cdnd, @gauss2d, [1, -3, 30, 0.2, 0.1, 100]);
+   plot(cgaussdnd);
+   keep_figure;
+
+   cgausssqw=func_eval(csqw, @gauss2d, [1, -3, 30, 0.2, 0.1, 100]);
+   plot(cgausssqw);
+   keep_figure;
+
+
+.. figure:: ../images/dnd_vs_sqw_fig3.jpg
+   :align: center
+   :width: 500
+
+.. figure:: ../images/dnd_vs_sqw_fig4.jpg
+   :align: center
+   :width: 500
+
+
+The two figures are identical, because the func_eval routine only uses the plot
+axis coordinates as its input, not (H, K, L, E).
+
+If you want to ``fit`` or ``simulate`` data with an S(Q, E) model, you should
+use ``sqw``. This is because you will account for the fact that you had to
+integrate along the non-plot axes correctly. The following example illustrates
+why this is important:
+
+.. code-block:: matlab
+
+   %model of ferromagnetic spin waves in the Horace demo
+   csimsqw=sqw_eval(csqw, @demo_FM_spinwaves_2dSlice_sqw, [4, 2, 1, 1, 1]);
+   csimdnd=sqw_eval(cdnd, @demo_FM_spinwaves_2dSlice_sqw, [4, 2, 1, 1, 1]);
+
+   %Dispersion has equal steepness along all reciprocal space directions.
+   plot(csimsqw);
+   keep_figure;
+
+   plot(csimdnd);
+   keep_figure;
+
+.. figure:: ../images/dnd_vs_sqw_fig5.jpg
+   :align: center
+   :width: 500
+
+.. figure:: ../images/dnd_vs_sqw_fig6.jpg
+   :align: center
+   :width: 500
+
+These are totally different.
+
+Why?
+
+Because the simulation of the ``sqw`` object includes the dispersion along the
+H-axis, and calculates what it is for the pixels actually measured. The
+simulation of the ``dnd`` object assumes that every point has the average value
+of H (zero in this case). So the latter gives a sharp dispersion, whereas the
+former is very broad.
+
+So if you have data from a system where there is some variation in the signal
+along a non-plot axis, you should use ``simulate`` with ``sqw`` objects in order
+to capture this correctly.
+
+Specific case A: resolution modelling
+=====================================
+
+If you want to include resolution in your simulation or fitting, you must use
+Tobyfit, and you also need the detector pixel information that you get in an
+``sqw`` object but not in a ``dnd``.
+
+.. warning::
+
+   Tobyfit will give an error message if you try to use it with a ``dnd``.
+
+Specific case B: spurion identification
+=======================================
+
+See separate tutorial about how to do this. Basically, if you need to know
+something about data from a particular run, or from a particular detector, you
+need ``sqw``.
+
+Specific case C: smoothing
+==========================
+
+If you apply the ``smooth`` algorithm to your data you will get a dataset of the
+same type back again.  Smoothing works for ``dnd``, but is forbidden for ``sqw``
+data. The reason is that the smoothing operation only makes sense in the plot
+axis coordinate frame. But doing that means you lose the connection between the
+signal displayed in the plot and the detector pixel information that contributed
+to it.
+
+Specific case D: symmetrisation
+===============================
+
+.. warning::
+
+   Currently in Horace 4.0.0, ``dnd`` symmetrisation is disabled. Due to
+   extended transforms in the ``sqw`` object.
+
+Symmetrisation does different things for ``sqw`` and ``dnd`` data. The latter
+can be folded along an axis parallel to a plot axis. The former can be folded
+along any axis. Generally you are much safer doing symmetrisation with ``sqw``
+objects.
+
+Whole Script
+============
+
+.. code-block:: matlab
+
+   %Take two cuts:
+   sqw_file='/mnt/data/Science/URu2Si2/data/sqw/Ei81_20K.sqw';
+
+   proj = line_proj([1, 0, 0], [0, 1, 0]);
+
+   csqw=cut(sqw_file, proj, [-0.5, 0.5], [-4, 0.04, -2], [-0.05, 0.05], [0, 0.8, 60]);
+
+   %identical to above, except extra argument at the end
+   cdnd=cut(sqw_file, proj, [-0.5, 0.5], [-4, 0.04, -2], [-0.05, 0.05], [0, 0.8, 60], '-nopix');
+
+   plot(compact(csqw));
+   lz 0 10;
+   keep_figure;
+
+   plot(compact(cdnd));
+   lz 0 10;
+   keep_figure;
+
+   cgaussdnd=func_eval(cdnd, @gauss2d, [1, -3, 30, 0.2, 0.1, 100]);
+   plot(cgaussdnd);
+   keep_figure;
+
+   cgausssqw=func_eval(csqw, @gauss2d, [1, -3, 30, 0.2, 0.1, 100]);
+   plot(cgausssqw);
+   keep_figure;
+
+   %model of ferromagnetic spin waves in the Horace demo
+   csimsqw=sqw_eval(csqw, @demo_FM_spinwaves_2dSlice_sqw, [4, 2, 1, 1, 1]);
+   csimdnd=sqw_eval(cdnd, @demo_FM_spinwaves_2dSlice_sqw, [4, 2, 1, 1, 1]);
+
+   %Dispersion has equal steepness along all reciprocal space directions.
+   plot(csimsqw);
+   keep_figure;
+
+   plot(csimdnd);
+   keep_figure;

unstable/developers/Become_a_developer.html

@@ -104,7 +104,7 @@ <h1>Become a developer<a class="headerlink" href="#become-a-developer" title="Pe
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/developers/Developer_info.html

@@ -133,7 +133,7 @@ <h2>Building Horace distribution kit<a class="headerlink" href="#building-horace
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/developers/For_Developers.html

@@ -115,7 +115,7 @@ <h2>Getting started<a class="headerlink" href="#getting-started" title="Permalin
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/developers/Known_bugs.html

@@ -141,7 +141,7 @@ <h3>Fatal Read Error<a class="headerlink" href="#fatal-read-error" title="Permal
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>
 

unstable/example_scripts/advanced_plotting.html

@@ -53,6 +53,7 @@
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html">Basic Usage</a></li>
 <li class="toctree-l2"><a class="reference internal" href="corrections.html">Corrections</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_corrections.html">Data Corrections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="dnd_vs_sqw.html">dnd vs sqw: the difference</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gpo_fitting_spinw.html">GPO fitting SpinW</a></li>
 <li class="toctree-l2"><a class="reference internal" href="horace_whole_course_full_script.html">Horace course</a></li>
 <li class="toctree-l2"><a class="reference internal" href="sample_misalignment.html">Sample Misalignment</a></li>
@@ -305,7 +306,7 @@ <h1>Advanced Plotting<a class="headerlink" href="#advanced-plotting" title="Perm
 
   <div role="contentinfo">
     <p>&#169; Copyright 2006-2023, STFC RAL.
-      <span class="lastupdated">Last updated on Nov 11, 2023, 10:14:03 PM.
+      <span class="lastupdated">Last updated on Nov 14, 2023, 11:48:03 AM.
       </span></p>
   </div>