eqc_direct.eqc_client
EqcClient
contains all RPC calls to process, get system status,
and fetch results.
- exception eqc_direct.eqc_client.InactiveRpcError[source]
Bases:
Exception
Custom exception wrapper around grpc._channel._InactiveRpcError.
- class eqc_direct.eqc_client.EqcResult[source]
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 foundeqc_direct.utils.JobCodes
err_desc – the error description for a given job submission. Full list of
err_desc
values can be found ineqc_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[source]
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
- class eqc_direct.eqc_client.EqcClient(ip_addr: str = 'localhost', port: str = '50051', max_data_size: int = 536870912)[source]
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 serverlock_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 [source]
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 [source]
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 devicelock_id
- Returns:
an
EqcResult
object
- system_status() dict [source]
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 [source]
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 keylock_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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
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 [source]
- Processes a job by:
submitting job
checks for status, until completes or fails
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
dictstart_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[source]
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[source]
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[source]
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[source]
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'}