Aquarius

HOW-TO GUIDES
Cookbook

DEVICES
Enter

Cookbook

This is the cookbook for using bluesky at the Belchem Beamline. Many examples and many commands are explicitly written in a form that is easy for the user/operator to simply copy and paste them into the bluesky terminal as they are or with little modification.

Start Bluesky

From a terminal write

bluesky_start

Start Phoebus GUI

To start the screens run this line in a terminal:

phoebus_start

To open the gui panels navigate to the folder /opt/phoebus/gui.

Move motors

If you want to move a motor, or a set of motors you can simply type:

mov motor1 position1 motor2 position2

or using relative motions

movr motor1 relative_motion1 motor2 relative_motion2

Change the PGM cff

To set the cff value to 2.5 use:

mov pgm.cff 2.5

Note that this will not produce any movement in the monochromator. The new cff will be set once you change the energy to a new one.

Scan

Select Plotted detector

One can choose a detector to be plotted using giving the command plotselect():

In [1]: plotselect()
Current detector: ['kth01']
Press enter to exit
Available detectors:
1. accelerator_current
2. kth01
Select detectors by one or more numbers (e.g., '1', '1 2', '1,2')

Scan Syntax

Command	Usage Example
Take readings from detectors.	`count 5 delay=1`
absolute scan one motor	`scan motor -1 1 10`
absolute scan multiple motors	`scan motor -1 1 motor2 -2 3 10`
relative scan one motor	`dscan motor -1 1 10`
relative mesh multiple motors	`dmesh motor1 -1 1 10 motor2 -2 2 20`
absolute mesh multiple motors	`amesh motor1 12 14 10 motor2 18 22 20`

Continuous scans

The following scan is available for motors using an EPICS motor record

mov_count motor start_pos end_pos velocity

Continuous energy scan

This plan read detectors while flying pgm energy with start, stop, initial scan velocity, and the delay between det sample time

flyscan pgm.en start=400 stop=450 vel=0.2 delay=0

Parameter	Type	Description	Default
`detectors`	list	A list of 'readable' objects.	None
`flyer`	FlyerDevice object	An object of FlyerDevice type.	None
`start`	float	The start value of the flyer.	None
`stop`	float	The stop value of the flyer.	None
`vel`	float	The initial velocity of the flyer.	0
`delay`	iterable or scalar	Time delay in seconds between successive readings.	0.1
`shutter`	Device	Device with open and close value attributes, used to control a shutter.	Optional
`md`	dict	A dictionary containing additional metadata.	Optional

Adding Custom Metadata to Scans

Custom metadata allows users to annotate scans with additional information that can be specific to the current context or experimental conditions. This metadata is added at the time of executing a scan plan by including a dictionary named md as a parameter in the scan command.

Below is an example of how to add custom metadata when executing a scan. In this example, the metadata includes the name of the operator and a description of the sample:

# Define the scan parameters and include custom metadata
scan motor 1 5 5 md={'operator':'John','sample':'gold'}

Abort Motion

Weather you are moving a motor or running a plan, the motion can be interrupted by pressing

ctrl+c

Magics

Command	Description
`ct`	Shows a reading of all the detectors.
`wa`	Shows all the motor positions. You can select which motors to show using their label.
`where`	Draws a line of the current motor position in the last scan.
`pic`	Moves the motor to the highest value of the signal from the detector in the last scan.
`cen`	Moves the motor to the center of the signal from the detector in the last scan.
`com`	Moves the motor to the center of mass of the signal from the detector in the last scan.
`minimum`	Moves the motor to the minimum of the signal from the detector in the last scan.

Data

The data is exported in a subfolder of ~/bluesky/data.

The data is exported as specfiles (that can be visualized with PyMCA), and as individual csv files.

Before starting taking measurements, make sure that you are exporting the data in the right folder.

User Data

Change your user folder using the following command:

bds.change_user('<user_name>')

Create an additional subfolder for each sample/part of the experiment (you need at least one).

bds.change_sample('<sample_name>')

This is the folder structure that you create


    ├── ~/bluesky/data
    │   ├── user_name
    │   │   └── sample_name
    │   │   │   ├── csv
    │   │   │   │   ├── 00001_meta.json
    │   │   │   │   ├── 00001_primary.csv
    │   │   │   │   └── 00001_baseline.csv
    │   │   │   └── sample1.spec

Specfile

Specfiles can be visualized using PyMCA. To start the program click on it on the dock, or just write pymca in a terminal.

Individual csv files

The csv folder contains three files for each scan:

scanNumber_baseline.csv: the baseline
scanNumber_meta.json: the metadata
scanNumber_primary.csv: the data

Average keithleys measurements

When measuring with the Keithleys, it is possible to instruct them to repeat the measurement n times, and return the averaged value.

kth1.avg_type.set('Repeat')
kth1.avg_num.put(5)

Suspenders

Bluesky can automatically pause a measurement in case some conditions are met, by using suspenders.

Injection

This suspender pause the measurements two seconds before and after the injection happens. To activate it and deactivate it use:

wait_for_injection()

Suspender: Beamshutter

This suspender pause the measurements if it detects that the beamshutter or the last valve are closed. To activate it and deactivate it use

check_beamshutter()

How to Write a Script

To begin writing scripts for Bluesky, create a personal folder within the ~/bluesky/user_scripts/your_name directory. You can store your scripts here. For reference, check out examples in ~/bluesky/user_scripts/examples.

Commands - supported syntax

You can write commands as you were on the IPython shell, for example

# Change Energy
mov pgm.en 400
# Perform scan
dscan motor -1 1 10
# Read detector
count det 5
# Check motor positions
wa

are all valid instructions. They will be executed sequentially.
You can also wrap commands in for loops and use the iterator index inline:

# Perform 5 dscan moving the motor from 0 to 20
# with the number of steps increasing by 1 at every cycle
# starting from 10 up to 14
for i in range(10,14):
    dscan motor 0 20 i

# Nested loops are also supported
for j in range(4):
    scan motor j 20 10
    for k in range(10,13):
        count [det1 det2] k
        wa motor

Commands - unsupported syntax

Using custom variables as commands' argument is not supported. For example:

my_var = 5
dscan motor -10 my_var 20 # unsupported

steps = [5, 6, 4]
for step in steps:
    scan motor -10 10 step # supported - step is the loop index

for i in range(1,5):
    scan motor -10 10 my_var # unsupported

To address these cases you must use the Bluesky standard syntax (next section).

Bluesky Standard Syntax

If you want to implement complex logic that is not supported by the commands syntax, you should use the standard Bluesky syntax:

# Scan over a motor from -10 to 10 in 20 steps 
# and read from det1, det2 at every step
RE(scan_plan([det1 det2], motor, -10, 10, 20))

note that if you are using standard commands (scan, mov, ... ) you have to attach the suffix _plan.

With this notation you can perform more complex operations, for examples:

# Define variables
starting_point = -10
end_point = 10
number_of_steps = 20
# Use variables in plan
RE(scan_plan([det1 det2], motor, starting_point, end_point, number_of_steps))

Types of Scripts

You can create either procedural scripts, which execute a sequence of instructions immediately upon loading, or scripts that define functions to be called interactively.

Procedural Scripts

For a procedural script, see the example at ~/bluesky/user_scripts/examples/example_script.py. This script performs the following actions:

Prints the current position of a simulated motor called motor.
Moves motor to position 12.
Executes a relative scan dscan of motor from -1 to +1 in 10 steps.

# Print the current position of the motor
print(f"Current position of the motor: {motor.readback.get()}")

# Move the motor to a specified position
mov motor 12

# Run a scan
dscan motor -1 1 10

To execute this script, use:

load_user_scripts('examples/example_script.py')

Scripts with Functions

This type of script defines a function, such as test_plan(), that encapsulates a series of operations:

def test_plan():
    """Execute this test plan."""
    # Print the current position of the motor
    print(f"Current position of motor: {motor.readback.get()}")

    # Move the motor to position 0
    mov motor 0

    # Run a scan
    dscan [noisy_det] motor -1 1 10

Load this script as follows:

load_user_script('examples/example_with_functions.py')

Once loaded, the function test_plan() is available in the IPython session. To execute it, simply enter:

test_plan()

You do not need to reload the script to execute the function multiple times unless you make modifications to it. If changes are made, reloading is necessary.

Devices

Devices in the Beamline

The devices in the beamline have different components. To see the different component of a device use device.component_names. For instance, to see the component of the plane grating monochromator, called pgm, use pgm.component_names

In general one can manipulate each component by referring to it as device.component. For example the energy of the monochromator is pgm.en.

Accelerator

label: accelerator

Motor	Description	Units
`acc.current`	The ring current	mA
`next_injection.time_next_injection`	Next injection time	sec

Keithleys

label: apertures

Motor	Description	Units	Port
`kth01.current`	Model 6517B	...	9001
`kth02.current`	Model 6514	...	9002

Water Apertures

label: apertures

Motor	Description	Units
`au.top`	Top aperture	mm
`au.bottom`	Bottom aperture	mm
`au.left`	Left aperture	mm
`au.right`	Right aperture	mm

First Mirror

label: mirrors

Motor	Description	Units
`m1.tx`	Translation in X	µm
`m1.ty`	Translation in Y	µm
`m1.tz`	Translation in Z	µm
`m1.rx`	Rotation about X axis	rad
`m1.ry`	Rotation about Y axis	rad
`m1.rz`	Rotation about Z axis	rad

Plane Grating Monochromator

label: pgm

Motor	Description	Units
`pgm.en`	Energy	eV
`pgm.cff`	Constant fix focus factor	a.u.
`pgm.diff_order`	Diffraction Order	a.u.
`pgm.slitwidth`	Exit Slit width	µm
`pgm.grating`	The grating that is being used	l/mm

Moxa Box

The Moxa Box is reachable at the IP 172.31.229.33 and the user admin.