Tutorial: XAFS Scans and Energy Scans¶
This notebook shows the following tasks:
First we have to setup haven, the beamline control library. Haven
contains most of the tools we will use. We can import haven, setup the
instrument, and create the run engine with the start_haven
command. After the required steps are completed, it will deliver us
into an ipython terminal.
We will also set metadata about who is running the beamline. This value will be saved in every plan executing on this run engine. This step is optional, but will allow database queries for scans taken by a specific person.
>>> RE.md["operator"] = "MFW" # <- Put your initials in here
Running a Single-Segment XANES scan¶
Running a scan in bluesky is a two step process.
First, create a plan. A plan generates messages with instructions
to do things like move a motor, wait for a motor to arrive at its
destination, and trigger and read a detector. To create a plan, you
call a function that will generate these messages. Calling the
function doesn’t actually execute the scan. In our case,
haven.xafs_scan(8325, 0.5, 1, 8350)
will create the plan, but the
plan will not do anything unless used with a run engine.
The xafs_scan()
plan requires at
least four values: (start, step, exposure, stop). start and stop
mark the boundaries of the energy range, in eV. step is the space
between energy points, in eV. Unless the range between start and
stop is a whole multiple of step, the stop energy will not
appear in the scan. exposure is the time, in seconds, for which to
count at each energy.
The optional argument E0 specifies the energy, in eV, of an x-ray absorbance edge. If given, all other energy values (i.e. start and stop) will be relative to E0.
>>> # These two plans will scan from 8323 eV to 8383 eV
>>> # in 2eV steps with 1 sec exposure
>>> absolute_plan = haven.xafs_scan(8323, 2, 1, 8383)
>>> relative_plan = haven.xafs_scan(-20, 2, 1, 50, E0=8333)
Before running either of these plans, we can verify that it will do
what we expect with the
simulators:summarize_plan()
helper. This function
will print a human-readable description of all the steps that will be
taken.
>>> summarize_plan(relative_plan)
Next, execute the plan on the run engine. As part of
start_haven
, we created a run engine. Now we will use this run
engine to execute the plan. The run engine will read the messages and
perform the appropriate tasks. We will also provide some meta-data,
which will allow us to determine the purpose of these scans in the
future. simulators:summarize_plan()
consumed the
plan so we have to create a new one.
When the run engine finishes the plan, it will return a unique identifier (UID). This UID is the best way to retrieve the data from the database. We will save the UID to a variable, and also print it to the page in case we want to recall it later.
>>> plan = haven.xafs_scan(-20, 2, 1, 50, E0=8333)
>>> # Run one of the plans with the previously created RunEngine
>>> uid = RE(plan, sample_name="Ni foil", purpose="training")
>>> print(uid)
Loading the Data¶
During execution the data are saved to a mongoDB database. Haven has tools to retrieve the data.
The load_data()
function will return a data set, provided we
supply the uid that we had previously recorded. It is possible to have
multiple experimental runs within a single call to the run engine, and
so our variable uid from above is actually a list of UIDs. Since
there was only one run, we will just use the first (and only) entry:
uid[0]
.
If the analysis is being done at a different time or place from running the scan, then the variable uid will probably not be set. In this case, it is possible to provide the UID that was printed above.
Optionally, the data can be saved to a text CSV file for
additional analysis. First we will convert it to a pandas DataFrame
and then use panda’s to_csv()
method. We will append the first
segment of the UID to the filename to descrease the likelihood that we
will overwrite data.
>>> # Uncomment this line to manually specify a UID
>>> # uid = ["927fa7dd-e331-45ca-bb9d-3f89d7c65b17"]
>>> # Load the data for the first (and only) UID in the list
>>> data = haven.load_data(uid[0])
>>> # Save the data to a CSV file, with tabs ("\t") instead of commas.
>>> data.to_pandas().to_csv(f"xafs_scan_example_{uid[0].split('-')[0]}.csv", sep='\t')
>>> # Plot the result
>>> data["od"] = data["It_raw_counts"] / data["I0_raw_counts"]
>>> plt.plot(data['energy'], data['od'])
Running a Multi-Segment XAFS Scan¶
The xafs_scan()
function can accept multiple sets of values to
accomodate additional scan regions. After the first set of four
parameters (start, step, exposure, stop), additional sets of
three parameters (step, exposure, stop) can be given and will
use the previous stop energy as its new start energy.
Additionally, Haven will look up the literature energy for a given X-ray absorption edge, in this case the Ni K-edge.
The call below will scan the following energies, relative to 8333 eV:
-50 to -10 eV (8283 to 8323 eV) in 5 eV steps with 0.5 sec exposure
-10 to +50 eV (8323 to 8383 eV) in 1 eV steps with 1 sec exposure
+50 to +200 eV (8383 to 8533 eV) in 10 eV steps with 0.5 sec exposure
>>> multisegment_plan = haven.xafs_scan(-50, 5, 0.5, # start, step, exposure
-10, 1, 1, # start, step, exposure
50, 10, 0.5, # start, step, exposure
200, # stop
E0="Ni_K")
>>> # Run the plan with the previously created RunEngine
>>> uid = RE(multisegment_plan, sample_name="Ni foil", purpose="training")
>>> print(uid)
Running a Multi-Segment EXAFS Scan in K-space¶
The xafs_scan() function can also accept one energy segment as X-ray wavenumbers instead of X-ray energy using the k_step, k_exposure and k_max keyword-only parameters. k_weight controls the increasing exposure time at higher wavenumbers.
>>> exafs_plan = haven.xafs_scan(-200, 5, 1.0, # start, step, exposure
-20, .3, 1, # start, step, exposure
30, # Last non-k energy point (also start of k-region in eV)
k_step=0.05, k_exposure=1.0, k_max=13.5, k_weight=0.5,
E0=8331.0)
>>> # Run the plan with the previously created RunEngine
>>> uid = RE(exafs_plan, sample_name="Ni foil", purpose="training")
>>> print(uid)
Modifying the List of Detectors¶
By default, xafs_scan()
measures all registered ion
chambers, most likely those set up during
haven.load_instrument()
called above. This default list can
be overridden by using the detectors argument. This example records
only those scaler channels whose EPICS records’ .DESC values are
“It”, “I0”, or “Iref”. Modify these names to suit your use case.
>>> detectors_plan = haven.xafs_scan(8323, 2, 1, 8383, detectors=["It", "I0", "Iref"])
>>> # Run the plan with the previously created RunEngine
>>> uid = RE(detectors_plan, LivePlot('It_raw_counts', 'energy_energy')
>>> print(uid)