The NIST scan framework is a framework that greatly simplifies the process of writing and maintaining scans of experimental parameters using the ARTIQ control system and language. The most common and repeated tasks of a scan are performed automatically by the framework:
- Iterating over a list of scan points.
- Repeating a measurement multiple times at each scan point.
- Mutating datasets with the experimental data collected during scan execution.
- Calculation of statistics on the collected data.
- Plotting of calculated mean values during execution.
- Fitting of a function to the calculated mean values.
- Validation of data before fitting.
- Validation of the fitted parameters after fitting.
Fitting validation at the end of the scan gives the user control over what fitted parameters should be considered valid and helps avoid incorrect fit parameters from being saved and later used in an experiment. The framework also adopts the philosophy of convention over configuration: datasets are stored for analysis and plotting in a standardize way which removes much of the data handling that needs to performed by the writer of a scan.
Please refer to https://pages.nist.gov/artiq_scan_framework/ for the full scan framework documentation including many worked examples and a full API listing. The following gives a broad overview of the most import aspects of the scan framework.
Active development
The framework has been thoroughly tested through its use in lab experiments at NIST since 2017. It is currently being used by the Quantum Processing Group and the Ion Storage Group at NIST.
The following are required for running the scan framework. Please see also REQUIREMENTS.md for a list of these requirements.
- Experimental control hardware running ARTIQ version 3.7
- Version 3.7 of the ARTIQ python package. Please see Installing ARTIQ for instructions on installing ARTIQ.
- Python version 3.5
Note: this is also a requirement for ARTIQ v3 and is covered by the first requirement. - The numpy python package compatible with Python version 3.5.
Note: numpy is installed automatically when installing ARTIQ via the m-labs conda channel. - The scipy python package compatible with Python version 3.5.
Note: scipy is installed automatically when installing ARTIQ via the m-labs conda channel.
(Optional)
- The matplotlib python package compatible with Python version 3.5.
Note: The matplotlib package is required only by testing routines in the curvefits.py module of the analysis subpackage. It is not required for typical use of the scan framework.
Below are instructions on performing a minimal install for getting started with the framework, which are intended for users just getting started with ARTIQ. Experienced ARTIQ users can follow the instructions in INSTALLING.md.
To install the framework, first install git to your computer.
Next, clone this repository to a location on your computer. In Windows, for example, open a command prompt after installing git and run
mkdir C:\src
cd C:\src
git clone https://github.com/usnistgov/scan_framework
dir
rem you should see a folder name scan_framework which contains all source code for the framework
This will download all of the required source files for the framework to C:\src\scan_framework. You can also
simply download the scan framework source directly from http://github.com/usnistgov/scan_framework and extract them
to a folder of your choosing if you do not wish to install git. Installing git makes it easier to receive future updates
and bug fixes and is recommended.
Next, add the directory that contains the folder named scan_framework to your
PYTHONPATH environment variable.
For the Windows example above, add an environment variable
with a variable name of PYTHONPATH and set it's value field to C:\src;
To check that this was successful, close the current command prompt, open a new command prompt and type
echo %PYTHONPATH%
If everything was successful, this will output C:\src;. Note, you will need to close the current command
prompt and open a new prompt for the PYTHONPATH variable to be updated.
Next, install ARTIQ version 3 if it is not already installed on your computer. Please see Installing ARTIQ for instructions on installing ARTIQ.
Next, start the ARTIQ master and ARTIQ dashboard programs.
artiq_master --device-db=C:/path/to/your/device_db.py --repository=C:/path/to/your/experiment/files
artiq_dashboard
Please see the ARTIQ manual release 3 for more details on running the
artiq_master and artiq_dashboard commands.
Finally, create the current_scan applet for the scan framework in the ARTIQ dashboard. In the ARTIQ dashboard
navigate to the Applets tab, right click and select New applet. Add the following source for the applet:
$python -m scan_framework.applets.plot_xy current_scan.plots.y
--x current_scan.plots.x
--fit current_scan.plots.fitline
--title current_scan.plots.plot_title
--x_scale current_scan.plots.x_scale
--x_units current_scan.plots.x_units
--y_scale current_scan.plots.y_scale
--x_label current_scan.plots.x_label
--y_units current_scan.plots.y_units
--y_label current_scan.plots.y_label
--rid current_scan.rid
--error current_scan.plots.error
For getting started, only the current_scan applet above is needed. Additional features of the scan framework
require additional applets listed below in the Applets section. To use those features you will
also need to create those additional applets to the dashboard.
The best way to start using the scan framework is by looking through a few of the example scans below and running them in the ARTIQ dashboard. A few examples do not require the ARTIQ hardware which allows testing the framework on a computer not connected to ARTIQ hardware.
The first four examples below provide everything that is needed for a large set of use cases. Examples are ordered from basic to advanced and are meant to be followed in more or less chronological order.
Scan examples/tutorials
- Ex0: Minimal Scan
- Ex1: Scan Arguments -- doesn't require ARTIQ hardware
- Ex2: Calculating & Plotting Statistics
- Ex3: Fitting
- Ex4: Callbacks -- see the documentation for details on all available callbacks.
- Ex5: Multiple Measurements -- Also create the 'example_5' applet below
- Ex6: Dynamic Models -- Also create the 'example_6' applet below
- Ex7a: Warmup Points 1
- Ex7b: Warmup Points 2
- Ex7c: Warmup Points 3
- Ex8: Rename Main Fit
- Ex9: After Measure Callback
- Ex10: Fit Guess Arguments
- Ex11: Fit Validations -- doesn't require ARTIQ hardware
- Ex12: Time Scans -- doesn't require ARTIQ hardware
- Ex13: Formatting Plots
Note:
To run an example, right click the Explorer tab in the dashboard and choose Open file outside repository.
Then navigate to the directory containing scan framework source/scan_framework/examples/scans folder and open and
the example scan.
Additional real world examples are provided in scan_framework/examples/scans and scan_framework/examples/models
that illustrate how the scan class is used in a real lab setup.
$python -m scan_framework.applets.plot_xy_ntrace_white
example_5.m1.stats.mean
--x1 example_5.m1.stats.points
--error1 example_5.m1.stats.error
--fit1 example_5.m1.fits.fitline
example_5.m2.stats.mean
--x2 example_5.m2.stats.points
--error2 example_5.m2.stats.error
--fit2 example_5.m2.fits.fitline
example_5.m2.stats.mean
--x3 example_5.m2.stats.points
--error3 example_5.m2.stats.error
--fit3 example_5.m2.fits.fitline
$python -m scan_framework.applets.plot_xy_ntrace_white
example_6.m1.stats.mean
--x1 example_6.m1.stats.points
--error1 example_6.m1.stats.error
--fit1 example_6.m1.fits.fitline
example_6.m2.stats.mean
--x2 example_6.m2.stats.points
--error2 example_6.m2.stats.error
--fit2 example_6.m2.fits.fitline
example_6.m2.stats.mean
--x3 example_6.m2.stats.points
--error3 example_6.m2.stats.error
--fit3 example_6.m2.fits.fitline
Full documentation is available at https://pages.nist.gov/artiq_scan_framework/
Detailed APIs are also available: TODO: Update Links
Framework features can be enabled or disabled in the build() method of your scan class
by setting the associated class attribute listed below to either True or False:
| Scan feature | Enabled by default? | Associated settings | Associated methods |
|---|---|---|---|
| Dataset mutating | Yes | self.enable_mutate |
|
| Fitting | Yes | self.enable_fitting |
|
| Pausing/Terminating | Yes | self.enable_pausing |
|
| Count monitoring | Yes | self.enable_count_monitor self.counts_prec |
|
| Reporting | Yes | self.enable_reporting |
self.report() self.report_fit() |
| Warm-up points | No | self.nwarmup_points |
|
| Auto tracking | No | self.enable_auto_tracking |
|
| Host scans | No | self.run_on_core |
|
| Scan simulating | No | self.enable_simulations |
|
| Profiling/Timing | No | self.enable_profiling self.enable_timing |
| Setting | Description |
|---|---|
self.enable_mutate |
Mutate mean values and standard errors datasets after each scan point. Used to monitor progress of scan while it is running. |
self.enable_fitting |
Enable or disable all fitting features |
self.enable_pausing |
Check pause via self.scheduler.check_pause() and automatically yield/terminate the scan when needed. |
self.enable_count_monitor |
Update the '/counts' dataset with the average of all values returned by 'measure()' during a single scan point. |
self.counts_prec |
Set to a value >= 0 to round the '/counts' dataset to the specified number of digits. |
self.enable_reporting |
Print useful information to the Log window before a scan starts (i.e. number of passes, etc.) and when a fit is performed (fitted values, etc.) |
self.nwarmup_points |
Number of warm-up points |
self.enable_auto_tracking |
Auto center the scan range around the last fitted value. |
self.run_on_core |
Set to False to run scans entirely on the host and not on the core device |
self.enable_simulations |
Turn on GUI arguments for simulating scans |
self.enable_profiling |
Profile the execution of the scan to find bottlenecks |
self.enable_timing |
Enable automatic timing of certain events. Currently only compilation time is timed |
Below are all the applet commands needed to view data generated by the scan framework. These are also available in applet_commands.txt
The current scan applet displays the average value returned from the measure() method at each scan point.
Each point displayed is for a single scan point. Scans configured to calculate statistics will automatically
write statistics to the current_scan namespace. The current scan applet plots this contained in the
current_scan namespace. This plot is updated as the scan executes.
$python -m scan_framework.applets.plot_xy current_scan.plots.y
--x current_scan.plots.x
--fit current_scan.plots.fitline
--title current_scan.plots.plot_title
--x_scale current_scan.plots.x_scale
--x_units current_scan.plots.x_units
--y_scale current_scan.plots.y_scale
--x_label current_scan.plots.x_label
--y_units current_scan.plots.y_units
--y_label current_scan.plots.y_label
--rid current_scan.rid
--error current_scan.plots.error
The count monitor applet displays the average value returned by the measure() method after each scan point completes.
${artiq_applet}big_number counts
The current histogram applet plots a histogram of all values returned by the measure() during a single scan point. The histogram gives the distribution in measurement values only for the current scan point. This plot is updated as the scan executes.
$python -m scan_framework.applets.plot_hist current_hist.bins
--x current_hist.bin_boundaries
--x_units current_hist.x_units
--x_label current_hist.x_label
--plot_title current_hist.plot_title
The current aggregate histogram applet plots a histogram of all values returned by the measure() during the entire scan. The histogram is aggregate over all scan points. This plot is updated as the scan executes.
$python -m scan_framework.applets.plot_hist current_hist.aggregate_bins
--x current_hist.bin_boundaries
--x_units current_hist.x_units
--x_label current_hist.x_label
--plot_title current_hist.plot_title
The current sub scan applet plots the mean value returned by the measure() method of the sub-scan of a 2D scan. This plot is updated as the scan executes and is cleared after each sub-scan completes.
$python -m scan_framework.applets.plot_xy current_scan.plots.dim1.y
--x current_scan.plots.dim1.x
--fit current_scan.plots.dim1.fitline
--title current_scan.plots.dim1.plot_title
--x_scale current_scan.plots.dim1.x_scale
--x_units current_scan.plots.dim1.x_units
--x_label current_scan.plots.dim1.x_label
--y_units current_scan.plots.dim1.y_units
--y_label current_scan.plots.dim1.y_label
--trigger current_scan.plots.trigger
--rid current_scan.rid
--i_plot current_scan.plots.subplot.i_plot
Same as the current sub-scan applet, except the curve of the best fit is not plotted.
$python -m scan_framework.applets.plot_xy current_scan.plots.dim1.y
--x current_scan.plots.dim1.x
--title current_scan.plots.dim1.plot_title
--x_scale current_scan.plots.dim1.x_scale
--x_units current_scan.plots.dim1.x_units
--x_label current_scan.plots.dim1.x_label
--y_units current_scan.plots.dim1.y_units
--y_label current_scan.plots.dim1.y_label
--trigger current_scan.plots.trigger
--rid current_scan.rid
--i_plot current_scan.plots.subplot.i_plot
Same as the current_scan appleta bove, but for the ARTIQ browser.
$python -m scan_framework.applets.plot_xy current_scan.plots.y
--x current_scan.plots.x
--fit current_scan.plots.fitline
--title current_scan.plots.plot_title
--x_scale current_scan.plots.x_scale
--x_units current_scan.plots.x_units
--y_scale current_scan.plots.y_scale
--x_label current_scan.plots.x_label
--y_units current_scan.plots.y_units
--y_label current_scan.plots.y_label
--rid current_scan.rid
--error current_scan.plots.error
--trigger 1
The following scan attributes are marked as kernel invariants by default:
self.npasses, self.nbins, self.nrepeats, self.npoints, self.nmeasurements,
self.do_fit, self.save_fit, self.fit_only
The kernel invariants can be changed anywhere within the child scan class by manually setting self.kernel_invariants .
The default behavior of the scan model is to save all data to the HDf5 file of the experiment, but to
not broadcast or persist datasets (i.e. save=True, broadcast=False and persist=False when
datasets are created).
The exception to this rule is saved fit parameters which are both broadcast and persisted as well as saved to the
HDf5 file (i.e. save=True, broadcast=True and persist=True when
datasets are created).
If you wish to override this behavior, set the save, broadcast, or persist attributes in the build method
of your scan model class
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
- Philip D. Kent, NIST and University of Colorado - Scan framework architecture and development.
- Kyle S. McKay, NIST and University of Colorado - Scan framework design and user specifications.
- Daniel H. Slichter, NIST - Analysis subpackage and curve fitting routines.
- Bryce Bullock, NIST and University of Colorado - Development of feature additions.
See also the list of contributors who participated in this project.
Also see the LICENSE.md and LICENSES directory
NIST-developed software is provided by NIST as a public service. You may use, copy, and distribute copies of the software in any medium, provided that you keep intact this entire notice. You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the software.
NIST-developed software is expressly provided "AS IS." NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE SOFTWARE.
You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. The software developed by NIST employees is not subject to copyright protection within the United States.
To see the latest statement, please visit: Copyright, Fair Use, and Licensing Statements for SRD, Data, and Software
All other source files are distributed under the GNU Lesser General Public License v3.0 or later.
SPDX-License-Identifier: LGPL-3.0-or-later
Questions regarding this project can be directed to Philip D. Kent (NIST Assoc.) philip.kent@nist.gov.