MXCuBE3 is the user interface for macromolecular crystallography experiments used at BioMAX. MXCuBe3 is the result of an international collaboration to create an intuitive and user friendly application. This page describes how to use the MXCuBE3 GUI to carry out experiments at BioMAX. Click on each of the following links to display information for each step.

MXCuBE3 runs on the Firefox browser installed on all the BioMAX control workstations. The GUI can be launched either from the MXCuBE3 icon on the workstation desktop or by typing the command “mxcube” on a terminal window. Type your user name and password to log in and access the list of you active proposals. Click on the current proposal and then on the Select Proposal button.
To launch MXCuBE3 from an already open browser window, type the url Once the interface loads, log in with you DUO user name and password and select the proposal.

Note: The first time ever you log in at a BioMAX machine under you user account, there will be no MXCuBE or other experiment software icons displayed until you open a terminal. This will run a login script and set up the desktop environment.

Usually during your experiment, the MAX IV 3 GeV ring will operate in top up mode and X-rays will be delivered to the beamline. You can monitor the electron beam current on MXCuBE. However the electron beam in the accelerator may be lost on occasion. If this happens, you can reopen the beamline from the Beamline Actions drop down menu, by selecting “open_beamline_shutters” or “beamtime_start”. When you finish your experiment outside staff support hours, run the “end_beamtime” option from the same menu to close the beamline.

You can change the energy for the experiment from the top bar in MXCuBE. Depending on the starting and ending energies, it can take over a minute for all the motors involved to finish moving. During this time, the beam position is not stable. Use the “check beam” tool under Beamline Actions after the energy has finished moving to see when the beam has stabilized.

Preparing to use the sample changer

Before connecting to MXCuBE3 to mount samples with the sample changer, you must have prepared a shipment containing a list of samples in ISPyB as described in the sample shipping procedure. This ensures that all your data will be given a unique name and stored under a directory named after your samples.

Note:The MAX IV sample changer supports samples mounted on UniPucks only.

Once you arrive to the beamline, staff will show you how to place your samples in the robot dewar. If you use the IsaraLoader iPAD tool while you load the pucks, the puck positions will be automatically entered in ISPyB. If you cannot use the tool, you need to log in to ISPyB to assign the puck positions; select your proposal number and click on the Prepare experiment tab; then, follow the steps listed in the page:

  • Select the dewar or dewars containing your samples.
  • Select the dewar containing the samples from the ISPyB “Prepare Experiment” tab.
  • Select the location (“basket”) in the sample changer dewar for all the UniPucks in the shipment. Click the Save button after completing this step.
  • Assignment of sample container to position in sample changer dewar.

Once the pucks are assigned (manually from ISPyB or automatically by the IsaraLoader), go to MXCuBE3:

  • Enable the robot (you can do this from the Data Collection menu, by clicking on the button to the left of the safety shutter, once the hutch is searched and locked).
  • click on the Sample Viewer menu, and synchronize the sample list with ISPyB. All the samples will be displayed in the screen.
Click on the ISPyB button to synchronize the sample information with ISPyB.

It is a good idea to filter the display to list only the samples you are interested in. For example, you can filter by basket, which will only list the samples in a single UniPuck placed in that basket, by samples entered via ISPyB (useful if you have partially filled pucks and you only want to see locations with samples), by sample name, etc.

Filtering the displayed samples. You can choose multiple criteria.

Important: Double-check that the fill pattern of pucks match exactly the information entered in ISPyB. If the robot mounts an non-existing sample, it will not be able to dismount it!

If you need to go inside the hutch after you have started robot operation, follow this procedure:

  • From MXCuBe3, use the Beamline Actions drop down menu to select the “prepare_open_hutch”. This scripted action will move the sample exchanger and other beamline motors to a safe position.
  • During execution of the script, a window will pop up on MXCuBE3. Do not press the “abort” button, doing so may require a robot reset by staff.
  • After the procedure is finished, the “Run” button will appear at the top of the window; then it is safe to go inside the hutch.

You will also follow the same procedure to go inside the hutch to dismount your samples after the experiment. Please make sure to close the dewar lid after dismounting the samples.

Mounting single samples

Once a sample information is loaded onto MXCuBE3 you can mount it by right clicking on the sample block. This displays a sample menu that displays all the possible actions for the sample.

    Sample menu shown upon right-clicking on a given sample

    To just mount the single sample, without any setup of an automated data collection run or other sequential actions, click on Mount. Once the sample is visible on the video screen, follow the steps in the sections below to center the sample and set up the data collection.

The rest of the selections in the menu are related to sample inclusion in a queue of automated or semiautomated tasks, as documented in the next section.

Queuing up samples and tasks

Although you can select and mount the samples one at a time, it is often more efficient to select several of them and set up a queue, which allows a number of tasks to be performed in an automatic or semiautomated sequence, while also providing the possibility to set up different tasks or data collection modes for some or all of the samples:

    • Select the samples. The fastest way to do this is to click and draw a rectangle over all the samples of interest, but you can also hold down the Ctrl key and click on individual samples. The selected samples will be surrounded by a discontinuous grey frame. then, use the Add to Queue button to add all the selected samples to the queue. The samples in the queue will be highlighted in blue. To remove a sample from the queue, right click on the sample and select Dequeue sample.
    • Selected samples.
    • If you wish to define characterization or data collection tasks at this point, use the drop down menu next to the Add to Queue, as described in the Data Collection section. The same parameters will be applied to all the samples in your current selection. Note that it is not possible to execute the newly defined data collection at this stage (the Run button is inactive). If you do not want to define tasks at this stage, simply skip this step.
    • Menu to add a task for all the samples selected.
      Adding a sample characterization task. The variables in the directory and data set names will be substituted by the values defined in ISPyB for each of the samples.
    • Click on the Add to queue button at the bottom of the task definition box. If you added data collection parameters, a small square will be displayed on the samples in the queue for each of the task or tasks added (C for “characterization” or DC for “data collection”. You can add multiple tasks for each sample.
    • If you want to remove a data collection task, click on the cross in the task button. It will also be possible to define the data collection tasks modify the parameters or add more data collections once the sample is mounted.

    If you have not defined any data collection tasks, go to the Data collection Tab and click on the Mount button next to each samples to mount them and collect data one by one. Before mounting a sample, the robot will automatically dismount the previous one.

    If you have defined tasks for all the samples, you can execute the queue by clicking on the Collect button in the Sample Overview tab or Run Queue in the Data collection Tab.

    • A configuration pop-up window will open with some options to run the queue:
      Window showing all the tasks that run sequentially in the queue.

      1. The Auto loop centering option can be used to center the loop in the beam. Automated centering may not work for small crystals in large loops. IN this case it is better to center the crystal manually.
      2. Select Automount next sample to dismount the current sample after all the tasks are defined and mount the following sample in the queue automatically. Only do this if you are confident that your chosen parameters for data collection or sample characterization are appropriate.
      3. Record crystal snapshots (see the information below).
    • Click Collect when everything is OK.

    You will be able to stop or pause the queue execution from the Data Collection view whenever you want to change the tasks or introduce more tasks.

"Create new sample" button. Use before going in to the hutch to mount a new sample
Click “Create new sample” button for manual sample setup.

Manual sample is an option for sample mounts or containers incompatible with the sample exchanger or for collecting data at room temperature. MXCuBE3 can be used to automatically close the beamline shutter and retract the instruments surrounding the diffractometer to facilitate mounting of a new sample (this configuration is known as the Transfer phase). To set the transfer phase, use the Beamline Actions drop down menu and select “prepare new sample”. Then, go into the hutch, mount the new sample and search and lock the hutch.

Input boxes used to enter the sample and protein names that will identify the data set.
Input boxes used to enter the sample and protein names that will identify the data set.

Once the sample is mounted, provide names for the sample and the protein in the respective input boxes in MXCuBE3:

  • Select the Queued Samples tab and click on the button named Create new sample
  • Click Add sample and mount. This will create an entry for the sample under the Current tab. If you click Add sample instead, the sample will just be added to the queued samples list, and you will have to “mount” it by clicking on the button next to the sample name. If you do not like the name you have created or you think that the sample does not look right and do not want to proceed to image collection, click Finish to remove it.
  • These names will be the base for the dataset files and data storage directory names, so you may not use any spaces or strange characters; if the input box remains lined in red, the chosen name is not valid.
  • Once you have mounted the sample, return to MXCuBE and change the diffractometer phase to Centring. Follow the steps described in the next section to bring the sample into focus and inspect it visually before proceeding with data collection.

The following steps are done automatically after a sample is mounted if you are running a queue. If you prefer to inspect the sample before taking diffraction shots or to choose which part of the sample to expose

  • The sample exchanger mount procedure changes the phase automatically to centring mode after mounting a new sample. In the centring phase, a backlight is inserted to make it easy to see the crystal and the sample moves close to the center of the camera view, provided that the length of the pin is standard. If the crystal is far away from the beam position (marked with a blue circle), right click on the crystal or, if not visible, on any portion of the pin or the mount that you can see on the screen and select Move to beam. Use the arrows next to the Omega input box to rotate the motor by 90 degrees and adjust the sample position in the other direction. You can also access the Move to beam function by holding the Shift key and double clicking on the point you wish to center; or translate the sample using the arrows on the translation tool located to the left of the screen.
    Sample translation tool. Click on the arrows to translate the sample . Click on the settings symbol to define the length of the translation.

    Sample visualization and video interaction menu
    Sample visualization and video interaction menu
  • Click on the icon named 3-click Centring to centre the sample in three clicks. Once the crystal is roughly centered at low zoom level, click on the Zoom icon to magnify the image or by holding the Z key and using the mouse scroll wheel. Adjust the centering if necessary with a new 3-click center -note that the first click will not do anything in terms of centering the crystal, it just reactivates the 3-centring function! After the centering is done, the point will be displayed in white. Make sure that you do not click on the 3-centring icon again, this will lose the coordinates for the centered position and you will have to recenter again in order to set up data collection.
  • It is a good idea to rotate Omega to make sure that the crystal remains in the beam at all orientations. You can use the arrows next to the input box to rotate the motor in 90 degree steps as mentioned above; you can also change the step size by entering a different number next in the input box to the right of the motor position; or hold down the R key and use the mouse scroll wheel.
  • If you want to proceed to a data collection already set up for a sample mounted with the robot, or if you want to set up a helical data collection or collect data from multiple spots on the crystal, make sure that you save the current position, by right clicking inside the point and selecting Save point. Saved points are displayed in green. If you just want to set up a data collection from the newly centered single point you can either save it or just select either Add Characterization or Add Datacollection from the right-click menu. You can move to any previously saved point by clicking on it.
  • If you right click outside the point you will have access to a different menu to collect 2D data (without rotating the crystal). This option can be useful to locate a good diffraction spot on an inhomogeneous crystal or determine a difficult-to-see crystal location

Knowing the flux (total number of photons per second on the sample) is important to be able to estimate the time that the crystal can last in the beam. MXCuBE3 will measure the flux before starting each data collection and saves it under the ISPyB experimental parameters; it also displays the last value measured at the top of the GUI. This value will depend on the beamline transmission and the beam defining aperture in use and also depends somewhat on the beam energy. Typically, you expect to measure 4-6×1012 photons/s through the 20 micron aperture with a focus beam and full transmission.

For the flux measurement, the software changes the MD3 phase and translates the sample closer to the cryojet by a small amount to avoid exposing it to the X-rays. It will be returned to the original position once the measurement is finished.

If you want to measure the beam manually (for example, to check the flux after changing the energy or the aperture size) open the Beamline Actions and run the calculate_flux action. Note: The flux value only gets updated before each data collection or when you run the calculate_flux function. If the beam disappears afterwards, the flux value will not change automatically. If you get a flux value of the order of or less than 107 photons/s (which is the error level in the measurement), there is no beam reaching the sample. If that is the case, check for obvious causes, such as a too high beam transmission, a loss of the electron beam in the R3 accelerator or a beamline shutter is closed. If that is not the case, contact staff

The flux value can be used for dose calculation, for instance in the raddose server.

Right-click on a defined point to access the data collection options
Right-click on a defined point to access the data collection options

There are three different modes implemented for oscillation data collection, described below. Since 2020, a fourth mode is available to to measure XRF spectra. In general, the only input required is what is displayed in the setup window when you select the desired mode.

Note that the default input values shown the first time you setup a data collection are not necessarily correct for your samples. Inspect them carefully and change them according to the recommendations below or the advice of the support person. The values you choose will be saved and selected by default for subsequent runs. If you type a parameter that differs from the current value, the input box will be lined in orange. This only means that the position of the motor will change when you start the data collection. The software will not allow you to type invalid values (for example, a value for the resolution that would result in the detector moving past its motion limit). Some optional input boxes will appear when clicking on the three dots below the required input. Some of these options are not fully implemented yet and it is better not to use them, unless the support person indicates otherwise.

  • Clicking on the Run Now button will start the data collection. Add to Queue will add it to the current queue, which can be of use when mounting samples manually to collect data from different points of the sample. Once a data collection is queued, use the Change button to modify the input parameters before the data collection is executed.
  • Running data collections are displayed in blue. If you notice a problem with the data collection setup, click on the Stop button to abort the data collection fully. Stopped runs are highlighted in red. It is possible to restart stopped runs by clicking on the run and then on any of the displayed input parameters. This will reopen the setup window.
  • The Pause button will stop the current action and allow you to resume the data collection, but does not have any effect once the actual data acquisition with the detector starts.
  • Once the data collection is complete, it will be highlighted in green. Data collections that finish with an error are displayed in red. If the collection finishes with a warning, it will be displayed in orange.
  • You can clone any run by right clicking on the run name header and selecting Duplicate from the drop down menu. The duplicated run will be then added to the end of the queue. Click on it and then on one of the input parameters to edit the data collection parameters.

Sample characterization

Sample characterization setup panel
Sample characterization setup panel

This function is used to collect up to 4 diffraction shots from a crystal at different orientations 90 degrees apart. Automated image analysis has not been implemented yet, but you can examine the images with the program Albula. A shortcut to run Albula in monitoring mode is provided in the workstation desktop.

For the characterization images, it is better to collect over a wide omega oscillation to make it easier to evaluate the quality of the diffraction by eye (0.5 or 1 degree), with an exposure time of 0.05-0.1 seconds per image and transmission of 20-100%, depending on the collimator size. For the resolution, try a value somewhat better than you expect. Also beam in mind that the initial resolution from the test images, whether estimated visually or calculated by integrating the images, will often be an underestimate of the useful diffraction limit of the crystal.

Data collection

For data collection on a single point, we recommend using exposure times of 11 ms per degree. With a defocused beam (50 microns), 0.1 degree images with 10 ms exposure per image at 50-100 % attenuation result in good quality data. We strongly recommend collecting 180 or 360 degrees (or more, for de novo phasing experiments) If the crystal is larger than the maximum available beam aperture size (currently 50 microns) it is advantageous to set up a helical data collection instead (see next section). For small crystals (around 10 microns) it may be better to use the focused beam with a small aperture.

Data collection setup panel
Data collection setup panel

Helical scan

If the crystal is larger than the beam, the best practice to minimize radiation damage is to make the beam as large as the crystal. If you are already using the largest beam size available at the beamline, helical collection will help mitigate radiation damage by bringing a fresh volume of the crystal into the beam for each image.

To set up a helical data collection, you must define the start and end points of the data collection along the crystal. You do this by centering the crystal and saving each of the points as described above. Then, click and drag the mouse over an area including both points. That will draw a line between the points defining the data collection axis. Ideally, it is best to use two points along the omega axis, but translation along the perpendicular axis is better than collecting about a fixed point.

XRF scan

The XRF scan is useful to detect the presence of heavy metals in the sample, whether they are present in the buffer or bound to the protein. In some cases, this can be useful to identify features in the density map.

When you start the scan, the fluorescence detector will move to point towards the sample. The software will acquire a series of very short exposures to determine the optimal beam transmission, which is typically rather low. The, the crystal is exposed during the time selected in the input window (we recommend to use 0.1 seconds). The resulting spectrum will be saved to ISPyB. Often, the dose recieved by the crystal during this measurement is not higher than the equivalent of 10-20 diffraction images, but if you are concerned about minimizing the dose, you can collect it after data collection, or use a poor quality sample.

The result file will be stored together with the diffraction images in the sample directory. Besides the h5 format file, we also save a png file for easier visualization. This file is also visible in ISPyB.

To collect crystal snapshots, click on the Snapshot icon. Make sure that you are in the centring phase, since it provides the best view of the crystal. After you have collected the snapshot, you can save the file to any location in your directories.

To have snapshots taken automatically during data collection, use the Settings pull down menu. You can take up to 4 snapshots. Bear in mind that the images are taken in the centring phase at intervals of 90 degrees and the changes between phases add extra time to the data collection.

Once a data collection is finished, the software will launch several automated data processing pipelines. The results can be browsed in the ISPyB interface. To access ISPyB from MXCuBe3 , select the completed data collection run and click on the ISPyB link. The ISPyB application will open in another browser tab. The first time you open you need to type in your user account name and password to log in. Once logged in, go back to the tab where MXCuBE3 is running and click on the link again. ISPyB will remember your credentials and take you directly to the results page for the selected data collection.

Please also see Data handling and processing at BioMAX.

Link to the Remote Access (RA) tab in MXCuBE3. The number next to the link corresponds to the number of observers connected to MXCuBE

MXCuBE3 supports multiple user log in from multiple locations, at the beamline or remotely. Any user belonging to the same proposal can be logged in simultaneously, although only one can issue commands and has control over the interface; this user is called “master”; by default, the master is the user who logs in first. The users who log in afterwards are “observers”. When one more than one user is logged, the number of observer users is displayed on top of the link to the Remote Access (RA) tab, and an icon to the chat tool appears to the right bottom of the interface. The RA tab lists all the users logged in and who is the current master.

Remote Access (RA) tab

The observer users can navigate through all the MXCuBE tabs and see what the user in control is doing. They can also use remote tools such as the beamline video feed and the chat and request control through by clicking on the Ask for control button in the Remote Access (RA) tab. Observers cannot use the Take control button; only user support staff can use this button, if it is necessary for experiment support or troubleshooting.

Links to the beamline video feed and chat tool

If an observer asks for control, the master can give control by clicking on the window that appears on their instance of MXCuBE. There is also a general option to transfer control by default after a timeout period. Finally, the master user can also give control at any time to any other account logged in by clicking on the control icon in the last column of the user information list in the RA tab (but the master cannot log out any other user; that is also a support staff tool).

The master user should be able to mount samples, collect data and control the beamline through MXCuBE regardless of location. Caution: Is it important that the master user always transfer control or logs out from MXCuBE before walking out of an experiment. Otherwise, unless the timeout option is enabled, noone else will be able to become master without staff’s help. If the master signs out from MXCuBE, the next user to log in will be the new master.

For general information about obtaining and preparing for remote beamtime, please read Remote experiments at BioMAX.

  • The most common problem is a lack of response of the video screen (it does not refresh and it does not respond to input). This lack of response can also happen with other information displayed on real time and is usually caused by a glitches in the connection to the video or other servers. It usually can be solved easily by refreshing the MXCuBE3 application page web page.
  • If it is not just the video that is not responding, or if a simple page reload does not work, try logging out and closing and reopening the browser. If the problem persists, call support staff so that they can restart the server and log in again to MXCuBE3. The video does not reconnect automatically after a server reset, and you will have to refresh the page to get it to update.
  • The sample queue will also be lost after a server reset and you will not be able to see which samples you have already collected data from either. However, the sample collection information is preserved in the ISPyB Data collection tab.
  • If the Sign out button appears to be inactive, try increasing the size of the browser window. This can be a problem when running MXCuBE3 on a small screen.
  • Currently MXCuBE does not issue any warning if the X-rays are not being delivered to the sample. If the diffraction images suddenly look blank (no scatter from the air creating a beamstop shadow, no counts on the detector), check that there is a current in the ring and that the beamline is open. If there is air scatter on the detector, check the alignment of the sample. If the beamline is open but the problem persists, contact staff.