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 ofmusrfitwhich makes it accessible to a broader audience! Many thanks Bastian!
-- Uldis Locans
I am very much indebted to Uldis work on 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!
+- 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 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!
-
+
« MusrRoot - an Extensible Open File Format for μSR @@ -66,10 +77,10 @@ extremely competent way to deal with his projects as well as to deal with the ch
- musrfit 1.7.6 documentation
+ + ++ musrfit 1.8.0 documentation
any2many - a Universal μSR-file-format converter
- « msr2data - A Program for Automatically Processing Multiple musrfit msr Files
+ « msr2data - A Program for Automatically Processing Multiple musrfit msr Files
::
Contents
::
@@ -33,21 +44,21 @@
- « msr2data - A Program for Automatically Processing Multiple musrfit msr Files
+ « msr2data - A Program for Automatically Processing Multiple musrfit msr Files
::
Contents
::
@@ -56,10 +67,10 @@ For a detailed description see
- © Copyright 2021, Andreas Suter.
- Last updated on Oct 02, 2021.
- Created using Sphinx 3.4.3.
+
- musrfit 1.7.6 documentation
+ + ++ musrfit 1.8.0 documentation
Bugtracking
« Acknowledgements @@ -30,7 +41,7 @@
« Acknowledgements @@ -52,10 +63,10 @@ or send an e-mail to A. Suter at PSI.
- musrfit 1.7.6 documentation
+ + ++ musrfit 1.8.0 documentation
How to Cite musrfit?
« Welcome to the musrfit documentation!
::
Contents
::
- Tutorial for musrfit »
+ Tutorial for musrfit »
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
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 μSR Data Analysis”, Physics Procedia 30, 69 (2012). http://dx.doi.org/10.1016/j.phpro.2012.04.042
- A. Suter, B.M. Wojek, “Musrfit: A Free Platform-Independent Framework for μ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
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
- 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
« Welcome to the musrfit documentation!
::
Contents
::
- Tutorial for musrfit »
+ Tutorial for musrfit »
- musrfit 1.7.6 documentation
+ + + + + + + + + + + -Symbols
|
+
|
A
|
-
|
+
|
+
|
B
|
-
|
+
|
+
|
C
|
-
|
+
|
+
|
D
|
-
|
+
|
+
|
E
|
+
|
F
| - | + |
|
+
|
G
|
-
|
+ + |
|
H
|
-
|
+
|
+
|
I
|
-
|
+
|
+
|
L
|
-
|
+
|
+
|
M
N
|
-
|
+
|
+
|
O
|
+
|
P
|
-
|
+
|
+
|
Q
|
+
|
R
|
-
|
+
|
+
|
S
|
-
|
+
|
+
|
T
|
-
|
+
|
+
|
U
| - |
|
+
|
+
|
V
|
-
|
+
|
+
|
X
|
+
|
Contents @@ -597,10 +951,10 @@
- musrfit 1.7.6 documentation
+ + ++ musrfit 1.8.0 documentation
Welcome to the musrfit documentation!
Contents
::
- How to Cite musrfit? »
+ How to Cite musrfit? »
Welcome to the musrfit documentation!¶
-
-
- How to Cite
musrfit?
- - Tutorial for
musrfit
- - Setting up
musrfiton Different Platforms-
+
- Setting up musrfit on Different Platforms -
- Setting up
musrfit/DKS: High Speed Fitting with GPU’s-
-
- Setting up
musrfit/DKSfor a Tesla K40c (NVIDIA)
- - Setting up
musrfit/DKSfor a AMD Graphic Card (Radeon R9 390X)
- - Setting up
musrfit/DKSfor macOS for OpenCL support
+ - Setting up musrfit / DKS: High Speed Fitting with GPU’s -
musredit: the GUI Based Interface tomusrfit-
+
- musredit: the GUI Based Interface to musrfit -
- msr2data - A Program for Automatically Processing Multiple
musrfitmsr Files-
+
- msr2data - A Program for Automatically Processing Multiple musrfit msr Files
- Basic Types of Usage
- Optional Parameters
- The Global Mode @@ -116,27 +127,27 @@
Indices and tables¶
- msr2data - A Program for Automatically Processing Multiple musrfit msr Files
- Setting up
Contents
::
- How to Cite musrfit? »
+ How to Cite musrfit? »
- musrfit 1.7.6 documentation
+ + ++ musrfit 1.8.0 documentation
msr2data - A Program for Automatically Processing Multiple musrfit msr Files
« mupp - μSR Parameter Plotter @@ -33,74 +44,76 @@
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 1 or a column ASCII file. This allows essentially to
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 [1] or a column ASCII file. This allows essentially to
-
-
Collect the fit parameters.
-Generate new input msr files based on old ones.
+- Collect the fit parameters. +
- Generate new input msr files based on old ones.
-
-
- 1 -
For an abridged description of this format see here. The DB files -produced by
msr2datacan be viewed for instance with mupp or μView see here, however, -they are not completely backward-compatible to the originaldb languagesince the parameter names can be longer than five or ++
[1] For an abridged description of this format see here. The DB files +produced by msr2data can be viewed for instance with mupp or μView see here, 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! - - +parameter names in the msr files! Basic Types of Usage¶
-Apart from numerous optional parameters that might be set, in principle there are four different ways of calling
msr2data. +Apart from numerous optional parameters 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 <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 below.
+- 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 below.
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-andnoheaderoptions as shall be seen later.
-If the
-musrfitoutput files do not have an<extension>as specified above like8472.msrone has to callmsr2datalike in the following example:$ msr2data 8472 8460 "" +
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:
+$ msr2data 8472 8460 ""
noheaderOptional Parameters¶
-As mentioned already above there are some optional parameters which change the behavior of
-msr2dataand 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,
-msr2datawrites 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-16will 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 defaultout.dborout.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
-msr2datawill invokemusrfitto fit the specified runs. -All msr files are assumed to be present, none is newly generated!
-- fit-<template>[!]
Additionally to the final data collection
-msr2datawill generate msr files for the runs specified in the list -of runs and invoke 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 callingmusrfitand 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 - -keep-mn2-output option is passed tomusrfit. -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,musrfitis called with -the - -title-from-data-file option. If no fitting is done, this option is ignored.
+- 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 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 - -keep-mn2-output 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 - -title-from-data-file option. If no fitting is done, this option is ignored.
- run-specific parameters
these parameters are tagged with the current run number in the format
-%0Xu, i.e.Xdigits with leading zeros, -at the end of the parameter name, e.g. for a 4-digit-formatted run numberalpha0123if the run number was 123 or -for a 8-digit-formatted run numberalpha00123456if the run number was 123456.Xhas to be at least 4.
-- common parameters
all parameters that are not run specific
-
+- 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 order of the parameters has to match the one described above, meaning the common parameters are listed first followed by +
- 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.
+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.
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.Xdigits with leading zeros, and has to be the rightmost number given in this -format in the file name.Xhas to be at least 4. The highest treatable run number is \(2^{32}-1 = 4294967295\).
-In order to keep
msr2dataworking properly the msr files should only contain one STATISTIC block at the end of the file and one FITPARAMETER block -right after the TITLE —musrfititself 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. ADDRUN statements are simply -copied! Since this is most probably not what one likes to do, it is suggested not to use thefit-<template>andmsr-<template>options if -ADDRUN statements were present in the template file.
-msr2datawill 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 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 \(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. 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.
and 2. Choose one of the ways to specify your list of runs as described under basic usage.
+- and 2. Choose one of the ways to specify your list of runs as described under basic usage.
Give the file extension here, e.g.
_zffor files like8472_zf.msr. If the files do not have an extension this -field stays empty.musredittakes care of passing the “” tomsr2dataas mentioned above.
-Activates the
fit-<template>option if<template>is entered. In case the optionChain Fitis not set the +- 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. +
- 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! -
Activates the
-o <outputFileName>option if<outputFileName>is entered. If nothing is entered the default output fileout.dborout.datis used.
+fit serves as template for the second and so on. The template field stays empty if no fits should be performed!
+- Activates the -o <outputFileName> option if <outputFileName> is entered. If nothing is entered the default output file out.db or out.dat is used.
shows the list of loaded collections. A collection is defined as
db- ordat-file (typically the -output from msr2data). If you call the open-dialog and select a collection of -msr-files,muppwill callmsr2dataand tries to generate a collection on-the-fly.
-in this list, the data-tags of the currently selected collection is presented. The data-tags can be -directly dragged over to the
x- andy-axis list. Another way is to select the data-tag -wished and clickadd Xto add the selected data-tag to thex-axis list. Analogous it is done -for they-axis.
-x-axis list. The labels are followed by(-X-)where the numberXcorresponds to the -selection it corresponds to. The numbering of the collection is as given in the collection list.
-y-axis list. The labels are followed by(-X-)where the numberXcorresponds to the -selection it corresponds to. The numbering of the collection is as given in the collection list.
-add Xallows to add the currently selected data-tag to thex-axis list.
-add Yallows to add the currently selected data-tag to they-axis list.
-remove Xwill remove the selectedx-axis tag.
-remove Ywill remove the selectedy-axis tag.
-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- andy-axis tags for each collection, you can do the following: -you addx- andy-axis data-tags for the first collection. Afterwards you select all the other -collections of interest and click onAdd Ditto.muppwill then add the corresponding -x- andy-axis data-tags accordingly. This is less error prone and quicker!
-Clicking the
-Plotbutton will invokemupp_plot(aROOTbased application) which will -present the data, as shown here
+
-
+
shows the list of loaded collections. A collection is defined as db- or dat-file (typically the +output from 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.
+
+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.
+
+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.
+
+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.
+
+add X allows to add the currently selected data-tag to the x-axis list.
+
+add Y allows to add the currently selected data-tag to the y-axis list.
+
+remove X will remove the selected x-axis tag.
+
+remove Y will remove the selected y-axis tag.
+
+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!
+
+Clicking the Plot button will invoke mupp_plot (a ROOT based application) which will +present the data, as shown here
+
+
+Remove Collection: will remove the selected collection
+
+Refresh Collection: will reload the collection (db- or dat-file). This is often useful +during beamtime where the collection is growing run-by-run.
+
+Command history window.
+
+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.
-Remove Collection: will remove the selected collection
-Refresh Collection: will reload the collection (db- ordat-file). This is often useful -during beamtime where the collection is growing run-by-run.
-Command history window.
-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'sfor the currently available -commands.
Define Variable Dialog¶
-
-
-
Variable text edit window.
-Collection link window.
-Shows the parameters of the selected collection.
-Check if the variable/error variable from the edit window is valid.
-Add the variable to the selected collection(s) if the parsing is successful.
+- Variable text edit window. +
- Collection link window. +
- Shows the parameters of the selected collection. +
- Check if the variable/error variable from the edit window is valid. +
- 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 asSigmaSC_10Err.Currently the following mathematical functions are defined:
+as SigmaSC_10 (see the above snapshot), the error variable need to be named as SigmaSC_10Err. +max,min,abs,sin,cos, -tan,exp,log,ln,pow.Currently the following mathematical functions are defined: max, min, abs, sin, cos, +tan, exp, log, ln, pow.
- 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- anddat-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. +
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 +mupp command line summary. 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.
-dataTis addressed by$dataT, etc. An example:
+via the ‘$’, e.g. dataT is addressed by $dataT, etc. An example: +var invT = 1000.0 / $dataTvar invT = 1000.0 / $dataT
Each variable has to be accompanied by its error variable. An error variable -is defined by the
-<var_name>followed byErr+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.
+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.txtmight look like this:# This is a comment +
An example script file sigmaSC-vs-temp.txt might look like this:
+# This is a comment # Script: sigmaSC-vs-temp.txt loadPath ./ @@ -191,7 +216,7 @@ macro SigmaSCVsTemp.C
The Usage Summary¶
-usage: mupp [OPTIONS] [[--path <fit-param-path>] <fit-param-file-names>] +
-usage: mupp [OPTIONS] [[--path <fit-param-path>] <fit-param-file-names>] OPTIONS: -h, --help: this help @@ -239,22 +264,22 @@ SCRIPT COMMANDS:+-- «
musredit: the GUI Based Interface tomusrfit+ « musredit: the GUI Based Interface to musrfit :: Contents :: - msr2data - A Program for Automatically Processing Multiplemusrfitmsr Files » + msr2data - A Program for Automatically Processing Multiple musrfit msr Files »- © Copyright 2021, Andreas Suter. - Last updated on Oct 02, 2021. - Created using Sphinx 3.4.3. + \ No newline at end of file diff --git a/doc/html/musr-root.html b/doc/html/musr-root.html index e693db77..64021976 100644 --- a/doc/html/musr-root.html +++ b/doc/html/musr-root.html @@ -1,28 +1,39 @@ + - - + - - -MusrRoot - an Extensible Open File Format for μSR — musrfit 1.7.6 documentation - + + +MusrRoot - an Extensible Open File Format for μSR — musrfit 1.8.0 documentation + - - - - - - - + + + + + + + + - -- musrfit 1.7.6 documentation
+ + +-+ musrfit 1.8.0 documentation
MusrRoot - an Extensible Open File Format for μSR
+-« any2many - a Universal μSR-file-format converter @@ -33,213 +44,214 @@
+MusrRoot - an Extensible Open File Format for μSR¶
Until 2011 different μSR file formats were used within PSI. The bulk-μSR instruments were -writing their data in the
+was decided to move forward to a open file format called MusrRoot to be described in the following.PSI-BINfile format, which is a fixed binary format with rather stringent +writing their data in the PSI-BIN file format, which is a fixed binary format with rather stringent limitations. The LE-μ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 calledMusrRootto be described in the following.Some Basics Concerning ROOT Files¶
The μSR data acquisition systems at PSI are utilizing MIDAS (see Midas Home Page). The MIDAS analyzer, which is responsible to build histograms, especially the μSR decay histograms, makes it very easy to build ROOT (see ROOT/CERN home page ) histogram objects (these -are
-TH1Fobjects for μSR decay histograms). ROOT is aC++object-oriented data mining and -analysis frame work. These histograms can be collected and saved in ROOT files (TFile). In order to ease +are TH1F objects for μ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) and ROOT/CERN Reference Guide.ROOT files (
-TFile) are binary files which can hold any kind of objects. ATFileis organized similarly -to a directory structure of an operating system. Within the ROOT framework, there is aTFilebrowser available -which allows to inspect these files. This browser (TBrowser) will show all object saved in theTFiledirectly, -if they derive fromTObject.The
+MusrRootfile format to be described below is only using a small subset of possible ROOT objects, namely: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 theMusrRootfile.
-TH1F: Hold the μ-decay-histograms.
-TObjArray: Holding collection of header information.
-TObjString: Holding the content of any header information.
+- TFolder: this are the top level objects in the MusrRoot file. +
- TH1F: Hold the μ-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 theTBrowser-object. +Since all these objects are deriving form TObject, they will be directly accessible via the TBrowser-object. For instance, the μ-decay-histograms can be directly plotted, are even fitted, out of the box.
MusrRoot an Extensible Open File Format for μ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 - ... +
-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 μSR decay histograms. There can be as many as needed, especially there is no limitation about their length. The histogram object names will behDecayXXX, whereXXX(leading zero int, i.e.%03d-inC/C++notation, starting with ‘1’) is the histogram number. The title and name of the histogram (see description of theTH1FROOT class) contains the label of the histogram, like ‘top’, ‘forward’, etc. How many of these histograms are present is accessible through theRunInfofolder in which the necessary header information are found (details see next sections). The folderSCAnaModulecontains 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.where hDecay001, etc. are ROOT histograms (to be more specific: TH1F), containing the μ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
-RunHeadercontains all needed meta-information to describe a μSR-run. The list of the minimal number of required “folders” of theRunHeaderis given in the following structure:RunHeader (TFolder) ---| - |- RunInfo (TObjArray) - |- DetectorInfo (TObjArray) - |- SampleEnvironmentInfo (TObjArray) - |- MagneticFieldEnvironmentInfo (TObjArray) - |- BeamlineInfo (TObjArray) +
Run Information Contained in RunHeader¶
+The RunHeader contains all needed meta-information to describe a μ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.
-RunInfocontains most information relevant for the user and will be itemized in RunInfo Overview and RunInfo Required.DetectorInfocontains detector specific information, like detector name, time zero bin, etc. (details is found under DetectorInfo Required).SampleEnvironmentInfo(details under SampleEnvironmentInfo Required), andMagneticFieldEnvironmentInfo(details under MagneticFieldEnvironmentInfo Required) store additional, more detailed information concerning the sample environment.BeamlineInfostores beamline relevant information (details under BeamlineInfo Required).Before elaborating more on the required items within this structure, a few words on the ROOT types used here:
+RunHeaderis aTFolderobject. All the “sub-directory” entries are of typeTObjArrayand collect items of typeTObjStringor otherTObjArray(i.e. sub-directories and sub-sub-directories, etc.).In brackets the object type is given. RunInfo contains most information relevant for the user and will be itemized in RunInfo Overview and RunInfo Required. DetectorInfo contains detector specific information, like detector name, time zero bin, etc. (details is found under DetectorInfo Required). SampleEnvironmentInfo (details under SampleEnvironmentInfo Required), and MagneticFieldEnvironmentInfo (details under MagneticFieldEnvironmentInfo Required) store additional, more detailed information concerning the sample environment. BeamlineInfo stores beamline relevant information (details under BeamlineInfo 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.).
-
-RunInfoOverview¶+
RunInfo Overview¶
+
-- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Version
TStringGIT version of
TMusrRunHeaderVersion +TString +GIT version of TMusrRunHeader Generic Validator URL
TStringURL of the generic
MusrRootvalidation xsd-file.Generic Validator URL +TString +URL of the generic MusrRoot validation xsd-file. Specific Validator URL
TStringURL of the instrument specific validation xsd-file.
Specific Validator URL +TString +URL of the instrument specific validation xsd-file. Generator
TStringProgram which wrote the
MusrRootfile, e.g.nemu_analyzerGenerator +TString +Program which wrote the MusrRoot file, e.g. nemu_analyzer File Name
TStringFile name of the
MusrRootfile, e.g.deltat_tdc_gps_4295.rootFile Name +TString +File name of the MusrRoot file, e.g. deltat_tdc_gps_4295.root Run Title
TString+ Run Title +TString +Run Number
Int_t+ Run Number +Int_t +Run Start Time
TStringISO 8601 date time
Run Start Time +TString +ISO 8601 date time Run Stop Time
TStringISO 8601 date time
Run Stop Time +TString +ISO 8601 date time Run Duration
TMusrRunPhysicalQuantityrun duration in sec
Run Duration +TMusrRunPhysicalQuantity +run duration in sec Laboratory
TStringe.g. PSI
Laboratory +TString +e.g. PSI Instrument
TStringe.g. GPS
Instrument +TString +e.g. GPS Muon Beam Momentum
TMusrRunPhysicalQuantitye.g. 28.1 MeV/c
Muon Beam Momentum +TMusrRunPhysicalQuantity +e.g. 28.1 MeV/c Muon Species
TStringpositive, or negative muon
Muon Species +TString +positive, or negative muon Muon Source
TStringe.g. Target E - Low Energy Muons or “Target M” …
Muon Source +TString +e.g. Target E - Low Energy Muons or “Target M” ... Setup
TString+ Setup +TString +Comment
TString+ Comment +TString +Sample Name
TString+ Sample Name +TString +Sample Temperature
TMusrRunPhysicalQuantitye.g. 3.21 +- 0.05 K; SP: 3.2; CF1
Sample Temperature +TMusrRunPhysicalQuantity +e.g. 3.21 +- 0.05 K; SP: 3.2; CF1 Sample Magnetic Field
TMusrRunPhysicalQuantitye.g. 350.002 +- 0.005 G; SP: 350; WXY
Sample Magnetic Field +TMusrRunPhysicalQuantity +e.g. 350.002 +- 0.005 G; SP: 350; WXY No of Histos
Int_t+ No of Histos +Int_t +Time Resolution
TMusrRunPhysicalQuantitye.g. 0.1953125 ns
Time Resolution +TMusrRunPhysicalQuantity +e.g. 0.1953125 ns RedGreen Offsets
TIntVectore.g. 0; 20
RedGreen Offsets +TIntVector +e.g. 0; 20 These entries should be clear except for the
+RedGreen Offsetsand the column “Internal Type” which shortly will be discussed before specifying the content of the other required folders.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. +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 Offsetswere introduced. One selection of 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 DetectorInfo Required). The entryNo of Histoswill only give 8 for the given example, -meaning that red/green multiplication is defined rather viaRedGreen Offsetsthan the number of histograms.
-Internal Types: in order to ease the handling of the
+MusrRootrun header, a classTMusrRunHeaderis available which deals -with it. The “Internal Type” specified, corresponds to the internal representation in within this class. In theMusrRootfile -these entries are all saved as browsable ROOT strings (TObjStringv). The only special type is ``TMusrRunPhysicalQuantitywhich +(see DetectorInfo 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:
-@@ -247,39 +259,39 @@ is introduced to deal with physical quantities. They always can be represented i<property name> <value> +- <estimated error> <unit>; SP: <demand>; <description> +
-<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 TMusrRunPhysicalQuantity - Possible Representations.A mock-up
+TBrowserprint-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, whereXis 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.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 TMusrRunPhysicalQuantity - Possible Representations.
+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.
-
+TMusrRunHeadermock up. The red shaded entries are of typeTMusrRunPhysicalQuantityTMusrRunHeader mock up. The red shaded entries are of type TMusrRunPhysicalQuantity
TMusrRunHeader Concept¶
The different μ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.
+- 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 (
+TMusrRunHeaderand 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))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 TMusrRunPhysicalQuantity - Possible Representations
-Collection of strings, represented by
TStringVector
-Collection of integers, represented by
TIntVector
-Collection of floating point numbers, represented by
TDoubleVector
+- Strings, represented by TString +
- Integers, represented by Int_t +
- Floating point numbers, represented by Double_t +
- Physical quantities, represented by TMusrRunPhysicalQuantity - Possible Representations +
- 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
+TMusrRunHeaderis implementing this run header concept. In following section code snippets will be discussed, showing how this is used on level of theMIDASanalyzer,musrfitreader routine, andany2manyconversion routines. The section Validation will discuss how to validateMusrRootfiles.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 Validation will discuss how to validate MusrRoot files.
User Interface for MusrRoot Run Header¶
-There are two things needed to deal with the
+MusrRootrun header, namely writing it and reading it. I will start with the writing as will be done in theMIDASanalyzer.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_runHeaderwhich is writing a full run header is part of themusrfitpackage. Here I will concentrate just on the most essential parts. First one needs an instance ofTMusrRunHeaderTMusrRunHeader *header = new TMusrRunHeader(); +
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
+-TMusrRunHeader *header = new TMusrRunHeader(); TMusrRunPhysicalQuantity prop;
-headeris the instance ofTMusrRunHeader.propis an instance ofTMusrRunPhysicalQuantitywhich will be needed further down in the description. In the next step some run header entries will be addedheader->Set("RunInfo/File Name", "deltat_tdc_gps_2871.root"); +
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
+-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 theMusrRootfile structure, followed by the “value” to be set, e.g. “=File Name=”.<value>can be any of the types listed at the beginning of Sec. TMusrRunHeader Concept. Here a few examples how to setTMusrRunPhysicalQuantity.prop.Set("Sample Temperature", 3.2, 3.21, 0.05, "K", "CF1"); +
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 Sec. TMusrRunHeader Concept. Here a few examples how to set TMusrRunPhysicalQuantity.
+-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"); @@ -289,16 +301,16 @@ is derived which is extending the base class to the needs of the instrument. header->Set("SampleEnvironmentInfo/CF3", prop);
Here
-TMusrRunPhysicalQuantityobjects are fed via the use of the overloaded set-method. For details see TMusrRunPhysicalQuantity - Possible Representations.To set some property within “sub-sub-directories” it would like this:
-header->Set("DetectorInfo/Detector001/Time Zero Bin", 3419.0); +
Here TMusrRunPhysicalQuantity objects are fed via the use of the overloaded set-method. For details see TMusrRunPhysicalQuantity - Possible Representations.
+To set some property within “sub-sub-directories” it would like this:
+header->Set("DetectorInfo/Detector001/Time Zero Bin", 3419.0);
To write the whole run header into a file would look something like this:
-TFile *f = new TFile(fileName, "RECREATE", "write_musrRoot_runHeader"); +
TFile *f = new TFile(fileName, "RECREATE", "write_musrRoot_runHeader"); if (f->IsZombie()) { delete f; - return -1; + return -1; } // create the needed TFolder object @@ -315,11 +327,11 @@ is derived which is extending the base class to the needs of the instrument.
Reading a MusrRoot Run Header¶
-The following code snippet shows how the extract the full run header from the
-MusrRootfile.TFile *f = new TFile(fileName, "READ", "read_musrRoot_runHeader"); +
The following code snippet shows how the extract the full run header from the MusrRoot file.
+-TFile *f = new TFile(fileName, "READ", "read_musrRoot_runHeader"); if (f->IsZombie()) { delete f; - return -1; + return -1; } TFolder *runHeader = 0; @@ -327,7 +339,7 @@ is derived which is extending the base class to the needs of the instrument. if (runHeader == 0) { cerr << endl << ">> **ERROR** Couldn't get top folder RunHeader"; closeFile(f); - return -1; + return -1; } TMusrRunHeader *header = new TMusrRunHeader(fileName); @@ -335,15 +347,15 @@ is derived which is extending the base class to the needs of the instrument. if (!header->ExtractAll(runHeader)) { cerr << endl << ">> **ERROR** couldn't extract all RunHeader information"; closeFile(f); - return -1; + return -1; } f->Close(); delete f;
The routine
-ExtractAll(TFolder *runHeader)decodes all theTObjStringobjects and fills internal data structures. This means when reading a MusrRoot -file the above handling is always needed. After theExtractAllcall, parameters can be extracted via the getter routines available. For instance to read the Run Number, the code would look likeBool_t ok; +
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
+-Bool_t ok; Int_t ival; header->Get("RunInfo/Run Number", ival, ok); if (ok) @@ -352,8 +364,8 @@ is derived which is extending the base class to the needs of the instrument. cout << endl << "**ERROR** Couldn't obtain the 'Run Number'.";
Reading a
-TMusrRunPhysicalQuantityobject, e.g. the sample temperature looks like thisTMusrRunPhysicalQuantity prop; +
Reading a TMusrRunPhysicalQuantity object, e.g. the sample temperature looks like this
+TMusrRunPhysicalQuantity prop; header->Get("RunInfo/Sample Temperature", prop, ok); if (ok) { @@ -369,186 +381,186 @@ is derived which is extending the base class to the needs of the instrument.
Validation of a MusrRoot File¶
-Since
+MusrRootis 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 programmusrRootValidation: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:
-
-MusrRootvalidation schemeIn the following this validation scheme will be discussed as it is implemented in
+musrRootValidation: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 +
- 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
libxml2is used, because also ROOT is requiring it.
- In a next step the XML file (holding the structure of the supposed
MusrRootfile is validated -against a XML schema. The minimum of required entries is described byMusrRoot.xsdwhich is -part ofmusrfitbut 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.
+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.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.
RunInfo (Required)¶
-+
- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Version
TStringGIT version of
TMusrRunHeaderVersion +TString +GIT version of TMusrRunHeader Generic Validator URL
TStringURL of the generic
MusrRootvalidation xsd-file. -e.g. http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRoot.xsdGeneric 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
TStringURL of the instrument specific validation xsd-file. -e.g. for LEM: http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRootLEM.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
TStringProgram which wrote the
MusrRootfile, e.g.nemu_analyzerGenerator +TString +Program which wrote the MusrRoot file, e.g. nemu_analyzer File Name
TStringFile name of the
MusrRootfile, e.g.deltat_tdc_gps_4295.rootFile Name +TString +File name of the MusrRoot file, e.g. deltat_tdc_gps_4295.root Run Title
TString+ Run Title +TString +Run Number
Int_t+ Run Number +Int_t +Run Start Time
TStringISO 8601 date time
Run Start Time +TString +ISO 8601 date time Run Stop Time
TStringISO 8601 date time
Run Stop Time +TString +ISO 8601 date time Run Duration
TMusrRunPhysicalQuantityrun duration in sec
Run Duration +TMusrRunPhysicalQuantity +run duration in sec Laboratory
TStringe.g. PSI
Laboratory +TString +e.g. PSI Instrument
TStringe.g. GPS
Instrument +TString +e.g. GPS Muon Beam Momentum
TMusrRunPhysicalQuantitye.g. 28.1 MeV/c
Muon Beam Momentum +TMusrRunPhysicalQuantity +e.g. 28.1 MeV/c Muon Species
TStringpoitive or negative muon
Muon Species +TString +poitive or negative muon Muon Source
TStringe.g. “Target E - Low Energy Muons” or “Target M” …
Muon Source +TString +e.g. “Target E - Low Energy Muons” or “Target M” ... Setup
TString+ Setup +TString +Comment
TString+ Comment +TString +Sample Name
TString+ Sample Name +TString +Sample Temperature
TMusrRunPhysicalQuantitye.g. 3.21 +- 0.05 K; SP: 3.2; CF1
Sample Temperature +TMusrRunPhysicalQuantity +e.g. 3.21 +- 0.05 K; SP: 3.2; CF1 Sample Magnetic Field
TMusrRunPhysicalQuantitye.g. 350.002 +- 0.005 G; SP: 350; WEW
Sample Magnetic Field +TMusrRunPhysicalQuantity +e.g. 350.002 +- 0.005 G; SP: 350; WEW No of Histos
Int_t+ No of Histos +Int_t +Time Resolution
TMusrRunPhysicalQuantitye.g. 0.1953125 ns
Time Resolution +TMusrRunPhysicalQuantity +e.g. 0.1953125 ns RedGreen Offsets
TIntVectore.g. 0; 20
RedGreen Offsets +TIntVector +e.g. 0; 20 DetectorInfo (Required)¶
-The
-DetectorInfois organized in a sub-tree likeDetectorInfo ---| - |- Detector001 - |- Detector002 - ... +
The DetectorInfo is organized in a sub-tree like
+-DetectorInfo ---| + |- Detector001 + |- Detector002 + ...
For each histogram in the
-histos/DecayAnaModulecorresponds 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+
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
+
@@ -556,22 +568,22 @@ at PSI an- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Name
TStringdetector name, e.g. Left-NPP
Name +TString +detector name, e.g. Left-NPP Histo Number
Int_thistogram number. This number corresponds to the histogram -number in the
histos/DecayAnaModulesub-tree.Histo Number +Int_t +histogram number. This number corresponds to the histogram +number in the histos/DecayAnaModule sub-tree. Histo Length
Int_tlength of the histogram (in bins)
Histo Length +Int_t +length of the histogram (in bins) Time Zero Bin
Double_tThe type is
Double_tsince for the high-field spectrometer -at PSI anInt_trepresentation would be not good enough.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+ First Good Bin +Int_t +Last Good Bin
Int_t+ Last Good Bin +Int_t +Int_tSampleEnvironmentInfo (Required)¶
Here only a single entry is required, namely
-+
@@ -579,23 +591,23 @@ at PSI an- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Cryo
TStringname of the used cryostat/oven, e.g.
Konti-2Cryo +TString +name of the used cryostat/oven, e.g. Konti-2 Int_tMagneticFieldEnvironmentInfo (Required)¶
Here only a single entry is required, namely
-+
@@ -603,22 +615,22 @@ In case of ZF measurements, there might be an entry like ZF.- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Magnet Name
TStringname of the used magnet, e.g.
WEW. -In case of ZF measurements, there might be an entry like ZF.Magnet Name +TString +name of the used magnet, e.g. WEW. +In case of ZF measurements, there might be an entry like ZF. BeamlineInfo (Required)¶
Here only a single entry is required, namely
-+
@@ -626,49 +638,49 @@ In case of ZF measurements, there might be an entry like ZF.- - -- - + + + Name
Internal Type
Comment
Name +Internal Type +Comment Name
TStringname of the beamline, e.g.
piM3.2Name +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 +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 -singleMusrRootfile. I will add comments in the tree structure by the symbol#. Lets start with the μ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 - ... +single MusrRoot file. I will add comments in the tree structure by the symbol #. Lets start with the μ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
-008to011). In order to fill in the different red / green +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, +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: +
-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 @@ -746,86 +758,86 @@ RunSummary: ...
Comment: the last sub-tree
+RunSummaryis not followingTMusrRunHeaderrule<number> - <label>: <value> -@<type>. -It is added in the instrument analyzer directly by other means than theTMusrRunHeader::Set-method. This is no problem! -SinceRunSummaryis not part of the requiredMusrRoot-file. One is quite free in adding any ROOT based information here.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.
TMusrRunPhysicalQuantity - Possible Representations¶
A physical property can be described as
-<property name>: <value> +- <estimated error> <unit>; SP: <demand>; <description> +
-<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 +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 thatTMusrRunPhysicalQuantity prop;+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>] +
<property name>: <value> <unit> [; <description>]
Code snippet:
-prop.Set("Muon Beam Momentum", 28.1, "MeV/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 +
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.
+011in 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: hereTMusrRunPhysicalQuantity.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>] +
<property name>: <val> +- <err> <unit>[; <description>]
Code snippet:
-prop.Set("CF3", MRH_UNDEFINED, 3.27, 0.09, "K", "strange temperature"); +
-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 +
Result in the RunHeader/SampleEnvironmentInfo:
+033 - CF3: 3.27 +- 0.09 K; strange temperature -@3
Possibility 3
-<property name>: <val> <unit>; SP: <demand>[; <description>] +
<property name>: <val> <unit>; SP: <demand>[; <description>]
Code snippet:
-prop.Set("CF4", 3.25, 3.28, "K"); +
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:
+-
+
Examples:
In order to illustrate the usage of these parameters a few examples with explanations are given below:
-$ msr2data 8400 8460 _tf_h13 -oABC.db fit-8472 +
-$ msr2data 8400 8460 _tf_h13 -oABC.db fit-8472
Using
-8472_tf_h13.msras first template,msr2datagenerates subsequent msr input files8400_tf_h13.msrthrough8460_tf_h13.msr, -callsmusrfitto perform a fit of these files and collects the results of the fits together with the DB header in the new fileABC.db. -Additionally, some information about external parameters like the temperature will be passed toABC.dbif it is present in the data files.$ msr2data [8500 8502-8504 8507] _zf fit-8472 noheader nosummary -o DEF.db +
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.
+-$ msr2data [8500 8502-8504 8507] _zf fit-8472 noheader nosummary -o DEF.db
Using
8472_zf.msras first template,msr2datagenerates subsequent msr input files8500_zf.msr,8502_zf.msr,8503_zf.msr, -8504_zf.msr, and8507_zf.msr, callsmusrfitto perform a fit of these files and collects the results of the fits in the fileDEF.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.
-$ msr2data 8595 8585 "" noheader fit-8472! -oGHI.dat data nosummary -k +
-$ msr2data 8595 8585 "" noheader fit-8472! -oGHI.dat data nosummary -k
Using
8472.msras template for all runs,msr2datagenerates the msr input files8595.msrthrough8585.msr, callsmusrfitwith -the option--keep-mn2-ouputto perform a fit of these files and collects the results of the fits in the column-structured ASCII fileGHI.dat+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.
-$ msr2data 8472 8475 "" fit -o none +
-$ msr2data 8472 8475 "" fit -o none
Take the given msr files
-8472.msrthrough8475.msrand callmusrfitwithout finally summarizing the results.$ msr2data 8472 8475 _tf_h13 msr-8471! +
Take the given msr files 8472.msr through 8475.msr and call musrfit without finally summarizing the results.
+-$ msr2data 8472 8475 _tf_h13 msr-8471!
Using
8471_tf_h13.msras template for all runs,msr2datagenerates the msr input files8472_tf_h13.msrthrough8475_tf_h13.msr. +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!
-$ msr2data [8472 8475-8479] _tf_h13 paramList 1-16 data -o bestData.dat +
-$ 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, -and8479_tf_h13.msrand write these parameters into a column like output filebestData.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.
The Global Mode¶
-Apart from all the options described above there is another program option: global. -This option changes the general behavior of
msr2datain that way that instead of processing one msr file for each +Apart from all the options described above 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
+used in conjunction with any of the described invocations of msr2data and together with all options stated above.msr2dataand together with all options stated above.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:
--
-
-
+
The FITPARAMETER block of an exemplary template file
-8472_example.msrcould 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 +
The 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 THEORY and -FUNCTIONS blocks. If however, those parameters are met,
-msr2datawill try to substitute them by mapped parameters -and add them accordingly to the map contained in each RUN block.When
-msr2datais called to generate a global msr file, e.g.$ msr2data 8471 8470 _example msr-8472 global +
Normally, within the template file there should not appear explicitly any run-specific parameters in the THEORY and +FUNCTIONS 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 RUN block.
+When msr2data is called to generate a global msr file, e.g.
+-$ msr2data 8471 8470 _example msr-8472 global
a new msr file
-8471+global_example.msris 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+globalidentifier and the template<extension>. The example’s global FITPARAMETER block would be:FITPARAMETER -# No Name Value Step Pos_Error Boundaries +
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 +# Common parameters for all runs - 1 Phase 35.8359 -3.94496 3.93749 - 2 Field 143.212 -0.27960 0.27885 100 200 + 1 Phase 35.8359 -3.94496 3.93749 + 2 Field 143.212 -0.27960 0.27885 100 200 -# Specific parameters for run 8471 +# 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 + 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 +# 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 + 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 @@ -267,50 +282,50 @@ followed by copies of the parameters specific to each run (in the specified orde 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!
+Note
+Please be aware of the fact that comments in the template msr file are not propagated to the newly generated global msr file!
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 run-list file. +as usual this includes also parameters stored in the run data files or externally specified parameters given in a run-list file. In order to reach this goal the global msr file has to obey certain rules:
-
-
Following these rules – which is achieved most easily by generating the global msr file using
-msr2dataas shown above – the parameters can be extracted e.g. like$ msr2data 8471 8470 _example global data -o globalFit.dat +
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
+-$ 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 fileglobalFit.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.
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 +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
-$ msr2data 8471 8470 _example global+ msr-8472 +
-$ msr2data 8471 8470 _example global+ msr-8472
Here,
+8472_example.msris first used as template to generate the file8471-OneRunFit_example.msr, thenmusrfitis called for it, the result -is used to generate8470-OneRunFit_example.msrandmusrfitis called for that file. Finally, the global fit file8471+global_example.msris -produced — including the fit results of theOneRunFitfiles for the run-specific parameters.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 fileOneRunFits.dbone could call-$ msr2data 8471 8470 -OneRunFit_example -o OneRunFits.db +be collected by msr2data. E.g. in order to produce a DB file OneRunFits.db one could call +
$ msr2data 8471 8470 -OneRunFit_example -o OneRunFits.db
-@@ -319,40 +334,40 @@ the file integrity and correct parameter order within these files.Note
-Please be aware that the program in this mode always generates new single-run msr files and always calls
musrfitfor them. In case there are +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 Graphical User Interface for msr2data Provided by musredit¶
-musredit, designed especially for the manipulation of
-musrfitmsr files and graphical front ends tomusrfit, offer an almost -self-explanatory graphical user interface tomsr2datadepicted below:
-
-
musredit, 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:
+-
+
-
-
The options tags correspond essentially to the description in optional parameters.
+The options tags correspond essentially to the description in optional parameters.
+-« mupp - μSR Parameter Plotter @@ -364,10 +379,10 @@ fit serves as template for the second and so on. The template field stays empty
- © Copyright 2021, Andreas Suter. - Last updated on Oct 02, 2021. - Created using Sphinx 3.4.3. + \ No newline at end of file diff --git a/doc/html/mupp.html b/doc/html/mupp.html index 2fbea78d..85619877 100644 --- a/doc/html/mupp.html +++ b/doc/html/mupp.html @@ -1,49 +1,60 @@ + - - + - - -mupp - μSR Parameter Plotter — musrfit 1.7.6 documentation - + + +mupp - μSR Parameter Plotter — musrfit 1.8.0 documentation + - - - - - - - + + + + + + + + - -- musrfit 1.7.6 documentation
+ + +-+ musrfit 1.8.0 documentation
mupp - μSR Parameter Plotter
+-- «
musredit: the GUI Based Interface tomusrfit+ « musredit: the GUI Based Interface to musrfit :: Contents :: - msr2data - A Program for Automatically Processing Multiplemusrfitmsr Files » + msr2data - A Program for Automatically Processing Multiple musrfit msr Files »+mupp - μSR Parameter Plotter¶
-muppis a little helper program which allows to quickly plot a collection of msr-file parameters, -as for instance generated by msr2data. It can handledb- anddat-files. -Also a collection ofmsr-files can be invoked.muppis heavily inspired by μView (see +mupp is a little helper program which allows to quickly plot a collection of msr-file parameters, +as for instance generated by msr2data. It can handle db- and dat-files. +Also a collection of msr-files can be invoked. mupp is heavily inspired by μView (see here).
-
+muppcan be operated from within as graphical user interface or via a command line scripting interface. -ThemuppGUI can be invoked either directly from the command line or from within musredit.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 musredit.
Each collection bundles a number of runs, where a run is a single μ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. @@ -51,99 +62,113 @@ Hence parameters can be seen as vectors and can be plot against each other.
The Graphical User Interface¶
A typical setting could look like this
--
-
The Scripting Interface¶
-
-muppcan 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 -mupp command line summary. Currently the following scripting commands are available:-
-
-
+
All four basic types of calling
-msr2datacontain 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:$ msr2data 8472 _tf_h13 +
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:
+-$ msr2data 8472 _tf_h13generates the DB file
-out.db(can be changed by using the -o option) from8472_tf_h13.msr.$ msr2data 8472 8474 _tf_h13 +
generates the DB file out.db (can be changed by using the -o option) from 8472_tf_h13.msr.
+-$ msr2data 8472 8474 _tf_h13
generates the DB file
-out.db(can be changed by using the -o option) from8472_tf_h13.msr,8473_tf_h13.msr, and8474_tf_h13.msr.$ msr2data [8472 8470] _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.
+-$ msr2data [8472 8470] _tf_h13
generates the DB file
-out.db(can be changed by using the -o option) from8472_tf_h13.msrand8470_tf_h13.msr.$ msr2data [8470:8474:2] _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.
+-$ msr2data [8470:8474:2] _tf_h13
generates the DB file
+out.db(can be changed by using the -o option) from8470_tf_h13.msr,8472_tf_h13.msr, and8474_tf_h13.msr.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¶
-$ msr2data run.list _tf_h13 +
-$ 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 filerun.listin 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 therun.listis the following:RUN VAR1 VAR2 VAR3 ... +
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 ... @@ -110,16 +123,18 @@ In this file it is also possible to include external parameters which s
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.
+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:
-
-