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, ssl_verify: bool | None = None)[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
ssl_verify – whether to verify the server’s TLS/SSL certificate, if None, then falls back to QCI_SSL_VERIFY environment variable (defaulting to True). Set to False to allow self-signed certificates (insecure).

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 ssl_verify: bool: Return whether the server’s TLS/SSL certificate is verified.

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.

Device metrics are keyed by the specific device name that was submitted, so a job requested on the “dirac-3” alias is keyed by “dirac-3_normalized_qudit” or “dirac-3_qudit”. The “dirac-3” alias is added alongside that key, referring to the same object, so either name reads the same device block.

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

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, including the required “device_type”, which may be “dirac-3s” and, unlike the “dirac-3” alias, is not remapped to a device-specific name
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:

The job body dict, whose “job_submission” holds the assembled problem_config and device_config.

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'

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'

DIRAC3 = 'dirac-3'

DIRAC3_NORMALIZED_QUDIT = 'dirac-3_normalized_qudit'

DIRAC3_QUDIT = 'dirac-3_qudit'

DIRAC3S = 'dirac-3s'

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_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

qci_client.optimization.utilities.add_device_aliases(*, metrics: dict) → dict[source]

Add the “dirac-3” alias to a job’s device metrics, which are keyed by the specific device name that was submitted rather than the alias that may have been requested.

The specific key is retained, and the alias refers to the same object rather than to a copy, so mutating one is visible through the other. Metrics that are missing, that hold no device block, or that are already keyed by the alias are returned unchanged.

Parameters:: metrics – response from a job-metrics GET call to API
Returns:: The same metrics dict, with device aliases added in place

qci_client.optimization

QCi optimization application v1.

qci_client.optimization.client

Client for QCi’s optimization API.

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
ssl_verify – whether to verify the server’s TLS/SSL certificate, if None, then falls back to QCI_SSL_VERIFY environment variable (defaulting to True). Set to False to allow self-signed certificates (insecure).

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 ssl_verify: bool: Return whether the server’s TLS/SSL certificate is verified.

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

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, including the required “device_type”, which may be “dirac-3s” and, unlike the “dirac-3” alias, is not remapped to a device-specific name
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:

The job body dict, whose “job_submission” holds the assembled problem_config and device_config.

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'

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'

DIRAC3 = 'dirac-3'

DIRAC3_NORMALIZED_QUDIT = 'dirac-3_normalized_qudit'

DIRAC3_QUDIT = 'dirac-3_qudit'

DIRAC3S = 'dirac-3s'

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_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

qci_client.optimization.utilities.add_device_aliases(*, metrics: dict) → dict[source]

Add the “dirac-3” alias to a job’s device metrics, which are keyed by the specific device name that was submitted rather than the alias that may have been requested.

Parameters:: metrics – response from a job-metrics GET call to API
Returns:: The same metrics dict, with device aliases added in place