OM - Realtime Experiment Monitoring

Running OM

Prepare workspace

(This section should take no more than 5-10 minutes)

At the beginning of your first shift you need to prepare OM's working directory. This requires access to the operator account for the hutch you will be running the experiment at (mfxopr, cxiopr, ...). The instructions below will be done from the perspective of mfxopr. You may need to subsitute the correct operator or machine names for your hutch to run the commands. The full set of commands without explanatory text can be copied at the end of this block - names will still need to be edited.

1. SSH into mfx-monitor with the operator account: ssh mfxopr@mfx-monitor. If you are using a terminal on a hutch control room machine you can simply use: ssh mfx-monitor
   • If you are not using a hutch machine you may need to do this in two steps. Note you must have special permission to login as mfxopr. If you do not, please use a control room terminal.
     1. ssh mfx-monitor
     2. ssh mfxopr@mfx-monitor
   • mfx-monitor is the default machine for launching OM; however, confirm with beamline staff if it is preferable to use mfx-daq.
2. Move to the OM directory: cd ~mfxopr/OM-GUI
3. Prepare the working directory by copying the template - replace <exp_name> with your experiment name, e.g. mfxx1001122:
   • cp -r template_2023 <exp_name>
4. Change to the workspace directory. If using an ePix10k2M detector use <exp_name>/om-workspace. If using a Rayonix detector use <exp_name>/om-workspace-rayonix
   • cd om-workspace[-rayonix]
5. There is a geometry (.geom) and a mask (.h5) file in this workspace directory. Update these files to the most recent versions. Ask beamline staff for where that may be located. If you need to perform any conversions see notes at the bottom of this page.
   • cp <new_geom>.geom epix10k2M.geom # Copy new geometry to replace epix10k2M.geom or rayonix.geom
   • cp <new_mask>.h5 epix10k2M.h5 # Copy new mask to replace epix10k2M.h5 or rayonix.h5
6. Modify the run_om.sh script in your workspace directory to use the proper machines for OM to run on.
   • By default, OM will use daq-mfx-mon02, daq-mfx-mon03, daq-mfx-mon04, and daq-mfx-mon05 to run on. Confirm with beamline staff that this is okay. Check where other things are running. Use wherepsana -d to see machines.
   • If you need to change the machines, modify the very last line of the script: --host daq-mfx-mon02,daq-mfx-mon03,daq-mfx-mon04,daq-mfx-mon05 $(pwd)/monitor_wrapper.sh. Note: There is no space between the commas and the hostnames.

ssh mfxopr@mfx-monitor # if on control room terminal simply ssh mfx-monitor
# If the above doesn't work, try it in two steps
# ssh mfx-monitor
# ssh mfxopr@mfx-monitor

cd ~mfxopr/OM-GUI
EXP_NAME=MYEXP1234 # REPLACE with experiment name
cp -r template_2023 $EXP_NAME
cd om-workspace-rayonix
cp <geom_file_location> rayonix.geom
cp <mask_file_location> rayonix.h5
nano run_om.sh # Double check the last line for appropriate machines.

Launching OM

Once the folder has been appropriately setup, there are a number of processes which need to be launched.

1. SSH back to the appropriate machine. As above, this is usually mfx-monitor; however, it may be mfx-daq depending on what the beamline staff say.
2. Launch the monitor process: cd ~mfxopr/OM-GUI/<exp_name>/om-workspace[-rayonix]; screen run_om.sh
   • The use of screen is preferred. This will allow other people to reattach to the session from another terminal to e.g. restart the monitor if there are any issues.
   • To detach from the session (it will remain running), use the key combination: Ctrl-a Ctrl-d
   • To reattach to the session type screen -xr. Do NOT use -dr -> This will detach all clients.
3. Launch the main GUI elements:
   • Main GUI: cd ~mfxopr/OM-GUI/<exp_name>/om-workspace[-rayonix]; ./run_gui.sh
   • Frame Viewer: cd ~mfxopr/OM-GUI/<exp_name>/om-workspace[-rayonix]; ./run_frame_viewer.sh
4. Optionally, start the parameter tweaker. This is only recommended for advanced users with extensive experience with the algorithm and the meaning of relevant parameters.
   • cd ~mfxopr/OM-GUI/<exp_name>/om-workspace[-rayonix]; ./run_parameter_tweaker.sh
   • Note, making modifications using the GUI interface of the parameter tweaker will NOT update the monitor process.
   • To update the parameters, after a more optimal set has been found using the GUI interface, copy the parameters into the appropriate locations in the monitor.yaml file. This is located in the same directory as all the other scripts to launch OM components. The monitor process must be restarted.

Note: Resetting Plots without restarting OM

Normally, to reset the accumulated plots, OM should be restarted. Restarting OM could however take several seconds, so it is possible to reset the plots without stopping the program.

1. SSH back to the appropriate machine. As above, this is usually mfx-monitor; however, it may be mfx-daq depending on what the beamline staff say.
2. Run the reset plot script: cd ~mfxopr/OM-GUI/<exp_name>/om-workspace[-rayonix]; ./reset_om_plots.sh

Potential Issues

Geometry

Geometry conventions lead to no shortage of potential issues at LCLS. Please pay careful attention to the formats you are using with OM. OM expects the .geom geometry file to follow Crystfel's format which is different from the psana format for geometry files.

(back to top)