bfit 4.7.9

β-NMR and β-NQR Data Analysis

bfit

bfit is a Python application aimed to aid in the analysis of β-detected nuclear magnetic/quadrupole resonance (β-NMR and β-NQR) data taken at TRIUMF. These techniques are similar to muon spin rotation (μSR) and "conventional" nuclear magnetic resonance (NMR), but use radioactive nuclei as their NMR probe in place of the muon or a stable isotope. The instruments and research program are governed through TRIUMF's CMMS, with more information given at https://bnmr.triumf.ca. An overview of instrumentation details and scientific applications of the β-NMR/β-NQR techniques can be found in several recent journal articles:

• W. A. MacFarlane. Implanted-ion βNMR: a new probe for nanoscience. Solid State Nucl. Magn. Reson. 68-69, 1-12 (2015).
• G. D. Morris. β-NMR. Hyperfine Interact. 225, 173-182 (2014).

The intended user of bfit is anyone performing experiments with or analyzing data taken from TRIUMF's β-NMR or β-NQR spectrometers - independent of whether they are a new student, visiting scientist, or someone with decades of experience. (e.g., someone from the "local" TRIUMF/CMMS/UBC group). A key goal of the project is to alleviate much of the technical tedium that is often encountered during any analysis. More generally, bfit has been written to fulfill the following needs:

• Provide the means for quick on-line analyses during beam time.
• Provide a useful and flexible API for refined analyses in Python, to be used in conjunction with bdata and the SciPy ecosystem.
• Provide an intuitive, user-friendly interface for non-programmers.
• Be easily maintainable and distributable.

Citing

If you use mudpy, bdata, or bfit in your work, please cite:

• D. Fujimoto. Digging into MUD with Python: mudpy, bdata, and bfit. arXiv:2004.10395 [physics.data-an].

Useful Links

• bfit
  • Wiki
    • API Reference
    • API Tutorial
    • GUI Tutorial
• mudpy
• bdata

Community Guidelines

• Contributing:
  • Please submit your contribution to bfit through the list of Pull Requests!
• Reporting issues and/or seeking support:
  • Please file a new ticket in bfit's list of Issues - I will get an email notification of your problem and try to fix it ASAP!

Installation and Use

Dependencies

The following packages/applications are needed prior to bfit installation:

• Python 3.6 or higher: a dynamically typed programming language. [install]
• Tkinter : Python's de-factor standard GUI package. [install]
• Cython : C-language extensions for Python. [install]
• NumPy : array programming library for Python. [install]

and the following are handelled automatically when retrieving bfit from the PyPI:

• argparse : a parser for command-line options, arguments and sub-commands.
• bdata : data structures and algorithms for retrieving/processing TRIUMF β-NMR/β-NQR data.
• iminuit : a Jupyter-friendly Python interface for the MINUIT2 library.
• Matplotlib : comprehensive library for creating static, animated, and interactive visualizations in Python.
• pandas : a fast, powerful, flexible and easy to use data analysis/manipulation tool.
• PyYAML : a next generation YAML parser and emitter for Python.
• requests : an elegant and simple HTTP library for Python, built for human beings.
• SciPy : fundamental algorithms for scientific computing in Python.
• tqdm : a fast, extensible progress bar for Python.

Install Instructions

	Command
From the PyPI as user (recommended)	pip install --user bfit
From the PyPI as root	pip install bfit
From source	python3 setup.py install

Note that pip should point to a (version 3) Python executable (e.g., python3, python3.8, etc.). If the above does not work, try using pip3 or python3 -m pip instead.

Optional Setup

For convenience, you may want to tell bfit where the data is stored on your machine. This is done by defining two environment variables: BNMR_ARCHIVE and BNQR_ARCHIVE. This can be done, for example, in your .bashrc script. Both variables expect the data to be stored in directories with a particular heirarchy:

/path/
    bnmr/
    bnqr/
        2017/
        2018/
            045123.msr

Here, the folders /path/bnmr/ and /path/bnqr/ both contain runs (i.e., .msr files) organized into subdirectories by year of aquasition. In this case, you would set (in your .bashrc):

export BNMR_ARCHIVE=/path/bnmr/
export BNQR_ARCHIVE=/path/bnqr/

If bfit cannot find the data, it will attempt to download the relavent MUD (i.e., .msr) files from https://cmms.triumf.ca/mud/runSel.html. This is the default behaviour for bfit installed from PyPI.

First Startup

To launch the GUI, from a terminal simply call:

bfit

If this fails, one can also use the alternative syntax:

python3 -m bfit

where python3 may be replaced with any (version 3) Python executable.

Testing

Testing your installation of bfit is most easily accomplished throught the collection of functions available within:

from bfit import test

Additionally, results from bfit may be compared directly against those from a number of independently developed applications:

• bnmr_1f : A command line tool to analyze CW resonance (1f) measurements (written by R. M. L. McFadden).
• bnmr_2e : A command line tool to analyze pulsed resonance (2e) measurements (written by R. M. L. McFadden).
• bnmrfit : A collection of PHYSICA scripts for inspecting all types of β-NMR data (written by Z. Salman). The scripts have been well-tested through over a decade of use, though maintenance of PHYSICA has long since ceased. Ironically, the fitting capabalities are somewhat minimal.
• bnmroffice : A GUI analysis tool for inspecting most types of β-NMR data, similar to bfit (written by H. Saadaoui). While used for many years, it is currently out-of-date with regards to recent run modes. Similarly, it is no longer actively maintained.
• musrfit : A popular and powerful analysis tool for time-differential μSR data. An add-on library for analyzing β-NMR SLR data (written by Z. Salman) is available (see the musrfit documentation).

These works, as well as number of unpublished ones (mostly by R. M. L. McFadden and W. A. MacFarlane), were used to test bfit. When fitting data, most of these codes rely on the MINUIT2 minimizer (based on the "classic" MINUIT code) provided within the ROOT framework. In this case, the migrad minimizer option in bfit (made available through iminuit) should be used for the best comparison.

Note that the run header information can be checked against the API provided by the TRIUMF CMMS group's online muon data (MUD) file "archive". For example, have a look at the header information for data/BNMR/2020/040123.msr.