adopted cmake to newest DKS version.

This patch fixes compilation errors that arise with recent ROOT versions (e.g., 6.34.02),
which require a ROOT::Minuit2::MnStrategy object to be passed when initializing the
ROOT::Minuit2::MnX (X = Migrad, Simplex, Minimize) minimizers (i.e., instead of the integer
representing the "strategy").

.gitignore

@@ -0,0 +1,2 @@
+# ignore all files generated from an in-repo build
+build/

CMakeLists.txt

@@ -1,9 +1,10 @@
-# - musrfit
+# - musrfit --- DKS -----------------------------------------------------------
 cmake_minimum_required(VERSION 3.17)
 
-project(musrfit VERSION 1.9.3 LANGUAGES C CXX)
+project(musrfit VERSION 1.9.9 LANGUAGES C CXX)
 
 #--- musrfit specific options -------------------------------------------------
+option(dks "build musrfit with DKS (GPU/MIC) support" ON)
 option(nexus "build optional NeXus support. Needed for ISIS" OFF)
 option(ASlibs "build optional ASlibs" OFF)
 option(BMWlibs "build optional BMWlibs" OFF)
@@ -71,7 +72,7 @@ find_package(PkgConfig REQUIRED)
 find_package(Git REQUIRED)
 
 #--- check for ROOT -----------------------------------------------------------
-find_package(ROOT 6.18 REQUIRED COMPONENTS Gui MathMore Minuit2 XMLParser)
+find_package(ROOT 6.16 REQUIRED COMPONENTS Gui MathMore Minuit2 XMLParser)
 if (ROOT_mathmore_FOUND)
   execute_process(COMMAND root-config --bindir OUTPUT_VARIABLE ROOT_BINDIR)
   string(STRIP ${ROOT_BINDIR} ROOT_BINDIR)
@@ -117,6 +118,42 @@ if (try_OpenMP)
   endif (OpenMP_CXX_FOUND)
 endif (try_OpenMP)
 
+#--- check for CUDA and/or OpenCL followed by DKS -----------------------------
+if (dks)
+  find_package(CUDA)
+  if (CUDA_FOUND)
+    message (STATUS "CUDA include: ${CUDA_INCLUDE_DIRS}")
+    message (STATUS "CUDA libs: ${CUDA_TOOLKIT_ROOT_DIR}/lib64")
+    message (STATUS "CUDA version: ${CUDA_VERSION}")
+    add_definitions(${DKS_CMAKE_CXX_FLAGS})
+  endif (CUDA_FOUND)
+
+  if (NOT CUDA_FOUND)
+    message(STATUS "CUDA not found, looking for OpenCL")
+    find_package(OpenCL)
+    if (OpenCL_FOUND)
+      message(STATUS "OpenCL version : ${OpenCL_VERSION_STRING}")
+      message(STATUS "OpenCL include dir: ${OpenCL_INCLUDE_DIR}")
+      message(STATUS "OpenCL library dir: ${OpenCL_LIBRARY}")
+      add_definitions(-DDKS_OPENCL)
+    endif (OpenCL_FOUND)
+  endif (NOT CUDA_FOUND)
+
+  if (NOT CUDA_FOUND AND NOT OpenCL_FOUND)
+    message(WARNING ">> Neither CUDA nor OpenCL found which are required for DKS, hence disable DKS support <<")
+  else (NOT CUDA_FOUND AND NOT OpenCL_FOUND)
+    find_package(DKS "1.2.0"
+	    HINTS "/usr/local/lib/"
+	  )
+ endif (NOT CUDA_FOUND AND NOT OpenCL_FOUND) 
+endif (dks)
+
+if (DKS_FOUND)
+  message(STATUS "DKS version : ${DKS_VERSION}")
+  message(STATUS "DKS include dir : ${DKS_INCLUDE_DIR}")
+  message(STATUS "DKS library : ${DKS_LIBRARY}")  
+endif (DKS_FOUND)	
+
 #--- check for Qt -------------------------------------------------------------
 if (qt_based_tools)
   # check for any Qt, i.e. AUTO
@@ -200,8 +237,10 @@ endif (qt_based_tools)
 
 #--- if NeXus check also for HDF4, HDF5, and MXML -----------------------------
 if (nexus)
-  find_package(HDF5 COMPONENTS CXX REQUIRED )
+  find_package(HDF5 COMPONENTS CXX REQUIRED)
+  if (HAVE_HDF4)
     find_package(HDF4 REQUIRED)
+  endif (HAVE_HDF4)  
   find_package(NEXUS REQUIRED)
   add_definitions(-DPNEXUS_ENABLED)
 endif (nexus)
@@ -222,6 +261,19 @@ else ()
   set(IS_GIT_REPO 0)
 endif ()
 
+#--- start create git-revision.h ----------------------------------------------
+if (IS_GIT_REPO)
+  execute_process(COMMAND sh ${CMAKE_SOURCE_DIR}/src/git_revision.sh)
+
+  set(HAVE_GIT_REV_H "-DHAVE_GIT_REV_H")  
+  set(GIT_REV_H "git-revision.h")
+else (IS_GIT_REPO)
+  set(HAVE_GIT_REV_H "")  
+  set(GIT_REV_H "")
+endif (IS_GIT_REPO)
+
+#--- end create git-revision.h ------------------------------------------------
+
 #--- rpath related things -----------------------------------------------------
 # use, i.e. don't skip the full RPATH for the build tree
 set(CMAKE_SKIP_BUILD_RPATH FALSE)
@@ -249,6 +301,8 @@ set(CMAKE_INSTALL_RPATH "${rpath}")
 add_subdirectory(src)
 
 #--- write summary of the installation
+cmake_host_system_information(RESULT PROCESSOR QUERY PROCESSOR_DESCRIPTION)
+
 message("")
 message("|-----------------------------------------------------------------------|")
 message("|                                                                       |")
@@ -257,7 +311,8 @@ message("|
 message("|-----------------------------------------------------------------------|")
 message("")
 message(" System:    ${CMAKE_HOST_SYSTEM_NAME} ${CMAKE_SYSTEM_PROCESSOR} - ${CMAKE_HOST_SYSTEM_VERSION}")
-message(" -------")
+message(" Processor: ${PROCESSOR} (${CMAKE_SYSTEM_PROCESSOR})")
+message(" ----------")
 message("")
 message(" musrfit Version: ${musrfit_VERSION}")
 message(" ----------------")
@@ -273,6 +328,7 @@ message(" GSL     found in ${GSL_INCLUDE_DIRS}, Version: ${GSL_VERSION}")
 message(" BOOST   found in ${Boost_INCLUDE_DIRS}, Version: ${Boost_VERSION}")
 message(" LibXML2 found in ${LIBXML2_INCLUDE_DIR}, Version: ${LIBXML2_VERSION_STRING}")
 message(" ROOT    found in ${ROOT_INCLUDE_DIRS}, Version: ${ROOT_VERSION}")
+
 if (OpenMP_FOUND)
   if (OpenMP_CXX_VERSION)
     message(" OpenMP  found Version: ${OpenMP_CXX_VERSION}")
@@ -280,10 +336,29 @@ if (OpenMP_FOUND)
     message(" OpenMP  found")
   endif (OpenMP_CXX_VERSION)
 endif (OpenMP_FOUND)
+message("")
+
+if (CUDA_FOUND)
+  message(" CUDA    found in ${CUDA_INCLUDE_DIRECTORIES} (Version: ${CUDA_VERSION})")
+endif (CUDA_FOUND)
+if (OpenCL_FOUND)
+  message(" OpenCL  found in ${OpenCL_INCLUDE_DIR} (Version: ${OpenCL_VERSION_STRING})")
+endif (OpenCL_FOUND)
+if (DKS_FOUND)
+  message(" DKS     found in ${DKS_INCLUDE_DIR} (Version: ${DKS_VERSION})")
+endif (DKS_FOUND)
+
+if (NOT CUDA_FOUND AND NOT OpenCL_FOUND AND NOT DKS_FOUND) 
+  message(" **WARNING** configured without DKS support! DKS, CUDA, OpenCL not found?")
+endif (NOT CUDA_FOUND AND NOT OpenCL_FOUND AND NOT DKS_FOUND) 
 
 if (nexus)
   message("")
+  if (HAVE_HDF4)
     message(" HDF4    found in ${HDF4_INCLUDE_DIRS}")
+  else (HAVE_HDF4)
+    message(" HDF4    not present.")	  
+  endif (HAVE_HDF4)	  
   message(" HDF5    found in ${HDF5_INCLUDE_DIRS}, Version: ${HDF5_VERSION}")
   message(" NeXus   found in ${NEXUS_INCLUDE_DIR}, Version: ${NEXUS_VERSION_STRING}")
 endif (nexus)

ChangeLog

@@ -12,6 +12,37 @@ or
 
 https://bitbucket.org/muonspin/musrfit/commits/all
 
+Release of V1.9.9, 2025/06/08
+=============================
+
+add THEORY functions for local Gaussian / global Lorentzian, and a simple F-mu-F function.
+
+Release of V1.9.8, 2025/03/24
+=============================
+
+add a user interface option to export data from a msr-file view (single- or multiple files).
+
+Release of V1.9.7, 2025/01/18
+=============================
+
+allow spaces in RUN block path-filename
+
+Release of V1.9.6, 2024/12/02
+=============================
+
+added jump to block feature in musredit.
+
+
+Release of V1.9.5, 2024/06/24
+=============================
+
+yaml export of ALL fit-parameters, as initiated by R.M.L. McFadden.
+
+Release of V1.9.4, 2024/06/08
+=============================
+
+enable OpenMP for macOS.
+
 Release of V1.9.3, 2024/04/19
 =============================
 
@@ -200,6 +231,7 @@ NEW 2016-04-28 msr2data gets a new option: paramList which allows to
                extract a subset of all the parameters of a collection
                of msr-files.
 NEW 2016-04-22 Added the theory function muMinusExpTF for mu minus fits
+NEW 2016-03-08 added a theory translator for DKS
 NEW 2016-02-23 It is now possible to export the averaged data/Fourier
 CHANGED 2016-12-18 updated the docu.
 CHANGED 2016-12-18 a couple of little improvements in musredit.
@@ -207,6 +239,7 @@ CHANGED 2016-08-10 drop NeXus support for Version < 4.4
 CHANGED 2016-04-26 start-/endTimeBin are now class members. This reduces 
                the number of recalculations.
 FIXED 2016-08-02 run lists are now properly loaded if containing nS-nE elements.
+FIXED 2016-04-14 added missing DKS selector in GetPhaseOptRealFourier.
 
 changes since 0.16.0
 ===================================

README.md

@@ -32,6 +32,7 @@ For a more exhaustive user documentation see:
 
 <andreas.suter@psi.ch>
 
-For the beta-NMR related parts, please contact Zaher Salman
+For the beta-NMR related parts, please contact
+
 <zaher.salman@psi.ch>
 

cmake/configure_musrfit_version_file.cmake.in

@@ -1,30 +0,0 @@
-# configure_musrfit_version_file.cmake.in:
-set(SRC_DIR "@CMAKE_SOURCE_DIR@")
-set(BIN_DIR "@CMAKE_CURRENT_BINARY_DIR@")
-
-# Set variables
-set(CMAKE_INSTALL_PREFIX "@CMAKE_INSTALL_PREFIX@")
-set(MUSRFIT_VERSION "@MUSRFIT_VERSION@")
-
-# Get the current working branch
-execute_process(
-  COMMAND git rev-parse --abbrev-ref HEAD
-  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-  OUTPUT_VARIABLE GIT_BRANCH
-  OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-
-# Get the latest abbreviated commit hash of the working branch
-execute_process(
-  COMMAND git log -1 --pretty="%h, %ci"
-  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-  OUTPUT_VARIABLE GIT_CURRENT_SHA1
-  OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-
-configure_file(
-  ${SRC_DIR}/cmake/git-revision.h.in
-  ${BIN_DIR}/git-revision.h
-  @ONLY
-)
-# EOF

doc/examples/BMWlibs/test-libGapIntegrals-ASCII.msr

@@ -11,7 +11,7 @@ FITPARAMETER
 ###############################################################
 THEORY
 asymmetry      1
-userFcn  libGapIntegrals TGapDWave 2 3 4 5
+userFcn  libGapIntegrals TGapPointPWave 2 3
 
 ###############################################################
 RUN data/libGapIntegrals-test PIM3 PSI ASCII   (name beamline institute data-file-format)

doc/examples/DepthProfiles/1300Ar/depth_profile_startup.xml

@@ -6,6 +6,30 @@
     <trim_sp>
         <data_path>./TRIMSP/</data_path>
         <rge_fln_pre>SiC_1300x_52nm_48nm_E</rge_fln_pre>
-        <energy_vect start="1000" stop="22000" step="1000"/>
+        <energy_list>
+            <energy>1000</energy>
+            <energy>2000</energy>
+            <energy>3000</energy>
+            <energy>4000</energy>
+            <energy>5000</energy>
+            <energy>6000</energy>
+            <energy>7000</energy>
+            <energy>8000</energy>
+            <energy>9000</energy>
+            <energy>10000</energy>
+            <energy>11000</energy>
+            <energy>12000</energy>
+            <energy>13000</energy>
+            <energy>14000</energy>
+            <energy>15000</energy>
+            <energy>16000</energy>
+            <energy>17000</energy>
+            <energy>17000</energy>
+            <energy>18000</energy>
+            <energy>19000</energy>
+            <energy>20000</energy>
+            <energy>21000</energy>
+            <energy>22000</energy>
+        </energy_list>
     </trim_sp>
 </depthProf>

doc/examples/DepthProfiles/1300x/depth_profile_startup.xml

@@ -6,6 +6,30 @@
     <trim_sp>
         <data_path>./TRIMSP/</data_path>
         <rge_fln_pre>SiC_1300x_52nm_48nm_E</rge_fln_pre>
-        <energy_vect start="1000" stop="22000" step="1000"/>
+        <energy_list>
+            <energy>1000</energy>
+            <energy>2000</energy>
+            <energy>3000</energy>
+            <energy>4000</energy>
+            <energy>5000</energy>
+            <energy>6000</energy>
+            <energy>7000</energy>
+            <energy>8000</energy>
+            <energy>9000</energy>
+            <energy>10000</energy>
+            <energy>11000</energy>
+            <energy>12000</energy>
+            <energy>13000</energy>
+            <energy>14000</energy>
+            <energy>15000</energy>
+            <energy>16000</energy>
+            <energy>17000</energy>
+            <energy>17000</energy>
+            <energy>18000</energy>
+            <energy>19000</energy>
+            <energy>20000</energy>
+            <energy>21000</energy>
+            <energy>22000</energy>
+        </energy_list>
     </trim_sp>
 </depthProf>

doc/examples/DepthProfiles/PECVD_Si/depth_profile_startup.xml

@@ -6,6 +6,30 @@
     <trim_sp>
         <data_path>./TRIMSP/</data_path>
         <rge_fln_pre>Si10_2.0_E</rge_fln_pre>
-        <energy_vect start="1000" stop="22000" step="1000"/>
+        <energy_list>
+            <energy>1000</energy>
+            <energy>2000</energy>
+            <energy>3000</energy>
+            <energy>4000</energy>
+            <energy>5000</energy>
+            <energy>6000</energy>
+            <energy>7000</energy>
+            <energy>8000</energy>
+            <energy>9000</energy>
+            <energy>10000</energy>
+            <energy>11000</energy>
+            <energy>12000</energy>
+            <energy>13000</energy>
+            <energy>14000</energy>
+            <energy>15000</energy>
+            <energy>16000</energy>
+            <energy>17000</energy>
+            <energy>17000</energy>
+            <energy>18000</energy>
+            <energy>19000</energy>
+            <energy>20000</energy>
+            <energy>21000</energy>
+            <energy>22000</energy>
+        </energy_list>
     </trim_sp>
 </depthProf>

doc/examples/DepthProfiles/PECVD_thermal_SiC/depth_profile_startup.xml

@@ -6,6 +6,30 @@
     <trim_sp>
         <data_path>./TRIMSP/</data_path>
         <rge_fln_pre>SiO2_70nm2.0_30nm2.2_SiC_E</rge_fln_pre>
-        <energy_vect start="1000" stop="22000" step="1000"/>
+        <energy_list>
+            <energy>1000</energy>
+            <energy>2000</energy>
+            <energy>3000</energy>
+            <energy>4000</energy>
+            <energy>5000</energy>
+            <energy>6000</energy>
+            <energy>7000</energy>
+            <energy>8000</energy>
+            <energy>9000</energy>
+            <energy>10000</energy>
+            <energy>11000</energy>
+            <energy>12000</energy>
+            <energy>13000</energy>
+            <energy>14000</energy>
+            <energy>15000</energy>
+            <energy>16000</energy>
+            <energy>17000</energy>
+            <energy>17000</energy>
+            <energy>18000</energy>
+            <energy>19000</energy>
+            <energy>20000</energy>
+            <energy>21000</energy>
+            <energy>22000</energy>
+        </energy_list>
     </trim_sp>
 </depthProf>

doc/examples/UserFcn/PUserFcn.cpp

@@ -8,7 +8,7 @@
 ***************************************************************************/
 
 /***************************************************************************
- *   Copyright (C) 2007-2024 by Andreas Suter                              *
+ *   Copyright (C) 2007-2025 by Andreas Suter                              *
  *   andreas.suter@psi.ch                                                  *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *

doc/examples/UserFcn/PUserFcn.h

@@ -8,7 +8,7 @@
 ***************************************************************************/
 
 /***************************************************************************
- *   Copyright (C) 2007-2021 by Andreas Suter                              *
+ *   Copyright (C) 2007-2025 by Andreas Suter                              *
  *   andreas.suter@psi.ch                                                  *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *

doc/examples/UserFcn/PUserFcnLinkDef.h

@@ -4,7 +4,7 @@
 
 ***************************************************************************/
 
-#ifdef __CINT__
+#ifdef __CLING__
 
 #pragma link off all globals;
 #pragma link off all classes;
@@ -12,4 +12,4 @@
 
 #pragma link C++ class PUserFcn+;
 
-#endif //__CINT__
+#endif //__CLING__

doc/examples/test-histo-HAL9500.msr

@@ -2,106 +2,106 @@ MnSi, FLC68.2, 50 K
 ###############################################################
 FITPARAMETER
 #      Nr. Name       Value     Step      Pos_Error Boundaries   
-        1 Rate_1      1.6687    0.0086      none        
-        2 Field_1     73089.883 0.090       none        
-        3 Rate_2      1.968     0.032       none        
-        4 Field_2     72289.02  0.24        none        
+        1 Rate_1      1.6686    -0.0085     0.0086      
+        2 Field_1     73089.887 -0.090      0.090       
+        3 Rate_2      1.967     -0.032      0.032       
+        4 Field_2     72289.02  -0.24       0.24        
         
-        5 Asym_1      0.2949    0.0030      none        
-        6 Frc_1       0.7316    0.0059      none        
-        7 Phase_1     55.61     0.52        none        
-        8 N0_1        940.35    0.54        none        
-        9 Bkg_1       1.523     0.064       none        
+        5 Asym_1      0.2949    -0.0030     0.0030      
+        6 Frc_1       0.7316    -0.0058     0.0059      
+        7 Phase_1     55.61     -0.52       0.52        
+        8 N0_1        940.36    -0.54       0.54        
+        9 Bkg_1       1.524     -0.064      0.064       
 
-       10 Asym_2      0.2960    0.0030      none        
-       11 Frc_2       0.7475    0.0059      none        
-       12 Phase_2     30.77     0.50        none        
-       13 N0_2        961.49    0.55        none        
-       14 Bkg_2       1.928     0.065       none        
+       10 Asym_2      0.2960    -0.0030     0.0030      
+       11 Frc_2       0.7475    -0.0058     0.0059      
+       12 Phase_2     30.77     -0.50       0.50        
+       13 N0_2        961.50    -0.55       0.55        
+       14 Bkg_2       1.929     -0.065      0.065       
 
-       15 Asym_3      0.3002    0.0029      none        
-       16 Frc_3       0.7462    0.0056      none        
-       17 Phase_3     18.03     0.48        none        
-       18 N0_3        1024.28   0.57        none        
-       19 Bkg_3       1.919     0.067       none        
+       15 Asym_3      0.3002    -0.0029     0.0029      
+       16 Frc_3       0.7462    -0.0056     0.0057      
+       17 Phase_3     18.03     -0.48       0.48        
+       18 N0_3        1024.29   -0.57       0.57        
+       19 Bkg_3       1.920     -0.067      0.067       
 
-       20 Asym_4      0.3088    0.0029      none        
-       21 Frc_4       0.7333    0.0054      none        
-       22 Phase_4     336.94    0.47        none        
-       23 N0_4        1029.36   0.57        none        
-       24 Bkg_4       1.863     0.067       none        
+       20 Asym_4      0.3088    -0.0029     0.0029      
+       21 Frc_4       0.7333    -0.0053     0.0054      
+       22 Phase_4     336.94    -0.48       0.47        
+       23 N0_4        1029.37   -0.57       0.57        
+       24 Bkg_4       1.865     -0.067      0.067       
 
-       25 Asym_5      0.3094    0.0029      none        
-       26 Frc_5       0.7416    0.0055      none        
-       27 Phase_5     280.32    0.48        none        
-       28 N0_5        1002.69   0.56        none        
-       29 Bkg_5       1.979     0.067       none        
+       25 Asym_5      0.3094    -0.0029     0.0029      
+       26 Frc_5       0.7416    -0.0054     0.0055      
+       27 Phase_5     280.33    -0.48       0.48        
+       28 N0_5        1002.70   -0.56       0.56        
+       29 Bkg_5       1.981     -0.067      0.067       
 
-       30 Asym_6      0.3153    0.0032      none        
-       31 Frc_6       0.7403    0.0058      none        
-       32 Phase_6     211.07    0.51        none        
-       33 N0_6        853.43    0.52        none        
-       34 Bkg_6       1.656     0.061       none        
+       30 Asym_6      0.3153    -0.0032     0.0032      
+       31 Frc_6       0.7403    -0.0057     0.0058      
+       32 Phase_6     211.07    -0.51       0.51        
+       33 N0_6        853.44    -0.52       0.52        
+       34 Bkg_6       1.658     -0.061      0.061       
 
-       35 Asym_7      0.3118    0.0032      none        
-       36 Frc_7       0.7378    0.0059      none        
-       37 Phase_7     161.74    0.51        none        
-       38 N0_7        858.76    0.52        none        
-       39 Bkg_7       1.594     0.061       none        
+       35 Asym_7      0.3118    -0.0032     0.0032      
+       36 Frc_7       0.7377    -0.0058     0.0059      
+       37 Phase_7     161.75    -0.51       0.51        
+       38 N0_7        858.77    -0.52       0.52        
+       39 Bkg_7       1.595     -0.061      0.062       
 
-       40 Asym_8      0.2985    0.0031      none        
-       41 Frc_8       0.7373    0.0061      none        
-       42 Phase_8     133.69    0.53        none        
-       43 N0_8        871.20    0.52        none        
-       44 Bkg_8       1.746     0.062       none        
+       40 Asym_8      0.2985    -0.0031     0.0031      
+       41 Frc_8       0.7373    -0.0060     0.0061      
+       42 Phase_8     133.70    -0.53       0.53        
+       43 N0_8        871.20    -0.52       0.52        
+       44 Bkg_8       1.748     -0.062      0.062       
 
-       45 Asym_9      0.2874    0.0027      none        
-       46 Frc_9       0.7340    0.0054      none        
-       47 Phase_9     158.63    0.47        none        
-       48 N0_9        1184.29   0.61        none        
-       49 Bkg_9       2.542     0.073       none        
+       45 Asym_9      0.2874    -0.0027     0.0027      
+       46 Frc_9       0.7340    -0.0054     0.0055      
+       47 Phase_9     158.63    -0.47       0.47        
+       48 N0_9        1184.30   -0.61       0.61        
+       49 Bkg_9       2.544     -0.073      0.073       
 
-       50 Asym_10     0.2846    0.0027      none        
-       51 Frc_10      0.7453    0.0055      none        
-       52 Phase_10    128.05    0.47        none        
-       53 N0_10       1193.66   0.61        none        
-       54 Bkg_10      2.394     0.073       none        
+       50 Asym_10     0.2845    -0.0027     0.0027      
+       51 Frc_10      0.7452    -0.0055     0.0055      
+       52 Phase_10    128.05    -0.47       0.47        
+       53 N0_10       1193.67   -0.61       0.61        
+       54 Bkg_10      2.396     -0.073      0.073       
 
-       55 Asym_11     0.2877    0.0026      none        
-       56 Frc_11      0.7463    0.0053      none        
-       57 Phase_11    102.43    0.45        none        
-       58 N0_11       1280.00   0.63        none        
-       59 Bkg_11      2.730     0.075       none        
+       55 Asym_11     0.2877    -0.0026     0.0026      
+       56 Frc_11      0.7462    -0.0052     0.0053      
+       57 Phase_11    102.42    -0.45       0.45        
+       58 N0_11       1280.01   -0.63       0.63        
+       59 Bkg_11      2.732     -0.075      0.075       
 
-       60 Asym_12     0.2919    0.0025      none        
-       61 Frc_12      0.7405    0.0050      none        
-       62 Phase_12    42.97     0.43        none        
-       63 N0_12       1383.96   0.66        none        
-       64 Bkg_12      2.807     0.078       none        
+       60 Asym_12     0.2919    -0.0025     0.0025      
+       61 Frc_12      0.7405    -0.0050     0.0050      
+       62 Phase_12    42.97     -0.43       0.43        
+       63 N0_12       1383.97   -0.66       0.66        
+       64 Bkg_12      2.809     -0.078      0.078       
 
-       65 Asym_13     0.2903    0.0025      none        
-       66 Frc_13      0.7494    0.0050      none        
-       67 Phase_13    350.74    0.43        none        
-       68 N0_13       1393.01   0.66        none        
-       69 Bkg_13      2.738     0.078       none        
+       65 Asym_13     0.2903    -0.0025     0.0025      
+       66 Frc_13      0.7493    -0.0050     0.0050      
+       67 Phase_13    350.74    -0.43       0.43        
+       68 N0_13       1393.02   -0.66       0.66        
+       69 Bkg_13      2.740     -0.078      0.079       
 
-       70 Asym_14     0.2968    0.0025      none        
-       71 Frc_14      0.7327    0.0049      none        
-       72 Phase_14    288.56    0.43        none        
-       73 N0_14       1374.46   0.66        none        
-       74 Bkg_14      2.768     0.078       none        
+       70 Asym_14     0.2968    -0.0025     0.0025      
+       71 Frc_14      0.7327    -0.0049     0.0050      
+       72 Phase_14    288.57    -0.43       0.43        
+       73 N0_14       1374.47   -0.66       0.66        
+       74 Bkg_14      2.771     -0.078      0.078       
 
-       75 Asym_15     0.2799    0.0025      none        
-       76 Frc_15      0.7427    0.0052      none        
-       77 Phase_15    282.56    0.45        none        
-       78 N0_15       1365.97   0.65        none        
-       79 Bkg_15      2.809     0.078       none        
+       75 Asym_15     0.2799    -0.0025     0.0025      
+       76 Frc_15      0.7427    -0.0052     0.0053      
+       77 Phase_15    282.56    -0.45       0.45        
+       78 N0_15       1365.99   -0.66       0.65        
+       79 Bkg_15      2.811     -0.078      0.078       
 
-       80 Asym_16     0.2771    0.0026      none        
-       81 Frc_16      0.7344    0.0055      none        
-       82 Phase_16    212.46    0.48        none        
-       83 N0_16       1256.94   0.63        none        
-       84 Bkg_16      2.458     0.074       none        
+       80 Asym_16     0.2771    -0.0026     0.0026      
+       81 Frc_16      0.7344    -0.0054     0.0055      
+       82 Phase_16    212.46    -0.48       0.48        
+       83 N0_16       1256.95   -0.63       0.63        
+       84 Bkg_16      2.460     -0.074      0.075       
 
 ###############################################################
 THEORY
@@ -257,9 +257,12 @@ t0              20039.0
 
 ###############################################################
 COMMANDS
+#OpenCL-GPU
+CUDA
 MAX_LIKELIHOOD
-PRINT_LEVEL 2
+#PRINT_LEVEL 2
 MINIMIZE
+MINOS
 SAVE
 
 ###############################################################
@@ -278,5 +281,5 @@ phase            par(7, 5, 16)
 range            7.1    7.5
 
 ###############################################################
-STATISTIC --- 2018-10-15 15:55:36
-  maxLH = 1286508.7, NDF = 1246064, maxLH/NDF = 1.032458
+STATISTIC --- 2023-11-09 09:38:03
+  maxLH = 1286509.8, NDF = 1246064, maxLH/NDF = 1.032459

doc/examples/test-histo-MusrRoot.msr

@@ -2,23 +2,23 @@ LSCO x=0.02 (224-227), T=12.00 (K), E=5.57 keV, WEW B=~49(G)/8.62(A), Tr=15.02 (
 ###############################################################
 FITPARAMETER
 #       No Name        Value     Step        Pos_Error   Boundaries
-        1 AsymT       0.05053   -0.00071    0.00072     0       0.33    
+        1 AsymT       0.05052   -0.00071    0.00072     0       0.33    
         2 Field       48.298    -0.094      0.095       
         3 RateT       0.129     -0.010      0.010       0       none    
         4 AsymL       0         0           none        0       0.33    
         5 RateL       0         0           none        
         6 AlphaLR     0.9784    -0.0013     0.0013      
         7 PhaseL      6.6       -1.6        1.6         -40     40      
-        8 BkgL        6.920     -0.048      0.048       
+        8 BkgL        6.921     -0.048      0.048       
         9 RelPhaseR   178.8     -1.9        1.9         150     210     
-       10 NormR       419.46    -0.40       0.40        
+       10 NormR       419.47    -0.40       0.40        
        11 BkgR        8.393     -0.050      0.050       
        12 AlphaTB     1.1025    -0.0015     0.0015      
        13 RelPhaseT   269.1     -1.9        1.9         240     300     
-       14 BkgT        7.466     -0.049      0.049       
+       14 BkgT        7.467     -0.049      0.049       
        15 NormB       393.08    -0.39       0.39        
        16 RelPhaseB   90.7      -2.0        2.0         60      120     
-       17 BkgB        7.092     -0.048      0.048       
+       17 BkgB        7.092     -0.048      0.047       
        18 One         1         0           none        
        19 Zero        0         0           none        
 
@@ -96,5 +96,5 @@ range    0   9   -0.15   0.15
 view_packing 500
 
 ###############################################################
-STATISTIC --- 2018-11-13 07:58:56
-  maxLH = 3971.7, NDF = 4001, maxLH/NDF = 0.992668
+STATISTIC --- 2023-10-25 11:01:10
+  maxLH = 3971.7, NDF = 4001, maxLH/NDF = 0.992678

doc/examples/test-histo-PSI-BIN.msr

@@ -8,9 +8,9 @@ FITPARAMETER
         4 Phase_L     178.95    -0.41       0.41        
         5 Phase_R     1.75      -0.39       0.39        
         6 N0_L        1097.9    -1.0        1.0         
-        7 N0_R        1159.7    -1.0        1.0         
+        7 N0_R        1159.8    -1.0        1.0         
         8 Bkg_L       54.47     -0.20       0.20        
-        9 Bkg_R       46.70     -0.19       0.19        
+        9 Bkg_R       46.71     -0.19       0.19        
 
 ###############################################################
 THEORY
@@ -47,6 +47,7 @@ t0              202.0
 
 ###############################################################
 COMMANDS
+CUDA
 SCALE_N0_BKG TRUE
 MINIMIZE
 MINOS
@@ -63,11 +64,11 @@ FOURIER
 units            Gauss   # units either 'Gauss', 'Tesla', 'MHz', or 'Mc/s'
 fourier_power    12
 apodization      NONE    # NONE, WEAK, MEDIUM, STRONG
-plot             POWER   # REAL, IMAG, REAL_AND_IMAG, POWER, PHASE
+plot             POWER   # REAL, IMAG, REAL_AND_IMAG, POWER, PHASE, PHASE_OPT_REAL
 phase            8.5
 #range_for_phase_correction 50.0 70.0
-range            0.0    200.0
+range            0    200
 
 ###############################################################
-STATISTIC --- 2015-01-05 14:09:47
-  chisq = 663.9, NDF = 515, chisq/NDF = 1.289169
+STATISTIC --- 2024-06-07 15:33:49
+  chisq = 663.9, NDF = 515, chisq/NDF = 1.289084

doc/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 28c8d31b3d0d7429fcebb7bd0074bdd3
+config: fae482e1a3134e03efb428cbbe21a254
 tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/html/_images/musrview2dat.svg

@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="22"
+   height="22"
+   viewBox="0 0 22.000001 22"
+   id="svg2"
+   version="1.1"
+   inkscape:version="1.0.2 (e86c870879, 2021-01-15)"
+   sodipodi:docname="musrview2dat-plain.svg">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow1Sstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Sstart"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path8245"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#da4453;stroke-width:1pt;stroke-opacity:1;fill:#da4453;fill-opacity:1"
+         transform="scale(0.2) translate(6,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Mstart"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path8257"
+         style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round;stroke:#da4453;stroke-opacity:1;fill:#da4453;fill-opacity:1"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(0.6) translate(0,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lend"
+       style="overflow:visible;"
+       inkscape:isstock="true">
+      <path
+         id="path8236"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#da4453;stroke-width:1pt;stroke-opacity:1;fill:#000000;fill-opacity:1"
+         transform="scale(0.8) rotate(180) translate(12.5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="38.863636"
+     inkscape:cx="11"
+     inkscape:cy="11"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="true"
+     units="pt"
+     inkscape:window-width="2560"
+     inkscape:window-height="1376"
+     inkscape:window-x="0"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1"
+     inkscape:snap-grids="true"
+     showguides="true"
+     borderlayer="true"
+     inkscape:showpageshadow="false"
+     inkscape:document-rotation="0">
+    <inkscape:grid
+       type="xygrid"
+       id="grid5486" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-1030.3622)">
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.935414;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 8.471,1031.8299 v 7"
+       id="path8054"
+       inkscape:connector-curvature="0" />
+    <g
+       id="g16411"
+       transform="translate(-1.9999996,0)">
+      <path
+         inkscape:connector-curvature="0"
+         id="path8035-5"
+         d="m 8.5000005,1043.3622 0,8"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000012;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         sodipodi:open="true"
+         d="m 10.000001,1043.8622 a 2.594672,3.5000203 0 0 1 2.594672,3.5 2.594672,3.5000203 0 0 1 -2.594672,3.5"
+         sodipodi:end="1.5707963"
+         sodipodi:start="4.712389"
+         sodipodi:ry="3.5000203"
+         sodipodi:rx="2.594672"
+         sodipodi:cy="1047.3622"
+         sodipodi:cx="10.000001"
+         sodipodi:type="arc"
+         id="path16389"
+         style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.99996012;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         inkscape:connector-curvature="0"
+         id="path16394"
+         d="m 8,1043.8622 2,0"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+      <path
+         inkscape:transform-center-y="-3.7031618"
+         inkscape:transform-center-x="-1.5617682"
+         inkscape:connector-curvature="0"
+         id="path16394-8"
+         d="m 8.0000005,1050.8622 1.9999995,0"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.911555;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 18.500001,1044.3384 v 6.6474"
+       id="path8054-0-0"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.935;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 16.4165,1043.8617 h 4.166666"
+       id="path8071-1"
+       inkscape:connector-curvature="0" />
+    <g
+       id="g16558"
+       transform="matrix(0.8331761,0,0,1,2.2916816,0)">
+      <path
+         inkscape:connector-curvature="0"
+         id="path16442"
+         d="m 11.002838,1050.8557 2.99716,-6.9869"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.09554851px;stroke-linecap:round;stroke-linejoin:bevel;stroke-opacity:1" />
+      <path
+         inkscape:connector-curvature="0"
+         id="path16444"
+         d="m 13.999998,1043.8688 2.997161,6.9869"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.09554851px;stroke-linecap:round;stroke-linejoin:miter;stroke-opacity:1" />
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 12,1049.3622 4,0"
+       id="path16450"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:#4d4d4d;fill-opacity:1;fill-rule:evenodd;stroke:#4d4d4d;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1.0000001,1049.8622 3.0000002,0"
+       id="path16452-9"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#4d4d4d;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1.0000001,1041.8622 5.0000001,0"
+       id="path16452-4-1"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#4d4d4d;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1.0000001,1043.8622 3.0000004,0"
+       id="path16452-4-7"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#4d4d4d;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1.0000001,1045.8622 2.0000001,0"
+       id="path16452-4-8"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#4d4d4d;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1.0000001,1047.8622 3.0000004,0"
+       id="path16452-4-89"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#da4453;stroke-width:1.00000012;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 12.353554,1040.1551 2,2 2.000001,-2"
+       id="path16535"
+       inkscape:connector-curvature="0" />
+    <g
+       id="g1261"
+       transform="translate(-2,-0.0478)">
+      <path
+         inkscape:connector-curvature="0"
+         id="path16442-7"
+         d="m 8.4971623,1031.91 -2.497162,6.9869"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:round;stroke-linejoin:bevel;stroke-opacity:1" />
+      <path
+         inkscape:connector-curvature="0"
+         id="path16444-4"
+         d="M 6.0000003,1038.8969 3.5028374,1031.91"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:round;stroke-linejoin:miter;stroke-opacity:1" />
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.935414;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 10.967707,1031.8299 v 7"
+       id="path8054-6"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.935;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 14,1031.7617 H 11"
+       id="path8054-6-8"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.935;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 14,1038.8617 H 11"
+       id="path8054-6-8-7"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.919364;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 14,1034.8617 H 11.0995"
+       id="path8054-6-8-7-2"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.900712;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 15.908054,1031.7306 1.0766,7.2162"
+       id="path8054-2"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.900712;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 21,1031.7626 -1.0766,7.2162"
+       id="path8054-2-7"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.901;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 18.39969,1035.6617 -1.30419,3.3269"
+       id="path8054-2-7-0"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.901;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 18.4995,1035.6617 1.30419,3.3269"
+       id="path8054-2-7-0-5"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

doc/html/_sources/acknowledgement.rst.txt

@@ -0,0 +1,22 @@
+.. include:: <isogrk1.txt>
+.. index:: acknowledgment
+
+.. _acknowledgment:
+
+Acknowledgements
+================
+
+
+**Bastian M. Wojek**
+  I am very much indebted to BMW for his rigorous testing of ``musrfit``, his many useful suggestions, contributions, and for the 
+  largest part of the user manual of ``musrfit`` which makes it accessible to a broader audience! Many thanks Bastian! 
+
+**Uldis Locans**
+  I am very much indebted to Uldis work on :ref:`DKS <setup-dks>` enabling the GPU support for ``musrfit``. His kind, calm, and 
+  extremely competent way to deal with his projects as well as to deal with the chaos of physicists way to think is admirable. Many thanks Uldis!
+
+**Zaher Salman**
+  Thanks for his beta-NMR and web-interface contributions to ``musrfit``!
+
+**Robert Scheuermann**
+  Thanks for his constant contructive input on ``musrfit``! 

doc/html/_sources/any2many.rst.txt

@@ -0,0 +1,8 @@
+.. include:: <isogrk1.txt>
+.. index:: any2many
+
+any2many - a Universal |mgr|\SR-file-format converter
+=====================================================
+
+``any2many`` allows to convert most |mgr|\SR-file-formats from one to the other.
+For a detailed description see :ref:`here <any2many>`.

doc/html/_sources/bugtracking.rst.txt

@@ -0,0 +1,9 @@
+.. index:: bugtracking
+.. _bugtracking:
+
+Bugtracking
+===========
+
+For reporting bugs or requesting new features and improvements please use 
+the `bitbucket-repo <https://bitbucket.org/muonspin/musrfit/issues>`_ (preferred) 
+or send an e-mail to A. Suter at PSI.

doc/html/_sources/cite.rst.txt

@@ -0,0 +1,18 @@
+.. include:: <isogrk1.txt>
+.. index:: cite
+.. _cite:
+
+How to Cite ``musrfit``?
+========================
+
+Since quite some effort is going into the development and maintenance of the ``musrfit`` package, you should at least acknowledge it in your publication if you have used it to analyze your data. Even better of course is to cite it properly by the reference given beneath 
+
+ * A.\  Suter, B.M. Wojek, "Musrfit: A Free Platform-Independent Framework for |mgr|\SR Data Analysis", Physics Procedia **30**, 69 (2012). `<http://dx.doi.org/10.1016/j.phpro.2012.04.042>`_
+
+The GPU high speed ``musrfit`` version is utilizing ``DKS``. In case you are using this version, please also add the following citations
+
+ * A.\  Adelmann, U. Locans, A. Suter, "The Dynamic Kernel Scheduler—Part 1", Computer Physics Communications **207**, 83 (2016). `<https://doi.org/10.1016/j.cpc.2016.05.013>`_
+ * U.\  Locans, *et al.*, "Real-time computation of parameter fitting and image reconstruction using graphical processing units", Computer Physics Communications **215**, 71 (2017). `<https://doi.org/10.1016/j.cpc.2017.02.007>`_
+ * U.\ Locans and A.\ Suter, "Musrfit – Real Time Parameter Fitting Using GPUs", JPS Conf. Proc. *21*, 011051 (2018). `<http://dx.doi.org/10.7566/JPSCP.21.011051>`_
+
+

doc/html/_sources/file-formats.rst.txt

@@ -0,0 +1,389 @@
+.. include:: <isogrk1.txt>
+.. index:: file-formats
+.. _file-formats:
+
+Short description and references to the supported file-formats
+==============================================================
+
+Currently the following |mgr|\SR and non-|mgr|\SR file formats are supported (in alphabetic order):
+
+* ascii (non-|mgr|\SR): :ref:`ASCII file format for non-u\SR <ascii-file-format>`
+* db (non-|mgr|\SR): :ref:`DB (triumf) <db-file-format>`
+* dat (non-|mgr|\SR): :ref:`DAT: CSV like data file <dat-file-format>`
+* mdu (|mgr|\SR): :ref:`MDU file format (PSI) <mdu-file-format>`
+* mud (|mgr|\SR): :ref:`MUon Data access file format (TRIUMF) <mud-file-format>`
+* musr-root (|mgr|\SR): :ref:`MusrRoot - an Extensible Open File Format for uSR <MusrRoot>`
+* nexus (|mgr|\SR): used to read NeXus files from ISIS (HDF4 and HDF5): :ref:`NeXus <nexus-file-format>`
+* psi-bin (|mgr|\SR): :ref:`PSI-BIN file format (PSI) <psi-bin-file-format>`
+* root (|mgr|\SR): specific version for LEM before 2012 :ref:`LEM ROOT file format<root-file-format>`
+* wkm (|mgr|\SR): special ascii file format used in the past by the TU Braunschweig (outdated): :ref:`WKM <wkm-file-format>`
+  
+.. index:: ascii-file-format
+.. _ascii-file-format:
+
+ASCII file format for non-|mgr|\SR
+----------------------------------
+
+This for instance can be used to fit :math:`1/\lambda^2 ~ \mathrm{vs} ~ T` to study gap properties of superconductors.
+Details about the gap-intergrals can be found in the memo *GapIntegrals.pdf* which can be found in the source code of musrfit
+under <musrfit-home-dir>/src/external/libGapIntegrals.
+
+This primitive file format has the following structure:
+
+Comment lines start with a '#' or '%' character.
+The file can start with some header info. The header is optional, as all its tags, but 
+if present it has the following format:
+
+::
+
+  HEADER
+  TITLE:  title
+  X-AXIS-TITLE: x-axis title
+  Y-AXIS-TITLE: y-axis title
+  SETUP:  setup
+  FIELD:  field
+  TEMP:   temperature
+  ENERGY: energy
+
+Field has to be given in (G), temperature in (K) and energy in (keV).
+
+The data are read column like and start with the data tag DATA, followed by the
+data columns, i.e.:
+
+::
+
+  DATA
+  x, y [, error y]
+
+where spaces, column, are a tab are possible separations.
+If no error in y is present, the weighting in the fit will be equal.
+
+A full example might look like this:
+
+::
+
+  # libGapIntegrals-test.dat
+  # This is a comment
+  % This as well
+  HEADER
+  TITLE: Test superconductor data
+  X-AXIS-TITLE: T (K)
+  Y-AXIS-TITLE: #lambda^{-2} (#mum^{-2})
+  SETUP: H #parallel c
+  FIELD: 100
+  TEMP: 0.0
+  ENERGY: 4200
+  # here the data will follow
+  DATA
+  # x, y, error y
+  0.0318411, 7.77455, 0.2
+  0.0629929, 7.9869, 0.15
+  0.113914, 7.64209, 0.15
+  0.202492, 7.37699, 0.15
+  0.302725, 7.70893, 0.12
+  0.447456, 7.77565, 0.12
+  0.611685, 7.45768, 0.12
+  0.813613, 7.19287, 0.12
+  1.00822, 7.57813, 0.12
+  1.24793, 7.31343, 0.12
+  1.50635, 7.16818, 0.12
+  1.74591, 6.99634, 0.12
+  1.99795, 6.90414, 0.12
+  2.25061, 6.41393, 0.12
+  2.4958, 6.66666, 0.12
+  2.75514, 5.93766, 0.12
+  3.00753, 5.61992, 0.12
+  3.26056, 4.89091, 0.12
+  3.49414, 4.52005, 0.08
+  3.75356, 3.73799, 0.08
+  3.99425, 2.84974, 0.08
+  4.30518, 1.35139, 0.08
+
+
+.. index:: db-file-format
+.. _db-file-format:
+
+DB file format for non-|mgr|\SR
+-------------------------------
+
+The DB file format is an *archaic* ascii file format from TRIUMF which is intended to be used to collect parameter summaries of various runs, which can be read directly by :ref:`mupp <mupp>`.
+
+The DB file is organized in a couple of tags defining various properties, followed by the parameter data with its errors.
+Tags and is content are always separated by an empty line.
+The first tag is the **TITLE**. Followed by the title in the next line
+
+::
+  
+  TITLE
+  This is the best data ever
+
+The next tag is the **ABSTRACT**, followed a potentially multi-line abstract, e.g.
+
+::
+
+  ABSTRACT
+  Here comes the detailed description ...
+
+The next tag, **LABELS**, are used to define human readable names for the data parameters to be followed:
+
+::
+
+  LABELS
+  T (K)
+  B (G)
+  ...
+
+The number of labels have to fit the number of parameters present!
+
+The next tag is **DATA**, which is a list of the parameter names as found in you msr-file.
+Unlike the other tags, here the list of names follow directly after the **DATA** tag
+
+::
+
+  DATA dataT dataB dataE dataTr ...
+
+Next there will be a line with the tag **\\\\-e**, followed by
+
+The parameters are afterwards listed as
+
+::
+
+  param-name = val, pos-err, neg-err,\
+
+After all the parameters listed of a specific run, the **run number** with the run title ends a run data set.
+This might look like this (be aware of the comma!):
+
+::
+
+  11231,,, AgPlate 250nm (T5034), T=200.00 K, E=12.99 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00
+
+A full example might look like this:
+
+::
+
+  TITLE
+  Ag Plate 2023 runs, Tr12kV, E=13keV, TF B=50G
+
+  Abstract
+  Summary of the
+
+  LABELS
+  T (K)
+  B (G)
+  Implantation Energy (keV)
+  Transport (kV)
+  RAL-RAR (kV)
+  RAT-RAB (kV)
+  Spin Rotation Angle (degree)
+  Asy
+  Lambda
+  Ph
+  Field
+  RelPh_L
+  N0_L
+  N_bkg_L
+  RelPh_T
+  N0_T
+  N_bkg_T
+  RelPh_R
+  alpha_LR
+  N_bkg_R
+  RelPh_B
+  alpha_TB
+  N_bkg_B
+  maxLH
+  NDF
+  maxLHred
+  RUN
+
+  Data dataT dataB dataE dataTr dataRALRAR dataRATRAB dataSpinRot Asy Lambda Ph Field RelPh_L N0_L N_bkg_L RelPh_T N0_T N_bkg_T RelPh_R alpha_LR N_bkg_R RelPh_B alpha_TB N_bkg_B maxLH NDF maxLHred RUN
+  \-e
+  dataT = 200.001, 0.0009, 0.0009,\
+  dataB = 49.49, 0, 0,\
+  dataE = 12.9952, 0, 0,\
+  dataTr = 11.9993, 0, 0,\
+  dataRALRAR = -0.008, 0, 0,\
+  dataRATRAB = -0.009, 0, 0,\
+  dataSpinRot = -10, 0, 0,\
+  Asy = 0.22466, 0.00084, -0.00084,\
+  Lambda = 0.0081, 0.0014, -0.0014,\
+  Ph = 12.14, 0.32, -0.32,\
+  Field = 50.837, 0.017, -0.017,\
+  RelPh_L = 0, 0, 0,\
+  N0_L = 430.67, 0.39, -0.39,\
+  N_bkg_L = 6.81, 0.048, -0.048,\
+  RelPh_T = -89.95, 0.4, -0.4,\
+  N0_T = 422.6, 0.37, -0.37,\
+  N_bkg_T = 7.125, 0.047, -0.048,\
+  RelPh_R = -178.55, 0.39, -0.39,\
+  alpha_LR = 0.9729, 0.0012, -0.0012,\
+  N_bkg_R = 7.375, 0.048, -0.048,\
+  RelPh_B = 90.38, 0.4, -0.4,\
+  alpha_TB = 0.9522, 0.0012, -0.0012,\
+  N_bkg_B = 6.546, 0.047, -0.047,\
+  maxLH = 20303.3, 0, 0,\
+  NDF = 20361, 0, 0,\
+  maxLHred = 0.997166, 0, 0,\
+  11231,,, AgPlate 250nm (T5034), T=200.00 K, E=12.99 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00
+  dataT = 153, 0.7, 0.7,\
+  dataB = 49.49, 0, 0,\
+  dataE = 12.9952, 0, 0,\
+  dataTr = 11.9993, 0, 0,\
+  dataRALRAR = -0.008, 0, 0,\
+  dataRATRAB = -0.009, 0, 0,\
+  dataSpinRot = -10, 0, 0,\
+  Asy = 0.22253, 0.00084, -0.00083,\
+  Lambda = 0.0055, 0.0014, -0.0014,\
+  Ph = 11.53, 0.32, -0.32,\
+  Field = 51.026, 0.017, -0.017,\
+  RelPh_L = 0, 0, 0,\
+  N0_L = 430.31, 0.39, -0.39,\
+  N_bkg_L = 6.762, 0.048, -0.048,\
+  RelPh_T = -89.3, 0.4, -0.4,\
+  N0_T = 422.31, 0.37, -0.37,\
+  N_bkg_T = 6.96, 0.047, -0.047,\
+  RelPh_R = -178.61, 0.4, -0.4,\
+  alpha_LR = 0.975, 0.0013, -0.0012,\
+  N_bkg_R = 7.361, 0.048, -0.048,\
+  RelPh_B = 90.24, 0.4, -0.4,\
+  alpha_TB = 0.9605, 0.0012, -0.0012,\
+  N_bkg_B = 6.623, 0.047, -0.047,\
+  maxLH = 20435.6, 0, 0,\
+  NDF = 20361, 0, 0,\
+  maxLHred = 1.00366, 0, 0,\
+  11235,,, AgPlate 250nm (T5034), T=151.72 K, E=13.00 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00
+  >> here many more run data would follow ...
+
+.. index:: dat-file-format
+.. _dat-file-format:
+
+DAT: CSV like file format for non-|mgr|\SR
+------------------------------------------
+
+This is typically used when exporting the parameter data from **msr2data** to be used in **mupp**, gnuplot, origin, or whatever parameter plotter you might use.
+The first line defines the parameter tags separated by spaces or tabs. If errors are available there are labeled be the ending *Err*.
+This is followed by the parameter values and its errors if present. A fill example looks like this:
+
+::
+
+  dataT        dataTErr        dataB        dataE        dataTr       dataRALRAR   dataRATRAB   dataSpinRot  Asy          AsyPosErr          AsyNegErr          Lambda       LambdaPosErr       LambdaNegErr       Ph           PhPosErr           PhNegErr           Field        FieldPosErr        FieldNegErr        RelPh_L      RelPh_LPosErr      RelPh_LNegErr      N0_L         N0_LPosErr         N0_LNegErr         N_bkg_L      N_bkg_LPosErr      N_bkg_LNegErr      RelPh_T      RelPh_TPosErr      RelPh_TNegErr      N0_T         N0_TPosErr         N0_TNegErr         N_bkg_T      N_bkg_TPosErr      N_bkg_TNegErr      RelPh_R      RelPh_RPosErr      RelPh_RNegErr      alpha_LR     alpha_LRPosErr     alpha_LRNegErr     N_bkg_R      N_bkg_RPosErr      N_bkg_RNegErr      RelPh_B      RelPh_BPosErr      RelPh_BNegErr      alpha_TB     alpha_TBPosErr     alpha_TBNegErr     N_bkg_B      N_bkg_BPosErr      N_bkg_BNegErr      maxLH        NDF          maxLHred     RUN          
+  200          0.007           99.48        1.11754      10.001       -0.008       -0.008       -10          0.1587        0.0012        0.0012        0.0263        0.003         0.003         29.85         0.64          0.64          101.179       0.035         0.035         0             0             0             219.27        0.27          0.27          2.676         0.033         0.033         -89.79        0.81          0.81          210.42        0.26          0.26          2.723         0.032         0.032         -179.73       0.81          0.81          0.9808        0.0017        0.0017        2.993         0.033         0.033         90.05         0.82          0.82          0.9755        0.0017        0.0017        2.501         0.032         0.032         20444.8      20361        1.00412      11400        
+  200          0.009           99.49        2.11668      10.001       -0.008       -0.008       -10          0.1732        0.0012        0.0012        0.0096        0.0025        0.0026        28.88         0.57          0.57          101.231       0.03          0.03          0             0             0             219.86        0.27          0.27          2.749         0.033         0.033         -88.87        0.71          0.71          211.47        0.26          0.26          2.791         0.032         0.032         -178.48       0.72          0.71          0.9678        0.0017        0.0017        2.969         0.033         0.033         90.94         0.73          0.73          0.9608        0.0017        0.0017        2.653         0.032         0.032         20182.5      20361        0.991233     11401        
+
+
+.. index:: mdu-file-format
+.. _mdu-file-format:
+
+MDU file format (psi) for |mgr|\SR
+----------------------------------
+
+For details about the PSI-BIN/MDU file format from PSI see `Class_MuSR_PSI <http://lmu.web.psi.ch/docu/manuals/bulk_manuals/software/Class_MuSR_PSI/index.html>`_
+
+.. index:: mud-file-format
+.. _mud-file-format:
+
+MUD file format (triumf) for |mgr|\SR
+-------------------------------------
+
+For details about the MUD file format from triumf see `MUon Data access <https://cmms.triumf.ca/mud/>`_ .
+
+.. _musr-root-file-format:
+
+MusrRoot file format (PSI) for |mgr|\SR
+---------------------------------------
+
+For details see :ref:`MusrRoot - an Extensible Open File Format for uSR <MusrRoot>`. 
+
+.. index:: nexus-file-format
+.. _nexus-file-format:
+
+NeXus file format (isis) for |mgr|\SR
+-------------------------------------
+
+For details about the NeXus file format from ISIS (UK) see `The application of the NeXus data format to ISIS muon data <https://doi.org/10.1016/S0921-4526(02)01613-7>`_ . For a detailed list of available meta information and data see `NeXus Instrument Definitions for ISIS muon Data <https://www.isis.stfc.ac.uk/Pages/nexus-definition-v27924.pdf>`_ .
+
+.. index:: psi-bin-file-format
+.. _psi-bin-file-format:
+
+PSI-BIN file format (psi) for |mgr|\SR
+--------------------------------------
+
+For details about the PSI-BIN/MDU file format from PSI see `Class_MuSR_PSI <http://lmu.web.psi.ch/docu/manuals/bulk_manuals/software/Class_MuSR_PSI/index.html>`_.
+
+
+.. index:: root-file-format
+.. _root-file-format:
+
+ROOT file format (psi/lem before 2012) for |mgr|\SR
+---------------------------------------------------
+
+For details about the API of ROOT files can be here: `ROOT files <https://root.cern/manual/root_files/>`_.
+The structure of the ROOT files (LEM, before 2012) looks like this:
+
+::
+
+  ROOT-file --|
+              |-- histos ---|
+              |             |-- DecayAnaModule
+              |             |-- PileUpAnaModule
+              |             |-- ScalerSumRate
+              |             |-- SCAnaModule
+              |
+              |-- RunInfo --|
+                            |-- RunSummary
+
+``histos``, ``RunInfo``, ``DecayAnaModule``, ``PileUpAnaModule``, ``ScalerSumRate``, ``SCAnaModule`` are **TFolder** objects.
+
+The ``DecayAnaModule`` object holds the positron spectra
+
+::
+  
+  DecayAnaModule --|
+                   |-- hDecay00
+                   |-- hDecay01
+                   |-- hDecay02
+                   |-- hDecay03
+                   |-- hDecay20
+                   |-- hDecay21
+                   |-- hDecay22
+                   |-- hDecay23
+
+The ``hDecayXX`` files or **TH1F** objects containing the positron spectra of the LEM detectors.
+
+The detectors (00, 01, 02, and 03) are the detectors (Left, Top, Right, Bottom). These are non-post-pileup (NPP) histograms.
+
+The detectors (20, 21, 22, and 23) are the detectors (Left, Top, Right, Bottom). These are post-pileup-corrected (PPC) histograms.
+
+The ``SCAnaModule`` contains various **TF1H** objects of slow control data of the run.
+
+The ``RunSummary`` is essentially an ascii dump, with summary information of the run.
+
+
+.. index:: wkm-file-format
+.. _wkm-file-format:
+
+WKM file format for |mgr|\SR
+----------------------------
+
+WKM is an obsolete ascii file format, originally introduced by people from the TU Braunschweig.
+It starts with a header which shows like this:
+
+::
+
+  - WKM data file converted with any2many
+  NEMU_Run:            2466
+  nemu_Run:            ./2466.wkm
+  Date:                13:22:00 2012-06-03 / 14:04:38 2012-06-03
+  Title:               LSCO x=0.02 (224-227), T=12.00 (K), E=5.57 keV, WEW B=~49(G)/8.62(A), Tr=15.02 (kV), Sample=8.70 (kV), SpinRot -10
+  Field:               49.11
+  Setup:               Sample, WEW, LowTemp-2
+  Temp:                11.999
+  TOF(M3S1):           nocut
+  Groups:              8
+  Channels:            66601
+  Resolution:          0.0001953125
+
+The header ends with an empty line.
+
+The data are stored as following: there are always 10 bin-counts per line.
+Between detectors, there will be an empty line.

doc/html/_sources/index.rst.txt

@@ -0,0 +1,32 @@
+.. musrfit docu documentation master file, created by
+   sphinx-quickstart on Sun Jun 17 11:00:32 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the musrfit documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   
+   cite
+   tutorial
+   user-manual
+   user-libs
+   setup-standard  
+   setup-dks
+   musredit
+   mupp
+   msr2data
+   any2many
+   file-formats
+   musr-root
+   acknowledgement
+   bugtracking
+   
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/html/_sources/msr2data.rst.txt

@@ -0,0 +1,374 @@
+.. include:: <isogrk1.txt>
+.. index:: msr2data
+
+.. _msr2data:
+
+msr2data - A Program for Automatically Processing Multiple ``musrfit`` msr Files
+================================================================================
+
+``msr2data`` (originally written by B. M. Wojek) is a program implemented in ``C++``. Its purpose is 
+to process multiple msr files (input files for ``musrfit``) with the same parameters and summarize the fitting 
+results either in a *TRIUMF DB* [#f1]_ or a *column ASCII* file. This allows essentially to
+
+#. Collect the fit parameters.
+#. Generate *new* input msr files based on old ones.
+
+.. [#f1] For an abridged description of this format see `here <http://musr.org/xyfit/dbformat.html>`_. The DB files 
+         produced by ``msr2data`` can be viewed for instance with :ref:`mupp <mupp>` or |mgr|\View `see here <http://musr.org/muview/>`_, however, 
+         they are not completely backward-compatible to the original ``db language`` since the parameter names can be longer than five or 
+         six characters! In order to establish this backward compatibility (if needed) the user has to ensure the correct length of the 
+         parameter names in the msr files!
+
+.. _msr2data-basic-usage:         
+
+Basic Types of Usage
+--------------------
+
+Apart from numerous :ref:`optional parameters <msr2data-opt-param>` that might be set, in principle there are four different ways of calling ``msr2data``. 
+These differ in how the list of runs which should be processed is supplied: 
+
+**msr2data <run> <extension> [optional parameters]**
+  A single run number. 
+**msr2data <firstRunNo> <lastRunNo> <extension> [optional parameters]**
+  An interval of run numbers is specified through the first and the last run number. The condition ``<firstRunNo>`` < ``<lastRunNo>`` is not necessary. 
+**msr2data \[ <runList> \] <extension> [optional parameters]**
+  Where ``<runList>`` is one or a combination of the following:
+  
+  #. ``<run0>, <run1>, <run2>, ... <runN>`` : run numbers, *e.g.* 123 124, 
+  #. ``<run0>-<runN>`` : a range, *e.g.* 123-125 -> 123 124 125, 
+  #. ``<run0>:<runN>:<step>`` : a sequence, *e.g.* 123:127:2 -> 123 125 127. ``<step>`` has to be a positive integer. 
+  #. A ``<runList>`` can also combine (1)-(3), *e.g.* 123 128-130 133, etc. 
+    
+**msr2data <runListFileName> <extension> [optional parameters]**
+  An ASCII file containing a list of run numbers and optional external parameters is passed to ``msr2data``. For the structure of the ASCII file 
+  see :ref:`below <run-list-file_structure>`. 
+  
+All four basic types of calling ``msr2data`` contain the *mandatory* file-name ``<extension>`` passed right after the list of runs. The meaning of 
+this ``<extension>`` should become clear after giving examples for all four cases:
+
+.. code-block:: bash
+
+  $ msr2data 8472 _tf_h13
+  
+generates the DB file ``out.db`` (can be changed by using the -o option) from ``8472_tf_h13.msr``.   
+
+.. code-block:: bash
+
+  $ msr2data 8472 8474 _tf_h13
+  
+generates the DB file ``out.db`` (can be changed by using the -o option) from ``8472_tf_h13.msr``, ``8473_tf_h13.msr``, and ``8474_tf_h13.msr``.   
+
+.. code-block:: bash
+
+  $ msr2data [8472 8470] _tf_h13
+  
+generates the DB file ``out.db`` (can be changed by using the -o option) from ``8472_tf_h13.msr`` and ``8470_tf_h13.msr``. 
+
+.. code-block:: bash
+
+  $ msr2data [8470:8474:2] _tf_h13
+  
+generates the DB file ``out.db`` (can be changed by using the -o option) from ``8470_tf_h13.msr``, ``8472_tf_h13.msr``, and ``8474_tf_h13.msr``.   
+  
+.. _run-list-file_structure:
+
+Run List File Structure
++++++++++++++++++++++++
+
+.. code-block:: bash
+
+  $ msr2data run.list _tf_h13
+
+generates the DB file ``out.db`` (can be changed by using the -o option) from all runs listed in the ASCII file ``run.list`` in the working directory. 
+In this file it is also possible to include *external* parameters which should be put in the resulting DB file. The structure of the ``run.list`` is the following:  
+
+::
+
+  RUN VAR1 VAR2 VAR3 ...
+  8460 200 27.1 46.2 ...
+  8472 205 27.1 46.3 ...
+  8453 210 27.2 45.9 ...
+  ·     ·    ·    ·
+  ·     ·    ·    ·
+  ·     ·    ·    ·
+
+*The first not commented and not empty line determines the parameter names and labels and has to be present!*
+
+It is allowed to add comments (with a preceding '#') or empty lines to the run-list file. 
+
+The following should be mentioned together with the above examples: 
+
+* The output files in the examples above are only newly created if they did *not* exist before invoking ``msr2data``. 
+  If the files were already present the msr file data would be appended! 
+* If the files have been newly created, also the DB file header is written. If the files were present before, only 
+  the data blocks are appended. The output of the header can either be forced or completely suppressed with the ``header`` 
+  and ``noheader`` options as shall be seen later. 
+* If the ``musrfit`` output files do not have an ``<extension>`` as specified above like ``8472.msr`` one has to call ``msr2data`` like in the following example:  
+
+  .. code-block:: bash
+  
+    $ msr2data 8472 8460 "" 
+  
+.. _msr2data-opt-param:
+
+Optional Parameters
+-------------------
+
+As mentioned already above there are some optional parameters which change the behavior of ``msr2data`` and can be passed in any order. Here is a complete list: 
+
+**data**
+  The output file format is changed to a simple column ASCII file (default output file name: out.dat). 
+**new**
+  An existing output file is deleted before new information is written to it. 
+**header**
+  Force the output of the file header even if the output file was present before. 
+**noheader**
+  The output of the file header is suppressed—also if the output file is newly created.
+  If either both or none of the header options are given, ``msr2data`` writes the file header only to new files 
+  and it solely appends the data blocks to an existing output file assuming that the header is present already. 
+**nosummary**
+  There will be no attempt to read additional information like the temperature or the applied magnetic field from 
+  the data files even if these information were present there. 
+**paramList <param>**
+  option used to select the parameters which shall be exported. ``<param>`` is a list of parameter numbers to be exported. 
+  Allowed lists are: ``<startNo>-<endNo>``, *e.g.* ``1-16`` will export parameters 1 to 16. Space separated numbers, *e.g.:* ``1 3 5``. 
+  A combination of both is possible, *e.g.* ``1-16 19 31 62``, and so on. 
+**-o<outputFileName>, -o <outputFileName>**
+  The processed data will be written to the file ``<outputFileName>`` instead of the default ``out.db`` or ``out.dat``. 
+  If ``<outputFileName>`` is equal to none (case-insensitive) the parameter data are not appended to any output file. 
+**fit**
+  Additionally to the final data collection ``msr2data`` will invoke ``musrfit`` to fit the specified runs. 
+  All msr files are assumed to be present, none is newly generated! 
+**fit-<template>[!]**
+  Additionally to the final data collection ``msr2data`` will generate msr files for the runs specified in the list 
+  of runs and invoke :ref:`musrfit <musrfit>` for performing fits of the data. As template for the first run the file 
+  ``<template><extension>.msr`` (or if not available: ``<template><extension>.mlog``) is used; the subsequent input 
+  files will be created using the msr output of the last processed runs ("chain fit"). However, if for all runs only 
+  the given template should be used one has to append an exclamation mark (**!**) to the ``<template>``. 
+**msr-<template>**
+  The same as ``fit-<template>[!]``, *without* calling ``musrfit`` and the final data collection, *i.e.* only the msr files for the given runs are generated. 
+**-k**
+  If specified together with the ``fit-<template>`` option, the :ref:`- -keep-mn2-output <musrfit>` option is passed to ``musrfit``. 
+  In the case no fits should be done, this option is ignored. 
+**-t**
+  In case this option is given additionally to the ``fit-<template> option``, ``musrfit`` is called with 
+  the :ref:`- -title-from-data-file <musrfit>` option. If no fitting is done, this option is ignored. 
+
+**Examples:**
+
+In order to illustrate the usage of these parameters a few examples with explanations are given below: 
+
+.. code-block:: bash
+
+  $ msr2data 8400 8460 _tf_h13 -oABC.db fit-8472 
+  
+Using ``8472_tf_h13.msr`` as first template, ``msr2data`` generates subsequent msr input files ``8400_tf_h13.msr`` through ``8460_tf_h13.msr``, 
+calls ``musrfit`` to perform a fit of these files and collects the results of the fits together with the DB header in the new file ``ABC.db``. 
+Additionally, some information about external parameters like the temperature will be passed to ``ABC.db`` if it is present in the data files.   
+
+.. code-block:: bash
+
+  $ msr2data [8500 8502-8504 8507] _zf fit-8472 noheader nosummary -o DEF.db 
+  
+Using ``8472_zf.msr`` as first template, ``msr2data`` generates subsequent msr input files ``8500_zf.msr``, ``8502_zf.msr``, ``8503_zf.msr``, 
+``8504_zf.msr``, and ``8507_zf.msr``, calls ``musrfit`` to perform a fit of these files and collects the results of the fits in the file ``DEF.db`` 
+*without* writing the DB file header or attempting to read additional information from the data files.
+
+.. code-block:: bash
+
+  $ msr2data 8595 8585 "" noheader fit-8472! -oGHI.dat data nosummary -k 
+  
+Using ``8472.msr`` as template for all runs, ``msr2data`` generates the msr input files ``8595.msr`` through ``8585.msr``, calls ``musrfit`` with 
+the option ``--keep-mn2-ouput`` to perform a fit of these files and collects the results of the fits in the column-structured ASCII file ``GHI.dat`` 
+*without* writing any file header or attempting to read additional information from the data files.   
+
+.. code-block:: bash
+
+  $ msr2data 8472 8475 "" fit -o none
+  
+Take the *given* msr files ``8472.msr`` through ``8475.msr`` and call ``musrfit`` *without* finally summarizing the results.
+
+.. code-block:: bash
+
+  $ msr2data 8472 8475 _tf_h13 msr-8471! 
+  
+Using ``8471_tf_h13.msr`` as template for all runs, ``msr2data`` generates the msr input files ``8472_tf_h13.msr`` through ``8475_tf_h13.msr``. 
+*No fitting will be performed and no DB or ASCII output will be generated!*
+
+.. code-block:: bash
+
+  $ msr2data [8472 8475-8479] _tf_h13 paramList 1-16 data -o bestData.dat 
+  
+Will collect the parameters 1 to 16 from the msr-files ``8472_tf_h13.msr``, ``8475_tf_h13.msr``, ``8476_tf_h13.msr``, ``8477_tf_h13.msr``, ``8478_tf_h13.msr``, 
+and ``8479_tf_h13.msr`` and write these parameters into a column like output file ``bestData.dat``.  
+  
+.. index:: msr2-data-global-mode
+  
+The Global Mode  
+---------------
+  
+Apart from all the options described :ref:`above <msr2data-opt-param>` there is another program option: **global**. 
+This option changes the general behavior of ``msr2data`` in that way that instead of processing one msr file for each 
+run it combines all specified runs in *one single msr file* with the possibility to define common parameters for all 
+runs as well as run-specific parameters. When writing the obtained parameters to a DB file or a column-structured 
+ASCII file that single msr file is read and the parameters valid for each run are extracted. The global option can be 
+used in conjunction with any of the described invocations of ``msr2data`` and together with all options stated :ref:`above <msr2data-opt-param>`.   
+
+File Generation
++++++++++++++++
+
+The general idea of this mode is to generate a global msr file on the basis of a working single-run msr file. For this 
+purpose a single-run template containing information about common and run-specific parameters should be created. These 
+parameters are identified through their parameter names: 
+
+**run-specific parameters**
+  these parameters are tagged with the current run number in the format ``%0Xu``, *i.e.* ``X`` digits with leading zeros, 
+  at the end of the parameter name, *e.g.* for a 4-digit-formatted run number ``alpha0123`` if the run number was 123 or 
+  for a 8-digit-formatted run number ``alpha00123456`` if the run number was 123456. ``X`` has to be at least 4. 
+**common parameters**
+  all parameters that are not run specific 
+  
+The :ref:`FITPARAMETER block <msr-fitparameter-block>` of an exemplary template file ``8472_example.msr`` could therefore look like:  
+
+::
+
+  FITPARAMETER
+  #       No   Name      Value     Step        Pos_Error    Boundaries
+          1    Phase     35.8359   -3.94496    3.93749
+          2    Asy8472   0.04501   -0.00208    0.00211      0       0.33
+          3    Field     143.212   -0.27960    0.27885      100     200
+          4    Rate8472  0.14245   -0.02501    0.02279      0       1
+            
+Here the parameters **2** and **4** would be treated as *run-specific* whereas the parameters **1** and **3** would be *common* to the original and all newly added runs.
+
+Normally, within the template file there should *not* appear explicitly any run-specific parameters in the :ref:`THEORY <msr-theory-block>` and 
+:ref:`FUNCTIONS <msr-functions-block>` blocks. If however, those parameters are met, ``msr2data`` will try to substitute them by mapped parameters 
+and add them accordingly to the map contained in each :ref:`RUN block <msr-run-block>`.
+
+When ``msr2data`` is called to generate a global msr file, *e.g.*
+
+.. code-block:: bash
+
+  $ msr2data 8471 8470 _example msr-8472 global 
+  
+a new msr file ``8471+global_example.msr`` is created. As can be seen in the example, the name of the global msr file always starts with the 
+first specified run number followed by the ``+global`` identifier and the template ``<extension>``. The example's global FITPARAMETER block would be:
+
+:: 
+
+  FITPARAMETER
+  #       No   Name      Value     Step        Pos_Error    Boundaries
+
+  # Common parameters for all runs
+
+          1    Phase     35.8359   -3.94496    3.93749
+          2    Field     143.212   -0.27960    0.27885      100     200
+
+  # Specific parameters for run 8471
+            
+          3    Asy8471   0.04501   -0.00208    0.00211      0       0.33
+          4    Rate8471  0.14245   -0.02501    0.02279      0       1
+
+  # Specific parameters for run 8470
+
+          5    Asy8470   0.04501   -0.00208    0.00211      0       0.33
+          6    Rate8470  0.14245   -0.02501    0.02279      0       1
+
+This shows that the fit parameters are reorganized in a way that the common parameters appear at the beginning of the parameter list and they are 
+followed by copies of the parameters specific to each run (in the specified order!). Additionally, for each specified run new RUN blocks are 
+created — for each run as many as found for the template run.
+
+During this reorganization all the affected parameter occurrences are changed accordingly! 
+            
+.. note::     
+
+  Please be aware of the fact that comments in the template msr file are *not* propagated to the newly generated global msr file!
+  
+.. index:: msr2data-global-param-extraction  
+  
+Parameter Extraction
+++++++++++++++++++++
+
+After fitting some model to the specified data the fit parameters can be extracted from the global msr file to a DB or column-structured ASCII file;
+as usual this includes also parameters stored in the run data files or externally specified parameters given in a :ref:`run-list file <run-list-file_structure>`. 
+In order to reach this goal the global msr file has to obey certain rules: 
+
+* The order of the parameters has to match the one described above, meaning the common parameters are listed first followed by 
+  the same number of parameters specific to each run tagged by the according run numbers at the end of the parameter names and 
+  having the same order as the specified list of runs.
+* The RUN blocks have to be ordered according to the list of runs to be processed. 
+
+Following these rules -- which is achieved most easily by generating the global msr file using ``msr2data`` as shown above -- the parameters can be extracted *e.g.* like
+
+.. code-block:: bash
+
+  $ msr2data 8471 8470 _example global data -o globalFit.dat 
+  
+This will read in the file ``8471+global_example.msr``, extract for each run all relevant parameters from the msr file as well as 
+from the according data files (if available) and append all of them in columns to the ASCII file ``globalFit.dat``.   
+
+.. index:: msr2data-global-extended
+
+The Extended Global Mode
+++++++++++++++++++++++++
+
+If a new global input file is generated, it is also possible to do an automatic pre-analysis for each single run using the specified template first; 
+afterwards the run-specific parameters of these single-run msr files are collected into the global msr file. In special cases this might be useful 
+to obtain a better set of starting values for the parameters, however, in most cases it will not replace the "manual review" of the generated global 
+input file. The option is activated by choosing the keyword **global+**. For example 
+
+.. code-block:: bash
+
+  $ msr2data 8471 8470 _example global+ msr-8472 
+  
+Here, ``8472_example.msr`` is first used as template to generate the file ``8471-OneRunFit_example.msr``, then ``musrfit`` is called for it, the result 
+is used to generate ``8470-OneRunFit_example.msr`` and ``musrfit`` is called for that file. Finally, the global fit file ``8471+global_example.msr`` is 
+produced — including the fit results of the ``OneRunFit`` files for the run-specific parameters.  
+
+By appending an exclamation mark **!** to the **global+** option, the given template will be used for every new file generation (similar to the fit option 
+explained before). The **+[!]** extension will be ignored, if no new global input file is generated.
+The single run msr files are *not* deleted at the moment. The information contained in them might be useful for some people. Of course the data can also 
+be collected by ``msr2data``. *E.g.* in order to produce a DB file ``OneRunFits.db`` one could call 
+
+.. code-block:: bash
+
+  $ msr2data 8471 8470 -OneRunFit_example -o OneRunFits.db 
+
+.. note::  
+
+  Please be aware that the program in this mode *always* generates new single-run msr files and *always* calls ``musrfit`` for them. In case there are 
+  already single-run fits present, these cannot be used in conjunction with this option. The program on purpose behaves in this way in order to ensure 
+  the file integrity and correct parameter order within these files.
+  
+Known Limitations
+-----------------
+
+* The indexing run number of the msr file has to be at the begin of every filename.
+* Within the data file name the ``RUN#`` has the format ``%0Xu``, *i.e.* ``X`` digits with leading zeros, and has to be the rightmost number given in this 
+  format in the file name. ``X`` has to be at least 4. The highest treatable run number is :math:`2^{32}-1 = 4294967295`.
+* In order to keep ``msr2data`` working properly the msr files should only contain *one* STATISTIC block at the end of the file and *one* FITPARAMETER block 
+  right after the TITLE — ``musrfit`` itself allows to have more creative msr files...  
+* The msr-file generation from a template takes only care of runs given on the *first* line of a ``RUN block``. :ref:`ADDRUN <msr-addrun>` statements are simply 
+  copied! Since this is most probably *not* what one likes to do, it is suggested *not* to use the ``fit-<template>`` and ``msr-<template>`` options if 
+  ADDRUN statements were present in the template file.   
+* ``msr2data`` will write only up to two successive empty lines in newly generated msr files. In case more subsequent empty lines are encountered in a template file, 
+  these are not copied! Actually, this measure is not a limitation but has been introduced to keep the msr files in a reasonable shape.   
+  
+The Graphical User Interface for msr2data Provided by musredit  
+--------------------------------------------------------------
+
+:ref:`musredit <musredit-sec>`, designed especially for the manipulation of ``musrfit`` msr files and graphical front ends to ``musrfit``, offer an almost 
+self-explanatory graphical user interface to ``msr2data`` depicted below:
+
+.. image:: ../images/msr2data-GUI.*
+
+1. and 2. Choose one of the ways to specify your list of runs as described under :ref:`basic usage <msr2data-basic-usage>`.
+
+3. Give the file extension here, *e.g.* ``_zf`` for files like ``8472_zf.msr``. If the files do not have an extension this 
+   field stays empty. ``musredit`` takes care of passing the "" to ``msr2data`` as mentioned above. 
+4. Activates the ``fit-<template>`` option if ``<template>`` is entered. In case the option ``Chain Fit`` is *not* set the 
+   given template will be used for the input-file generation for all runs to be fitted — otherwise the output of the first 
+   fit serves as template for the second and so on. The template field stays empty if *no* fits should be performed! 
+5. Activates the ``-o <outputFileName>`` option if ``<outputFileName>`` is entered. If nothing is entered the default output file ``out.db`` or ``out.dat`` is used.  
+
+The options tags correspond essentially to the description in :ref:`optional parameters <msr2data-opt-param>`.

doc/html/_sources/mupp.rst.txt

@@ -0,0 +1,238 @@
+.. include:: <isogrk1.txt>
+.. index:: mupp
+.. _mupp:
+
+mupp - |mgr|\SR Parameter Plotter
+=================================
+
+``mupp`` is a little helper program which allows to quickly plot a collection of msr-file parameters,
+as for instance generated by :ref:`msr2data <msr2data>`. It can handle ``db``- and ``dat``-files.
+Also a collection of ``msr``-files can be invoked. ``mupp`` is heavily inspired by |mgr|\View (see
+`here <http://musr.org/muview/>`_).
+
+``mupp`` can be operated from within as graphical user interface or via a command line scripting interface.
+The ``mupp`` GUI can be invoked either directly from the command line or from within :ref:`musredit <musredit-sec>`.
+
+Each collection bundles a number of runs, where a run is a single |mgr|\SR measurement.
+A run is analyzed by a number of parameters (defined in the msr-files), and complemented by
+additional physical parameters as the temperature, magnetic field, implantation energy, etc.
+Hence parameters can be seen as vectors and can be plot against each other. 
+
+.. index:: mupp-gui
+
+The Graphical User Interface
+----------------------------
+
+A typical setting could look like this
+
+.. image:: ../images/mupp-gui-0.*
+
+1. shows the list of loaded collections. A collection is defined as ``db``- or ``dat``-file (typically the 
+   output from :ref:`msr2data <msr2data>`). If you call the open-dialog and select a collection of
+   ``msr``-files, ``mupp`` will call ``msr2data`` and tries to generate a collection on-the-fly.
+2. in this list, the data-tags of the currently selected collection is presented. The data-tags can be
+   directly dragged over to the ``x``- and ``y``-axis list. Another way is to select the data-tag
+   wished and click ``add X`` to add the selected data-tag to the ``x``-axis list. Analogous it is done
+   for the ``y``-axis.
+3. ``x``-axis list. The labels are followed by ``(-X-)`` where the number ``X`` corresponds to the
+   selection it corresponds to. The numbering of the collection is as given in the collection list.
+4. ``y``-axis list. The labels are followed by ``(-X-)`` where the number ``X`` corresponds to the
+   selection it corresponds to. The numbering of the collection is as given in the collection list.
+5. ``add X`` allows to add the currently selected data-tag to the ``x``-axis list.   
+6. ``add Y`` allows to add the currently selected data-tag to the ``y``-axis list. 
+7. ``remove X`` will remove the selected ``x``-axis tag.
+8. ``remove Y`` will remove the selected ``y``-axis tag.
+9. Often one would like to compare trends of different settings. In the above example each collections
+   holds an energy scans for a given temperature. Each collection is measured at a different temperature.
+   Now, instead of adding ``x``- and ``y``-axis tags for each collection, you can do the following:
+   you add ``x``- and ``y``-axis data-tags for the first collection. Afterwards you select all the other
+   collections of interest and click on ``Add Ditto``. ``mupp`` will then add the corresponding
+   ``x``- and ``y``-axis data-tags accordingly. This is less error prone and quicker!
+10. Clicking the ``Plot`` button will invoke ``mupp_plot`` (a ``ROOT`` based application) which will
+    present the data, as shown here
+    
+    .. image:: ../images/mupp-plot-0.*
+      :height: 600px
+      
+11. ``Remove Collection``: will remove the selected collection
+12. ``Refresh Collection``: will reload the collection (``db``- or ``dat``-file). This is often useful
+    during beamtime where the collection is growing run-by-run.
+13. Command history window.
+14. This is the script command line. Currently it allows to perform the tasks without mouse gambling.
+    In the future much more commands are planed. See the ``Help / Cmd's`` for the currently available
+    commands.
+
+Define Variable Dialog
+++++++++++++++++++++++    
+
+.. image:: ../images/mupp-add-var.*
+
+1. Variable text edit window.
+2. Collection link window.
+3. Shows the parameters of the selected collection.
+4. Check if the variable/error variable from the edit window is valid.
+5. Add the variable to the selected collection(s) if the parsing is successful.
+
+A variable defined here is a mathematical expression defined by parameters of loaded collections.
+Since a parameter also has an associated error, also newly defined variables **always** need
+to be defined together with a corresponding error variable. If the name of a variable is defined
+as ``SigmaSC_10`` (see the above snapshot), the error variable need to be named as ``SigmaSC_10Err``.
+
+Currently the following mathematical functions are defined: ``max``, ``min``, ``abs``, ``sin``, ``cos``,
+``tan``, ``exp``, ``log``, ``ln``, ``pow``.
+
+.. index:: mupp-scripting
+    
+The Scripting Interface
+-----------------------
+
+``mupp`` can also be operated in a scripting like manner. The use cases are plot updates during run time, 
+or web-based interaction which requests figures. A script is invoked by the command line option ``-s`` (see
+:ref:`mupp command line summary <mupp-usage>`. Currently the following scripting commands are available:
+
+**loadPath <dir>** 
+  set the load path to ``<dir>``. Bash variables like $HOME are accepted. This is the path where to look for collection files (``db``- and ``dat``-files).
+
+**load <coll>** 
+  will load the collection ``<coll>``.
+
+**selectAll** 
+  will select all loaded collections. This means every plot of variable x/y will be carried out to *ALL* collections.
+  
+**select <nn>** 
+  selects collection ``<nn>``, where ``<nn>`` is either the *number* of the collections, or its *name*, *e.g.* 
+  select YBCO-40nm-T5K-FC150mT-Escan.db.
+  
+**x <label>**   
+  add ``<label>`` as a *x*-variable. Only *one* is allowed.
+  
+**y <label(s)>**
+  add ``<label(s)>`` as *y*-variable. *Multiple* labels are possible. 
+  
+**norm**
+  this will normalize all the *y*-variables by their maximum.   
+  
+**savePath <dir>**
+  set the save path to ``<dir>``. The place where the macros, and/or the plot output will be saved.  
+  
+**plot <fln>**
+  where ``<fln>`` is the file name with extension under which the plot should be saved.
+  
+**macro <fln>**
+  where ``<fln>`` is the file name under which the root macro should be saved.
+  
+**var <var_name> = <expr>**
+  defines a variable.
+  <expr> is a mathematical expression where collection variables are addressed 
+  via the '$', e.g. ``dataT`` is addressed by ``$dataT``, etc. An example:
+  
+  ``var invT = 1000.0 / $dataT``
+  
+  Each variable has to be accompanied by its error variable. An error variable
+  is defined by the ``<var_name>`` followed by ``Err``
+  For the above example the error variable is
+  
+  ``var invTErr = $invT * $dataTErr / $dataT``
+  
+**col <nn> : <var_name>**
+   links <var_name> to the collection <nn>, where <nn> is the number of the 
+   collection as defined by the order of load, starting with 0.   
+  
+An example script file ``sigmaSC-vs-temp.txt`` might look like this:
+
+::
+
+  # This is a comment
+  # Script: sigmaSC-vs-temp.txt
+
+  loadPath ./
+
+  load YBCO-40nm-FC-E3p8keV-B10mT-Tscan.db  # collection 0
+  load YBCO-40nm-FC-E3p8keV-B150mT-Tscan.db # collection 1
+
+  # define variables: for each variable an associated error variable is needed.
+  # B=10mT
+  var SigmaSC_10 = pow(abs(pow($Sigma,2.0)-pow(0.11,2.0)), 0.5) # 0.11 (1/us) is the nuclear contribution (T>Tc)
+  var SigmaSC_10Err = pow(pow($Sigma*$SigmaErr,2.0)+pow(0.11*0.0025,2.0), 0.5)/$SigmaSC_10
+  # B=150mT
+  var SigmaSC_150 = pow(abs(pow($Sigma,2.0)-pow(0.075,2.0)), 0.5) # 0.075 (1/us) is the nuclear contribution (T>Tc)
+  var SigmaSC_150Err = pow(pow($Sigma*$SigmaErr,2.0)+pow(0.075*0.0025,2.0), 0.5)/$SigmaSC_150
+
+  # link variables to collections
+  col 0 : SigmaSC_10    # error variable SigmaSC_10Err doesn't need to be given, it is automatically linked to SigmaSC_10
+  col 1 : SigmaSC_150
+
+  norm # normalize the plot to the maximum of each y-data-set
+
+  # the next 3 cmds means the following: use collection 0, add dataT to the x-axis,
+  # and SigmaSC_10 to the y-axis
+  select 0 
+  x dataT
+  y SigmaSC_10
+
+  select 1
+  x dataT
+  y SigmaSC_150
+
+  # where to save the output
+  savePath ./
+  
+  # create a pdf output file of the above defined xy-data sets. Currently also
+  # other file formats are supported, like png, jpg, etc.
+  plot SigmaSCVsTemp.pdf
+
+  # creates a ROOT macro which can be used for further refinement
+  macro SigmaSCVsTemp.C
+
+  # end
+
+.. index:: mupp-usage
+.. _mupp-usage:
+
+The Usage Summary
+-----------------
+
+::
+ 
+  usage: mupp [OPTIONS] [[--path <fit-param-path>] <fit-param-file-names>]
+
+  OPTIONS:
+    -h, --help: this help
+    -v, --version: current mupp version
+    -s <fln>, --script <fln>: <fln> being a mupp script.
+    --path <fit-param-path>: path where to look for the <fit-param-file-names>
+    <fit-param-file-names>: list of file name(s) to be loaded.
+       allowed formats are: db, dat, msr
+
+
+  SCRIPT COMMANDS:
+     Lines starting with '#', '%', or '//' are comments and will be ignored.
+     The same is true for empty lines. Comments are also allowed at the end
+     for a command, i.e. loadPath ./ # the best place ever.
+
+     load <coll>     : load a collection. <coll> is the filename of the
+                       collection (*.db, *.dat)
+     loadPath <path> : set the load path to <path>; accepting bash variables
+                       like $HOME, etc.
+     x <var-name>    : set a x-axis variable. <var-name> is a data tag of
+                       the db/dat-file.
+     y <var-name>    : set a y-axis variable. <var-name> is a data tag of
+                       the db/dat-file.
+     select <nn>     : select collection <nn>, where <nn> is the row-number
+                       or the name of the collection to be selected.
+     selectAll       : i.e. already set 'x', 'y' will apply to ALL collections
+                       present.
+     savePath <path> : sets the save path to <path>; accepting bash variables
+                       like $HOME, etc.
+     plot <fln>      : where <fln> is the file name with extension under which
+                       the plot should be saved.
+     macro <fln>     : where <fln> is the file name under which the root macro
+                       should be saved.
+     var <var_name> = <expr> : defines a variable.
+                               <expr> is a mathematical expression where
+                               collection variables are addressed via the '$',
+                               e.g. dataT is addressed by $dataT, etc.
+     col <nn> : <var_name>   : links <var_name> to the collection <nn>, where
+                               <nn> is the number of the collection as defined
+                               by the order of load, starting with 0.
+              

doc/html/_sources/musr-root.rst.txt

@@ -0,0 +1,681 @@
+.. include:: <isogrk1.txt>
+.. index:: MusrRoot
+
+.. _MusrRoot:
+
+MusrRoot - an Extensible Open File Format for |mgr|\SR
+======================================================
+
+Until 2011 different |mgr|\SR file formats were used within PSI. The bulk-|mgr|\SR instruments were 
+writing their data in the ``PSI-BIN`` file format, which is a fixed binary format with rather stringent 
+limitations. The LE-|mgr|\SR (LEM) instrument was using a ROOT (CERN) based file format which was tightly 
+tailored to the special needs of the LEM instrument. This situation was unsatisfactorily and hence it 
+was decided to move forward to a open file format called ``MusrRoot`` to be described in the following.
+
+Some Basics Concerning ROOT Files
+---------------------------------
+
+The |mgr|\SR data acquisition systems at PSI are utilizing MIDAS (see `Midas Home Page <https://midas.triumf.ca/MidasWiki/index.php/Main_Page>`_). 
+The MIDAS analyzer, which is responsible to build histograms, especially the |mgr|\SR decay histograms, makes 
+it very easy to build ROOT (see `ROOT/CERN home page <https://root.cern.ch>`_ ) histogram objects (these 
+are ``TH1F`` objects for |mgr|\SR decay histograms). ROOT is a ``C++`` object-oriented data mining and 
+analysis frame work. These histograms can be collected and saved in ROOT files (``TFile``). In order to ease 
+the understanding of the upcoming definitions, a few ROOT related things shall be summaries here. For details 
+concerning the ROOT frame work documentation please check `ROOT/CERN Users Guide(s) <https://root.cern.ch/root-user-guides-and-manuals>`_ 
+and `ROOT/CERN Reference Guide <https://root.cern.ch/guides/reference-guide>`_. 
+
+ROOT files (``TFile``) are binary files which can hold any kind of objects. A ``TFile`` is organized similarly 
+to a directory structure of an operating system. Within the ROOT framework, there is a ``TFile`` browser available 
+which allows to inspect these files. This browser (``TBrowser``) will show all object saved in the ``TFile`` directly, 
+if they derive from ``TObject``. 
+
+The ``MusrRoot`` file format to be described below is only using a small subset of possible ROOT objects, namely:
+
+* ``TFolder``: this are the top level objects in the ``MusrRoot`` file.
+* ``TH1F``: Hold the |mgr|-decay-histograms.
+* ``TObjArray``: Holding collection of header information.
+* ``TObjString``: Holding the content of any header information. 
+
+Since all these objects are deriving form ``TObject``, they will be directly accessible via the ``TBrowser``-object. 
+For instance, the |mgr|-decay-histograms can be directly plotted, are even fitted, out of the box. 
+
+MusrRoot an Extensible Open File Format for |mgr|\SR 
+----------------------------------------------------
+
+As mentioned before, ROOT files are open-file-format files meaning that they can contain more entries (and most probably will) than the ones specified in the following. The specified ones will be the mandatory ones for all instruments. Before defining all mandatory entries, the MusrRoot file structure shall be sketched.
+
+The MusrRoot file structure looks like: 
+
+::
+
+  histos ---|
+            |- DecayAnaModule ---|
+            |                    |- hDecay001
+            |                    |- hDecay002
+            |                    ...
+            |
+            |- SCAnaModule ---|
+            ...               |- hSampleTemperature
+                              |- hSampleMagneticField
+                              ...
+  RunHeader ---|
+               |- RunInfo
+               |- DetectorInfo ---|
+               |                  |- Detector001
+               |                  |- Detector002
+               |                  ...
+               |
+               |- SampleEnvironmentInfo
+               |- MagneticFieldEnvironmentInfo
+               |- BeamlineInfo
+               ...
+               
+where ``hDecay001``, etc. are ROOT histograms (to be more specific: ``TH1F``), containing the |mgr|\SR decay histograms. There can be as many as needed, especially there is no limitation about their length. The histogram object names will be ``hDecayXXX``, where ``XXX`` (leading zero int, *i.e.* ``%03d`` 
+in ``C/C++`` notation, starting with '1') is the histogram number. The title and name of the histogram (see description of the ``TH1F`` ROOT class) contains the label of the histogram, like 'top', 'forward', etc. How many of these histograms are present is accessible through the ``RunInfo`` folder in which the necessary header information are found (details see next sections). The folder ``SCAnaModule`` contains histograms of some of the slow-control parameters, as for instance the sample temperature versus time, the applied field versus time, etc. Again the label of the histogram will give more specific information about its content. 
+
+Run Information Contained in ``RunHeader``
+++++++++++++++++++++++++++++++++++++++++++
+
+The ``RunHeader`` contains all needed meta-information to describe a |mgr|\SR-run. The list of the minimal number of required "folders" of the ``RunHeader`` is given in the following structure:
+
+::
+
+  RunHeader (TFolder) ---|
+                         |- RunInfo (TObjArray)
+                         |- DetectorInfo (TObjArray)
+                         |- SampleEnvironmentInfo (TObjArray)
+                         |- MagneticFieldEnvironmentInfo (TObjArray)
+                         |- BeamlineInfo (TObjArray)
+
+In brackets the object type is given. ``RunInfo`` contains most information relevant for the user and will be itemized in :ref:`RunInfo Overview <musr-root-overview>` and :ref:`RunInfo Required <run-info-required>`. ``DetectorInfo`` contains detector specific information, like detector name, time zero bin, etc. (details is found under :ref:`DetectorInfo Required <detector-info-required>`). ``SampleEnvironmentInfo`` (details under :ref:`SampleEnvironmentInfo Required <sample-environment-info-required>`), and ``MagneticFieldEnvironmentInfo`` (details under :ref:`MagneticFieldEnvironmentInfo Required <magnetic-field-environment-info-required>`) store additional, more detailed information concerning the sample environment. ``BeamlineInfo`` stores beamline relevant information (details under :ref:`BeamlineInfo Required <beamline-info-required>`).
+
+Before elaborating more on the required items within this structure, a few words on the ROOT types used here: ``RunHeader`` is a ``TFolder`` object. All the "sub-directory" entries are of type ``TObjArray`` and collect items of type ``TObjString`` or other ``TObjArray`` (*i.e.* sub-directories and sub-sub-directories, etc.).
+
+.. index:: MusrRoot-Overview
+.. _musr-root-overview:
+
+``RunInfo`` Overview
+^^^^^^^^^^^^^^^^^^^^
+
+======================== ============================ =====================================================
+Name                     Internal Type                Comment
+======================== ============================ =====================================================
+Version                  ``TString``                  GIT version of ``TMusrRunHeader``
+Generic Validator URL    ``TString``                  URL of the generic ``MusrRoot`` validation xsd-file.
+Specific Validator URL   ``TString``                  URL of the instrument specific validation xsd-file.
+Generator                ``TString``                  Program which wrote the ``MusrRoot`` file, *e.g.* ``nemu_analyzer``
+File Name                ``TString``                  File name of the ``MusrRoot`` file, *e.g.* ``deltat_tdc_gps_4295.root``
+Run Title                ``TString`` 
+Run Number               ``Int_t`` 
+Run Start Time           ``TString``                  ISO 8601 date time
+Run Stop Time            ``TString``                  ISO 8601 date time
+Run Duration             ``TMusrRunPhysicalQuantity`` run duration in sec
+Laboratory               ``TString``                  *e.g.* PSI
+Instrument               ``TString``                  *e.g.* GPS
+Muon Beam Momentum       ``TMusrRunPhysicalQuantity`` *e.g.* 28.1 MeV/c
+Muon Species             ``TString``                  positive, or negative muon
+Muon Source              ``TString``                  *e.g.* Target E - Low Energy Muons or "Target M" ... 
+Setup                    ``TString``  
+Comment                  ``TString`` 
+Sample Name              ``TString`` 
+Sample Temperature       ``TMusrRunPhysicalQuantity`` *e.g.* 3.21 +- 0.05 K; SP: 3.2; CF1
+Sample Magnetic Field    ``TMusrRunPhysicalQuantity`` *e.g.* 350.002 +- 0.005 G; SP: 350; WXY
+No of Histos             ``Int_t``
+Time Resolution          ``TMusrRunPhysicalQuantity`` *e.g.* 0.1953125 ns
+RedGreen Offsets         ``TIntVector``               *e.g.* 0; 20
+======================== ============================ =====================================================
+
+These entries should be clear except for the ``RedGreen Offsets`` and the column "Internal Type" which shortly will be discussed before specifying the content of the other required folders.
+
+#. ``RedGreen Offsets``: in case experiments are performed with external stimuli, there will be a collection of related histograms. 
+   For instance for electrical field experiments, there will be histograms for field on/off, doubling the number of needed histograms. 
+   In order to distinguish them easier in the data file, the ``RedGreen Offsets`` were introduced. One selection of histograms 
+   (assuming for the moment 8 detectors) will be numbered from 1 to 8 (lets say the field off ones). The other set of histograms 
+   (field on in this example) will then start with 21 through 28 (see table above). The same will be true for the detector information 
+   (see :ref:`DetectorInfo Required <detector-info-required>`). The entry ``No of Histos`` will only give 8 for the given example, 
+   meaning that red/green multiplication is defined rather via ``RedGreen Offsets`` than the number of histograms. 
+#. Internal Types: in order to ease the handling of the ``MusrRoot`` run header, a class ``TMusrRunHeader`` is available which deals 
+   with it. The "Internal Type" specified, corresponds to the internal representation in within this class. In the ``MusrRoot`` file 
+   these entries are all saved as browsable ROOT strings (``TObjStringv). The only special type is ``TMusrRunPhysicalQuantity`` which 
+   is introduced to deal with physical quantities. They always can be represented in the following way:
+   
+   ::
+   
+     <property name> <value> +- <estimated error> <unit>; SP: <demand>; <description>
+     
+Not all of these values are needed to be given and depending on which are given, the representation in the ``MusrRootv file will be different (handled by ``TMusrRunHeader``). Examples are given in the comment column of the table above. For details see  :ref:`TMusrRunPhysicalQuantity - Possible Representations <musr-run-physical-quantity>`. 
+
+A mock-up ``TBrowser`` print-out would look like the one shown in the following figure. You might notice, that at the end of each entry you find a ``-@X``, where ``X`` is a number. This is an encoding of the internal type of the entry and is the price to be payed not using derived types. The next section will explain this in much more detail. 
+
+.. image:: ../images/MusrRoot-RunInfo.*
+
+``TMusrRunHeader`` mock up. The red shaded entries are of type ``TMusrRunPhysicalQuantity``
+
+.. _musr-run-header-concept:
+
+TMusrRunHeader Concept
+----------------------
+
+The different |mgr|\SR instruments need different information to be written into the data file (next to the most important ones: the histograms). The above defined properties are the *minimal number of required* ones. There are different possible approaches to deal with it on the implementation level. 
+
+* A base class dealing with *minimal* required standard is defined. Afterwards for each instrument a class 
+  is derived which is extending the base class to the needs of the instrument.
+* The base class is defined in a more abstract way, and some external, text-based description is given which defines the details of the instrument. 
+
+Even though the first approach is very clean, it would mean a lot of maintenance work. The 2nd approach is slightly more demanding for the handling class (``TMusrRunHeader`` and helper classes), but having the advantage of easy maintainability and expandability. The idea is that all header information can be classified into 7 groups (see previous and following section(s))
+
+#. Strings, represented by ``TString``
+#. Integers, represented by ``Int_t``
+#. Floating point numbers, represented by ``Double_t``
+#. Physical quantities, represented by :ref:`TMusrRunPhysicalQuantity - Possible Representations <musr-run-physical-quantity>`
+#. Collection of strings, represented by ``TStringVector``
+#. Collection of integers, represented by ``TIntVector``
+#. Collection of floating point numbers, represented by ``TDoubleVector`` 
+
+These properties can be collected by themselves in form of vectors. This way any needed information can be written into the ROOT file. The class ``TMusrRunHeader`` is implementing this run header concept. In following section code snippets will be discussed, showing how this is used on level of the ``MIDAS`` analyzer, ``musrfit`` reader routine, and ``any2many`` conversion routines. The section :ref:`Validation <musr-root-validation>` will discuss how to validate ``MusrRoot`` files. 
+
+    
+User Interface for MusrRoot Run Header
+++++++++++++++++++++++++++++++++++++++
+
+There are two things needed to deal with the ``MusrRoot`` run header, namely writing it and reading it. I will start with the writing as will be done in the ``MIDAS`` analyzer. 
+
+Writing a MusrRoot Run Header
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An example program ``write_musrRoot_runHeader`` which is writing a full run header is part of the ``musrfit`` package. Here I will concentrate just on the most essential parts. First one needs an instance of ``TMusrRunHeader``
+
+.. code-block:: c++
+
+  TMusrRunHeader *header = new TMusrRunHeader();
+  TMusrRunPhysicalQuantity prop;
+  
+``header`` is the instance of ``TMusrRunHeader``. ``prop`` is an instance of ``TMusrRunPhysicalQuantity`` which will be needed further down in the description. In the next step some run header entries will be added 
+
+.. code-block:: c++
+
+  header->Set("RunInfo/File Name", "deltat_tdc_gps_2871.root");
+  header->Set("RunInfo/Run Title", "here comes the run title");
+  header->Set("RunInfo/Run Number", 2871);
+  
+Adding information is done via the multiple overloaded ``Set(<pathName>,<value>)`` method. Here ``<pathName>`` is a string representing the "path" like representation in the ``MusrRoot`` file structure, followed by the "value" to be set, *e.g.* "=File Name=". ``<value>`` can be any of the types listed at the beginning of :ref:`Sec. TMusrRunHeader Concept <musr-run-header-concept>`. Here a few examples how to set ``TMusrRunPhysicalQuantity``. 
+
+.. code-block:: c++
+
+  prop.Set("Sample Temperature", 3.2, 3.21, 0.05, "K", "CF1");
+  header->Set("RunInfo/Sample Temperature", prop);
+
+  prop.Set("Time Resolution", 0.1953125, "ns", "TDC 9999");
+  header->Set("RunInfo/Time Resolution", prop);
+
+  prop.Set("CF3", MRH_UNDEFINED, 3.27, 0.09, "K", "strange temperature");
+  header->Set("SampleEnvironmentInfo/CF3", prop);
+  
+Here ``TMusrRunPhysicalQuantity`` objects are fed via the use of the overloaded set-method. For details see :ref:`TMusrRunPhysicalQuantity - Possible Representations <musr-run-physical-quantity>`.   
+
+To set some property within "sub-sub-directories" it would like this: 
+
+.. code-block:: c++
+
+  header->Set("DetectorInfo/Detector001/Time Zero Bin", 3419.0);
+  
+To write the whole run header into a file would look something like this: 
+
+.. code-block:: c++
+
+  TFile *f = new TFile(fileName, "RECREATE", "write_musrRoot_runHeader");
+  if (f->IsZombie()) {
+    delete f;
+    return -1;
+  }
+
+  // create the needed TFolder object
+  TFolder *runHeader = new TFolder("RunHeader", "MusrRoot Run Header Info");
+
+  // create the "directory" structure
+  if (header->FillFolder(runHeader)) {
+    runHeader->Write(); // write run header to file
+  }
+
+  f->Close();
+
+Reading a MusrRoot Run Header 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following code snippet shows how the extract the full run header from the ``MusrRoot`` file. 
+
+.. code-block:: c++
+
+  TFile *f = new TFile(fileName, "READ", "read_musrRoot_runHeader");
+  if (f->IsZombie()) {
+    delete f;
+    return -1;
+  }
+
+  TFolder *runHeader = 0;
+  f->GetObject("RunHeader", runHeader);
+  if (runHeader == 0) {
+    cerr << endl << ">> **ERROR** Couldn't get top folder RunHeader";
+    closeFile(f);
+    return -1;
+  }
+
+  TMusrRunHeader *header = new TMusrRunHeader(fileName);
+
+  if (!header->ExtractAll(runHeader)) {
+    cerr << endl << ">> **ERROR** couldn't extract all RunHeader information";
+    closeFile(f);
+    return -1;
+  }
+
+  f->Close();
+  delete f;
+
+
+The routine ``ExtractAll(TFolder *runHeader)`` decodes all the ``TObjString`` objects and fills internal data structures. This means when reading a MusrRoot -file the above handling is always needed. After the ``ExtractAll`` call, parameters can be extracted via the getter routines available. For instance to read the Run Number, the code would look like   
+
+.. code-block:: c++
+
+  Bool_t ok;
+  Int_t ival;  
+  header->Get("RunInfo/Run Number", ival, ok);
+  if (ok)
+    cout << endl << "Run Number: " << ival;
+  else
+    cout << endl << "**ERROR** Couldn't obtain the 'Run Number'.";
+    
+Reading a ``TMusrRunPhysicalQuantity`` object, *e.g.* the sample temperature looks like this 
+
+.. code-block:: c++
+
+  TMusrRunPhysicalQuantity prop;
+
+  header->Get("RunInfo/Sample Temperature", prop, ok);
+  if (ok) {
+    cout << endl << "Sample Temperature: " << prop.GetValue() << " +- ";
+    cout << prop.GetError() << " " << prop.GetUnit().Data();
+    cout << "; SP: " << prop.GetDemand() << "; " << prop.GetDescription().Data();
+  } else {
+    cout << endl << "**ERROR** Couldn't obtain the 'Sample Temperature'.";
+  }
+
+.. index:: MusrRoot-Validation
+.. _musr-root-validation:
+
+Validation of a MusrRoot File 
++++++++++++++++++++++++++++++
+
+Since ``MusrRoot`` is an open and extensible file format a mechanism is needed to validate that a given file is indeed holding the minimum of required entries. To check this the following scheme is implemented in the program ``musrRootValidation``:
+
+.. image:: ../images/MusrRootValidationScheme.*
+
+``MusrRoot`` validation scheme
+
+In the following this validation scheme will be discussed as it is implemented in ``musrRootValidation``: 
+
+#. It is checked if the given file name is a ``TFile``
+#. The file structure is recursively parsed and mapped into an temporary XML file. XML is used 
+   since there are ample of parser and validation frameworks at hand. For details check any decent 
+   book about XML. Here the ``libxml2`` is used, because also ROOT is requiring it.
+#. In a next step the XML file (holding the structure of the supposed ``MusrRoot`` file is validated 
+   against a XML schema. The minimum of required entries is described by ``MusrRoot.xsd`` which is 
+   part of ``musrfit`` but also available from the PSI/LMU web-page.
+#. If the schema validation is successful additional semantic checks (like is the number of decay 
+   histograms the same as the number of detector entries, etc.) will be preformed. 
+
+This validation scheme is useful for people which define instrument specific extensions of the base ``MusrRoot``, as for instance the LEM instrument at PSI. It is also useful for people writing file converters in order to cross check if the generated file is valid.    
+   
+.. _run-info-required:
+
+RunInfo (Required)
+------------------
+
+========================== ============================= =====================================================
+Name                       Internal Type                 Comment
+========================== ============================= =====================================================
+Version                    ``TString``                   GIT version of ``TMusrRunHeader``
+Generic Validator URL      ``TString``                   URL of the generic ``MusrRoot`` validation xsd-file. 
+                                                         *e.g.* `<http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRoot.xsd>`_
+Specific Validator URL     ``TString``                   URL of the instrument specific validation xsd-file.
+                                                         *e.g.* for LEM: `<http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRootLEM.xsd>`_
+Generator                  ``TString``                   Program which wrote the ``MusrRoot`` file, *e.g.* ``nemu_analyzer``
+File Name                  ``TString``                   File name of the ``MusrRoot`` file, *e.g.* ``deltat_tdc_gps_4295.root``
+Run Title                  ``TString``
+Run Number                 ``Int_t``
+Run Start Time             ``TString``                   ISO 8601 date time
+Run Stop Time              ``TString``                   ISO 8601 date time
+Run Duration               ``TMusrRunPhysicalQuantity``  run duration in sec 
+Laboratory                 ``TString``                   *e.g.* PSI
+Instrument                 ``TString``                   *e.g.* GPS
+Muon Beam Momentum         ``TMusrRunPhysicalQuantity``  *e.g.* 28.1 MeV/c
+Muon Species               ``TString``                   poitive or negative muon
+Muon Source                ``TString``                   *e.g.* "Target E - Low Energy Muons" or "Target M" ...
+Setup                      ``TString``                  
+Comment                    ``TString``
+Sample Name                ``TString``
+Sample Temperature         ``TMusrRunPhysicalQuantity``  *e.g.* 3.21 +- 0.05 K; SP: 3.2; CF1 
+Sample Magnetic Field      ``TMusrRunPhysicalQuantity``  *e.g.* 350.002 +- 0.005 G; SP: 350; WEW 
+No of Histos               ``Int_t``
+Time Resolution            ``TMusrRunPhysicalQuantity``  *e.g.* 0.1953125 ns
+RedGreen Offsets           ``TIntVector``                *e.g.* 0; 20 
+========================== ============================= =====================================================
+
+.. _detector-info-required:
+
+DetectorInfo (Required)
+-----------------------
+
+The ``DetectorInfo`` is organized in a sub-tree like
+
+::
+
+  DetectorInfo ---|
+                  |- Detector001
+                  |- Detector002
+                  ...
+
+
+
+For each histogram in the ``histos/DecayAnaModule`` corresponds detector entry here.
+
+The numbering of the detectors has to correspond the its histogram, *e.g.* ``hDecay023 <=> Detector023``, *i.e.* potentially discontinuous to show red / green breaks.
+
+``Detector<XXX>`` has the elements 
+
+========================== ============================= =====================================================
+Name                       Internal Type                 Comment
+========================== ============================= =====================================================
+Name                       ``TString``                   detector name, *e.g.* Left-NPP
+Histo Number               ``Int_t``                     histogram number. This number corresponds to the histogram 
+                                                         number in the ``histos/DecayAnaModule`` sub-tree.
+Histo Length               ``Int_t``                     length of the histogram (in bins)
+Time Zero Bin              ``Double_t``                  The type is ``Double_t`` since for the high-field spectrometer 
+                                                         at PSI an ``Int_t`` representation would be not good enough.  
+First Good Bin             ``Int_t``
+Last Good Bin              ``Int_t``
+========================== ============================= =====================================================
+
+.. _sample-environment-info-required:
+
+SampleEnvironmentInfo (Required)
+--------------------------------
+
+Here only a single entry is required, namely 
+
+========================== ============================= =====================================================
+Name                       Internal Type                 Comment
+========================== ============================= =====================================================
+Cryo                       ``TString``                   name of the used cryostat/oven, *e.g.* ``Konti-2`` 
+========================== ============================= =====================================================
+
+.. _magnetic-field-environment-info-required:
+
+MagneticFieldEnvironmentInfo (Required)
+---------------------------------------
+
+Here only a single entry is required, namely 
+
+========================== ============================= =====================================================
+Name                       Internal Type                 Comment
+========================== ============================= =====================================================
+Magnet Name                ``TString``                   name of the used magnet, *e.g.* ``WEW``. 
+                                                         In case of ZF measurements, there might be an entry like ZF. 
+========================== ============================= =====================================================
+
+.. _beamline-info-required:
+
+BeamlineInfo (Required)
+-----------------------
+
+Here only a single entry is required, namely 
+
+========================== ============================= =====================================================
+Name                       Internal Type                 Comment
+========================== ============================= =====================================================
+Name                       ``TString``                   name of the beamline, *e.g.* ``piM3.2``
+========================== ============================= =====================================================
+
+Exhaustive MusrRoot Tree Including Everything Required
+------------------------------------------------------
+
+Here it is assumed that there are hypothetical *red / green data* with electric field on/off and light on/off, 
+and hence 4 data sets per detector, and 8 detectors of the instrument: ``left/forward``, ``top/forward``, ``right/forward``, 
+``bottom/forward``, ``left/backward``, ``top/backward``, ``right/backward``, ``bottom/backward``. To show the whole 
+tree structure, it will be split in the representation afterwards, but keep in mind: this will be all part of a 
+single ``MusrRoot`` file. I will add comments in the tree structure by the symbol ``#``. Lets start with the |mgr|\SR data histograms: 
+
+::
+
+  histos -|
+          |- DecayAnaModule -|
+                             |- hDecay001 # left/forward, electric field off, light off
+                             |- hDecay002 # top/forward, electric field off, light off
+                             |- hDecay003 # right/forward, electric field off, light off
+                             |- hDecay004 # bottom/forward, electric field off, light off
+                             ...
+                             |- hDecay007 # right/backward, electric field off, light off
+                             |- hDecay008 # bottom/backward, electric field off, light off
+                             |- hDecay011 # left/forward, electric field on, light off
+                             |- hDecay012 # top/forward, electric field on, light off
+                             |- hDecay013 # right/forward, electric field on, light off
+                             |- hDecay014 # bottom/forward, electric field on, light off
+                             ...
+                             |- hDecay017 # right/backward, electric field on, light off
+                             |- hDecay018 # bottom/backward, electric field on, light off
+                             |- hDecay021 # left/forward, electric field off, light on
+                             |- hDecay022 # top/forward, electric field off, light on
+                             |- hDecay023 # right/forward, electric field off, light on
+                             |- hDecay024 # bottom/forward, electric field off, light on
+                             ...
+                             |- hDecay027 # right/backward, electric field off, light on
+                             |- hDecay028 # bottom/backward, electric field off, light on
+                             |- hDecay031 # left/forward, electric field on, light on
+                             |- hDecay032 # top/forward, electric field on, light on
+                             |- hDecay033 # right/forward, electric field on, light on
+                             |- hDecay034 # bottom/forward, electric field on, light on
+                             ...
+                             |- hDecay037 # right/backward, electric field on, light on
+                             |- hDecay038 # bottom/backward, electric field on, light on
+                             ...
+
+*Comments*: as can be seen the histograms are continuous numbered until there is a red / green mode switch where 
+the histogram number "jumps" (*e.g.* from ``008`` to ``011``). In order to fill in the different red / green 
+histograms an offset is added (here 10, 20, and 30).                              
+
+Next the whole ``RunHeader``. Here the information will be grouped in different folders collecting related information, 
+like general run info, detector info, sample and magnetic field environment info, beamline info, etc.
+
+::
+
+  RunInfo:
+    000 - Version: $Id: TMusrRunHeader.cpp 5092 2012-03-13 07:47:00Z nemu $ -@0
+    001 - Generic Validator URL: http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRoot.xsd -@0
+    002 - Specific Validator URL: http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRootLEM.xsd -@0
+    003 - Generator: nemu_analyzer -@0
+    004 - File Name: lem12_his_0234.root -@0
+    005 - Run Title: here comes the run title -@0
+    006 - Run Number: 234 -@1
+    007 - Run Start Time: 2012-04-19 14:25:22 -@0
+    008 - Run Stop Time: 2012-04-19 19:13:47 -@0
+    009 - Run Duration: 17305 sec -@3
+    010 - Laboratory: PSI -@0
+    011 - Instrument: LEM -@0
+    012 - Muon Beam Momentum: 28.1 MeV/c -@3
+    013 - Muon Species: positive muon -@0
+    014 - Muon Source: target E -@0
+    015 - Setup: a very special setup -@0
+    016 - Comment: nothing more to be said -@0
+    017 - Sample Name: the best ever -@0
+    018 - Sample Temperature: 3.21 +- 0.05 K; SP: 3.2 -@3
+    019 - Sample Magnetic Field: 350.002 +- 0.005 G; SP: 350 -@3
+    020 - No of Histos: 8 -@1
+    021 - Time Resolution: 0.1953125 ns;  TDC 9999 -@3
+    022 - RedGreen Offsets: 0; 10; 20; 30
+  DetectorInfo:
+    Detector001:
+      023 - Name: Left/Forward - electric field off, light off -@0
+      024 - Histo Number: 1 -@1
+      025 - Histo Length: 66661 -@1
+      026 - Time Zero Bin: 3419.000000 -@2
+      027 - First Good Bin: 3419 -@1
+      028 - Last Good Bin: 66661 -@1
+    Detector002:
+      029 - Name: Top/Forward - electric field off, light off -@0
+      030 - Histo Number: 2 -@1
+      031 - Histo Length: 66661 -@1
+      032 - Time Zero Bin: 3419.000000 -@2
+      033 - First Good Bin: 3419 -@1
+      034 - Last Good Bin: 66661 -@1
+
+    ...
+
+    Detector038:
+      213 - Name: Bottom/Backward - electric field on, light on -@0
+      214 - Histo Number: 38 -@1
+      215 - Histo Length: 66661 -@1
+      216 - Time Zero Bin: 3419.000000 -@2
+      217 - First Good Bin: 3419 -@1
+      218 - Last Good Bin: 66661 -@1
+
+  SampleEnvironmentInfo:
+    219 - Cryo: Konti-1 -@0
+    220 - Insert: X123 -@0
+    221 - Orientation: c-axis perp spin, perp field. spin perp field -@0
+  MagneticFieldEnvironmentInfo:
+    222 - Magnet Name: WEW -@0
+    223 - Current: 17.34 A -@3
+  BeamlineInfo:
+    224 - Name: muE4 -@0
+  ScalerInfo:
+    225 - Ip: 12332123 -@1
+  RunSummary:
+    0000 - Wed Oct  5 01:30:37 2011 Run 2856 started.
+    0001 - Wed Oct  5 02:02:51 2011 Run 2856 stopped.
+    0002 - 
+    0003 - LCO, T=170.02(K), wTF ~30(G)/5.18(A), Tr/Sa=15.02/8.50(kV), E=5.63(keV), LEDb off, BP off
+    0004 - =========================================================================================
+    0005 - 
+    0006 - #BUC---- B e g i n of User Comment ------ Do not edit this line
+    0007 - #EUC----   E n d   of User Comment ------ Do not edit this line
+    0008 - 
+    0009 - ======================   E v e n t  definition   =========================
+    0010 -
+    0011 - Events: 
+    0012 - Event_0: (BC)-MCP1-(e+); Event_1:( BC)-TD-MCP2-(e+); Event_2: LEmuSR, (BC)-TD-e 
+    ...
+
+
+
+*Comment*: the last sub-tree ``RunSummary`` is not following ``TMusrRunHeader`` rule ``<number> - <label>: <value> -@<type>``. 
+It is added in the instrument analyzer directly by other means than the ``TMusrRunHeader::Set``-method. This is no problem! 
+Since ``RunSummary`` is not part of the required ``MusrRoot``-file. One is quite free in adding any ROOT based information here. 
+                             
+.. index:: MusrRoot-TMusrRunPhysicalQuantity
+.. _musr-run-physical-quantity:
+
+TMusrRunPhysicalQuantity - Possible Representations 
+---------------------------------------------------
+
+A physical property can be described as 
+
+::
+
+  <property name>: <value> +- <estimated error> <unit>; SP: <demand>; <description>
+  
+where ``<property name>`` is the name of the quantity, *e.g.* Sample Temperature, ``<value>`` the value 
+of the quantity, ``<estimated error>`` the error estimate, *e.g.* the standard deviation, ``<unit>`` the unit, 
+*e.g.* K, ``<demand>`` a demand value, *e.g.* the set point of the temperature. ``<description>`` is a 
+possible additional comment for this quantity.
+
+.. note:: 
+
+  Not *all* of these quantities are always needed. The list of handled combination are given 
+  hereafter together with the ``C++`` code snipped how to set it. It is assumed that ``TMusrRunPhysicalQuantity prop;`` 
+  is somewhere defined.
+  
+**Possibility 1**
+
+:: 
+
+  <property name>: <value> <unit> [; <description>]
+  
+Code snippet: 
+
+.. code-block:: c++
+
+  prop.Set("Muon Beam Momentum", 28.1, "MeV/c");
+  header->Set("RunInfo/Muon Beam Momentum", prop);
+
+  prop.Set("Time Resolution", 0.1953125, "ns", "TDC 9999");
+  header->Set("RunInfo/Time Resolution", prop);
+  
+Result in the ``RunHeader/RunInfo``:   
+
+::
+
+  011 - Muon Beam Momentum: 28.1 MeV/c -@3
+  013 - Time Resolution: 0.1953125 ns; TDC 9999 -@3
+  
+The number on front of the token (*e.g.* ``011`` in front of Muon Beam Momentum) will depend on the position where 
+the entry has been added. The last token, ``-@3``, is the encoding of the type: here ``TMusrRunPhysicalQuantity``.   
+
+**Possibility 2**
+
+::
+
+  <property name>: <val> +- <err> <unit>[; <description>]
+  
+Code snippet:   
+  
+.. code-block:: c++
+  
+  prop.Set("CF3", MRH_UNDEFINED, 3.27, 0.09, "K", "strange temperature");
+  header->Set("SampleEnvironmentInfo/CF3", prop);
+  
+Result in the ``RunHeader/SampleEnvironmentInfo``:   
+
+::
+ 
+  033 - CF3: 3.27 +- 0.09 K; strange temperature -@3 
+  
+**Possibility 3**
+
+::
+
+  <property name>: <val> <unit>; SP: <demand>[; <description>]
+    
+Code snippet:
+
+.. code-block:: c++
+
+  prop.Set("CF4", 3.25, 3.28, "K");
+  header->Set("SampleEnvironmentInfo/CF4", prop);
+
+  prop.Set("CF5", 3.26, 3.29, "K", "another strange temperature");
+  header->Set("SampleEnvironmentInfo/CF5", prop);
+  
+Result in the ``RunHeader/SampleEnvironmentInfo``:   
+
+::
+
+  034 - CF4: 3.28 K; SP: 3.25 -@3
+  035 - CF5: 3.29 K; SP: 3.26; another strange temperature -@3
+  
+**Possibility 4**
+
+::
+
+  <property name>: <value> +- <estimated error> <unit>; SP: <demand>; <description>
+    
+Code snippet:
+
+.. code-block:: c++
+  
+  prop.Set("Sample Magnetic Field", 350.0, 350.002, 0.005, "G", "WXY");
+  header->Set("RunInfo/Sample Magnetic Field", prop);
+  
+Result in the ``RunHeader/SampleEnvironmentInfo``:  
+
+::
+
+  017 - Sample Magnetic Field: 350.002 +- 0.005 G; SP: 350.0; WXY -@3

doc/html/_sources/musredit.rst.txt

@@ -0,0 +1,523 @@
+.. include:: <isogrk1.txt>
+.. index:: musredit
+
+.. _musredit-sec:
+
+``musredit``: the GUI Based Interface to ``musrfit``
+====================================================
+
+Introduction
+------------
+
+.. _Qt: https://qt.io
+
+``musredit`` is an editor which also provide a graphical user interface to the programs contained in the ``musrfit`` suite and are intended 
+to help the user handle ``musrfit`` msr files. It is implemented in ``C++`` and use the `Qt`_ framework. ``musredit`` is based on Qt 4.6, Qt 5.6 (or above), or Qt6.x. 
+The Qt 5.6 and Qt 6.x version of ``musredit`` will be actively developed, whereas the Qt 4.x version will only get bug fixing and eventually will be dropped.
+On this documentation page only the features related to ``musrfit`` are described — the basic editor functions which should be self-explanatory are *not*.
+``musrgui`` is an outdated early version of ``musredit`` and will not described anymore. If still in use, the user is urged to switch to ``musredit``.
+
+.. note::
+
+  Before going on using ``musredit`` it is strongly recommended to read the :ref:`manual of musrfit <user-manual>` first!
+  
+Available Executable, Configuration Files and their Basic Usage
+----------------------------------------------------------------
+
+musredit (musrgui)
+++++++++++++++++++
+
+``musredit`` (``musrgui``) is the editor executable. If called from within a shell it accepts a few optional parameters: 
+
+**<msr-files>**
+  File names of the msr files that should be opened in separate editor tabs on startup of ``musredit``. 
+**- -help**
+  Displays a small help notice in the shell explaining the basic usage of the program. 
+**- -version**
+  Prints the version number of ``musredit``. 
+
+If called without any parameters an empty editor window opens.
+
+.. index:: musredit_startup
+
+musredit_startup.xml
+++++++++++++++++++++
+
+``musredit_startup.xml`` is the configuration file located under ``$HOME\.musrfit\musredit``. It is also possible to have another version 
+of this file in the working directory which then will be used!
+
+In this file the following ``XML`` tags are allowed to define settings and might proof useful for all users of ``musredit``: 
+
+**<general></general>**
+  set the default paths to executable and files in this environment 
+  
+  **<exec_path>PATH_TO_EXEC</exec_path>**
+    set the path ``PATH_TO_EXEC`` where the executable ``musrfit``, ``musrview``, ``musrt0``, etc. can be found (inside the ``<general>`` environment) 
+  **<default_save_path>SAVE_PATH</default_save_path>**
+    specify the path ``SAVE_PATH`` where ``musredit`` point by default when opening and saving msr files (inside the ``<general>`` environment). Default is the current directory. 
+  **<msr_default_file_path>MSR_DEF_PATH</msr_default_file_path>**
+    set the path ``MSR_DEF_PATH`` where the default msr files provided by ``musredit`` are stored (inside the ``<general>`` environment) 
+  **<timeout>3600</timeout>**
+    timeout in seconds after which :ref:`musrview <musrview>` canvas will automatically quit. A value of 0 or 
+    a negative number will keep the ``musrview`` canvas open without self-determination.
+  **<keep_minuit2_output>y/n</keep_minuit2_output>**
+    flag indicating if the ``MINUIT2`` output shall be kept per msr-file ('y') or only for the current msr-file ('n'). 
+  **<dump_ascii>y/n</dump_ascii>**
+    flag indicating if ``musrfit`` shall dump fit data into ascii format. See help of :ref:`musrfit <musrfit>`.
+  **<dump_root>y/n</dump_root>**
+    flag indicating if ``musrfit`` shall dump fit data into root format. See help of :ref:`musrfit <musrfit>`.
+  **<title_from_data_file>y/n</title_from_data_file>**
+    specify if ``musrfit`` should be called with the ``-t`` option by default (inside the ``<general>`` environment) 
+  **<chisq_pre_run_block>y/n</chisq_pre_run_block>**
+    flag indicating if per-run chisq shall be written into the msr-output-file. 
+  **<estimate_n0>y/n</estimate_n0>** 
+    flag indicating if for a single histogram fit :math:`N_0` shall be estimated before the fit procedure starts. 
+  **<musrview_show_fourier>y/n</musrview_show_fourier>**
+    flag indicating if ``musrview`` will directly present the Fourier transform rather than the time domain data. 
+  **<musrview_show_avg>y/n</musrview_show_avg>**
+    flag indicating if ``musrview`` will directly present averaged data, typically used for Fourier power spectra. 
+  **<enable_musrt0>y/n</enable_musrt0>**
+    specify if :ref:`musrt0 <musrt0>` can be called from within ``musredit`` (inside the ``<general>`` environment) 
+    
+**<font_settings></font_settings>**
+  set the default font in this environment 
+    
+  **<font_name>FONT</font_name>**
+    specify the name of the font ``FONT`` to be used by default in ``musredit`` (inside the ``<font_settings>`` environment) 
+  **<font_size>N</font_size>**
+    specify the size ``N`` of the font to be used by default in ``musredit`` (inside the ``<font_settings>`` environment)
+    
+**<msr_file_defaults></msr_file_defaults>**
+  put the default settings for newly created msr files in this environment
+
+  **<beamline>BL</beamline>**
+    set the name of the muon beamline ``BL`` here (inside a ``<msr_file_defaults>`` environment) 
+  **<institute>INST</institute>**
+    set the name of the facility ``INST`` where the beamline ``BL`` is located. Valid settings are ``PSI``, ``RAL``, ``JPARC``, and ``TRIUMF`` (inside a ``<msr_file_defaults>`` environment) 
+  **<file_format>FF</file_format>**
+    specify the default data file format ``FF`` here. Valid formats are ``NEXUS``, ``MUSR-ROOT``, ``ROOT-NPP``, ``ROOT-PPC``, ``PSI-BIN``, ``PSI-MDU``, ``MDU-ASCII``, ``WKM``, ``MUD``, ``ASCII``, and ``DB`` (inside a ``<msr_file_defaults>`` environment) 
+  **<lifetime_correction>y/n</lifetime_correction>**
+    choose if by default the ``lifetimecorrection`` option should be set (inside a ``<msr_file_defaults>`` environment) 
+
+**<msr2data_defaults></msr2data_defaults>**
+  define the default options for calling :ref:`msr2data <msr2data>` in this environment; the options set here are ticked by default in the graphical interface of ``musredit``.     
+  
+  **<chain_fit>y/n</chain_fit>**
+    (un)set the chain fit (!) option (inside a ``<msr2data_defaults>`` environment) 
+  **<write_data_header>y/n</write_data_header>**
+    (un)set the noheader option (inside a ``<msr2data_defaults>`` environment) 
+  **<ignore_data_header_info>y/n</ignore_data_header_info>**
+    (un)set the nosummary option (inside a ``<msr2data_defaults>`` environment) 
+  **<keep_minuit2_output>y/n</keep_minuit2_output>**
+    (un)set the ``-k`` option (inside a ``<msr2data_defaults>`` environment) 
+  **<write_column_data>y/n</write_column_data>**
+    (un)set the ``data`` option (inside a ``<msr2data_defaults>`` environment) 
+  **<create_msr_file_only>y/n</create_msr_file_only>**
+    (un)set the ``msr`` option in case a template run is specified (inside a ``<msr2data_defaults>`` environment) 
+  **<fit_only>y/n</fit_only>**
+    (un)set the ``fit`` option in case no template run is specified (inside a ``<msr2data_defaults>`` environment) 
+  **<global>y/n</global>**
+    (un)set the ``global`` option (inside a ``<msr2data_defaults>`` environment) 
+  **<global_plus>y/n</global_plus>**
+    (un)set the ``global+`` option (inside a ``<msr2data_defaults>`` environment) 
+  **<recreate_data_file>y/n</recreate_data_file>**
+    (un)set the ``musredit`` option for recreating the output file (inside a ``<msr2data_defaults>`` environment) 
+  **<open_file_after_fitting>y/n</open_file_after_fitting>**
+    (un)set the ``musredit`` option for opening msr files after fitting (inside a ``<msr2data_defaults>`` environment)
+    
+Additionally, there are some settings defined in this XML file which should be only changed by experienced users who like to add new features to ``musredit``:     
+
+**<help_section></help_section>**
+  define various help messages in this environment
+
+  **<musr_web_X>LINK</musr_web_X>**
+    define the ``LINK`` to the help page ``musr_web_X``, where ``X`` is ``main``, ``title``, ``parameters``, ``theory``, ``functions``, ``run``, 
+    ``command``, ``fourier``, ``plot``, ``statistics``, ``msr2data``, or ``musrFT`` (inside a ``<help_section>`` environment) 
+
+**<func_pixmap_path>PIX_PATH</func_pixmap_path>**
+  set the path ``PIX_PATH`` to LaTeX pixmaps visualizing the various supported theory functions 
+  
+**<theory_functions></theory_functions>**
+  define the functions for a msr file's :ref:`THEORY block <msr-theory-block>` according to the correct syntax in this environment   
+  
+  **<func></func>** 
+    specify a function here (inside a ``<theory_functions>`` environment) 
+    
+    **<name>NAME</name>**
+      the ``NAME`` of the function in the msr file (inside a ``<func>`` environment) 
+    **<comment>COMMENT</comment>**
+      description of the used parameters (inside a ``<func>`` environment) 
+    **<label>LABEL</label>**
+      ``LABEL`` of the function in the ``musredit`` menu (inside a ``<func>`` environment) 
+    **<pixmap>PIXMAP</pixmap>**
+      LaTeX picture used to describe the function and stored in the ``PIX_PATH`` (inside a ``<func>`` environment) 
+    **<params>N</params>**
+      number of parameters ``N`` used by the function (inside a ``<func>`` environment) 
+      
+An example of the ``musredit_startup.xml`` looks like:    
+
+.. code-block:: xml
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <musredit_startup xmlns="http://lmu.web.psi.ch/musrfit/user/MUSR/MusrGui.html">
+    <comment>
+      This is handling default setting parameters for the musredit.
+    </comment>
+    <general>
+      <exec_path>/usr/local/root/bin</exec_path>
+      <default_save_path>./</default_save_path>
+      <msr_default_file_path>/usr/local/root/share/doc/musrfit/templates</msr_default_file_path>
+      <timeout>3600</timeout>
+      <keep_minuit2_output>n</keep_minuit2_output>
+      <dump_ascii>n</dump_ascii>
+      <dump_root>n</dump_root>
+      <title_from_data_file>y</title_from_data_file>
+      <chisq_per_run_block>n</chisq_per_run_block>
+      <estimate_n0>y</estimate_n0>
+      <musrview_show_fourier>n</musrview_show_fourier>
+      <musrview_show_avg>n</musrview_show_avg>
+      <enable_musrt0>y</enable_musrt0>
+    </general>
+    <recent_files>
+      <path_file_name>/usr/local/root/share/doc/musrfit/examples/test-histo-PSI-BIN.msr</path_file_name>
+    </recent_files>
+    <help_section>
+      <musr_web_main>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html</musr_web_main>
+      <musr_web_title>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheTitle</musr_web_title>
+      <musr_web_parameters>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheFitparameterBlock</musr_web_parameters>
+      <musr_web_theory>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheTheoryBlock</musr_web_theory>
+      <musr_web_functions>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheFunctionsBlock</musr_web_functions>
+      <musr_web_run>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheRunBlock</musr_web_run>
+      <musr_web_command>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheCommandsBlock</musr_web_command>
+      <musr_web_fourier>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheFourierBlock</musr_web_fourier>
+      <musr_web_plot>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#ThePlotBlock</musr_web_plot>
+      <musr_web_statistic>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#TheStatisticBlock</musr_web_statistic>
+      <musr_web_msr2data>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/Msr2Data.html</musr_web_msr2data>
+      <musr_web_musrFT>file:///usr/local/root/share/doc/musrfit/html/user/MUSR/MusrFit.html#A_2.3_musrFT</musr_web_musrFT>
+    </help_section>
+    <font_settings>
+      <font_name>Monospace</font_name>
+      <font_size>12</font_size>
+    </font_settings>
+    <msr_file_defaults>
+      <beamline>mue4</beamline>
+      <institute>psi</institute>
+      <file_format>musr-root</file_format>
+      <lifetime_correction>y</lifetime_correction>
+    </msr_file_defaults>
+    <msr2data_defaults>
+      <chain_fit>y</chain_fit>
+      <write_data_header>y</write_data_header>
+      <ignore_data_header_info>n</ignore_data_header_info>
+      <keep_minuit2_output>n</keep_minuit2_output>
+      <write_column_data>n</write_column_data>
+      <recreate_data_file>n</recreate_data_file>
+      <open_file_after_fitting>y</open_file_after_fitting>
+      <create_msr_file_only>n</create_msr_file_only>
+      <fit_only>n</fit_only>
+      <global>n</global>
+      <global_plus>n</global_plus>
+    </msr2data_defaults>
+    <func_pixmap_path>/usr/local/root/share/doc/musrfit/latex_images</func_pixmap_path>
+    <theory_functions>
+      <func>
+        <name>asymmetry</name>
+        <comment></comment>
+        <label>Asymmetry</label>
+        <pixmap>asymmetry.png</pixmap>
+        <params>1</params>
+      </func>
+      <func>
+        <name>statGssKT</name>
+        <comment>(rate)</comment>
+        <label>static Gauss KT</label>
+        <pixmap>statGssKT.png</pixmap>
+        <params>1</params>
+      </func>
+    </theory_functions>
+  </musredit_startup>
+  
+.. index:: musredit-features
+
+musredit Features
+-----------------
+
+The features of ``musrfit`` which can be accessed by the graphical front ends ``musredit`` will be described in the following. All functions 
+can either be called by choosing them from the *MusrFit menu*, by clicking the respective button in the *MusrFit bar*, or by using a *keyboard shortcut*. 
+
+**musrWiz**
+
+  .. image:: ../images/musrWiz.* 
+
+  ``musrWiz`` is a helper programs which allows to create a msr-file from scratch without too much a priori knowledge. For details see :ref:`musrWiz <musrWiz>`. 
+
+.. index:: musrWiz
+.. _musrWiz:
+
+**Calculate Chisq**
+
+  .. image:: ../images/musrchisq.*
+
+  Calls ``musrfit`` with the option ``-c``, *i.e.* calculates the :math:`\chi^2` or log max-likelihood for the active msr file tab. Shortcut-key: ``Alt+C``.
+  The equivalent call on the command line would be
+
+  .. code-block:: bash
+
+    $ musrfit -c <msr-file>
+
+**Fit**    
+  
+  .. image:: ../images/musrfit.*
+  
+  Calls ``musrfit`` for fitting of the active msr file in the currently active tab. Shortcut-key: ``Alt+F``.
+  The equivalent call on the command line could look like
+  
+  .. code-block:: bash
+  
+    $ musrfit <msr-file> [optional parameters]
+    
+  The optional parameters may be chosen under :ref:`Preferences <musredit-prefs>`. For further information refer to the manual of :ref:`musrfit <user-manual>`. 
+
+**Swap Msr <-> Mlog**
+
+  .. image:: ../images/musrswap.*
+  
+  Swap the msr and mlog files. *E.g.*, for a file called ``8472_zf.msr``, this is copied to ``8472_zf.mlog`` and vice versa. Shortcut-key: ``Alt+S``.
+  
+**Set Steps**
+
+  .. image:: ../images/musrStep.*
+  
+  ``musrStep`` allows to adjust the step size, *i.e.* the initial steps for the fitter. Shortcut-key: ``Alt+P``.
+  
+**Msr2Data**
+
+  .. image:: ../images/msr2data.*
+  
+  Opens a graphical interface to the ``msr2data`` program described in detail in its :ref:`own manual <msr2data>`. Shortcut-key: ``Alt+2``.
+  
+**mupp**
+
+  .. image:: ../images/mupp.*
+  
+  Application which allows to plot ``*.db`` and ``*.dat`` parameter files. Shortcut-key: ``Alt+U``.
+  For a detailed description see the :ref:`mupp docu <mupp>`.
+
+**View2Dat**
+
+  .. image:: ../images/musrview2dat.*
+  
+  Used to export the data of a collection of msr-files. Essentially the same as calling ``musrview`` and selecting ``Export Data``, but
+  all in the background, with the option to feed a collection of msr-files, rather than going through this process one after the other.
+  Why you might want to do that? You might want to use another plotting program (not ROOT) to present your data.
+  
+**View**
+
+  .. image:: ../images/musrview.*
+  
+  Calls ``musrview`` from the active tab of ``musredit``. For more details see the :ref:`musrview <musrview>` docu. Shortcut-key: ``Alt+V``.
+  The equivalent call on the command line could look like
+  
+  .. code-block:: bash
+  
+    $ musrview <msr-file> [optional parameters]
+    
+**T0**
+
+  .. image:: ../images/musrt0-icon.*
+  
+  Calls ``musrt0`` which allows to set the ``T0`` values for all the runs. For more details see the :ref:`musrt0 <musrt0>` docu.
+  The equivalent call on the command line could look like
+  
+  .. code-block:: bash
+  
+    $ musrt0 <msr-file> [optional parameters]
+    
+**Raw Fourier**
+
+  .. image:: ../images/musrFT.*
+  
+  Calls ``musrFT`` which allows to perform a Fourier transform of the raw data. For more details see the :ref:`musrFT <musrFT>` docu. 
+  The equivalent call on the command line could look like
+  
+  .. code-block:: bash
+
+    $ musrFT <msr-file> [optional parameters]
+
+.. _musredit-prefs:  
+  
+**Preferences**
+
+  .. image:: ../images/musrprefs.*
+
+  Opens a window in which the optional parameters that should be passed to musrfit can be chosen.
+  For further information refer to the manual of :ref:`musrfit <musrfit>`. 
+  
+**Dump Header**
+
+  .. image:: ../images/musrdump.*
+  
+  Opens a file dialog which allows to select a |mgr|\SR data file. When this file can be read, the run header info is dumped into a dialog window. 
+  Essentially this calls ``dump_header`` internally. 
+  
+musrWiz
+-------
+
+``musrWiz`` is a helper program which allows to easily create the necessary msr-file needed as an input for ``musrfit``. 
+``musrWiz`` is still in it's early stage; not all options are already implemented and here and there you will likely find some bugs. 
+From ``musredit`` it can be accessed via the MusrFit menu or the wand 
+
+.. image:: ../images/musredit-musrWiz.*
+
+The ``musrWiz`` GUI is organized in a couple of different dialogues which some information needs to be provided by the user. 
+In the following these different dialogues will be discussed briefly. 
+
+.. index:: musrWiz-Introduction
+
+musrWiz-Introduction
+++++++++++++++++++++
+
+The introduction dialogue 
+
+.. image:: ../images/musrWiz-Intro.*
+
+#. an explicit msr-file name can be provided here. More often the msr-file name is generated out of the run number.
+#. year of the run data.
+#. run number. If no explicit msr-file is provided, the run number together with fit type and type of measurement will be used to generate the msr-file name.
+#. from the pull down menu the institute (for which a necessary ``xml``-file is provided) has to be choosen.
+#. from the pull down menu the the instrument can be chosen.
+#. the fit type has to be chosen. Possible fit types are: ``Single Histo`` / ``Single Histo RRF`` / ``Asymmetry`` / ``Asymmetry RRF`` / ``Mu Minus`` / ``None muSR``
+#. type of measurement is essentially needed for the grouping of the detectors. Possible are: ``ZF`` for zero field measurements / ``TF`` for transverse field measurements / ``LF`` for longitudinal field measurements. 
+   Depending on the choice and instrument some additional question might be asked, *e.g.* which magnet has been used.
+#. ``T0``'s: this last menu defines from where to get the t0's. The options are: ``from data file``, *i.e.* the t0 are assumed to be correctly set 
+   in the provided data file ``call musrT0``, *i.e.* after the msr-file is generated, ``musrt0`` will be called which allows the user to find the 
+   proper t0 from the prompt peak ``enter here`` will provide a pop-up menu where the t0 parameter can be given explicitly. 
+   
+If all this information have been provided ``Next>`` will lead you the the theory dialogue.   
+
+.. index:: musrWiz-Theory
+
+musrWiz - Theory
+++++++++++++++++
+
+The theory dialogue is used to define the fitting function. There are two ways of using it:
+
+#. choose a template theory function. This option has the advantage that the next steps will be very easy because 
+   within the template almost everything is already pre-defined. The disadvantage is that you are not free in setting 
+   up your theory function as you would like to have.
+#. freely write your theory function. The advantage here is that you can customize your theory function at your needs. 
+   This will come at the cost that you also will need to define ``maps``, ``functions``, etc. yourself. The good thing    
+   though is that at the very end you can save this as a template for future re-use. 
+
+First the template path will be described. The theory dialogue looks like this
+
+.. image:: ../images/musrWiz-Theory.*
+
+#. This is a text edit field were you can enter the theory fit function as you would like to have it. In the example 
+   given the theory reads :math:`p1 \exp(-p2\, t) \cos(2 \pi\, f1 + m1)`, where ``pX`` stands for parameter, ``fX`` for function, 
+   ``mX`` for map, and ``X`` for the corresponding number.
+#. The ``Clear All`` button will clear whatever you entered in the text field above.
+#. This pull-down menu allows to select a theory function which will be added to the text field above by pressing 
+   the ``Add`` button. Pre defined theory function starting with a ``T`` are templates rather than only theory function strings.
+#. The ``Add`` button is used to add the chosen theory function / template from the pull-down menu to its left.
+#. The ``Check`` button is used to make a syntactical check of whatever is written in the text edit field. 
+
+.. index:: musrWiz-Functions
+
+musrWiz - Functions
++++++++++++++++++++
+
+In the Functions dialogue all the necessary functions can be entered. A function operates *only* on fitting parameters. 
+This is different to the theory function which operates on the fitting parameters and the time. The dialogue looks like this 
+
+.. image:: ../images/musrWiz-Functions.*
+
+
+#. a text edit field in which the various needed functions can be entered. In case a template theory is used, the appropriate function should be shown here and *no* editing will be needed here.
+#. pressing ``Show Theory`` button will pop-up a little window showing the previously entered theory function. This is handy when defining its own theory, *i.e.* not working with a template. 
+
+.. image:: ../images/musrWiz-Functions-and-Theory.*
+
+.. index:: musrWiz-Maps
+
+musrWiz - Maps
+++++++++++++++
+
+.. image:: ../images/musrWiz-Maps.*
+
+The map dialogue will list the maps previously used in the theory and functions blocks/dialogues before. Again, if a template is used, nothing needs to be entered here.
+
+#. The ``Show Theory`` button allows to show the currently defined theory and the functions. 
+
+.. index:: musrWiz-FitParam
+
+musrWiz - Fit Parameters
+++++++++++++++++++++++++
+
+.. image:: ../images/musrWiz-FitParam.*
+
+In the fit parameter dialogue all parameter names can be defined. Furthermore the starting values for the parameters, the step 
+(initial step size for the parameter fit), and any boundaries can be defined here. 
+
+#. The ``Show Theory`` button allows to show the currently defined theory and the functions.
+
+.. index:: musrWiz-FitInfo
+
+musrWiz - Fit Info
+++++++++++++++++++
+
+Collects all the ``musrfit`` and ``MINUIT2`` specific fit commands.
+
+.. image:: ../images/musrWiz-FitInfo.*
+
+
+#. allows to define the time fit range (start time, end time).
+#. packing defines how many bins of the original data shall be combined (added, also called re-binning).
+#. in this text field to fitting commands are given (see the ``MINUIT`` and :ref:`musrfit <msr-commands-block>` manual for details). 
+
+.. index:: musrWiz-Create
+
+musrWiz - Create
+++++++++++++++++
+
+Collects the last necessary information before creating the msr-file.
+
+.. image:: ../images/musrWiz-Create.*
+
+
+#. shows the path where the msr-file will be saved. If you would like to save it somewhere else press the ``Save As (msr-file path)`` button.
+#. pressing this button will allow you to find the path where to save the msr-file.
+#. pressing this button will save to current configuration as a template for future re-use. 
+
+.. index:: musrStep
+
+musrStep
+--------
+
+``musrStep`` is a little helper program which allows to reset the initial step size. This sometimes comes very handy if working on an instrument 
+with many detectors after a fit slightly went wrong leaving you with a far too small initial step size for further iterations. To edit all the steps 
+individually is tedious and error prone. Here ``musrStep`` can help. 
+
+.. image:: ../images/musrStep-GUI.*
+
+When invoking ``musrStep`` the above dialogue will popup
+
+#. shows the relevant parts of the FITPARAMETER block. The only editable column is step.
+#. ``Check Specific`` will popup a dialogue where a template string can be entered, *e.g.* ``Asym``. As a result all fit parameters containing the template string will be selected.
+#. ``Check All`` will select all fit parameters.
+#. ``Uncheck All`` will unselect all fit parameters.
+#. ``Modify Automatic`` will change all the step values automatically. It basically sets all the step sizes to 1% of 
+   the corresponding fit parameter value, except the phases where the step will be set to a value of 5 degrees.
+#. ``Modify Selected`` will start the dialogue shown beneath. Follow the description there.
+#. ``Save&Quit`` will save the current step values, close the dialogue and reload the modified msr-file.
+#. ``Cancel`` will cancel the ``musrStep`` dialogue without modifying anything. 
+
+.. image:: ../images/musrStep-Modify-Selected.*
+
+When clicking on ``Modify Selected`` the above dialogue will be presented. It allows to manipulate all selected fit parameter step values according to the following rules 
+
+#. ``Scale by Factor`` will scale the step value by the factor given in the field (2). If the ``Absolute Value`` check box is selected, rather than scaling the factor value will be used to modify the step value.
+#. scaling factor or absolute value to modify the step values of the selected fit parameters.
+#. checking the ``Absolute Value`` check box will change the meaning from *Scale by Factor* to *Copy Factor Value*.
+#. ``Scale Automatically`` will modify the step values of the selected fit parameters according to the rules described before.
+#. ``Cancel`` will cancel the dialogue. 

doc/html/_sources/setup-dks.rst.txt

@@ -0,0 +1,273 @@
+.. include:: <isogrk1.txt>
+.. index:: dks
+
+.. _setup-dks:
+
+Setting up ``musrfit`` / ``DKS``: High Speed Fitting with GPU's 
+===============================================================
+
+In the years 2016/2017 we explored ways to speed up current fitting frameworks, especially ``musrfit.`` 
+This allows now to analyze histogram sets of high field spectrometers like ``HAL-9500`` at PSI without 
+the *error-prone* RRF fitting (see U. Locans and A. Suter, 
+`musrfit - Real Time Parameter Fitting Using GPU <http://dx.doi.org/10.7566/JPSCP.21.011051>`_, and the 
+Memo from A. Suter, "Rotating Reference Frame Fits", in the ``musrfit`` source code). At the same time 
+it can help to speed-up elaborate global fits tremendously, and dealing properly with muonium. It also 
+allows Apple macOS users to speed up their fitting code on the CPU. Currently it is not straight forward 
+to get ``musrfit`` multi-threaded under macOS since Apple doesn't be default support ``OpenMP``. ``DKS`` 
+enables ``musrfit`` to utilize ``OpenCL`` instead which is present on macOS by default. 
+
+.. warning:: 
+
+  Before you run into the shop to buy a gamer graphic card or a Tesla card, make sure that you have an 
+  appropriate server with a sufficiently strong power supply! 
+  
+.. note::
+
+  However, the current ``musrfit/DKS`` version doesn't yet support all theory functions on the GPU. 
+  In case the theory function is not yet available for the GPU, ``musrfit`` will fall back to the CPU implementation. 
+  
+Conceptually the setup of ``musrfit/DKS`` is as following:
+
+#. install the latest hardware driver for your graphic card.
+#. install the GPU SDK which enables number crunching (``CUDA`` for NVIDIA, ``OpenCL`` for AMD)
+#. install ``DKS``
+#. install the ``musrfit`` version which is ``DKS`` ready   
+
+In the following the description for the installation of ``musrfit/DKS`` for the following systems will be discussed in some more detail:
+
+* NVIDIA Tesla K40c
+* AMD Graphic Card (Radeon R9 390X)
+* macOS in order to get ``OpenCL`` support 
+
+The usage of ``musrfit`` with GPU acceleration and ``OpenCL`` support is described in the 
+:ref:`User manual of the μSR data analysis software musrfit <user-manual>`. The additional 
+``musrfit/DKS`` are found :ref:`here <msr-commands-block-dks>`.
+
+.. index:: dks-setup-tesla
+
+Setting up ``musrfit/DKS`` for a Tesla K40c (NVIDIA) 
+----------------------------------------------------
+
+It is assumed that the Tesla K40c is already physically installed on your system. For now I only 
+will discuss to set it up for a Linux based system. In order to check that your operating systems 
+see the card, enter the following command in the terminal: 
+
+.. code-block:: bash
+
+  $ lspci | grep NVIDIA
+
+The response should look something like 
+
+::
+
+  05:00.0 3D controller: NVIDIA Corporation GK110BGL [Tesla K40c] (rev a1)
+  
+which means that the OS physically recognizes your card. 
+
+Driver Installation for the Tesla K40c 
+++++++++++++++++++++++++++++++++++++++
+
+Next, you will need to download and install the driver for your card. Select the proper operating system, 
+card, etc. from the `NVIDIA download center <http://www.nvidia.com/Download/index.aspx?lang=en-us>`_. At PSI 
+we are running currently Red Hat Enterprise Linux 7.x (RHEL) for which we will get a ``rpm`` (something like 
+``nvidia-diag-driver-local-repo-rhel7-375.66-1.x86_64.rpm``). Install it and make sure there is no conflict 
+with the nouveau driver of the system. 
+
+.. index:: cuda-install
+
+Installation of CUDA
+++++++++++++++++++++
+
+Download the `CUDA SDK <https://developer.nvidia.com/cuda-downloads>`_ form NVIDIA for your system. Again, 
+for the RHEL 7.x this is an ``rpm``. After the installation of the rpm you should reboot your machine. 
+Afterwards you are ready for the installation of ``DKS``. 
+
+.. index:: dks-install
+
+Installation of DKS
++++++++++++++++++++
+
+For the following list of commands the ``'$'`` will be given as the command prompt. *Do not enter it!* 
+Also some comments will be added starting with a ``'#'`` which can be omitted. They are only there to 
+explain what is going on. ``DKS`` stands for Dynamical Kernel Scheduler and provides a thin interface 
+allowing host applications to incorporate GPU's and other hardware accelerators.
+
+Details can be found in the papers listed :ref:`here <cite>`.
+
+In brief the installation should be something like this:
+
+.. code-block:: bash
+
+  # go to whatever directory you would like to clone/install DKS
+  # For macOS DKS will likely to got to $HOME/Applications to be consistent with the musrfit docu for macOS
+  $ cd $HOME/Apps
+  $ git clone git://gitea.psi.ch:LMU/DKS.git
+  $ cd DKS
+  $ mkdir build
+  $ cd build
+  $ cmake ../ -DENABLE_MUSR=1 -DCMAKE_INSTALL_PREFIX=../exec
+  $ cmake --build ./ --clean-first
+  $ make install
+  
+Since ``DKS`` is installed in a non-standard path, a couple of additional small steps are required. 
+This will be different for Linux compared to macOS.
+
+For **Linux:**
+
+add the ``DKS`` library path to ``/etc/ld.so.conf.d/musrfit-x86_64.conf`` and execute as super user
+
+.. code-block:: bash
+
+  $ /sbin/ldconfig
+  
+For **macOS:**  
+
+add the ``DKS`` path to ``$HOME/.profile``:
+
+.. code-block:: bash
+
+  export DKS=$HOME/Applications/DKS/exec
+  export LD_LIBRARY_PATH=$DKS/lib:$LD_LIBRARY_PATH
+
+  launchctl setenv DKS $DKS
+  launchctl setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH
+  
+  
+.. _musrfit-dks-install:  
+  
+Installation of musrfit for DKS 
++++++++++++++++++++++++++++++++
+ 
+Most of the installation steps are the same as described for ``musrfit`` without GPU support. 
+Here only the differences are explained. First checkout ``musrfit``, then you will need to 
+switch the working branch which is done by
+ 
+.. code-block:: bash
+ 
+ $ cd $HOME/Apps/musrfit
+ $ git checkout dks6
+ 
+Install via cmake
+^^^^^^^^^^^^^^^^^
+
+There is on more configuration switch 
+
+**-Ddks=<value>**
+  it allows to enable/disable ``DKS`` support. The default is ``<value>=1``, *i.e.* enabled. To disable use ``<value>=0``. 
+  
+For a typical setup on a RHEL or macOS system it could look like this   
+
+.. code-block:: bash
+
+  $ cmake ../ -DCMAKE_INSTALL_PREFIX=$ROOTSYS -DASlibs=1 -DBMWlibs=1 -Dnexus=1 -Ddks=1
+
+After
+
+.. code-block:: bash
+
+  $ cmake --build ./ --clean-first -- -j8
+  $ make install
+  
+and updating the shared library lookup table (*only* needed for Linux)   
+
+.. code-block:: bash
+
+  $ /sbin/ldconfig # as superuser / root
+  
+you are done with the setup. 
+
+.. index:: dks-setup-amd-graphic-card
+
+Setting up ``musrfit/DKS`` for a AMD Graphic Card (Radeon R9 390X)
+------------------------------------------------------------------
+
+Driver Installation for an AMD Graphic Card, *e.g.* Radeon R9 390X 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This will depend slightly on the AMD Card and operating system. Here I will summaries how it was done 
+on a RHEL (Linux) system using a Radeon R9 390X.
+
+It is assumed that the Radeon R9 390X is already physically installed on your system. For now I only 
+will discuss to set it up for a Linux based system. In order to check that your operating systems see 
+the card, enter the following command in the terminal:
+
+.. code-block:: bash
+
+  $ lspci | grep AMD
+  
+The response should look something like   
+
+::
+
+  84:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Hawaii XT / Grenada XT [Radeon R9 290X/390X] (rev 80)
+  
+which means that the OS physically recognizes your card.   
+
+For RHEL7.x the AMDGPU-PRO driver should be used. It can be downloaded from `AMD <http://support.amd.com/en-us/kb-articles/Pages/AMDGPU-PRO-RedHat-Install.aspx>`_. Unpack the driver 
+
+.. code-block:: bash
+
+  $ tar -Jxvf amdgpu-pro-17.10-414273.tar.xz
+  $ cd amdgpu-pro-17.10-414273
+
+Install the driver as root
+
+.. code-block:: bash
+
+  $ ./amdgpu-pro-install --compute -y
+  
+Here I assume that the AMD graphic card is only used for computation. You need to add the following command 
+in order that the user **blabla** (change this to the appropriate user name) can access the GPU (otherwise 
+only root works):   
+
+.. code-block:: bash
+
+  $ /sbin/usermod -a -G video blabla
+  
+Reboot the machine. 
+
+AMD APP Software Development Kit (SDK) to enable ``OpenCL`` support
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The AMD APP Software Development Kit (SDK) is a complete development platform created by AMD to allow you to 
+quickly and easily develop applications accelerated by AMD APP technology. The SDK provides samples, documentation, 
+and other materials to quickly get you started leveraging accelerated compute using ``OpenCL`` or ``C++ AMP`` in your 
+``C/C++`` applications. 
+
+Download the AMD APP SDK 3.0 from `AMD-SDK <http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/>`_.
+
+Extract the installer
+
+.. code-block:: bash
+
+  $ tar -xvjf AMD-APP-SDKInstaller-v3.0.130.136-GA-linux64.tar.bz2
+
+Run the installer
+
+.. code-block:: bash
+
+  $ ./AMD-APP-SDK-v3.0.130.136-GA-linux64.sh
+
+This will install the AMD APP SDK to ``/opt/AMDAPPSDK-3.0/`` where you can find the ``OpenCL`` include 
+and library files, as well as documentation and sample code. The install guide for AMD OpenCL SDK can 
+be found at `AMD SDK Installation Notes <http://developer.amd.com/wordpress/media/2012/10/AMD_APP_SDK_InstallationNotes.pdf>`_.
+
+Installation of DKS and musrfit
++++++++++++++++++++++++++++++++
+ 
+To install ``DKS`` and ``musrfit`` follow the instructions :ref:`above <musrfit-dks-install>`.
+
+.. index:: dks-opencl-macOS
+
+Setting up ``musrfit/DKS`` for macOS for OpenCL support 
+-------------------------------------------------------
+
+Since Apple is not providing an out-of-the-box ``OpenMP`` support on their macOS compiler framework (Xcode), 
+typically ``musrfit`` is just running *single threaded*. Here ``DKS`` can help since it delivers ``OpenCL`` 
+support which is present on macOS. Hence, if you would like to run ``musrfit`` multi-threaded the easiest 
+way is to use ``DKS``. 
+
+Since there is no graphic card involved, you do not need any graphic card driver of additional SDK. 
+The only thing you need ``DKS`` and the proper ``musrfit`` version.
+
+The installation instruction for ``DKS/musrfit`` can be found :ref:`here <musrfit-dks-install>`. 

doc/html/_sources/tutorial.rst.txt

@@ -0,0 +1,417 @@
+.. include:: <isogrk1.txt>
+.. index:: tutorial
+
+Tutorial for ``musrfit``
+========================
+
+Single-histogram-fit tutorial
+-----------------------------
+
+The |mgr|\SR-data-analysis process using musrfit is based on so-called msr files. These files contain all 
+information needed for the analysis such as names of the data files, a theory function, fit and plot parameters, 
+and so on. It is the idea of this page to explain the basic use of an msr file and the different programs 
+of the ``musrfit`` suite using the example of a single-histogram fit to time-differential transverse-field 
+|mgr|\SR data. For a complete description of all options please refer to the :ref:`manual <user-manual>`. 
+
+The example deals with a diamagnetic sample that has been measured in an applied field of approximately 150 G in 
+the `GPS spectrometer <https://www.psi.ch/smus/gps>`_ at `PSI <https://www.psi.ch>`_ using the "transverse geometry". 
+In this geometry the muon spin is rotated about 50° up and the field is applied parallel to the muon momentum. 
+Hence, the relevant positron counters (to detect the spin precession) are placed above (histogram 3), below (histogram 4) and right of (histogram 5) the sample. The run numbers start from 3110. 
+
+To analyze these data (in a simple way) one starts out from the msr file ``3110_tutorial.msr`` provided together 
+with the source-code distribution in the sub-directory ``doc/examples/``. This ASCII file can be edited using any 
+text editor. For convenience the editor ``musredit`` is provided which offer some msr-file-specific functionalities 
+and additionally serve as front ends to the underlying programs. In the following it is assumed that the file is 
+open within ``musredit``.
+
+The msr file 
+++++++++++++
+
+The msr file itself is divided into different blocks; a full description of the format can be found :ref:`here <msr-file-format>`. 
+In the file ``3110_tutorial.msr`` these blocks are successively: 
+
+:ref:`The title <msr-title-block>`
+
+::
+
+  sample XYZ
+  
+A descriptive title of the file.  
+
+:ref:`The FITPARAMETER block <msr-fitparameter-block>`
+
+::
+
+  FITPARAMETER
+  #    No Name        Value     Step        Pos_Error   Boundaries
+        1 NormUp      4500      5           none        0       none    
+        2 BgUp        200       1           none        0       none    
+        3 PhaseUp     15        1           none        
+
+        4 NormDown    4500      5           none        0       none    
+        5 BgDown      200       1           none        0       none    
+        6 PhaseDown   195       1           none        
+
+        7 NormRight   600       5           none        0       none    
+        8 BgRight     40        1           none        0       none    
+        9 PhaseRight  285       1           none         
+
+       10 AsymSig1    0.17      0.01        none        0       0.33    
+       11 RateSig1    2.5       0.1         none        0       none
+       12 FieldSig1   100       1           none       
+
+       13 AsymSig2    0.02      0.01        none        0       0.33    
+       14 RateSig2    0.5       0.1         none       
+       15 FieldSig2   150       1           none
+
+The list of parameters used in the theory function to describe the set of data. 
+Each parameter has a number, a name, an initial value and an initial step (for 
+the fitting process). If a parameter should be fixed, the initial step is set 
+to 0. After a fit (see below), this block contains the determined parameter values 
+and uncertainties (in the ``Step`` column). If asymmetric errors are determined, these 
+will be listed in the ``Step`` column (negative) and the ``Pos_Error`` column (positive). 
+Optionally, lower and upper boundaries for the parameters can be specified as 
+shown above.
+       
+The meaning of the parameters above is explained in the following:
+
+Since a :ref:`single-histogram fit <single-histogram-fit>` should be done, some 
+histogram-specific parameters are needed. These are a normalization constant (parameter 1), 
+a parameter describing the background of uncorrelated events (parameter 2) and the initial 
+phase of the spin precession with respect to the detector (parameter 3). As stated above, 
+there are three histograms containing useful information ("Up", "Down", "Right"); hence, 
+this set of parameters has to be present for each of them (parameters 1–9).
+The remaining parameters are used to model the decay asymmetry which is assumed to be equal 
+for all histograms. In this example one has two signals (*e.g.* from the sample and the 
+sample holder), each with an amplitude (parameters 10 and 13), a depolarization rate 
+(parameters 11 and 14) and a mean field (here given in Gauss, parameters 12 and 15). 
+
+:ref:`The THEORY block <msr-theory-block>`
+
+::
+
+  THEORY
+  asymmetry     10
+  simplExpo     11          (rate)
+  TFieldCos   map1  fun1       (phase frequency)
+  +
+  asymmetry     13
+  simpleGss     14          (rate)
+  TFieldCos   map1  fun2       (phase frequency)
+  
+The THEORY block is used to define a fit-parameter-dependent theory function used to model 
+the decay asymmetry. Different :ref:`predefined <msr-theory-block>` and :ref:`user-defined <user-functions>` 
+functions can be combined here. Theory lines following each other are *multiplied* and the **+** sign 
+is used to add different (here: two) signal contributions. The numbers are the parameter numbers 
+according to the ``FITPARAMETER block``. ``map`` and ``fun`` are used to refer to 
+histogram-dependent parameters and to interrelate fit parameters, respectively (see below).  
+
+:ref:`The FUNCTIONS block <msr-functions-block>`
+
+::
+
+  FUNCTIONS
+  fun1 = gamma_mu * par12
+  fun2 = gamma_mu * par15
+  
+Here functions interrelating different fit parameters and predefined constants can be defined for 
+the use in the ``THEORY block``. In the example, the functions are used to calculate the 
+muon-spin-precession frequencies for the given fields [:math:`\nu = \gamma_\mu B / (2\pi)`]. One 
+function is used for each signal. Altogether, the theory function defined above is 
+:math:`A(t) = p_{10} e^{-p_{11} t} \cos(\varphi_i \pi/180 + \gamma_\mu p_{12} t) + p_{13} e^{-(p_{14} t)^2/2} \cos(\varphi_i \pi/180 + \gamma_\mu p_{15} t)`, where the *p* are the parameters in the ``FITPARAMETER block`` and :math:`\varphi_i = p_3, p_6, p_9` 
+depending on the histogram as shall be seen later.  
+
+:ref:`The RUN block <msr-run-block>`
+
+::
+
+  RUN data/deltat_pta_gps_3110 PIM3 PSI PSI-BIN   (name beamline institute data-file-format)
+  fittype         0         (single histogram fit)
+  norm            1
+  backgr.fit      2
+  map             3    0    0    0    0    0    0    0    0    0
+  forward         3       
+  data            1       8000    
+  t0              1     
+  fit             0       4.9    
+  packing         20  
+  
+The RUN blocks are used to collect information on the data to be analyzed. Specifically, these are: 
+
+  ::
+  
+    RUN data/deltat_pta_gps_3110 PIM3 PSI PSI-BIN   (name beamline institute data-file-format)
+    
+  The path to the data file and the file format (NEXUS, ROOT-NPP, ROOT-PPC, PSI-BIN, PSI-MDU, WKM, MUD, MDU-ASCII).
+  
+  ::
+  
+    fittype         0         (single histogram fit)
+    
+  the fit type (0 = single-histogram fit) 
+  
+  ::
+  
+    norm            1
+    
+  the number of the fit parameter representing the normalization constant 
+  
+  ::
+  
+    backgr.fit      2
+    
+  the number of the fit parameter representing the background 
+   
+  ::
+   
+    map             3    0    0    0    0    0    0    0    0    0
+     
+  the definition of the **maps** used in the ``THEORY block`` — RUN-block-specific 
+  parameters are given here; in this example, **map1** is substituted by **parameter 3** 
+  in the ``THEORY block`` for this RUN block and **map2**, **map3**, and so on are undefined.   
+   
+  ::
+   
+    forward         3
+     
+  the histogram number; in this example 3 corresponds to the histogram of the "Up" positron counter 
+   
+  ::
+   
+    data            1        8000
+     
+  start and end bins of the range containing useful data in the histogram (to be adjusted, *e.g.* by using ``musrt0``, see below) 
+   
+  ::
+   
+    t0              1
+     
+  histogram bin corresponding to the time zero (muon implantation time) (to be adjusted, *e.g.* by ``musrt0``, see below)  
+   
+  ::
+   
+    fit             0       4.9
+     
+  start and end times (in |mgr|\s) defining the fit range. *In case the fit range 
+  exceeds the range of useful data (specified above using the data tag), eventually 
+  this data range is used as fit range.* 
+    
+  ::
+    
+    packing         20
+  
+  the packing of the histograms (in histogram bins)
+    
+  Since the data of three histograms is to be analyzed, the file contains not only one but 
+  three RUN blocks — each defining the histogram-specific information following the example given above.
+  
+:ref:`The COMMAND block <msr-commands-block>`
+
+::
+
+  COMMANDS
+  MINIMIZE
+  MINOS
+  SAVE
+  
+In the ``COMMANDS block``, a sequence of operations that should be performed is defined. 
+Here, the requested operations are the minimization of :math:`\chi^2` (MINIMIZE), the 
+calculation of *asymmetric errors* (MINOS) as well as saving the found parameter values 
+and uncertainties to the msr file (SAVE). A full description of the possible commands can 
+be found :ref:`here <msr-commands-block>`.   
+  
+:ref:`The FOURIER block <msr-fourier-block>`
+
+::
+  
+  FOURIER
+  units            Gauss   # units either 'Gauss', 'MHz', or 'Mc/s'
+  fourier_power    10
+  apodization      WEAK    # NONE, WEAK, MEDIUM, STRONG
+  plot             POWER   # REAL, IMAG, REAL_AND_IMAG, POWER, PHASE
+  phase            par3
+  range            0.0    600.0
+
+The ``FOURIER block`` is used to define basic settings for the Fourier transform available 
+in :ref:`musrview <musrview>`. These are: 
+  
+  ::
+  
+    units            Gauss   # units either 'Gauss', 'MHz', or 'Mc/s'
+    
+  the units of the Fourier domain 
+  
+  ::
+  
+    fourier_power    10
+    
+  the number of data points used for the discrete transform, here :math:`2^{10}=1024`.   
+  
+  ::
+  
+    apodization      WEAK    # NONE, WEAK, MEDIUM, STRONG
+    
+  the :ref:`apodization <msr-fourier-block-apodization>` to be used
+  
+  ::
+  
+    plot             POWER   # REAL, IMAG, REAL_AND_IMAG, POWER, PHASE 
+    
+  what should be plotted (real part, imaginary part, and so on) 
+  
+  ::
+  
+    phase            par3
+    
+  the initial phase of the input data is given here in degrees. Optionally, a phase parameter 
+  from the ``FITPARAMETER block`` can be given, here **par3** takes the value of **parameter 3**. 
+  
+  ::
+  
+    range            0.0    600.0
+    
+  the start and end points of the range of the Fourier transform in the units specified above 
+  
+:ref:`The PLOT block <msr-plot-block>`
+
+::
+
+  PLOT 0   (single histo plot)
+  runs     1   2   
+  range    0   4  -0.2   0.2
+  
+The ``PLOT block`` defines which data (corresponding to the given RUN blocks) is plotted when 
+:ref:`musrview <musrview>` is called. In the given example, a canvas would be drawn containing 
+the (life-time-corrected) data of the first two ``RUN blocks`` ("Up" and "Down" positron counters). 
+The abscissa would range from 0 to 4 |mgr|\s, the axis of ordinates from -0.2 to 0.2.
+It is possible to define more than one ``PLOT block``. Each ``PLOT block`` corresponds to a 
+separate canvas. Therefore, the second ``PLOT block`` in the file  
+
+::
+
+  PLOT 0   (single histo plot)
+  runs     3   
+  use_fit_ranges
+  
+produces an additional window containing the (not life-time-corrected) data of the third ``RUN block`` 
+("Right" positron counter). The abscissa ranges from 0 to 4.9 |mgr|\s (according to the fit range given 
+in the ``RUN block``).  
+
+:ref:`The STATISTIC block <msr-statistic-block>`
+
+::
+
+  STATISTIC --- 2011-07-09 10:58:44
+  chisq = 1348.1764, NDF = 1146, chisq/NDF = 1.176419
+  
+This 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 :math:`\chi^2` and the 
+number of degrees of freedom in the fit.
+These information only have a meaning if the fitting procedure has been executed at 
+least once and the fit has converged!   
+  
+Determine t0 and the data range using musrt0
+++++++++++++++++++++++++++++++++++++++++++++
+
+Before the given model can be fitted to the data, the data ranges and time zeros of the different 
+``RUN blocks`` have to be set correctly. This can be achieved using :ref:`musrt0 <musrt0>`. 
+Starting this program by selecting the ``musrt0`` button in ``musredit`` or calling from a terminal 
+
+.. code-block:: bash
+
+  $ musrt0 3110_tutorial.msr
+  
+opens an interactive window plotting the data of the first RUN block:  
+
+.. image:: ../images/tutorial-musrt0-1.*
+
+The green line (at bin 1) represents time zero, the blue lines the start (at bin 1) and end (at bin 8000) 
+of the data range and the optional red lines give the limits of the background range (if the background 
+shall not be determined by the fit). All lines can be either dragged to reasonable locations or set by 
+pressing the corresponding keyboard shortcuts. In the example the time zero can be set by pressing **T** 
+(which moves the green line to the bin containing the maximum number of counts), the start of the data 
+range should be set to about five bins later by zooming into the graph around bin 250 and pressing **d** 
+when the cursor is found at a suitable location:
+
+.. image:: ../images/tutorial-musrt0-2.*
+
+After all lines have been adjusted for the first histogram, one can go on to the second by pressing **q**. 
+This procedure is repeated until all ranges have been set correctly. When finished with the last histogram 
+the new t0 and data-range values will be written to the msr file. A full description of ``musrt0`` can be 
+found :ref:`here <musrt0>`.
+
+Fit the model to the data using ``musrfit``
++++++++++++++++++++++++++++++++++++++++++++
+
+Now that the basics of the msr file have been introduced and the necessary adjustments have been done one 
+can proceed with fitting the specified model to the data. This is done by selecting the ``musrfit`` icon 
+in ``musredit`` or calling from a terminal 
+
+.. code-block:: bash
+
+  $ musrfit 3110_tutorial.msr
+  
+After the fitting procedure has finished the msr file is updated and contains the newly determined values 
+of the fit parameters.   
+
+View the data and the fit using ``musrview``
+++++++++++++++++++++++++++++++++++++++++++++
+
+The data and the corresponding fit can be visualized by choosing the ``musrview`` icon in ``musredit`` or 
+calling from a terminal 
+
+.. code-block:: bash
+
+  $ musrview 3110_tutorial.msr
+
+This creates the windows according to the given PLOT blocks in the msr file:
+
+.. image:: ../images/tutorial-musrview-1.*
+
+The basic features of ``musrview`` can be found in the ``Musrfit menu``. They include: 
+
+* export the shown data and the model to an ASCII file with comma-separated values
+* presenting the difference between the shown data and the model (keyboard shortcut: **d**)
+* calculate and show the Fourier transform of the shown data (keyboard shortcut: **f**), *e.g.* for 
+  the asymmetry of the "Up" and "Down" detectors:
+  
+.. image:: ../images/tutorial-musrview-FT.*
+
+Process multiple msr files using ``msr2data``
++++++++++++++++++++++++++++++++++++++++++++++
+
+This short introduction is concluded by calling attention to the program :ref:`msr2data <msr2data>`. 
+As the name indicates the main purpose of this program is to extract the ``FITPARAMETER`` block 
+information from multiple msr files with the same structure and to summarize them in a single 
+ASCII file (either in ``TRIUMF DB`` format or simple columns). However, as described in detail 
+in the manual, it is not only possible to collect data from msr files but also to create new 
+msr files from a template and to process these files using ``musrfit`` on the fly.
+
+Assuming the successive runs **3111** through **3114** can be analyzed using the same model introduced 
+above for run **3110** (*e.g.* in the case one has done measurements at different temperatures) one can 
+use the file ``3110_tutorial.msr`` as template, generate the files ``3111_tutorial.msr`` through 
+``3114_tutorial.msr`` with the corresponding updates in the RUN blocks, call for each one ``musrfit`` 
+and finally summarize the FITPARAMETER block information of all processed files in an ASCII output 
+file ``tutorial-T-dependence.dat`` (simple columns). If further information on the temperature or the 
+applied field is available in the data files these will be included as well in the resulting ASCII file.
+From the terminal this would be done as follows:
+
+.. code-block:: bash
+
+  $ msr2data 3110 3114 _tutorial fit-3110 -o tutorial-T-dependence.dat data
+  
+To achieve the same in ``musredit`` (in this snapshot in the *dark theme*) one selects the ``msr2data`` icon and fills the form accordingly:  
+
+.. image:: ../images/tutorial-musredit-msr2data.*
+
+Further reading 
++++++++++++++++
+
+This page only summarizes the very basic features and options of the programs contained in the ``musrfit`` suite. 
+For a complete description please refer to the manuals of :ref:`musrfit <musrfit>` (including :ref:`musrview <musrview>`, 
+:ref:`musrt0 <musrt0>`, and :ref:`musrFT <musrFT>`), :ref:`mupp <mupp>`, :ref:`musredit <musredit-sec>`, and :ref:`msr2data <msr2data>`. 
+
+Asymmtery-fit tutorial
+----------------------
+
+to be written yet.

doc/html/_sources/user-libs.rst.txt

@@ -0,0 +1,895 @@
+.. include:: <isogrk1.txt>
+.. index:: user-libs
+
+.. _user-libs:
+
+Documentation of user libs (user functions) 
+===========================================
+
+.. index:: BMW-libs
+.. _BMW-libs:
+
+Meissner-Profiles / Vortex-Lattice related functions (BMW libs)
+---------------------------------------------------------------
+
+.. index:: libFitPofB
+
+libFitPofB
+++++++++++
+
+Introduction
+^^^^^^^^^^^^
+
+``libFitPofB`` is a collection of ``C++`` classes using the ``musrfit`` :ref:`user-functions <user-functions>` 
+interface in order to facilitate the usage in conjunction with ``musrfit``. The classes contained in this 
+library generally implement calculations of one-dimensional static magnetic field distributions 
+:math:`p(B)` which lead to the muon-spin depolarization functions 
+
+.. math::
+
+  {\cal P}(t) = \int p(B) \cos(\gamma_\mu B t + \varphi) dB,
+  
+where :math:`\gamma_\mu = 2 \pi \times 135.54` MHz/T is the gyromagnetic ratio of the muon and :math:`\varphi` 
+is the initial phase of the muon spins with respect to the positron detector. At the moment the only available 
+implementations deal with field distributions measured in local isotropic superconductors, either by means of 
+low-energy |mgr|\SR (see `<https://www.psi.ch/smus/lem>`_) in the Meissner state or by bulk |mgr|\SR in the mixed state. 
+In the following the basic usage of the library in ``musrfit`` is explained—the calculations by themselves are only 
+outlined. For further information please refer to the original literature and/or the source code of the implementation.
+
+.. note:: 
+
+  In order to supply certain information needed for the calculations but not suited to be stored in the ``musrfit`` 
+  msr files an ``XML`` configuration file in the working directory is used. For details, see below.
+  
+.. note:: 
+
+  The implementations in this library heavily rely on `FFTW3 <http://fftw.org/>`_. In principle, it always checks what 
+  is the best way to do efficient Fourier transforms for a given machine before the transforms are actually done. If 
+  repeatedly Fourier transforms of the same (sizable) length should be done, it might be worth storing the once 
+  obtained information in an external file and just load it the next time this information is needed 
+  (`wisdom handling <http://fftw.org/fftw3_doc/Wisdom.html>`_). In case this feature shall be used, a valid wisdom 
+  file has to be specified in the ``XML`` file. 
+  
+.. note::
+
+  The model functions described in the following do generally *not behave nicely* in conjunction with ``MINUIT`` 
+  function minimizations (or maximizations). The analysis process at the moment in most cases involves some 
+  tedious trial-and-error procedure, where the displayed MINUIT information as always deserves attention. 
+  This is especially true if small effects should be analyzed (*e.g.* small diamagnetic shifts in superconductors). 
+  The parameter uncertainty in many cases has to be estimated independently. Due to these limitations, also 
+  the use of the fit option of ``msr2data`` *cannot* be advised. 
+   
+.. note::
+
+  If these classes still prove useful and results obtained through them are part of scientific publications, 
+  an acknowledgment of the use of the library is appreciated.
+  
+LE-|mgr|\SR
+^^^^^^^^^^^
+
+.. index:: 1D-London-Meissner
+
+One-dimensional London model for the Meissner state of isotropic superconductors 
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The models for analyzing LE-|mgr|\SR data assume the magnetic induction :math:`B(z)` to vary only in the 
+dimension parallel to the momentum of the incident muons. In such a case the magnetic field distribution is given by 
+
+.. math::
+
+  p(B) = n(z) \left| \frac{dB(z)}{dz} \right|^{-1}
+  
+where :math:`n(z)` is the muon implantation profile simulated by ``TRIM.SP``. 
+
+Assuming an array of *N* isotropic local superconductors with a total thickness *d* in the Meissner state 
+the magnetic induction is given by solving the 1D London equation 
+
+.. math::
+
+   \frac{\partial^2}{\partial z^2}B_i(z) = \frac{1}{\lambda_i^2}B_i(z) 
+   
+for each layer *i* taking into account the boundary conditions (F. London, Superfluids: Macroscopic Theory of Superconductivity, Dover (1961), p. 34)
+
+.. math:: 
+
+   B_1(0) = B_N(d) = \mu_0H
+   
+   B_i(d_i) = B_{i+1}(d_i)
+   
+   \lambda_i^2B_i'(z)\Big\vert_{z=d_i} = \lambda_{i+1}^2B_{i+1}'(z)\Big\vert_{z=d_i}, 
+   
+where the :math:`d_i` specify the interfaces between two adjacent layers and :math:`\lambda_i` is 
+the magnetic field penetration depth in the constituent :math:`i`.
+
+The calculation of the field distribution has been set up for a superconducting half-space as well 
+as superconducting thin films with up to three superconducting layers with different penetration depths. 
+The muon-spin depolarization functions are calculated using the following lines in the ``THEORY`` block 
+of a ``musrfit`` msr file: 
+
+.. index:: TLondon1DHS
+
+**Superconducting half-space**
+
+::
+
+  userFcn  libFitPofB TLondon1DHS 1 2 3 4 5
+
+The parameters are:
+
+#. phase (deg)
+#. muon implantation energy as specified in the :ref:`XML startup <BMWlibs-XML>` file (keV)
+#. applied field (G)
+#. thickness of the dead layer (nm)
+#. magnetic field penetration depth (nm) 
+
+.. index:: TLondon1D1L
+
+**Superconducting thin film (one layer)**
+
+:: 
+
+  userFcn  libFitPofB TLondon1D1L 1 2 3 4 5 6 [a b]
+  
+The mandatory parameters are:
+
+#. phase (deg)
+#. muon implantation energy as specified in the :ref:`XML startup <BMWlibs-XML>` file (keV)
+#. applied field (G)
+#. thickness of the dead layer (nm)
+#. thickness of the actually superconducting layer (nm)
+#. magnetic field penetration depth (nm)   
+
+The optional parameters are:
+
+a. fraction f\ :sub:`1` of muons in the thin film contributing to the signal (0 ≤ f\ :sub:`1` ≤ 1)
+b. fraction f\ :sub:`s` of muons in the substrate contributing to the signal (0 ≤ f\ :sub:`s` ≤ 1)
+
+.. index:: TLondon1D2L
+
+**Superconducting thin-film bilayer heterostructure**
+
+::
+
+  userFcn  libFitPofB TLondon1D2L 1 2 3 4 5 6 7 8 [a b c]
+       
+The mandatory parameters are:
+
+#. phase (deg)
+#. muon implantation energy as specified in the :ref:`XML startup <BMWlibs-XML>` file (keV)
+#. applied field (G)
+#. thickness of the dead layer (nm)
+#. thickness of the actually superconducting first layer (nm)
+#. thickness of the actually superconducting second layer (nm)
+#. magnetic field penetration depth of the first layer (nm)
+#. magnetic field penetration depth of the second layer (nm) 
+
+The optional parameters are:
+
+a. fraction f\ :sub:`1` of muons in the dead and first layer contributing to the signal (0 ≤ f\ :sub:`1` ≤ 1)
+b. fraction f\ :sub:`2` of muons in the second layer contributing to the signal (0 ≤ f\ :sub:`2` ≤ 1)
+c. fraction f\ :sub:`s` of muons in the substrate contributing to the signal (0 ≤ f\ :sub:`s` ≤ 1) 
+
+.. index:: TLondon1D3L
+
+**Superconducting thin-film trilayer heterostructure**
+
+::
+
+  userFcn  libFitPofB TLondon1D3L 1 2 3 4 5 6 7 8 9 10 [a b c d]
+
+The mandatory parameters are:
+
+#. phase (deg)
+#. muon implantation energy as specified in the :ref:`XML startup <BMWlibs-XML>` file (keV)
+#. applied field (G)
+#. thickness of the dead layer (nm)
+#. thickness of the actually superconducting first layer (nm)
+#. thickness of the actually superconducting second layer (nm)
+#. thickness of the actually superconducting third layer (nm)
+#. magnetic field penetration depth of the first layer (nm)
+#. magnetic field penetration depth of the second layer (nm)
+#. magnetic field penetration depth of the third layer (nm) 
+
+The optional parameters are:
+
+a. fraction f\ :sub:`1` of muons in the dead and first layer contributing to the signal (0 ≤ f\ :sub:`1` ≤ 1)
+b. fraction f\ :sub:`2` of muons in the second layer contributing to the signal (0 ≤ f\ :sub:`2` ≤ 1)
+c. fraction f\ :sub:`3` of muons in the third layer contributing to the signal (0 ≤ f\ :sub:`3` ≤ 1)
+d. fraction f\ :sub:`s` of muons in the substrate contributing to the signal (0 ≤ f\ :sub:`s` ≤ 1) 
+   
+Bulk |mgr|\SR
+^^^^^^^^^^^^^
+
+.. index:: Vortex-State-Isotropic
+
+Field distributions in the mixed state of isotropic superconductors 
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+When investigating superconductors in the mixed state by means of conventional |mgr|\SR a 
+two-dimensional flux-line lattice is probed randomly by the muons. The spatial field 
+distributions within such an ordered lattice are modeled using the Fourier series
+
+.. math::
+
+   B(\mathbf{r}) = \langle B \rangle \sum\limits_{\mathbf{K}}B_{\mathbf{K}}\exp(-\imath\mathbf{K}\mathbf{r}), 
+   
+where :math:`\mathbf{r}=(x,y)`, **K** are the reciprocal lattice vectors of a two-dimensional 
+vortex lattice and the :math:`B_{\mathbf{K}}` are the Fourier coefficients depending on the 
+magnetic penetration depth :math:`\lambda` and the superconducting coherence length :math:`\xi`. 
+The :math:`B_{\mathbf{K}}` for some specific models are as follows:    
+
+**London model with Gaussian cutoff** (E.H. Brandt, `J. Low Temp. Phys. 73, 355 (1988) <http://dx.doi.org/10.1007/BF00683568>`_.)
+
+.. math::
+
+   B_{\mathbf{K}} = \frac{\exp\left({-K^2\xi^2/2}\right)}{1 + K^2\lambda^2}
+
+**Modified London model** (T.M. Riseman *et al.*, `Phys. Rev. B 52, 10569 (1995) <http://dx.doi.org/10.1103/PhysRevB.52.10569>`_.)   
+
+.. math::
+   
+  B_{\mathbf{K}} = \frac{\exp\left({-K^2\xi^2/2(1-b)}\right)}{1 + K^2\lambda^2/(1-b)},
+    
+where :math:`b = \langle B \rangle / (\mu_0 H_{\rm c2})`. 
+
+**Analytical Ginzburg-Landau model** ( A. Yaouanc, P. Dalmas de Réotier and E.H. Brandt, `Phys. Rev. B 55, 11107 (1997) <http://dx.doi.org/10.1103/PhysRevB.55.11107>`_)
+
+.. math::
+
+  B_{\mathbf{K}} = \frac{f_{\infty}K_1\left(\frac{\xi_v}{\lambda}\sqrt{f_{\infty}^2+\lambda^2K^2}\right)}{K_1\left(\frac{\xi_v}{\lambda}f_{\infty}\right)\sqrt{f_{\infty}^2+\lambda^2K^2}},
+  
+where :math:`f_{\infty} = 1 - b^4,~\xi_v = \xi\left(\sqrt{2}-{3\xi}/\left({4\lambda}\right)\right)\sqrt{(1+b^4)(1-2b(1-b)^2)}` and
+:math:`K_1` is a modified Bessel function.
+
+Apart from the mentioned analytic models the **numerical Ginzburg-Landau model** (`E.H. Brandt, Phys. Rev. B 68, 054506 (2003). <http://dx.doi.org/10.1103/PhysRevB.68.054506>`_) is available. In this case :math:`B(\mathbf{r})` is obtained by an iterative minimization of the free energy of the vortex lattice. 
+
+**Concerning the applicability (e.g. field regions) of each of the mentioned models please refer to the original publications!**
+
+At the moment, the calculation of the field distribution has been implemented for *triangular* flux-line lattices. 
+The number of grid lines in which the inter-vortex distance is divided for the calculations to be specified through 
+the :ref:`XML startup <BMWlibs-XML>`.
+The muon-spin depolarization functions finally are calculated using the following lines in the THEORY block of a ``musrfit`` msr file: 
+
+.. index:: Vortex-Gaussian-CutOff
+
+**2D triangular vortex lattice, London model with Gaussian cutoff** 
+
+::
+
+  userFcn  libFitPofB TBulkTriVortexLondon 1 2 3 4
+  
+The parameters are:
+
+#. phase (deg)
+#. mean magnetic induction (G)
+#. magnetic penetration depth (nm)
+#. Ginzburg-Landau coherence length (nm)   
+
+.. index:: Vortex-London-modified
+
+**2D triangular vortex lattice, modified London model**
+
+::
+
+  userFcn  libFitPofB TBulkTriVortexML 1 2 3 4
+  
+The parameters are:
+
+#. phase (deg)
+#. mean magnetic induction (G)
+#. magnetic penetration depth (nm)
+#. Ginzburg-Landau coherence length (nm)   
+
+.. index:: Vortex-Analytic-GL
+
+**2D triangular vortex lattice, analytic Ginzburg-Landau model** 
+
+::
+
+  userFcn  libFitPofB TBulkTriVortexAGL 1 2 3 4
+  
+The parameters are:
+
+#. phase (deg)
+#. mean magnetic induction (G)
+#. magnetic penetration depth (nm)
+#. Ginzburg-Landau coherence length (nm) 
+
+.. index:: Vortex-Numeric-GL
+
+**2D triangular vortex lattice, numerical Ginzburg-Landau model**
+
+::
+
+  userFcn  libFitPofB TBulkTriVortexNGL 1 2 3 4
+  
+The parameters are:
+
+#. phase (deg)
+#. mean magnetic induction (G)
+#. magnetic penetration depth (nm)
+#. Ginzburg-Landau coherence length (nm) 
+
+.. note::
+
+  In order to improve the convergence of ``MIGRAD`` it has proven useful to use the log-likelihood 
+  maximization instead of the :math:`\chi^2` minimization routines and to choose sufficiently large 
+  initial steps for the parameters. Calling ``MINOS`` in conjunction with these functions is futile.
+
+Therefore, the :ref:`COMMANDS block <msr-commands-block>` of the msr file could look like:   
+
+::
+
+  COMMANDS
+  STRATEGY 2
+  MAX_LIKELIHOOD
+  MIGRAD
+  HESSE
+  SAVE
+  
+.. index:: BMWlibs-XML
+.. _BMWlibs-XML:
+   
+The XML startup file
+^^^^^^^^^^^^^^^^^^^^
+
+``BMW_startup.xml`` is a configuration file located in the working directory. In this file some settings 
+like the time and field resolution of the calculations as well as the present muon implantation profiles 
+for a LE-|mgr|\SR analysis have to be defined. The following XML tags are allowed to define settings: 
+
+**<debug>ONE_OR_ZERO</debug>**
+  activate the debugging output of the settings read from the XML file by setting 1, deactivate it with 0.
+**<wisdom>PATH_TO_FILE</wisdom>**
+  specify the ``PATH_TO_FILE`` to an `FFTW3 wisdom file <http://fftw.org/fftw3_doc/Wisdom.html#Wisdom>`_ 
+  that should be used; if the ``PATH_TO_FILE`` is invalid, no ``FFTW3`` wisdom will be used.
+**<delta_t>ResT</delta_t>**
+  set the time resolution ``ResT`` for the calculated depolarization function in microseconds.
+**<delta_B>ResB</delta_B>**
+  set the field resolution ``ResB`` for the calculated field distribution in Gauss.
+**<VortexLattice></VortexLattice>**
+  set the parameters used for the calculation of the spatial field distribution of a vortex lattice.
+  
+  **<N_VortexGrid>N</N_VortexGrid>**
+    specify the number of points **N** (in each of the two dimensions) for which the fields within the 
+    vortex lattice are calculated (inside a **<VortexLattice>** environment) 
+    
+**<LEM></LEM>**     
+  set the parameters used for the calculation of LE-|mgr|\SR field distributions 
+  
+  **<data_path>DATA_PATH_PREFIX</data_path>**
+    specify the ``DATA_PATH_PREFIX`` to the ``TRIM.SP`` implantation profiles (inside a **<LEM>** environment)
+  **<N_theory>N_THEORY</N_theory>**
+    specify the number of points **N_THEORY** for which *B(z)* is calculated (inside a **<LEM>** environment)
+    The specification of this number is not needed if the calculation of the inverse of *B(z)* is implemented!
+  **<energy_list></energy_list>**
+    set the energies for which ``TRIM.SP`` implantation profiles are available (inside a **<LEM>** environment) 
+    
+    **<energy_label>LABEL</energy_label>**
+      specify the **LABEL** within the file name of a available ``TRIM.SP`` ``RGE`` file (inside a **<energy_list>** environment)
+      The expected name of the ``RGE`` file will be: ``DATA_PATH_PREFIX + LABEL + .rge`` 
+    **<energy>E</energy>**
+      specify the muon energy *E* (in keV) belonging to the ``TRIM.SP`` ``RGE`` file given above (inside a **<energy_list>** environment)   
+      
+An example XML file looks as follows:      
+
+.. code-block:: xml
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <BMW>
+    <debug>0</debug>
+    <wisdom>/home/user/WordsOfWisdom.dat</wisdom>
+    <delta_t>0.01</delta_t>
+    <delta_B>0.5</delta_B>
+    <VortexLattice>
+      <N_VortexGrid>1024</N_VortexGrid>
+    </VortexLattice>
+    <LEM>
+      <data_path>/home/user/TrimSP/some-sample-</data_path>
+      <N_theory>5000</N_theory>
+      <energy_list>
+        <energy_label>02_0</energy_label>
+        <energy>2.0</energy>
+        <energy_label>03_0</energy_label>
+        <energy>3.0</energy>
+        <energy_label>03_6</energy_label>
+        <energy>3.6</energy>
+        <energy_label>05_0</energy_label>
+        <energy>5.0</energy>
+        <energy_label>05_3</energy_label>
+        <energy>5.3</energy>
+      </energy_list>
+    </LEM>
+  </BMW>
+
+.. index:: gap-integral-libs
+.. _gap-integral-libs:
+
+Supeconducting Gap-Integrals to calculate :math:`1/\lambda^2` vs :math:`T`
+--------------------------------------------------------------------------
+
+The details about the various superconducting gap-integrals are found in the 
+pdf-file **GapIntegrals.pdf** which can be found in the musrfit source under
+``<musrfit-dir>/src/external/libGapIntegrals/``.
+  
+.. index:: nonlocal-libs
+.. _nonlocal-libs:
+
+Nonlocal superconductivity related Meissner screening functions (AS libs) 
+-------------------------------------------------------------------------
+
+This library allows to calculate the magnetic field profile :math:`B(z)` for nonlocal superconductors.
+For details see `A. Suter, et al., PRB 72, 024506 (2005) <http://dx.doi.org/10.1103/PhysRevLett.95.197201>`_, and references therein.
+
+The provided function calculates the muon spin polarization
+
+.. math::
+
+  P(t, E) = \int n(z, E)\, \cos(\gamma_\mu B(z) t + \phi) \, dz, 
+  
+
+where :math:`B(z)` is calculated in the limit of specular reflection.
+The corresponding user function is called as
+
+::
+
+  userFcn  libPNL_PippardFitter PNL_PippardFitter 1 2 3 4 5 6 7 8 9
+
+with the parameters
+
+#. implantation energy in (keV).
+#. reduced temperature :math:`t=T/T_c`.
+#. thickness in (nm).
+#. electron mean path, :math:`\ell` in (nm).
+#. superconducting coherence length, :math:`\xi` in (nm).
+#. London penetration length, :math:`\lambda_{\rm L}` in (nm).
+#. external magnetic field strength in (G).
+#. the effective detector phase, :math:`\varphi` in :math:`(^\circ)`.
+#. a "dead layer" thickness in (nm).
+
+Typically this function needs to be multiplied by a Gaussian in order to take into account: nuclear dipole broadening, partial trapped flux, etc.
+
+In order to find the muon stopping profile, :math:`n(z,E)`, needed for the calculation, the library needs to find the corresponding trimsp
+rge-files (muon stoppping profiles). For this the library reads at start-up the following xml-file (example):
+
+.. code-block:: xml
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <nonlocal xmlns="http://nemu.web.psi.ch/musrfit/nonlocal">
+      <comment>
+          nonlocal_startup.xml
+      </comment>
+      <nonlocal_par>
+          <fourier_points>262144</fourier_points>
+      </nonlocal_par>
+      <trim_sp>
+          <data_path>./profiles/</data_path>
+          <rge_fln_pre>Sn_E</rge_fln_pre>
+          <energy_list>
+              <energy>1000</energy>
+              <energy>2000</energy>
+              <energy>4000</energy>
+              <energy>6000</energy>
+              <energy>8000</energy>
+              <energy>10000</energy>
+              <energy>12000</energy>
+              <energy>14100</energy>
+              <energy>18000</energy>
+              <energy>22000</energy>
+              <energy>25000</energy>
+              <energy>27300</energy>
+          </energy_list>
+      </trim_sp>
+  </nonlocal>
+
+Here the number of Fourier points needed in the calculation can be defined (``fourier_points``). The ``trim_sp`` section
+contains all the information needed to load the proper muon stopping profiles. ``data_path`` is the path to the needed rge-files.
+``rge_fln_pre`` is the rge-file prefix, and ``energy`` are all the energy tags. E.g. ``./profile/Sn_E1000.rge`` would be the first
+muon stopping profile for an energy of :math:`E=1000` (eV).
+
+The name of the xml-file has to be ``nonlocal_startup.xml`` and needs to be placed in the directory where the analysis takes place, i.e.
+in the directory of all the msr-files.
+
+.. index:: DepthProf-lib
+.. _DepthProf-lib:
+
+Depth resolved information (AS libs) 
+------------------------------------
+
+A method to extract depth-resolved information from the implantation energy dependence of the experimental parameters in a low-energy
+muon spin spectroscopy experiment. For details see `A. F. A. Simões, et al. Review of Scientific Instruments. 2020; 91(2): 023906 (7 pp.) <https://doi.org/10.1063/1.5126529>`_.
+
+If you have a layered material (e.g. :math:`N` layers), properties like the asymmetry might depend on the layer in which the muons are stopped.
+For instance there might be different probabilities for muonium formation depending on the material, charge transfer layers, etc.
+
+Since the muon stopping distribution, :math:`n(z)`, has some finite range, these properties will be smeared out. For the following we define
+the stopping probability, :math:`p_{i}(E)` for a finite slice :math:`i`, ranging from :math:`z \in [a, b]` as
+
+.. math::
+
+  p_{i}(E) = \int_a^b n(z,E) \, dz
+
+Furthermore it is assumes that there is a sharp transition between the layers of the property of interest, e.g. the diamagnetic fraction, :math:`f_i`.
+Hence the measured property as function of energy is
+
+.. math::
+
+  f(E) = \sum_{i=1}^N p_{i}(E) \cdot f_i.
+
+.. note:: 
+
+  Currently it is recommended to read in the data in ASCII or DAT format as a non-|mgr|\SR fit  :ref:`(fit type 8) <non-musr-fit>`.
+
+The user library for the depth profile analysis looks for a **3 layer material**, assuming one is looking for the diamagnetic fraction, like
+
+::
+
+  ###############################################################
+  FITPARAMETER
+  #      Nr.   Name        Value     Step      Pos_Error  Boundaries    
+          1    f1          0.54540   0.00072     none        0       1       
+          2    f2          0.23957   0.00048     none        
+          3    f3          0.05615   0.00047     none        0       1       
+          4    x1          63.5000   0.0014      none        
+          5    x2          101.5001  0.0044      none        
+
+  ###############################################################
+  THEORY
+  userFcn  libPDepthProfile PDepthProfile 1 2 3 4 5
+
+Here, :math:`f1` is the diamagnetic fraction of the first layer, etc. :math:`x1` is the thickness of the first layer, etc.
+
+In order to find the muon stopping profile, :math:`n(z,E)`, needed for the calculation, the library needs to find the corresponding trimsp
+rge-files (muon stoppping profiles). For this the library reads at start-up the following xml-file (example):
+
+.. code-block:: xml
+  
+  <?xml version="1.0" encoding="UTF-8"?>
+  <depthProf xmlns="http://nemu.web.psi.ch/musrfit/depthProf">
+      <comment>
+          TrimSp information
+      </comment>
+      <trim_sp>
+          <data_path>./TRIMSP/</data_path>
+          <rge_fln_pre>SiO2_70nm2.0_30nm2.2_SiC_E</rge_fln_pre>
+          <energy_vect start="1000" stop="22000" step="1000"/>
+      </trim_sp>
+  </depthProf>
+
+
+.. index:: BNMR-libs
+.. _BNMR-libs:
+
+Functions to analyze |bgr|-NMR data (BNMR libs) 
+-------------------------------------------------------------------------
+
+This is a collection of ``C++`` classes using the ``musrfit`` :ref:`user-functions <user-functions>` 
+interface in order to facilitate the usage in conjunction with ``musrfit``. It consists of two libraries: 
+
+* ``libBNMR`` contains functions to fit spin lattice relaxation (SLR) data.
+* ``libLineProfile`` contains functions to fit resonance lineshapes.
+
+
+.. note:: 
+
+  Currently it is recommended to read in the data in ASCII format as a non-|mgr|\SR fit  :ref:`(fit type 8) <non-musr-fit>`.
+
+.. index:: libBNMR
+
+libBNMR
+++++++++++
+
+In |bgr|-NMR the SLR is usually measured by implanting a pulse of :math:`^8`\ Li with a length :math:`t_0` into the sample. 
+The asymmetry is measured both during the pulse and afterwards. For a a general spin relaxation function :math:`f(t)` the time evolution of the asymmetry is then given by [`Z. Salman, et al., PRL 96, 147601 (2006) <http://dx.doi.org/10.1103/PhysRevLett.96.147601>`_]: 
+
+
+
+.. index:: SLR
+.. _SLR:
+
+.. math::  
+   P(t) = \left\{\begin{matrix}
+  \frac{\int_0^t e^{-(t-t')/\tau_{\mathrm{Li}}}f(t-t')dt'}{\int_0^t e^{-t'/\tau_{\mathrm{Li}}}dt' }       &  t\leq t_0\\[6pt]
+  \frac{\int_0^{t_0}e^{-(t_0-t')/\tau_{\mathrm{Li}}}f(t-t')dt'}{\int_0^{t_0}e^{-t'/\tau_{\mathrm{Li}}}dt'}    &  t> t_0,
+  \end{matrix}\right.
+
+where :math:`\tau_{\mathrm{Li}}=1.21`\ s is the :math:`^8`\ Li lifetime.
+
+
+Functions
+^^^^^^^^^^^^
+The ``libBNMR`` library currently contains the following functions:
+
+
+
+
+.. index:: ExpRlx
+
+**Exponential relaxation**
+
+::
+
+  userFcn libBNMR ExpRlx 1 2
+
+The parameters are:
+
+#. pulse length :math:`t_0` (s)
+#. relaxation rate :math:`\lambda` (s\ :math:`^{-1}`\ )
+
+This function implements :math:`f(t)=e^{-\lambda t}`.
+
+.. index:: SExpRlx
+
+**Stretched exponential relaxation**
+
+::
+
+  userFcn libBNMR SExpRlx 1 2 3
+
+The parameters are:
+
+#. pulse length :math:`t_0` (s)
+#. relaxation rate :math:`\lambda` (s\ :math:`^{-1}`\ )
+#. stretching exponent :math:`\beta`
+
+This function implements :math:`f(t)=e^{-(\lambda t)^{\beta}}`.
+
+
+  
+.. index:: libLineProfile
+
+libLineProfile
++++++++++++++++++
+In addition to some simple line shapes ``libLineProfile`` contains functions to fit chemical shift anisotropies in the powder average.
+Their functional form can be found in  `M. Mehring, Principles of High Resolution NMR in Solids (Springer 1983) <http://dx.doi.org/10.1007/978-3-642-68756-3_2>`_.
+
+For an axially symmetric interaction it is given by:
+
+.. index:: Iax
+.. _Iax:
+
+.. math::
+
+      I_{\mathrm ax}(f)=\left\{\begin{matrix} \frac{1}{2\sqrt{(f_\parallel-f_\perp)(f-f_\perp)}}& f\in(f_\perp,f_\parallel)\cup(f_\parallel,f_\perp)\\[6pt] 0 & \text{otherwise}\end{matrix} \right.
+
+where :math:`f_\parallel` and :math:`f_\perp` are the frequencies that would be observed if the field is oriented paralell or perpendicular to the symmetry axis, respectively.
+
+
+| In case of a completely anisotropic interaction, the powder average can be described by the frequencies along the three principle axis :math:`f_1,f_2,f_3`.
+| Assume without loss of generality that :math:`f_1<f_2<f_3`, then
+
+.. index:: Ianiso
+.. _Ianiso:
+
+.. math::  
+      I(f)&=\left\{\begin{matrix}
+        \frac{K(m)}{\pi\sqrt{(f-f_1)(f_3-f_2)}},& f_3\geq f>f_2 \\[9pt]
+        \frac{K(m)}{\pi\sqrt{(f_3-f)(f_2-f_1)}},& f_2>f\geq f_1\\[9pt]
+        0 & \text{otherwise}
+      \end{matrix} \right.  \\
+ 	\\
+      m&=\left\{\begin{matrix}
+        \frac{(f_2-f_1)(f_3-f)}{(f_3-f_2)(f-f_1)},& f_3\geq f>f_2 \\[6pt]
+        \frac{(f-f_1)(f_3-f_2)}{(f_3-f)(f_2-f_1)},& f_2>f\geq f_1\\[6pt]
+      \end{matrix} \right.  \\
+ 	\\
+      K(m)&=\int_0^{\pi/2}\frac{\mathrm d\varphi}{\sqrt{1-m^2\sin^2{\varphi}}},
+
+
+:math:`K(m)` is the complete elliptic integral of the first kind.
+
+
+
+Functions
+^^^^^^^^^^^^
+The ``libLineProfile`` library currently contains the following functions:
+
+
+
+
+.. index:: LineGauss
+
+**Gaussian**
+
+::
+
+  userFcn  libLineProfile LineGauss 1 2
+
+The parameters are:
+
+#. center of the line :math:`f_0`
+#. FWHM of the line :math:`\sigma`
+
+| The height of the peak is 1.
+| The functional form is given by
+
+.. math::
+   A(f)=e^{-\frac{4\ln 2 (f-f_0)^2}{ \sigma^2}}
+
+
+.. index:: LineLorentzian
+
+**Lorentzian**
+
+::
+
+  userFcn  libLineProfile LineLorentzian 1 2
+
+The parameters are:
+
+#. center of the line :math:`f_0`
+#. FWHM of the line :math:`w`
+
+| The height of the peak is 1. 
+| The functional form is given by
+
+.. math::
+    A(f)= \frac{w^2}{4(f-f_0)^2+w^2}
+
+
+.. index:: LineLaplace
+
+**Laplacian**
+
+::
+
+  userFcn  libLineProfile LineLaplace 1 2
+
+The parameters are:
+
+#. center of the line :math:`f_0`
+#. FWHM of the line :math:`w`
+
+| The height of the peak is 1. 
+| The functional form is given by
+
+.. math::
+ A(f)=e^{-2\ln 2 \left|\frac{f-f_0}{w}\right|}
+
+
+
+.. index:: LineSkewLorentzian
+
+**Skewed Lorentzian**
+
+::
+
+  userFcn  libLineProfile LineSkewLorentzian 1 2 3
+
+The parameters are:
+
+#. center of the line :math:`f_0`
+#. width of the line :math:`w`
+#. skewness parameter :math:`a`
+
+| The height of the peak is 1. 
+| The functional form is given by
+
+.. math::
+    A(f)=  \frac{w w_a}{4(f-f_0)^2+w_a^2}, \quad w_a=\frac{2w}{1+e^{a(f-f_0)}}
+
+
+
+.. index:: LineSkewLorentzian2
+
+**Skewed Lorentzian 2**
+
+::
+
+  userFcn  libLineProfile LineSkewLorentzian2 1 2 3
+
+The parameters are:
+
+#. center of the line :math:`f_0`
+#. width left of the center :math:`w_1`
+#. width right of the center :math:`w_2`
+
+| The height of the peak is 1. 
+| The functional form is given by
+
+.. math::
+    A(f)=  \left\{\begin{matrix}\frac{{w_1}^2}{4{(f-f_0)}^2+{w_1}^2},&f\leq f_0\\[9pt] \frac{{w_2}^2}{4{(f-f_0)}^2+{w_2}^2},&f>f_0\end{matrix}\right.
+
+
+
+.. index:: PowderLineAxialLor
+
+
+**Powder average of an axially symmetric interaction convoluted with a Lorentzian**
+
+::
+
+  userFcn  libLineProfile PowderLineAxialLor 1 2 3
+
+The parameters are:
+
+#.  frequency for the field oriented paralell to the symmetry axis :math:`f_\parallel`
+#.  frequency for the field oriented perpendicular to the symmetry axis :math:`f_\parallel`
+#.  FWHM of the Lorentzian :math:`w`
+
+| The height of the peak is :math:`\sim`\ 1. 
+| The functional form is given by
+
+.. math::
+    A(f)= I_{\mathrm ax}(f)\circledast\left( \frac{w^2}{4f^2+w^2} \right)
+
+with :math:`I_{\mathrm ax}(f)` defined :ref:`above <Iax>`.
+
+    
+
+.. index:: PowderLineAxialGss
+
+
+**Powder average of an axially symmetric interaction convoluted with a Gaussian**
+
+::
+
+  userFcn  libLineProfile PowderLineAxialGss 1 2 3
+
+The parameters are:
+
+#.  frequency for the field oriented paralell to the symmetry axis :math:`f_\parallel`
+#.  frequency for the field oriented perpendicular to the symmetry axis :math:`f_\parallel`
+#. FWHM of the Gaussian :math:`\sigma`
+
+| The height of the peak is :math:`\sim`\ 1. 
+| The functional form is given by
+
+.. math::
+    A(f)= I_{\mathrm ax}(f)\circledast\left( e^{-\frac{4\ln 2 (f-f_0)^2}{ \sigma^2}} \right)
+
+with :math:`I_{\mathrm ax}(f)` defined :ref:`above <Iax>`.
+
+  
+
+.. index:: PowderLineAsymLor
+
+
+**Powder average of an anisotropic interaction convoluted with a Lorentzian**
+
+::
+
+  userFcn  libLineProfile PowderLineAsymLor 1 2 3 4
+
+The parameters are:
+
+#.   :math:`f_1`
+#.   :math:`f_1`
+#.   :math:`f_3` frequencies along the principal axes
+#. FWHM of the Lorentzian :math:`w`
+
+| The height of the peak is :math:`\sim`\ 1. 
+| The functional form is given by
+
+.. math::
+    A(f)= I(f)\circledast\left( \frac{w^2}{4f^2+w^2} \right)
+
+with :math:`I(f)` defined :ref:`above <Ianiso>`. Note that :math:`f_1<f_2<f_3` is not required by the code.
+  
+    
+    
+.. index:: PowderLineAsymGss
+
+
+**Powder average of an anisotropic interaction convoluted with a Gaussian**
+
+::
+
+  userFcn  libLineProfile PowderLineAsymGss 1 2 3 4
+
+The parameters are:
+
+#.   :math:`f_1`
+#.   :math:`f_1`
+#.   :math:`f_3` frequencies along the principal axes
+#. FWHM of the Gaussian :math:`\sigma`
+
+| The height of the peak is :math:`\sim`\ 1. 
+| The functional form is given by
+
+.. math::
+    A(f)= I(f)\circledast\left( e^{-\frac{4\ln 2 (f-f_0)^2}{ \sigma^2}} \right)
+
+with :math:`I(f)` defined :ref:`above <Ianiso>`. Note that :math:`f_1<f_2<f_3` is not required by the code.
+
+
+

doc/html/_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}

doc/html/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -15,6 +15,12 @@ div.clearer {
     clear: both;
 }
 
+div.section::after {
+    display: block;
+    content: '';
+    clear: left;
+}
+
 /* -- relbar ---------------------------------------------------------------- */
 
 div.related {
@@ -81,6 +87,10 @@ div.sphinxsidebar input {
     font-size: 1em;
 }
 
+div.sphinxsidebar #searchbox form.search {
+    overflow: hidden;
+}
+
 div.sphinxsidebar #searchbox input[type="text"] {
     float: left;
     width: 80%;
@@ -120,7 +130,7 @@ ul.search li a {
     font-weight: bold;
 }
 
-ul.search li div.context {
+ul.search li p.context {
     color: #888;
     margin: 2px 0 0 30px;
     text-align: left;
@@ -212,7 +222,7 @@ table.modindextable td {
 /* -- general body styles --------------------------------------------------- */
 
 div.body {
-    min-width: 450px;
+    min-width: 360px;
     max-width: 800px;
 }
 
@@ -227,6 +237,10 @@ a.headerlink {
     visibility: hidden;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -257,19 +271,25 @@ p.rubric {
     font-weight: bold;
 }
 
-img.align-left, .figure.align-left, object.align-left {
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
     clear: left;
     float: left;
     margin-right: 1em;
 }
 
-img.align-right, .figure.align-right, object.align-right {
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
     clear: right;
     float: right;
     margin-left: 1em;
 }
 
-img.align-center, .figure.align-center, object.align-center {
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+img.align-default, figure.align-default, .figure.align-default {
   display: block;
   margin-left: auto;
   margin-right: auto;
@@ -283,30 +303,45 @@ img.align-center, .figure.align-center, object.align-center {
     text-align: center;
 }
 
+.align-default {
+    text-align: center;
+}
+
 .align-right {
     text-align: right;
 }
 
 /* -- sidebars -------------------------------------------------------------- */
 
-div.sidebar {
+div.sidebar,
+aside.sidebar {
     margin: 0 0 0.5em 1em;
     border: 1px solid #ddb;
-    padding: 7px 7px 0 7px;
+    padding: 7px;
     background-color: #ffe;
     width: 40%;
     float: right;
+    clear: right;
+    overflow-x: auto;
 }
 
 p.sidebar-title {
     font-weight: bold;
 }
 
+nav.contents,
+aside.topic,
+div.admonition, div.topic, blockquote {
+    clear: left;
+}
+
 /* -- topics ---------------------------------------------------------------- */
 
+nav.contents,
+aside.topic,
 div.topic {
     border: 1px solid #ccc;
-    padding: 7px 7px 0 7px;
+    padding: 7px;
     margin: 10px 0 10px 0;
 }
 
@@ -328,10 +363,6 @@ div.admonition dt {
     font-weight: bold;
 }
 
-div.admonition dl {
-    margin-bottom: 0;
-}
-
 p.admonition-title {
     margin: 0px 10px 5px 0px;
     font-weight: bold;
@@ -342,9 +373,34 @@ div.body p.centered {
     margin-top: 25px;
 }
 
+/* -- content of sidebars/topics/admonitions -------------------------------- */
+
+div.sidebar > :last-child,
+aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
+div.topic > :last-child,
+div.admonition > :last-child {
+    margin-bottom: 0;
+}
+
+div.sidebar::after,
+aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
+div.topic::after,
+div.admonition::after,
+blockquote::after {
+    display: block;
+    content: '';
+    clear: both;
+}
+
 /* -- tables ---------------------------------------------------------------- */
 
 table.docutils {
+    margin-top: 10px;
+    margin-bottom: 10px;
     border: 0;
     border-collapse: collapse;
 }
@@ -354,6 +410,11 @@ table.align-center {
     margin-right: auto;
 }
 
+table.align-default {
+    margin-left: auto;
+    margin-right: auto;
+}
+
 table caption span.caption-number {
     font-style: italic;
 }
@@ -369,10 +430,6 @@ table.docutils td, table.docutils th {
     border-bottom: 1px solid #aaa;
 }
 
-table.footnote td, table.footnote th {
-    border: 0 !important;
-}
-
 th {
     text-align: left;
     padding-right: 5px;
@@ -387,22 +444,34 @@ table.citation td {
     border-bottom: none;
 }
 
+th > :first-child,
+td > :first-child {
+    margin-top: 0px;
+}
+
+th > :last-child,
+td > :last-child {
+    margin-bottom: 0px;
+}
+
 /* -- figures --------------------------------------------------------------- */
 
-div.figure {
+div.figure, figure {
     margin: 0.5em;
     padding: 0.5em;
 }
 
-div.figure p.caption {
+div.figure p.caption, figcaption {
     padding: 0.3em;
 }
 
-div.figure p.caption span.caption-number {
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
     font-style: italic;
 }
 
-div.figure p.caption span.caption-text {
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
 }
 
 /* -- field list styles ----------------------------------------------------- */
@@ -427,6 +496,74 @@ table.field-list td, table.field-list th {
     hyphens: manual;
 }
 
+/* -- hlist styles ---------------------------------------------------------- */
+
+table.hlist {
+    margin: 1em 0;
+}
+
+table.hlist td {
+    vertical-align: top;
+}
+
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+	font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.sig-name {
+	font-size: 1.1em;
+}
+
+code.descname {
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+	font-family: unset;
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+	color: #0033B3;
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+	color: #1750EB;
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+	color: #067D17;
+}
+
+
 /* -- other body styles ----------------------------------------------------- */
 
 ol.arabic {
@@ -449,11 +586,81 @@ ol.upperroman {
     list-style: upper-roman;
 }
 
+:not(li) > ol > li:first-child > :first-child,
+:not(li) > ul > li:first-child > :first-child {
+    margin-top: 0px;
+}
+
+:not(li) > ol > li:last-child > :last-child,
+:not(li) > ul > li:last-child > :last-child {
+    margin-bottom: 0px;
+}
+
+ol.simple ol p,
+ol.simple ul p,
+ul.simple ol p,
+ul.simple ul p {
+    margin-top: 0;
+}
+
+ol.simple > li:not(:first-child) > p,
+ul.simple > li:not(:first-child) > p {
+    margin-top: 0;
+}
+
+ol.simple p,
+ul.simple p {
+    margin-bottom: 0;
+}
+
+aside.footnote > span,
+div.citation > span {
+    float: left;
+}
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
+    margin-bottom: 0em;
+}
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
+    content: "";
+    clear: both;
+}
+
+dl.field-list {
+    display: grid;
+    grid-template-columns: fit-content(30%) auto;
+}
+
+dl.field-list > dt {
+    font-weight: bold;
+    word-break: break-word;
+    padding-left: 0.5em;
+    padding-right: 5px;
+}
+
+dl.field-list > dd {
+    padding-left: 0.5em;
+    margin-top: 0em;
+    margin-left: 0em;
+    margin-bottom: 0em;
+}
+
 dl {
     margin-bottom: 15px;
 }
 
-dd p {
+dd > :first-child {
     margin-top: 0px;
 }
 
@@ -467,6 +674,21 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+    margin-bottom: 0;
+}
+
 dt:target, span.highlighted {
     background-color: #fbe54e;
 }
@@ -480,14 +702,6 @@ dl.glossary dt {
     font-size: 1.1em;
 }
 
-.optional {
-    font-size: 1.3em;
-}
-
-.sig-paren {
-    font-size: larger;
-}
-
 .versionmodified {
     font-style: italic;
 }
@@ -526,11 +740,26 @@ dl.glossary dt {
     font-style: oblique;
 }
 
+.classifier:before {
+    font-style: normal;
+    margin: 0 0.5em;
+    content: ":";
+    display: inline-block;
+}
+
 abbr, acronym {
     border-bottom: dotted 1px;
     cursor: help;
 }
 
+.translated {
+    background-color: rgba(207, 255, 207, 0.2)
+}
+
+.untranslated {
+    background-color: rgba(255, 207, 207, 0.2)
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {
@@ -538,29 +767,69 @@ pre {
     overflow-y: hidden;  /* fixes display issues on Chrome browsers */
 }
 
+pre, div[class*="highlight-"] {
+    clear: both;
+}
+
 span.pre {
     -moz-hyphens: none;
     -ms-hyphens: none;
     -webkit-hyphens: none;
     hyphens: none;
+    white-space: nowrap;
+}
+
+div[class*="highlight-"] {
+    margin: 1em 0;
 }
 
 td.linenos pre {
-    padding: 5px 0px;
     border: 0;
     background-color: transparent;
     color: #aaa;
 }
 
 table.highlighttable {
-    margin-left: 0.5em;
+    display: block;
+}
+
+table.highlighttable tbody {
+    display: block;
+}
+
+table.highlighttable tr {
+    display: flex;
 }
 
 table.highlighttable td {
-    padding: 0 0.5em 0 0.5em;
+    margin: 0;
+    padding: 0;
+}
+
+table.highlighttable td.linenos {
+    padding-right: 0.5em;
+}
+
+table.highlighttable td.code {
+    flex: 1;
+    overflow: hidden;
+}
+
+.highlight .hll {
+    display: block;
+}
+
+div.highlight pre,
+table.highlighttable pre {
+    margin: 0;
+}
+
+div.code-block-caption + div {
+    margin-top: 0;
 }
 
 div.code-block-caption {
+    margin-top: 1em;
     padding: 2px 5px;
     font-size: small;
 }
@@ -569,8 +838,14 @@ div.code-block-caption code {
     background-color: transparent;
 }
 
-div.code-block-caption + div > div.highlight > pre {
-    margin-top: 0;
+table.highlighttable td.linenos,
+span.linenos,
+div.highlight span.gp {  /* gp: Generic.Prompt */
+  user-select: none;
+  -webkit-user-select: text; /* Safari fallback only */
+  -webkit-user-select: none; /* Chrome/Safari */
+  -moz-user-select: none; /* Firefox */
+  -ms-user-select: none; /* IE10+ */
 }
 
 div.code-block-caption span.caption-number {
@@ -582,21 +857,7 @@ div.code-block-caption span.caption-text {
 }
 
 div.literal-block-wrapper {
-    padding: 1em 1em 0;
-}
-
-div.literal-block-wrapper div.highlight {
-    margin: 0;
-}
-
-code.descname {
-    background-color: transparent;
-    font-weight: bold;
-    font-size: 1.2em;
-}
-
-code.descclassname {
-    background-color: transparent;
+    margin: 1em 0;
 }
 
 code.xref, a code {
@@ -637,8 +898,7 @@ span.eqno {
 }
 
 span.eqno a.headerlink {
-    position: relative;
-    left: 0px;
+    position: absolute;
     z-index: 1;
 }
 

doc/html/_static/css/badge_only.css

@@ -1 +1 @@
-.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-weight:normal;font-style:normal;src:url("../fonts/fontawesome-webfont.eot");src:url("../fonts/fontawesome-webfont.eot?#iefix") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff") format("woff"),url("../fonts/fontawesome-webfont.ttf") format("truetype"),url("../fonts/fontawesome-webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up{height:auto;max-height:100%}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}.rst-versions.rst-badge .icon-book{float:none}.rst-versions.rst-badge .fa-book{float:none}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}
+.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}

doc/html/_static/doctools.js

@@ -2,312 +2,155 @@
  * doctools.js
  * ~~~~~~~~~~~
  *
- * Sphinx JavaScript utilities for all documentation.
+ * Base JavaScript utilities for all Sphinx HTML documentation.
  *
- * :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
+"use strict";
 
-/**
- * select a different prefix for underscore
- */
-$u = _.noConflict();
+const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
+  "TEXTAREA",
+  "INPUT",
+  "SELECT",
+  "BUTTON",
+]);
 
-/**
- * make the code below compatible with browsers without
- * an installed firebug like debugger
-if (!window.console || !console.firebug) {
-  var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
-    "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
-    "profile", "profileEnd"];
-  window.console = {};
-  for (var i = 0; i < names.length; ++i)
-    window.console[names[i]] = function() {};
-}
- */
-
-/**
- * small helper function to urldecode strings
- */
-jQuery.urldecode = function(x) {
-  return decodeURIComponent(x).replace(/\+/g, ' ');
-};
-
-/**
- * small helper function to urlencode strings
- */
-jQuery.urlencode = encodeURIComponent;
-
-/**
- * This function returns the parsed url parameters of the
- * current request. Multiple values per key are supported,
- * it will always return arrays of strings for the value parts.
- */
-jQuery.getQueryParameters = function(s) {
-  if (typeof s === 'undefined')
-    s = document.location.search;
-  var parts = s.substr(s.indexOf('?') + 1).split('&');
-  var result = {};
-  for (var i = 0; i < parts.length; i++) {
-    var tmp = parts[i].split('=', 2);
-    var key = jQuery.urldecode(tmp[0]);
-    var value = jQuery.urldecode(tmp[1]);
-    if (key in result)
-      result[key].push(value);
-    else
-      result[key] = [value];
-  }
-  return result;
-};
-
-/**
- * highlight a given string on a jquery object by wrapping it in
- * span elements with the given class name.
- */
-jQuery.fn.highlightText = function(text, className) {
-  function highlight(node, addItems) {
-    if (node.nodeType === 3) {
-      var val = node.nodeValue;
-      var pos = val.toLowerCase().indexOf(text);
-      if (pos >= 0 &&
-          !jQuery(node.parentNode).hasClass(className) &&
-          !jQuery(node.parentNode).hasClass("nohighlight")) {
-        var span;
-        var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
-        if (isInSVG) {
-          span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+const _ready = (callback) => {
+  if (document.readyState !== "loading") {
+    callback();
   } else {
-          span = document.createElement("span");
-          span.className = className;
+    document.addEventListener("DOMContentLoaded", callback);
   }
-        span.appendChild(document.createTextNode(val.substr(pos, text.length)));
-        node.parentNode.insertBefore(span, node.parentNode.insertBefore(
-          document.createTextNode(val.substr(pos + text.length)),
-          node.nextSibling));
-        node.nodeValue = val.substr(0, pos);
-        if (isInSVG) {
-          var bbox = span.getBBox();
-          var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-       	  rect.x.baseVal.value = bbox.x;
-          rect.y.baseVal.value = bbox.y;
-          rect.width.baseVal.value = bbox.width;
-          rect.height.baseVal.value = bbox.height;
-          rect.setAttribute('class', className);
-          var parentOfText = node.parentNode.parentNode;
-          addItems.push({
-              "parent": node.parentNode,
-              "target": rect});
-        }
-      }
-    }
-    else if (!jQuery(node).is("button, select, textarea")) {
-      jQuery.each(node.childNodes, function() {
-        highlight(this, addItems);
-      });
-    }
-  }
-  var addItems = [];
-  var result = this.each(function() {
-    highlight(this, addItems);
-  });
-  for (var i = 0; i < addItems.length; ++i) {
-    jQuery(addItems[i].parent).before(addItems[i].target);
-  }
-  return result;
 };
 
-/*
- * backward compatibility for jQuery.browser
- * This will be supported until firefox bug is fixed.
- */
-if (!jQuery.browser) {
-  jQuery.uaMatch = function(ua) {
-    ua = ua.toLowerCase();
-
-    var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
-      /(webkit)[ \/]([\w.]+)/.exec(ua) ||
-      /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
-      /(msie) ([\w.]+)/.exec(ua) ||
-      ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
-      [];
-
-    return {
-      browser: match[ 1 ] || "",
-      version: match[ 2 ] || "0"
-    };
-  };
-  jQuery.browser = {};
-  jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
-}
-
 /**
  * Small JavaScript module for the documentation.
  */
-var Documentation = {
-
-  init : function() {
-    this.fixFirefoxAnchorBug();
-    this.highlightSearchWords();
-    this.initIndexTable();
-    
+const Documentation = {
+  init: () => {
+    Documentation.initDomainIndexTable();
+    Documentation.initOnKeyListeners();
   },
 
   /**
    * i18n support
    */
-  TRANSLATIONS : {},
-  PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
-  LOCALE : 'unknown',
+  TRANSLATIONS: {},
+  PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
+  LOCALE: "unknown",
 
   // gettext and ngettext don't access this so that the functions
   // can safely bound to a different name (_ = Documentation.gettext)
-  gettext : function(string) {
-    var translated = Documentation.TRANSLATIONS[string];
-    if (typeof translated === 'undefined')
-      return string;
-    return (typeof translated === 'string') ? translated : translated[0];
+  gettext: (string) => {
+    const translated = Documentation.TRANSLATIONS[string];
+    switch (typeof translated) {
+      case "undefined":
+        return string; // no translation
+      case "string":
+        return translated; // translation exists
+      default:
+        return translated[0]; // (singular, plural) translation tuple exists
+    }
   },
 
-  ngettext : function(singular, plural, n) {
-    var translated = Documentation.TRANSLATIONS[singular];
-    if (typeof translated === 'undefined')
-      return (n == 1) ? singular : plural;
-    return translated[Documentation.PLURALEXPR(n)];
+  ngettext: (singular, plural, n) => {
+    const translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated !== "undefined")
+      return translated[Documentation.PLURAL_EXPR(n)];
+    return n === 1 ? singular : plural;
   },
 
-  addTranslations : function(catalog) {
-    for (var key in catalog.messages)
-      this.TRANSLATIONS[key] = catalog.messages[key];
-    this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
-    this.LOCALE = catalog.locale;
+  addTranslations: (catalog) => {
+    Object.assign(Documentation.TRANSLATIONS, catalog.messages);
+    Documentation.PLURAL_EXPR = new Function(
+      "n",
+      `return (${catalog.plural_expr})`
+    );
+    Documentation.LOCALE = catalog.locale;
   },
 
   /**
-   * add context elements like header anchor links
+   * helper function to focus on search bar
    */
-  addContextElements : function() {
-    $('div[id] > :header:first').each(function() {
-      $('<a class="headerlink">\u00B6</a>').
-      attr('href', '#' + this.id).
-      attr('title', _('Permalink to this headline')).
-      appendTo(this);
-    });
-    $('dt[id]').each(function() {
-      $('<a class="headerlink">\u00B6</a>').
-      attr('href', '#' + this.id).
-      attr('title', _('Permalink to this definition')).
-      appendTo(this);
+  focusSearchBar: () => {
+    document.querySelectorAll("input[name=q]")[0]?.focus();
+  },
+
+  /**
+   * Initialise the domain index toggle buttons
+   */
+  initDomainIndexTable: () => {
+    const toggler = (el) => {
+      const idNumber = el.id.substr(7);
+      const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
+      if (el.src.substr(-9) === "minus.png") {
+        el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
+        toggledRows.forEach((el) => (el.style.display = "none"));
+      } else {
+        el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
+        toggledRows.forEach((el) => (el.style.display = ""));
+      }
+    };
+
+    const togglerElements = document.querySelectorAll("img.toggler");
+    togglerElements.forEach((el) =>
+      el.addEventListener("click", (event) => toggler(event.currentTarget))
+    );
+    togglerElements.forEach((el) => (el.style.display = ""));
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
+  },
+
+  initOnKeyListeners: () => {
+    // only install a listener if it is really needed
+    if (
+      !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
+      !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+    )
+      return;
+
+    document.addEventListener("keydown", (event) => {
+      // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      // bail with special keys
+      if (event.altKey || event.ctrlKey || event.metaKey) return;
+
+      if (!event.shiftKey) {
+        switch (event.key) {
+          case "ArrowLeft":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const prevLink = document.querySelector('link[rel="prev"]');
+            if (prevLink && prevLink.href) {
+              window.location.href = prevLink.href;
+              event.preventDefault();
+            }
+            break;
+          case "ArrowRight":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const nextLink = document.querySelector('link[rel="next"]');
+            if (nextLink && nextLink.href) {
+              window.location.href = nextLink.href;
+              event.preventDefault();
+            }
+            break;
+        }
+      }
+
+      // some keyboard layouts may need Shift to get /
+      switch (event.key) {
+        case "/":
+          if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
+          Documentation.focusSearchBar();
+          event.preventDefault();
+      }
     });
   },
-
-  /**
-   * workaround a firefox stupidity
-   * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
-   */
-  fixFirefoxAnchorBug : function() {
-    if (document.location.hash && $.browser.mozilla)
-      window.setTimeout(function() {
-        document.location.href += '';
-      }, 10);
-  },
-
-  /**
-   * highlight the search words provided in the url in the text
-   */
-  highlightSearchWords : function() {
-    var params = $.getQueryParameters();
-    var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
-    if (terms.length) {
-      var body = $('div.body');
-      if (!body.length) {
-        body = $('body');
-      }
-      window.setTimeout(function() {
-        $.each(terms, function() {
-          body.highlightText(this.toLowerCase(), 'highlighted');
-        });
-      }, 10);
-      $('<p class="highlight-link"><a href="javascript:Documentation.' +
-        'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
-          .appendTo($('#searchbox'));
-    }
-  },
-
-  /**
-   * init the domain index toggle buttons
-   */
-  initIndexTable : function() {
-    var togglers = $('img.toggler').click(function() {
-      var src = $(this).attr('src');
-      var idnum = $(this).attr('id').substr(7);
-      $('tr.cg-' + idnum).toggle();
-      if (src.substr(-9) === 'minus.png')
-        $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
-      else
-        $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
-    }).css('display', '');
-    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
-        togglers.click();
-    }
-  },
-
-  /**
-   * helper function to hide the search marks again
-   */
-  hideSearchWords : function() {
-    $('#searchbox .highlight-link').fadeOut(300);
-    $('span.highlighted').removeClass('highlighted');
-  },
-
-  /**
-   * make the url absolute
-   */
-  makeURL : function(relativeURL) {
-    return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
-  },
-
-  /**
-   * get the current relative url
-   */
-  getCurrentURL : function() {
-    var path = document.location.pathname;
-    var parts = path.split(/\//);
-    $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
-      if (this === '..')
-        parts.pop();
-    });
-    var url = parts.join('/');
-    return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
-  },
-
-  initOnKeyListeners: function() {
-    $(document).keyup(function(event) {
-      var activeElementType = document.activeElement.tagName;
-      // don't navigate when in search box or textarea
-      if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') {
-        switch (event.keyCode) {
-          case 37: // left
-            var prevHref = $('link[rel="prev"]').prop('href');
-            if (prevHref) {
-              window.location.href = prevHref;
-              return false;
-            }
-          case 39: // right
-            var nextHref = $('link[rel="next"]').prop('href');
-            if (nextHref) {
-              window.location.href = nextHref;
-              return false;
-            }
-        }
-      }
-    });
-  }
 };
 
 // quick alias for translations
-_ = Documentation.gettext;
+const _ = Documentation.gettext;
 
-$(document).ready(function() {
-  Documentation.init();
-});
+_ready(Documentation.init);

doc/html/_static/documentation_options.js

@@ -1,9 +1,13 @@
-var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '1.9.3',
-    LANGUAGE: 'None',
+const DOCUMENTATION_OPTIONS = {
+    VERSION: '1.9.9',
+    LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
+    BUILDER: 'html',
     FILE_SUFFIX: '.html',
+    LINK_SUFFIX: '.html',
     HAS_SOURCE: true,
-    SOURCELINK_SUFFIX: '.txt'
+    SOURCELINK_SUFFIX: '.txt',
+    NAVIGATION_WITH_KEYS: false,
+    SHOW_SEARCH_SUMMARY: true,
+    ENABLE_SEARCH_SHORTCUTS: true,
 };