gwcelery.tasks.orchestrator module

This module implements the alert orchestrator, which responsible for the vetting and annotation workflow to produce preliminary, initial, and update alerts for gravitational-wave event candidates.

The orchestrator consists of two LVAlert message handlers:

• handle_superevent() is called for each superevent. It waits for a short duration of orchestrator_timeout seconds for the selection of the superevent by the superevent manager to stabilize, then performs data quality checks. If the data quality checks pass, then it calls preliminary_alert() to copy annotations from the preferred event and send the preliminary GCN notice.

• handle_cbc_event() is called for each CBC event. It performs some CBC-specific annotations that depend closely on the CBC matched-filter parameters estimates and that might influence selection of the preferred event: rapid sky localization with BAYESTAR and rapid source classification.

  Note that there is no equivalent of this task for burst events because both burst searches (cWB, LIB) have integrated source localization and have no other annotations.

Preliminary Alerts

The flow chart below illustrates the operation of these two tasks.

Initial and Update Alerts

The initial_alert() and update_alert() tasks create Initial and Update alerts respectively. At the moment, there is no handler or user interface to trigger these tasks, and they must be invoked manually (see Command-Line Tools). A flow chart for the initial alerts is shown below; the flow chart for update alerts is the same.

Retraction Alerts

Likewise, the retraction_alert() task creates Retraction alerts, and at the moment must be invoked manually. A flow chart is shown below.

Tasks

Tasks that comprise the alert orchestrator, which responsible for the vetting and annotation workflow to produce preliminary, initial, and update alerts for gravitational-wave event candidates.

(task)gwcelery.tasks.orchestrator.handle_superevent(alert)

Schedule annotations for new superevents.

After waiting for a time specified by the orchestrator_timeout configuration variable for the choice of preferred event to settle down, this task peforms data quality checks with gwcelery.tasks.detchar.check_vectors() and calls preliminary_alert() to send a preliminary GCN notice.

(task)gwcelery.tasks.orchestrator.handle_cbc_event(alert)

Peform annotations for CBC events that depend on pipeline-specific matched-filter parameter estimates.

Notes

This LVAlert message handler is triggered by updates that include the files psd.xml.gz and ranking_data.xml.gz. The table below lists which files are created as a result, and which tasks generate them.

(task)gwcelery.tasks.orchestrator.preliminary_alert(event, superevent_id)

Produce a preliminary alert by copying any sky maps.

This consists of the following steps:

1. Copy any sky maps and source classification from the preferred event to the superevent.
2. Create standard annotations for sky maps including all-sky plots by calling gwcelery.tasks.skymaps.annotate_fits().
3. Create a preliminary VOEvent.
4. Send the VOEvent to GCN.
5. Apply the GCN_PRELIM_SENT label to the superevent.
6. Create and upload a GCN Circular draft.
7. Start parameter estimation with LALInference.

(task)gwcelery.tasks.orchestrator.initial_or_update_alert(superevent_id, alert_type, skymap_filename=None)

Create and send initial or update GCN notice.

Parameters:

• superevent_id (str) – The superevent ID.
• alert_type ({'initial', 'update'}) – The alert type.
• skymap_filename (str, optional) – The sky map to send. If None, then most recent public sky map is used.

(task)gwcelery.tasks.orchestrator.initial_alert(superevent_id, skymap_filename=None)

Produce an initial alert.

This does nothing more than call initial_or_update_alert() with alert_type='initial'.

Parameters:

• superevent_id (str) – The superevent ID.
• skymap_filename (str, optional) – The sky map to send. If None, then most recent public sky map is used.

(task)gwcelery.tasks.orchestrator.update_alert(superevent_id, skymap_filename=None)

Produce an update alert.

This does nothing more than call initial_or_update_alert() with alert_type='update'.

Parameters:

• superevent_id (str) – The superevent ID.
• skymap_filename (str, optional) – The sky map to send. If None, then most recent public sky map is used.

(task)gwcelery.tasks.orchestrator.retraction_alert(superevent_id)

Produce a retraction alert. This is currently just a stub and does nothing more than create and send a VOEvent.