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

  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

    Get job URL with job ID.

  get_job_status_url(*, job_id: str) → str

    Get job-status URL using job ID.

  get_job_metrics_url(job_id: str) → str

    Get legacy job-metrics URL using job ID.

  get_job_metrics_v1_url(job_id: str) → str

    Get v1 job-metrics URL using job ID.

  get_job_metrics_v2_url(job_id: str) → str

    Get v2 job-metrics URL using job ID.

  get_job_allocations_url() → str

    Get job-allocations URL.

  property files_url

    Get files URL.

  get_file_id_url(*, file_id: str) → str

    Get file URL with file ID.

  get_file_contents_url(*, file_id: str, part_number: int) → str

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

  upload_file(*, file: dict) → dict

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

  download_file(*, file_id: str) → dict

    Download file (metadata and then parts concurrently).

  submit_job(*, job_body: dict) → dict

    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

    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

    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

    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

    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

    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

    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

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

    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

  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)

  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)

  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)

  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)

  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)

  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

  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

  Get file type from a file.

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

  Get file configuration and file type from a file.

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

  Format metadata body.

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

  Format part body.

qci_client.optimization.utilities.zip_payload(*, payload: PartPatchRequestBody) → bytes
  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

  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