Config

Reference document for the functions and classes users may use to configure Forge.

Functions

qcware.forge.config.additional_config(**kwargs)

This provides a context manager through which the qcware python client library can be temporarily reconfigured, for example to allow a longer client timeout for a call, or to make a call with different credentials. To use it, one must provide a set of keywords which map to the arguments of an ApiCallContext, for example, to make a single call with a client timout of five minutes:

``` with additional_config(client_tiemout=5*60):

result = optimize_binary(…)

```

qcware.forge.config.async_interval_between_tries(override: Optional[float] = None)

Return the maximum time the server should sit pinging the database for a result before giving up.

This is configurable by the environment variable QCWARE_SERVER_TIMEOUT

The default value is 10 seconds; the maximum is 50

qcware.forge.config.client_api_incompatibility_message(client_version: packaging.version.Version, host_version: packaging.version.Version) → str: Returns an informative string based on the severity of incompatibility between client and host API versions

qcware.forge.config.client_api_semver() → str: Reports the semantic API version used by the client

qcware.forge.config.client_timeout(override: Optional[int] = None)

Returns the maximum time the api should retry polling when running in synchronous mode before returning the error state that the call is not complete and allowing the user to poll manually.

This is configurable by the environment variable QCWARE_CLIENT_TIMEOUT

The default value is 60 seconds

qcware.forge.config.do_client_api_compatibility_check(client_version_string: Optional[str] = None, host_version_string: Optional[str] = None): Checks the client and host API versions and prints an informative string if the versions differ in a material way.

qcware.forge.config.do_client_api_compatibility_check_once(client_version_string: Optional[str] = None, host_version_string: Optional[str] = None): If an API compatibility check has not been done between client and the selected host, do it now and disable further checks.

qcware.forge.config.host_api_semver() → str: Returns the semantic API version string reported by the host.

qcware.forge.config.ibmq_credentials(token: str, hub: Optional[str] = None, group: Optional[str] = None, project: Optional[str] = None)

qcware.forge.config.is_valid_host_url(url: Optional[str]) → bool: Checks if a host url is valid. A valid host url is just a scheme (http/https), a net location, and no path.

qcware.forge.config.ibmq_credentials_from_ibmq(ibmq)

qcware.forge.config.qcware_api_key(override: Optional[str] = None) → str: Returns the API key from environment variable QCWARE_API_KEY, config file, or the provided override (if the override is provided, this function simply returns the provided override)

qcware.forge.config.qcware_host(override: Optional[str] = None) → str

Returns the QCWare host url from the environment variable QCWARE_HOST, a config file, or the provided override. The url should be in the form ‘scheme://netloc’ where scheme is http or https and netloc is the IP address or name of the host. No trailing slash is required (or desired).

If an override is provided, this function checks for validity and returns the override.

qcware.forge.config.scheduling_mode(override: Optional[qcware.forge.config.config.SchedulingMode] = None)

Returns the scheduling mode, only relevant for backends that have availability windows. “immediate” means a call should fail if called for outside its availability window, while “next_available” means such calls should be automaticall scheduled for the next availability window.

A reschedule is not a guarantee that the job will be run within that window! If not, it will stay in the queue until the next availability window.

qcware.forge.config.server_timeout(override: Optional[int] = None)

Returns the maximum time the api should retry polling when running in synchronous mode before returning the error state that the call is not complete and allowing the user to poll manually.

This is configurable by the environment variable QCWARE_CLIENT_TIMEOUT

The default value is 60 seconds

qcware.forge.config.set_api_key(key: str): Set’s the user’s forge API key via environment variable. Equivalent to os.environ[‘QCWARE_API_KEY’]=key

qcware.forge.config.set_async_interval_between_tries(new_interval: float)

Set the maximum server timeout.

This sets how long the server will poll for a result before returning to the client with a result or ‘still waiting’ message.

Normally the user should not change this from the default value of 10s.

qcware.forge.config.set_client_timeout(new_wait: int)

Sets the maximum time the API should retry polling the server before returning the error state that the call is not complete.

This may be set to any value greater than or equal to 0 seconds.

qcware.forge.config.set_environment_environment(new_environment: str): Set the Environment … environment.

qcware.forge.config.set_environment_source_file(new_source_file: str): Set the source file recorded in the context environment.

qcware.forge.config.set_host(host_url: str)

qcware.forge.config.set_ibmq_credentials(token: Optional[str] = None, hub: Optional[str] = None, group: Optional[str] = None, project: Optional[str] = None): Set the IBMQ credentials “by hand”.

qcware.forge.config.set_ibmq_credentials_from_ibmq_provider(provider: qiskit.providers.ibmq.accountprovider.AccountProvider)

Set the IBMQ credentials from an ibmq provider object.

Called normally as set_ibmq_credentials_from_ibmq(IBMQ.providers()[0]). The IBMQ “factory” can provide several providers, particularly if your IBMQ token is associated with various hubs, groups, or projects.

qcware.forge.config.set_server_timeout(new_wait: int)

Sets the maximum time the API should retry polling the server before returning the error state that the call is not complete.

This may be set to any value greater than or equal to 0 seconds.

qcware.forge.config.set_scheduling_mode(new_mode: qcware.forge.config.config.SchedulingMode)

Sets the scheduling mode, only relevant for backends that have availability windows. “immediate” means a call should fail if called for outside its availability window, while “next_available” means such calls should be automaticall scheduled for the next availability window.

A reschedule is not a guarantee that the job will be run within that window! If not, it will stay in the queue until the next availability window.

Classes

class qcware.forge.config.ApiCallContext(*, qcware_host: Optional[str] = None, credentials: Optional[qcware.forge.config.config.ApiCredentials] = None, environment: Optional[qcware.forge.config.config.Environment] = None, server_timeout: Optional[int] = None, client_timeout: Optional[int] = None, async_interval_between_tries: Optional[float] = None, scheduling_mode: Optional[qcware.forge.config.config.SchedulingMode] = None)

The context sent over with every API call.

A number of things are listed as “optional” which really are not; they are created by default in the root_context function. By allowing them to be optional, you can augment the current context with “temporary contexts” that override only one field (or a subset).

class qcware.forge.config.ApiCredentials(*, qcware_api_key: Optional[str] = None, ibmq: Optional[qcware.forge.config.config.IBMQCredentials] = None)

class qcware.forge.config.Environment(*, client: str, client_version: str, python_version: str, environment: str, source_file: str)

This deserves a little explanation; it is greatly helpful to us when diagnosing a problem to have recorded information about the “environment” of the call. These are manually overloadable should users wish to hide this information, but it is set by default in this fashion:

client, client_version: usually “qcware” and this library’s version

version environment: the sort of “global environment”. Usually this is set by environment variable “QCWARE_ENVIRONMENT_ENVIRONMENT”, which is “hosted_jupyter”on hosted jupyter notebooks, or “local” for a local installation.

source_file: this is empty by default so that we do not collect unnecessary information from users. It is set in our hosted example notebooks so that we can see what calls come from example notebooks. This is set via the environment variable QCWARE_ENVIRONMENT_SOURCE_FILE.

class qcware.forge.config.IBMQCredentials(*, token: Optional[str] = None, hub: Optional[str] = None, group: Optional[str] = None, project: Optional[str] = None)

classmethod from_ibmq(ibmq): Creates the IBMQ credentials from an existing initialized IBMQFactory object. To be used as

from qiskit import IBMQ IBMQ.load_account() # or enable_account(…) credentials=IBMQCredentials.from_ibmq(IBMQ)

class qcware.forge.config.SchedulingMode(value)

Scheduling modes for API calls.

‘immediate’ means ‘attempt this now; if it must be rescheduled (such as for an unavailable backend), fail with an exception’

‘next_available’ means ‘attempt this now, but if the backend is unavailable, schedule during the next availability window.’