qci_client.optimization

QCi optimization application v1.

qci_client.optimization.client

Client for QCi’s optimization API.

class qci_client.optimization.client.OptimizationClient(*, url: str | None = None, api_token: str | None = None, timeout: float | None = None, max_workers: int = 8, compress: bool = False)[source]

Bases: object

Used to run optimization jobs against QCi hardware.

Provides access to QCi’s public API for running optimization problems on Dirac devices, including file uploads/downloads and submitting/retrieving entire jobs.

Parameters:

• url – url basepath to API endpoint, including scheme, if None, then falls back to QCI_API_URL environment variable
• api_token – refresh token for authenticating to API, if None, then falls back to QCI_TOKEN environment variable
• timeout – number of seconds before timing out requests, None waits indefinitely
• max_workers – number of threads for concurrent file download calls
• compress – compress file metadata and parts before uploading

property url: str

Return API URL.

property api_token: str

Return API token.

property timeout: float | None

Return timeout setting.

property max_workers: int

Return maximum number of concurrent workers for file operations.

property compress: bool

Return file compression usage flag.

property jobs_url

Get jobs URL.

get_job_id_url(*, job_id: str) → str[source]

Get job URL with job ID.

get_job_status_url(*, job_id: str) → str[source]

Get job-status URL using job ID.

get_job_metrics_url(job_id: str) → str[source]

Get legacy job-metrics URL using job ID.

get_job_metrics_v1_url(job_id: str) → str[source]

Get v1 job-metrics URL using job ID.

get_job_metrics_v2_url(job_id: str) → str[source]

Get v2 job-metrics URL using job ID.

get_job_allocations_url() → str[source]

Get job-allocations URL.

property files_url

Get files URL.

get_file_id_url(*, file_id: str) → str[source]

Get file URL with file ID.

get_file_contents_url(*, file_id: str, part_number: int) → str[source]

Get file contents URL with file ID and file part number.

upload_file(*, file: dict) → dict[source]

Upload file (metadata and then parts concurrently). Returns dict with file ID.

download_file(*, file_id: str) → dict[source]

Download file (metadata and then parts concurrently).

submit_job(*, job_body: dict) → dict[source]

Submit a job via a request to QCi’s optimization API.

Parameters:

job_body – formatted json body that includes all parameters for the job

Returns:

Response from POST call to API (see get_job_results())

cancel_job(*, job_id: str) → dict[source]

Cancel a job via a PATCH request to QCi’s optimization API.

Only SUBMITTED, QUEUED, and RUNNING jobs will be successfully cancelled, raising an exception otherwise.

Parameters:

job_id – ID of job

Returns:

Response from PATCH call to API

get_job_results(*, job_id: str) → dict[source]

Get job_info, status, and results of a (possibly uncompleted) job by its ID.

Parameters:

job_id – ID of job

Returns:

Dictionary with latest job_info, status, and results.

get_job_status(*, job_id: str) → dict[source]

Get the status of a job by its ID.

Parameters:

job_id – ID of job

Returns:

Response from GET call to API

get_job_metrics(*, job_id: str) → dict[source]

Get the metrics for a job by its ID. v2 metrics are tried first, then legacy/v1 metrics.

Parameters:

job_id – ID of job

Returns:

Response from GET call to API

get_job_response(*, job_id: str) → dict[source]

Get a response for a job by id, which may/may not be finished.

Parameters:

job_id – ID of job

Return dict:

json response

get_allocations() → dict[source]

Get allocations for running jobs on different device classes.

Return dict:

json response

build_job_body(*, job_type: JobType | str, job_params: dict, qubo_file_id: str | None = None, graph_file_id: str | None = None, hamiltonian_file_id: str | None = None, objective_file_id: str | None = None, constraints_file_id: str | None = None, polynomial_file_id: str | None = None, job_name: str | None = None, job_tags: list | None = None) → dict[source]

Constructs body for job submission requests.

Parameters:

• job_type – an enum.JobType or one of the string values defined in enum.JobType
• job_params – dict of params to be passed to job submission in “params” key
• qubo_file_id – file id from files API for uploaded qubo
• graph_file_id – file id from files API for uploaded graph
• hamiltonian_file_id – file id from files API for uploaded hamiltonian
• objective_file_id – file id from files API for uploaded objective
• constraints_file_id – file id from files API for uploaded constraints
• polynomial_file_id – file id from files API for uploaded polynomial
• job_name – user specified name for job submission
• job_tags – user specified labels for classifying and filtering user jobs after submission

Returns:

None

process_job(*, job_body: dict, wait: bool = True, verbose: bool = True) → dict[source]

Parameters:

• job_body – formatted json dict for body of job submission request
• wait – wait synchronously for job to complete
• verbose – track operations’ progress using timestamped console logs

Returns:

if wait is True, then dict with job_info, status, and results and results

fields (results is None if job is not successfully COMPLETED)

if wait is False, then response dict from submitted job, which includes

job_id for subsequent retrieval (see get_job_results())

list_files() → dict[source]

List files (metadata only).

Returns:

dict containing list of files

qci_client.optimization.data_converter

Functions for data conversion.

qci_client.optimization.data_converter.data_to_json(*, file: dict) → dict[source]

Converts data in file input into JSON-serializable dictionary that can be passed to Qatalyst REST API

Parameters:

file – file dictionary whose data of type numpy.ndarray, scipy.sparse.spmatrix, or networkx.Graph is to be converted

Returns:

file dictionary with JSON-serializable data

qci_client.optimization.enum

Enumerations.

class qci_client.optimization.enum.JobType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of all job types, which are specific to qci-client.

SAMPLE_QUBO = 'sample-qubo'

GRAPH_PARTITIONING = 'graph-partitioning'

SAMPLE_CONTRAINT = 'sample-constraint'

SAMPLE_HAMILTONIAN = 'sample-hamiltonian'

SAMPLE_HAMILTONIAN_INTEGER = 'sample-hamiltonian-integer'

SAMPLE_HAMILTONIAN_ISING = 'sample-hamiltonian-ising'

class qci_client.optimization.enum.ProblemType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of all problem types, where values match jobs API values.

GP = 'graph_partitioning'

IHO = 'ising_hamiltonian_optimization'

NQHO = 'normalized_qudit_hamiltonian_optimization'

NQHO_CONTINUOUS = 'normalized_qudit_hamiltonian_optimization_continuous'

NQHO_INTEGER = 'normalized_qudit_hamiltonian_optimization_integer'

QHO = 'qudit_hamiltonian_optimization'

QLCBO = 'quadratic_linearly_constrained_binary_optimization'

QUBO = 'quadratic_unconstrained_binary_optimization'

class qci_client.optimization.enum.DeviceType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of all device types, where values match jobs API values.

DIRAC1 = 'dirac-1'

DIRAC2 = 'dirac-2'

DIRAC3 = 'dirac-3'

DIRAC3_NORMALIZED_QUDIT = 'dirac-3_normalized_qudit'

DIRAC3_QUDIT = 'dirac-3_qudit'

class qci_client.optimization.enum.JobStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of all jobs statuses, where values match jobs API values.

SUBMITTED = 'SUBMITTED'

QUEUED = 'QUEUED'

RUNNING = 'RUNNING'

COMPLETED = 'COMPLETED'

ERRORED = 'ERRORED'

CANCELLED = 'CANCELLED'

class qci_client.optimization.enum.FileType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of all file types, where values match files API values.

CONSTRAINTS = 'constraints'

GRAPH = 'graph'

HAMILTONIAN = 'hamiltonian'

OBJECTIVE = 'objective'

POLYNOMIAL = 'polynomial'

QUBO = 'qubo'

GP_RESULTS = 'graph_partitioning_results'

IHO_RESULTS = 'ising_hamiltonian_optimization_results'

NQHO_CONTINUOUS_RESULTS = 'normalized_qudit_hamiltonian_optimization_continuous_results'

NQHO_INTEGER_RESULTS = 'normalized_qudit_hamiltonian_optimization_integer_results'

NQHO_RESULTS = 'normalized_qudit_hamiltonian_optimization_results'

QHO_RESULTS = 'qudit_hamiltonian_optimization_results'

QLCBO_RESULTS = 'quadratic_linearly_constrained_binary_optimization_results'

QUBO_RESULTS = 'quadratic_unconstrained_binary_optimization_results'

qci_client.optimization.enum.get_file_type(*, file: dict) → FileType[source]

Get file type from a file.

qci_client.optimization.utilities

Utilities, especially for creating request bodies.

qci_client.optimization.utilities.get_file_type(*, file: dict) → FileType[source]

Get file type from a file.

qci_client.optimization.utilities.get_file_config(*, file: dict) → Tuple[dict, FileType][source]

Get file configuration and file type from a file.

qci_client.optimization.utilities.get_post_request_body(*, file: dict) → MetadataPostRequestBody[source]

Format metadata body.

qci_client.optimization.utilities.get_patch_request_body(*, file: dict) → PartPatchRequestBody[source]

Format part body.

qci_client.optimization.utilities.zip_payload(*, payload: PartPatchRequestBody) → bytes[source]

Parameters:

payload – str - json contents of file to be zipped

Returns:

zipped request_body

qci_client.optimization.utilities.file_part_generator(*, file: dict, compress: bool) → Generator[source]

Break file-to-upload’s data dictionary into chunks, formatting correctly with each returned chunk.

Parameters:

• file – file to break up into file parts
• compress – whether or not file parts are to be compressed

Returns:

generator of (part_body, part_number) tuples