# eqc_direct.eqc_client

`EqcClient` contains all RPC calls to process, get system status, and fetch results.

exception eqc_direct.eqc_client.InactiveRpcError

  Bases: `Exception`

  Custom exception wrapper around grpc._channel._InactiveRpcError.

class eqc_direct.eqc_client.EqcResult

  Bases: `TypedDict`

  EQC results object. Will not contain a ground state or spins if err_code not 0.

  Parameters:

    - err_code – the error code for a given job. Full list of `err_code` values can be found `eqc_direct.utils.JobCodes`

    - err_desc – the error description for a given job submission. Full list of `err_desc` values can be found in `eqc_direct.utils.JobCodes`

    - runtime – solving time in seconds

    - energy – energy for best solution found

    - solution – vector of floats representing the lowest energy solution

  Note:

    - Eqc1 only support ising formulation where possible solution values are {-1, 1}

    - all other formulations have length n solution vector of floats that sum to the device constraint (Eqc2 and Eqc3)

  err_code: int
  err_desc: str
  runtime: float
  energy: float | None
  solution: List[float] | None

class eqc_direct.eqc_client.HealthCheckResponse

  Bases: `TypedDict`

  Health check response object structure. Unless `debug` is specified at submission only returns pass/fail for each test.

  Parameters:

    - debug – whether health check was run in debug mode

    - err_code – if non-zero indicates an error in health check

    - err_desc – describes errors that occurred during health check run

    - entropy_pass – pass/fail for entropy test

    - stability_pass – pass/fail for stability test

    - extinction_ratio_pass – pass/fail for extinction ratio tests

    - small_problem_pass – pass/fail for small problem ground state test

    - entropy_data – test data for entropy tests only returned if debug=True

    - stability_data – test data for stability tests only returned if debug=True

    - extinction_ratio_data – test data for extinction ratio tests only returned if debug=True

    - small_problem_result – Eqc results object for small problem test if debug=True

  debug: bool
  err_code: int
  err_desc: str
  entropy_pass: bool | None
  stability_pass: bool | None
  extinction_ratio_pass: bool | None
  small_problem_pass: bool | None
  entropy_data: List[float] | None
  stability_data: List[float] | None
  extinction_ratio_data: List[float] | None
  small_problem_result: EqcResult | None

class eqc_direct.eqc_client.EqcClient(ip_addr: str = 'localhost', port: str = '50051', max_data_size: int = 536870912)

  Bases: `object`

  Provides calls to process jobs using EQC RPC server

  Parameters:

    - ip_addr – The IP address of the RPC server

    - port – The port that the RPC server is running on

    - max_data_size – the max send and recieve message length for RPC server

  Note

  `lock_id` is used by a variety of class functions. It is set to an empty string by default since default for device server `lock_id` is also an empty string. This allows for single user processing without having to acquire a device lock.

  submit_job(problem_data: ndarray, lock_id: str = '', sum_constraint: float = 1, relaxation_schedule: int = 2, continuous_soln: bool = True) → dict

    Submits data to be processed by EQC device

    Parameters:

      - problem_data – an array of problem data to be optimized

      - lock_id – a UUID to allow for multi-user processing

      - sum_constraint – a normalization constraint that is applied to the problem space that is used to calculate `ground_state` energy. Value must be greater than or equal to 1.

      - relaxation_schedule – four different schedules represented in integer parameter. Higher values reduce the variation in the analog spin values and therefore, lead to better ground state for input problem. Accepts range of values in set [1,4].

      - continuous_soln – whether solutions should be returned as integer or continuous values. In order to obtain integer solutions a distillation method is applied to the continuous solutions to map them to integer values.

    Returns:

      a member of `eqc_direct.utils.JobCodes` as a dict with the following keys:

      - err_code: int- job submission error code

      - err_desc: str- error code description for submission

  fetch_result(lock_id: str = '') → EqcResult

    Request last EQC job results. Returns results from the most recent run on the device.

    Parameters:

      lock_id – a valid `lock_id` that matches current device `lock_id`

    Returns:

      an `EqcResult` object

  system_status() → dict

    Client call to obtain EQC system status

    Returns:

      a member of `eqc_direct.utils.SysStatus` as a dict:

      - status_code: int- current system status code

      - status_desc: str- description of current system status

  acquire_lock() → dict

    Makes a single attempt to acquire exclusive lock on hardware execution. Locking can be used to ensure orderly processing in multi-user environments. Lock can only be acquired when no other user has acquired the lock or when the system has been idle for 60 seconds while another user has the lock. This idle timeout prevents one user from blocking other users from using the machine even if they are not active.

    Returns:

      a member of `eqc_direct.utils.LockManageStatus` as a dict along with an additional key `lock_id`:

      - lock_id: str- if acquired the current device lock_id else empty string

      - status_code: int- status code for lock id acquisition

      - status_desc: str- a description for the associated status code

  release_lock(lock_id: str = '') → dict

    Releases exclusive lock for running health check or submitting job

    Parameters:

      lock_id – a UUID with currently acquired exclusive device lock

    Returns:

      a member of `eqc_direct.utils.LockManageStatus` as a dict:

      - status_code: int- status code for lock id acquisition

      - status_desc: str- a description for the associated status code

  check_lock(lock_id: str = '') → dict

    Checks if submitted `lock_id` has execution lock on the device

    Parameters:

      lock_id – a UUID which will be checked to determine if has exclusive device execution lock

    Returns:

      a member of `eqc_direct.utils.LockCheckStatus` as a dict:

      - status_code: int- status code for lock check

      - status_desc: str- a description for the associated status code

  start_health_check(lock_id: str = '', entropy: bool = False, stability: bool = False, extinction_ratio: bool = False, small_problem: bool = False, debug: bool = False) → dict

    Runs health checks for an Eqc device must have lock to run.

    Parameters:

      - lock_id – the execution lock_id as acquired by acquire_lock

      - entropy – request run of entropy test on Eqc device (more info)

      - stability – request run of stability test on Eqc device (more info)

      - extinction_ratio – request test of extinction ratio on Eqc device (more info)

      - small_problem – run small problem and test valid result (more info)

      - debug – return verbose output from health check

    Returns:

      one of the members of `eqc_direct.utils.JobCodes` as a dict with the following keys:

      - err_code: int- non-zero value indicates error

      - err_desc: str- a description for associated error code

  fetch_health_check_result(lock_id='') → HealthCheckResponse

    Fetch health check data from previous run of health check tests

    Parameters:

      lock_id – requires a lock_id that was acquired by

    Returns:

      dict object `HealthCheckResponse`

    Note

    This result structure hasn’t been finalized. When C++ code is written will know exact format of augmented data.

  stop_running_process(lock_id: str = '') → dict

    Stops a running process either a health check or a Eqc job. Process locks will release automatically based on a timeout which is maintained in the server code if they are not released using this.

    Parameters:

      lock_id – requires a lock_id that was acquired by

    Returns:

      a member of `eqc_direct.utils.SysStatus` as dict with following keys:

      - status_code: int- the system code after stopping

      - status_desc: str- the associated system status description

  run_health_check(lock_id: str = '', entropy: bool = False, stability: bool = False, extinction_ratio: bool = False, small_problem: bool = False, debug: bool = False) → HealthCheckResponse

    Runs health checks for an Eqc device. Requires a validate lock on the device.

    Parameters:

      - lock_id – the execution lock_id as acquired by acquire_lock

      - entropy – request run of entropy test on Eqc device (more info)

      - stability – request run of stability test on Eqc device (more info)

      - extinction_ratio – request test of extinction ratio on Eqc device (more info)

      - small_problem – run small problem and test valid result (more info)

      - debug – return verbose output from health check

      - lock_id – requires a lock_id that was acquired by

    Returns:

      dict object `HealthCheckResponse`

    Note

    This result structure hasn’t been finalized. When C++ code is written will know exact format of augmented data.

  wait_for_lock() → tuple

    Waits for lock indefinitely calling `acquire_lock()`

    Returns:

      a tuple of the following items:

      - lock_id: str- exclusive lock for device execution with a timeout

      - start_queue_ts: int- time in ns on which lock was acquired is an int

      - end_queue_ts: int- time in ns on which queue for lock ended is an int.

  process_job(hamiltonian: ndarray, sum_constraint: float = 1, relaxation_schedule: int = 4, continuous_soln: bool = True, lock_id: str = '') → dict
    Processes a job by:

      1. submitting job

      2. checks for status, until completes or fails

      3. returns results

    Parameters:

      - hamiltonian – np.ndarray an (n,n+1) array representing the problem hamiltonian

      - sum_constraint – a normalization constraint that is applied to the problem space that is used to calculate `ground_state` energy. Value must be greater than or equal to 1.

      - relaxation_schedule – four different schedules represented in integer parameter. Higher values reduce the variation in the analog spin values and therefore, lead to better ground state for input problem. Accepts range of values in set [1,4].

      - continuous_soln – whether solutions should be returned as integer or continuous values.

      - lock_id – a str with exclusive lock for device execution with a timeout

    Returns:

      dict of results and timings with the following keys:

      - results: `EqcResult` dict

      - start_job_ts: time in ns marking start of job_submission

      - end_job_ts: time in ns marking end of job submission complete

# eqc_direct.utils

Utilities for running server sim and client

class eqc_direct.utils.SysStatus

  Bases: `object`

  Status codes for system paired with their descriptions.

  IDLE = {'status_code': 0, 'status_desc': 'IDLE'}
  JOB_RUNNING = {'status_code': 1, 'status_desc': 'JOB_RUNNING'}
  HEALTH_CHECK = {'status_code': 2, 'status_desc': 'HEALTH_CHECK'}
  FAILED_ENTROPY = {'status_code': 3, 'status_desc': 'FAILED_ENTROPY'}

class eqc_direct.utils.LockCheckStatus

  Bases: `object`

  Statuses codes for checking lock status paired with their descriptions

  AVAILABLE = {'status_code': 0, 'status_desc': 'Lock available'}
  USER_LOCKED = {'status_code': 1, 'status_desc': 'lock_id matches current server lock_id'}
  UNAVAILABLE = {'status_code': 2, 'status_desc': 'Execution lock is in use by another user'}

class eqc_direct.utils.LockManageStatus

  Bases: `object`

  Statuses and descriptions for acquiring and releasing lock

  SUCCESS = {'status_code': 0, 'status_desc': 'Success'}
  MISMATCH = {'status_code': 1, 'status_desc': 'lock_id does not match current device lock_id'}
  BUSY = {'status_code': 2, 'status_desc': 'Lock currently in use unable to perform operation'}

class eqc_direct.utils.JobCodes

  Bases: `object`

  Job codes for errors paired with their descriptions

  NORMAL = {'err_code': 0, 'err_desc': 'Success'}
  BAD_INPUT = {'err_code': 1, 'err_desc': 'Incorrectly formatted matrix'}
  DEVICE_BUSY = {'err_code': 2, 'err_desc': 'Device currently processing other request'}
  LOCK_MISMATCH = {'err_code': 3, 'err_desc': "lock_id doesn't match current device lock"}
  NO_ENTROPY = {'err_code': 4, 'err_desc': 'Device failed to capture entropy during sampling'}
  INVALID_SUM_CONSTRAINT = {'err_code': 5, 'err_desc': 'Sum constraint must be greater than 0'}
  CONSTRAINT_SOLN_TYPE_MISMATCH = {'err_code': 6, 'err_desc': 'If `continuous_soln`=False then `sum_constraint` must be an integer'}

eqc_direct.utils.message_to_dict(grpc_message) → dict

  Converts a grpc message to a dictionary

  Parameters:

    grpc_message – original grpc message

  Returns:

    original message parsed as a dict