Sample position scans

8. Sample position scans#

8.1. General line scans#

In the nomenclature of BMM, a line scan is a simple scan of a single motor axis with an on-screen plot. At BMM this sort of scan is typically done using the linescan() plan. This is a wrapper around BlueSky’s rel_scan().

In BMM’s linescan() plan, the scan is always a relative scan around the current position of the motor being scanned. It works like this:

RE(linescan(xafs_x, 'it', -4, 4, 81))

The arguments are:

  1. The motor axis to be scanned. This can be either the motor’s name in Bluesky.

  2. A string indicating the detector for the plotted signal. The choices are:

    • it: display the ratio of It/I0

    • if: display the sum of four silicon drift channels normalized by I0

    • i0: display the signal on I0

    • ir: display the ratio of Ir/It

  3. The starting position of the motor scan, relative to the current position.

  4. The ending position of the motor scan, relative to the current position.

  5. The number of steps in the scan.

Note that the first two arguments can be in either order. The plan will sort it out for you. These are equivalent:

RE(linescan('it', xafs_x, -4, 4, 81))
RE(linescan(xafs_x, 'it', -4, 4, 81))

At the end of the scan, you are prompted with the following question:

Pluck motor position from the plot? yes: y the Enter (or just Enter), no: n then Enter

If you answer y then Enter, or simply hit Enter, you will be prompted to single click the left mouse button leftclick on the plot.

You will then be prompted a second time with the value you selected.

The motor that was scanned will then move to the motor position you clicked on.

You can skip the “click for motor position” step by typing n and hitting Enter.

8.1.1. Plucking a point from a line scan#

If you want to repeat the action of clicking on a point and moving the motor to the click-upon point, do:

RE(pluck())

This will enable the left mouse leftclick click and subsequent motion on the most recent plot.

Warning

The pluck() command works on any plot made through the Kafka plotter. Be sure you are clicking on the plot you intend to pluck from!

8.1.2. Revisit a line scan#

Needs to be verified

Does this still work post-data-security?

Retrieve data from the database using the database key or scan ID:

ls2dat('/path/to/output.file', '<id>')

This writes from the database to an output file. The output file is a simple column data file without header or metadata.

The first argument is the name of the output data file. The second argument is either the scan’s unique ID – something like 42447313-46a5-42ef-bf8a-46fedc2c2bd1 – or the scan’s transient id number.

8.2. Specific line scans#

Some scan types are performed often enough and always with the same arguments that they have special names.

Rocking curve scan

This command:

RE(rocking_curve())

does a scan of the pitch of the second mono crystal and plots the signal on I0. At the end of the scan, it moves to the position of the center of mass of the rocking curve. This scan is useful after a large change of energy. It also opens the slits to 3 mm in vertical size before starting the scan, then returns the slits to their original height after the scan.

You can put this scan in a macro using:

yield from rocking_curve()
Slit height scan

This command:

RE(slit_height())

Runs a scan of the DM3 BCT motor around its current position. At the end of the scan, you are prompted to left click leftclick on the plot to choose a position to move the slit height to. This scan is useful for verifying that the slits are in the correct orientation for the delivery of beam from the mirrors.

Optionally, the scan will move to the center of mass of the measurement, skipping the prompt and plot interaction:

RE(slit_height(move=True))

You can put this scan in a macro using:

yield from slit_height()
Align ex situ sample holder

If the ex situ sample wheel is in approximately the right position such that X-rays are passing through a slot on the outer ring, you can center the slot around the beam with:

RE(find_slot())

This will run linescans in the X and Y directions, fitting a lineshape to each scan in order to find the center position. The same can be done by hand by doing:

RE(linescan(xafs_y, 'It',  -3,  3, 31))
RE(linescan(xafs_x, 'It', -10, 10, 31))

each time selecting the center when prompted.

You can put this scan in a macro using:

yield from find_slot()

8.3. Area scans#

Todo

A raster scan type – i.e. RE(raster()) – that does an areascan as described here, makes a nice figure using matplotlib’s contourf, exports data in formats used by popular plotting programs, and writes a dossier was tested in 2022-2. Current status: dossier is written, scan works, documentation needs to be written.

An area scan is a simple scan of a two motor axes with an on-screen heat map. At BMM this sort of scan is typically done using the areascan() plan. This is a wrapper around BlueSky’s rel_grid_scan(). Because the sample stages at BMM do not have encoders, the area scan is made by retreading the direction of the fast motor rather than snaking back and forth.

In BMM’s areascan() plan, the scan is always a relative scan around the current positions of both motors being scanned. It works like this:

RE(areascan('it', '<slow_motor>', -4, 4, 81, '<fast_motor>', -2, 2, 41))

The arguments are:

  1. The slow motor axis. This can be either the motor’s BlueSky name or the nickname in Table 6.1. So, these are equivalent:

    RE(areascan('it', 'x', -4, 4, 81, 'y', -2, 2, 41))
RE(areascan('it', xafs_x, -4, 4, 81, xafs_y, -2, 2, 41))
RE(areascan('it', xafs_x, -4, 4, 81, 'y', -2, 2, 41))

    For a motor that does not have a nickname, you must use the BlueSky name, as in this very silly example:

    RE(areascan('it', slits3_outboard, -1, 1, 21, dcm_pitch, -2, 2, 41))

  2. The starting position of the slow motor, relative to the current position.

  3. The ending position of the slow motor, relative to the current position.

  4. The number of steps to take on the slow motor.

  5. The fast motor axis. This can be either the motor’s BlueSky name or the nickname in Table 6.1.

  6. The starting position of the fast motor, relative to the current position.

  7. The ending position of the fast motor, relative to the current position.

  8. The number of steps to take on the fast motor.

  9. The detector for the plotted signal. The choices are it, if, and i0. For the it choice, the plot will display the ratio of It/I0. Similarly for the if choice, the plot will display the sum of four silicon drift channels normalized by I0. For the i0 choice, the signal on the I0 chamber will be plotted.

At the end of the scan, you are prompted with the following question:

Pluck motor position from the plot? [Yn]

If you answer Y, or simply hit Return, you will be prompted to single click the left mouse button leftclick on the plot. Both motors will then move to the position you clicked on.

You can skip the “click for motor position” step by typing n and hitting Return.

8.3.1. Plucking a point from an area scan#

If you want to repeat the action of clicking on a point and moving the motor to the click-upon point, do:

RE(pluck())

This will enable the left mouse click leftclick and subsequent motion on the most recent plot. The pluck() command only works on the most recent plot. You may not pluck from an older plot that is still displayed on the screen.

Of course, an older plot remains active in the sense that you can pass the cursor over the plot and read the mouse coordinates in the bottom, left corner of the plot window. You can find a point in this way, then do a movement command:

RE(mv(xafs_x, 28.31, xafs_y, 113.97))

8.3.2. Revisit an area scan#

Needs to be verified

Does this still work post-data-security?

Retrieve data from the database using the database key or scan ID:

as2dat('/path/to/output.file', '<id>')

This writes from the database to an output file. The output file is a simple column data file. The format of this data file is columns with datablocks (i.e. rows of constant value of the slow motor) separated by blank lines. This is a format that works with Gnuplot and other plotting programs.

The first argument is the name of the output data file. The second argument is either the scan’s unique ID – something like 42447313-46a5-42ef-bf8a-46fedc2c2bd1 – or the scan’s transient id number.