GWCloud class

The GWCloud object class can be thought of as the link to the GWCloud service, though they are primarily used as a means by which to manipulate Bilby jobs. It can used for submitting a new job to the queue, obtaining the information for a single specific job, or even obtaining lists of jobs matching certain search criteria. Indeed, BilbyJob objects also use a reference to the GWCloud class to request their own files and information.

class gwcloud_python.gwcloud.GWCloud(token='', auth_endpoint='https://gwcloud.org.au/auth/graphql', endpoint='https://gwcloud.org.au/bilby/graphql')

Bases: object

GWCloud class provides an API for interacting with Bilby, allowing jobs to be submitted and acquired.

Parameters:

token (str, optional) – API token for a Bilby user. If omitted, creates an anonymous read-only GWCloud instance
auth_endpoint (str, optional) – URL to which we send the authentication queries, by default GWCLOUD_AUTH_ENDPOINT
endpoint (str, optional) – URL to which we send the queries, by default GWCLOUD_ENDPOINT

client

Handles a lot of the underlying logic surrounding the queries

Type:: GWDC

create_event_id(event_id, gps_time, trigger_id=None, nickname=None, is_ligo_event=False)

Create an Event ID that can be assigned to Bilby Jobs

INFO: Event IDs can only be created by a select few users.

Parameters:

event_id (str) – ID of the event, must be of the form GW123456_123456
gps_time (float) – The GPS time that this Event ID represents, e.g. 1126259462.391
trigger_id (str, optional) – Trigger ID of the event, must be of the form S123456a, by default None
nickname (str, optional) – Common name used to identify the event, by default None
is_ligo_event (bool, optional) – Should the event be visible to ligo users only, by default False

Returns:

The created Event ID

Return type:

.EventID

delete_event_id(event_id)

Delete an Event ID

INFO: Event IDs can only be deleted by a select few users.

Parameters:: event_id (str) – ID of the event, must be of the form GW123456_123456

get_all_event_ids()

Obtain a list of all Event IDs

Parameters:: event_id (str) – ID of the event, must be of the form GW123456_123456
Returns:: A list of all .EventID objects
Return type:: list

get_event_id(event_id)

Get EventID by the event_id

Parameters:: event_id (str) – Event ID of the form GW123456_123456
Returns:: The requested Event ID
Return type:: .EventID

get_files_by_reference(file_references)

Obtains file data when provided a FileReferenceList

Parameters:: file_references (FileReferenceList) – Contains the FileReference objects for which to download the contents
Returns:: List of tuples containing the file path and file contents as a byte string
Return type:: list

get_job_by_id(job_id)

Get a Bilby job instance corresponding to a specific job ID

Parameters:: job_id (str) – ID of job to obtain
Returns:: BilbyJob instance corresponding to the input ID
Return type:: BilbyJob

get_official_job_list(search='')

Get list of public Bilby jobs corresponding to a search of “labels.name:Official” and a time_range of “Any time”

Parameters:: search (str, optional) – Search terms by which to filter public job list, by default “”
Returns:: List of BilbyJob instances for the official jobs corresponding to the search terms
Return type:: list

get_public_job_list(search='', time_range=TimeRange.ANY, number=100)

Obtains a list of public Bilby jobs, filtering based on the search terms and the time range within which the job was created.

Parameters:

search (str, optional) – Search terms by which to filter public job list, by default “”
time_range (TimeRange or str, optional) – Time range by which to filter job list, by default TimeRange.ANY
number (int, optional) – Number of job results to return in one request, by default 100

Returns:

List of BilbyJob instances for the jobs corresponding to the search terms and in the specified time range

Return type:

list

get_user_jobs(number=100)

Obtains a list of Bilby jobs created by the user, filtering based on the search terms and the time range within which the job was created.

Parameters:: number (int, optional) – Number of job results to return in one request, by default 100
Returns:: List of BilbyJob instances for the jobs corresponding to the search terms and in the specified time range
Return type:: list

save_files_by_reference(file_references, root_path)

Save files when provided a FileReferenceList and a root path

Parameters:

file_references (FileReferenceList) – Contains the FileReference objects for which to save the associated files
root_path (str or Path) – Directory into which to save the files

start_bilby_job_from_file(job_name, job_description, private, ini_file, cluster=Cluster.DEFAULT)

Submit the parameters required to start a Bilby job, using an .ini file

Parameters:

job_name (str) – Name of the job to be created
job_description (str) – Description of the job to be created
private (bool) – True if job should be private, False if public
ini_file (str or Path) – Path to an .ini file for running a Bilby job
cluster (Cluster or str) – The name of the cluster to submit the job to

Returns:

Message received from server after job submission

Return type:

str

start_bilby_job_from_string(job_name, job_description, private, ini_string, cluster=Cluster.DEFAULT)

Submit the parameters required to start a Bilby job, using the contents of an .ini file

Parameters:

job_name (str) – Name of the job to be created
job_description (str) – Description of the job to be created
private (bool) – True if job should be private, False if public
ini_string (str) – The contents of a Bilby ini file
cluster (Cluster or str) – The name of the cluster to submit the job to

Returns:

Message received from server after job submission

Return type:

str

update_event_id(event_id, gps_time=None, trigger_id=None, nickname=None, is_ligo_event=None)

Create an Event ID that can be assigned to Bilby Jobs

INFO: Event IDs can only be updated by a select few users.

Parameters:

event_id (str) – ID of the event, must be of the form GW123456_123456
gps_time (float, optional) – The GPS time that this Event ID represents, e.g. 1126259462.391
trigger_id (str, optional) – Trigger ID of the event, must be of the form S123456a, by default None
nickname (str, optional) – Common name used to identify the event, by default None
is_ligo_event (bool, optional) – Should the event be visible to ligo users only, by default None

Returns:

The updated Event ID

Return type:

.EventID

upload_external_job(job_name, job_description, private, ini_string, url)

Upload a Bilby job to GWCloud with external results

Parameters:

job_name (str) – Name of the job to be created
job_description (str) – Description of the job to be created
private (bool) – True if job should be private, False if public
ini_string (str) – The contents of a Bilby ini file
url (str) – The URL to the external results. Might be a url directly to a result file, or to a directory listing, or something else

Returns:

The created Bilby job

Return type:

BilbyJob

upload_job_archive(description, job_archive, public=False)

Upload a bilby job to GWCloud by job output archive

Parameters:

description (str) – The description of the job to add to the database
public (bool) – If the uploaded job should be public or not
job_archive (str) – The path to the job output archive to upload

Returns:

The created Bilby job

Return type:

BilbyJob

upload_job_directory(description, job_directory, public=False)

Upload a bilby job to GWCloud by job output directory

Parameters:

description (str) – The description of the job to add to the database
public (bool) – If the uploaded job should be public or not
job_directory (str) – The path to the job output directory to upload

Returns:

The created Bilby job

Return type:

BilbyJob