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.
- 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
- 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.
- 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_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_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
- property jobs_url
Get jobs URL.
- 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'
- 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'
- 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_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'
- QLCBO = 'quadratic_linearly_constrained_binary_optimization'
- QUBO = 'quadratic_unconstrained_binary_optimization'
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.