Skip to content

Runs: configuring

This page covers how to customise what happens at run transitions.

For the concepts and day-to-day use, see Runs: overview.

Doing work during run transitions

All midas programs can perform actions when a run is started/stopped/paused/resumed. See Runs: programming for details.

It is also possible to run a custom script when the run starts or stops. To implement this, you can create the ODB keys:

  • /Programs/Execute on start run
  • /Programs/Execute on stop run
  • /Programs/Execute on start abort

Each ODB key should specify a script or command to run. A common use for this system is to log some key information in a "runlog" database, without having to write a full midas program that is always running. Midas supports logging information to a runlog automatically, but many experiments like to do more advanced processing than the built-in tools provide.

The Execute on start abort script gets called if we try to start a run, but a program reports that there is a problem that should prevent the run from actually starting.

The command is run with /bin/sh -c, without any extra arguments, on the machine of the program that started the run (usually mhttpd). midas doesn't wait for it to finish, and its output is discarded, so write to a log file if needed.

Getting the transition and run number

  • To get the run number of the run that is starting/stopping, read /Runinfo/Run number from the ODB.
  • To get the transition that is happening (e.g. starting/stopping) pass an argument to your script (or run a different program for each transition). For example, you could run python3 /path/to/some/script.py start for the "start run" script.

If using these scripts to populate a runlog, it is a good idea to support "backfilling" information from runs that were missed (either because the data was taken before the script was written, or because whatever database you're writing to was unavailable). This is most easily achieved by using the ODB dumps that mlogger writes at the end of each run. The example below includes support for this.

Example runlog python script

This Python script can be used for all three keys by setting them to:

Key Value
/Programs/Execute on start run python3 /path/to/runlog.py start
/Programs/Execute on stop run python3 /path/to/runlog.py stop
/Programs/Execute on start abort python3 /path/to/runlog.py startabort

It reads the run number from the live ODB, and currently just prints it to screen. It needs the midas Python package.

To fill in runs that were missed, run it by hand with the path to an ODB dump, e.g. run01234.json.

#!/usr/bin/env python3
"""
Example script for the "/Programs/Execute on xxx" keys:

    runlog.py start         (Execute on start run)
    runlog.py stop          (Execute on stop run)
    runlog.py startabort    (Execute on start abort)

To fill in runs that were missed, run it by hand with
the ODB dump that mlogger wrote at the end of the run:

    runlog.py backfill run01234.json
"""

import argparse
import json
import midas.client

parser = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("transition", choices=["start", "stop", "startabort", "backfill"])
parser.add_argument("odb_dump", nargs="?", help="when backfilling, the end-of-run ODB dump")
args = parser.parse_args()

if args.transition == "backfill":
    if args.odb_dump is None:
        parser.error("backfill needs an ODB dump file")

    # Read the run number from the end-of-run ODB dump
    with open(args.odb_dump) as f:
        odb = json.load(f)
    run_number = odb["Runinfo"]["Run number"]
    transition = "stop"
else:
    if args.odb_dump is not None:
        parser.error(f"{args.transition} doesn't take an ODB dump file")

    # Read the run number from the live ODB
    with midas.client.MidasClient("runlog") as client:
        run_number = client.odb_get("/Runinfo/Run number")
    transition = args.transition

# This is where the real work would happen, e.g. writing to a runlog database
print(f"Run {run_number}: {transition}")

When midas runs the script, its output is discarded. To see it while testing, add e.g. >> /tmp/runlog.txt 2>&1 to the end of the ODB values.

Deferred transitions

Clients can register a "deferred transition" so that they can do more work before the transition actually happens.

An example use case is to take some extra "calibration" data at the end of a run. So when the user clicks the "Stop" button, your experiment could enable a calibration system, acquire a set number of events, and then actually allow the run to stop.

When a transition is being deferred, the Transition webpage shows a message indicating what is happening:

Deferred transition

Preventing a run from starting

Any program can run its own logic and prevent a run transition from happening.

There are also 2 extra checks that can be enabled by setting flags in the ODB to y:

  • /Experiment/Prevent start on alarms will prevent a run from starting if any alarms are currently triggered
  • /Experiment/Prevent start on required progs will prevent a run from starting if any program that has been marked as required is not currently running

These checks are very useful for minimising the amount of data taken while the experiment is clearly in a sub-optimal state.

Asking questions when the run starts (edit on start)

You can ask the user to answer questions when they are starting a run. This is useful for

  • verifying critical settings, such as whether data should be written to disk or not
  • creating a simple interface for parameters that are changed often, without having to write a custom webpage or having the user find the correct setting in the ODB

Edit-on-start web interface

You can enable this by creating the ODB directory /Experiment/Edit on start. In there, you can either add new keys or create links to other keys in the ODB. For example, to show a checkbox asking whether to write data to disk, you could create a link to /Logger/Write data. You could do this either using the web interface, or the odbedit command-line tool:

odbedit -c 'mkdir "/Experiment/Edit on start"'
odbedit -c 'ln "/Logger/Write data" "/Experiment/Edit on start/Write data"'

Adding help text

You can specify help text (aka parameter comments) for each question by creating the ODB directory /Experiment/Parameter comments. Add keys (of type "string") with the same name as the variable in the "Edit on start" directory. Again, you can this using either the web interface or the odbedit command-line tool:

odbedit -c 'mkdir "/Experiment/Parameter comments"'
odbedit -c 'create string "/Experiment/Parameter comments/Write data"'
odbedit -c 'set "/Experiment/Parameter comments/Write data" "Write data to disk?"'

Parameter comments for links

If you want to provide a comment for an "edit on start" parameter that is a link, you must use the name of the link itself, not the name of its target. For example:

  • If the link name is /Experiment/Edit on start/Write midas file
  • ... and the link target is /Logger/Write data
  • ... the comment should be in /Experiment/Parameter comments/Write midas file, NOT .../Write data

Parameter comments may include HTML. For example, you could highlight a comment in red by setting the comment to:

<span style="color:red">Write data to disk?</span>

Preventing the user from editing the run number

You can create the special ODB key /Experiment/Edit on start/Edit run number as a boolean. If you set this to n, then the run number will not be editable from the "start run" web interface, and will automatically increment by 1.

Note that this does not prevent any code from editing the run number, or prevent users from directly editing the run number in /Runinfo/Run number. It is purely a convenience to limit the options available on the "start run" interface.

When the questions get asked

The questions are shown when users start a run using the web interface or using the odbedit start command.

They are NOT shown when a run is started automatically by code, by the sequencer, or using the odbedit start now command.