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 api_token: str: Return API token.

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

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

property compress: bool: Return file compression usage flag.

download_file(*, file_id: str) → dict[source]: Download file (metadata and then parts concurrently).

property files_url: Get files URL.

get_allocations() → dict[source]

Get allocations for running jobs on different device classes.

Return dict:: json response

get_file_contents_url(*, file_id: str, part_number: int) → str[source]: Get file contents URL with file ID and file part number.

get_file_id_url(*, file_id: str) → str[source]: Get file URL with file ID.

get_job_allocations_url() → str[source]: Get job-allocations URL.

get_job_id_url(*, job_id: str) → str[source]: Get job URL with job ID.

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_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_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_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_status_url(*, job_id: str) → str[source]: Get job-status URL using job ID.

property jobs_url: Get jobs URL.

list_files() → dict[source]

List files (metadata only).

Returns:: dict containing list of files

property max_workers: int: Return maximum number of concurrent workers for file operations.

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())

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())

property timeout: float | None: Return timeout setting.

upload_file(*, file: dict) → dict[source]: Upload file (metadata and then parts concurrently). Returns dict with file ID.

property url: str: Return API URL.

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.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.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'

GP_RESULTS = 'graph_partitioning_results'

GRAPH = 'graph'

HAMILTONIAN = 'hamiltonian'

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'

OBJECTIVE = 'objective'

POLYNOMIAL = 'polynomial'

QHO_RESULTS = 'qudit_hamiltonian_optimization_results'

QLCBO_RESULTS = 'quadratic_linearly_constrained_binary_optimization_results'

QUBO = 'qubo'

QUBO_RESULTS = 'quadratic_unconstrained_binary_optimization_results'

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.

CANCELLED = 'CANCELLED'

COMPLETED = 'COMPLETED'

ERRORED = 'ERRORED'

QUEUED = 'QUEUED'

RUNNING = 'RUNNING'

SUBMITTED = 'SUBMITTED'

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.

GRAPH_PARTITIONING = 'graph-partitioning'

SAMPLE_CONTRAINT = 'sample-constraint'

SAMPLE_HAMILTONIAN = 'sample-hamiltonian'

SAMPLE_HAMILTONIAN_INTEGER = 'sample-hamiltonian-integer'

SAMPLE_HAMILTONIAN_ISING = 'sample-hamiltonian-ising'

SAMPLE_QUBO = 'sample-qubo'

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'

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.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.get_file_config(*, file: dict) → Tuple[dict, FileType][source]: Get file configuration and file type from a file.

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

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

qci_client.optimization.utilities.get_post_request_body(*, file: dict) → MetadataPostRequestBody[source]: Format metadata 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

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

property api_token: str: Return API token.

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

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

property compress: bool: Return file compression usage flag.

download_file(*, file_id: str) → dict[source]: Download file (metadata and then parts concurrently).

property files_url: Get files URL.

get_allocations() → dict[source]

Get allocations for running jobs on different device classes.

Return dict:: json response

get_file_contents_url(*, file_id: str, part_number: int) → str[source]: Get file contents URL with file ID and file part number.

get_file_id_url(*, file_id: str) → str[source]: Get file URL with file ID.

get_job_allocations_url() → str[source]: Get job-allocations URL.

get_job_id_url(*, job_id: str) → str[source]: Get job URL with job ID.

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_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_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_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_status_url(*, job_id: str) → str[source]: Get job-status URL using job ID.

property jobs_url: Get jobs URL.

list_files() → dict[source]

List files (metadata only).

Returns:: dict containing list of files

property max_workers: int: Return maximum number of concurrent workers for file operations.

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())

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())

property timeout: float | None: Return timeout setting.

upload_file(*, file: dict) → dict[source]: Upload file (metadata and then parts concurrently). Returns dict with file ID.

property url: str: Return API URL.

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.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.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'

GP_RESULTS = 'graph_partitioning_results'

GRAPH = 'graph'

HAMILTONIAN = 'hamiltonian'

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'

OBJECTIVE = 'objective'

POLYNOMIAL = 'polynomial'

QHO_RESULTS = 'qudit_hamiltonian_optimization_results'

QLCBO_RESULTS = 'quadratic_linearly_constrained_binary_optimization_results'

QUBO = 'qubo'

QUBO_RESULTS = 'quadratic_unconstrained_binary_optimization_results'

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.

CANCELLED = 'CANCELLED'

COMPLETED = 'COMPLETED'

ERRORED = 'ERRORED'

QUEUED = 'QUEUED'

RUNNING = 'RUNNING'

SUBMITTED = 'SUBMITTED'

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.

GRAPH_PARTITIONING = 'graph-partitioning'

SAMPLE_CONTRAINT = 'sample-constraint'

SAMPLE_HAMILTONIAN = 'sample-hamiltonian'

SAMPLE_HAMILTONIAN_INTEGER = 'sample-hamiltonian-integer'

SAMPLE_HAMILTONIAN_ISING = 'sample-hamiltonian-ising'

SAMPLE_QUBO = 'sample-qubo'

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'

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.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.get_file_config(*, file: dict) → Tuple[dict, FileType][source]: Get file configuration and file type from a file.

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

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

qci_client.optimization.utilities.get_post_request_body(*, file: dict) → MetadataPostRequestBody[source]: Format metadata 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