Async Client

This class provides an async interface to qognitive’s API. Under the hood, it uses the aiohttp library to make HTTP requests to the API.

class qcog_python_client.AsyncQcogClient

Bases: BaseQcogClient[AIOHTTPClient], AsyncTrainProtocol, AsyncInferenceProtocol

async classmethod create(*, token: str | None = None, hostname: str = 'dev.qognitive.io', port: int = 443, api_version: str = 'v1', safe_mode: bool = False, version: str = '0.0.63') → AsyncQcogClient

Asyncronous Qcog api client implementation.

This is similar to the sync client with the exception that any API calls will be async and require an await

For example:

hsm = (await AsyncQcogClient.create(...)).pauli(...)
await hsm.data(...)
await hsm.train(...)

where the “…” would be replaced with desired parametrization

If we wanted, we could infer after training, right away.

result: pd.DataFrame = await hsm.inference(...)

but this would require us to explicitly wait for training to complete

await hsm.wait_for_training()
result: pd.DataFrame = await hsm.inference(...)

to make sure training has successfully completed.

Parameters:

  • token (str | None) – A valid API token granting access optional when unset (or None) expects to find the proper value as QCOG_API_TOKEN environment variable

  • hostname (str) – API endpoint hostname, currently defaults to dev.qognitive.io

  • port (int) – port value default to https 443

  • api_version (str) – the “vX” part of the url for the api version

  • safe_mode (bool) – if true runs healthchecks before running any api call sequences

  • version (str) – the qcog version to use. Must be no smaller than OLDEST_VERSION and no greater than NEWEST_VERSION

Returns:

the client object

Return type:

AsyncQcogClient

async data(data: DataFrame) → AsyncQcogClient

Upload a dataset for training.

For a fresh “to train” model and properly initialized model upload a pandas DataFrame dataset.

Parameters:

  • data (pd.DataFrame:) – the dataset as a DataFrame

  • upload (bool:) – if true post the dataset

Returns:

itself

Return type:

AsyncQcogClient

ensemble(operators: list[str | int], dim: int = 16, num_axes: int = 4, sigma_sq: dict[str, float] = {}, sigma_sq_optimization: dict[str, float] = {}, seed: int = 42, target_operator: list[str | int] = []) → AsyncQcogClient

Select EnsembleModel for the training.

property http_client: CLIENT

Return the http client.

async inference(data: DataFrame, parameters: InferenceParameters) → DataFrame

From a trained model query an inference.

Parameters:

  • data (pd.DataFrame) – the dataset as a DataFrame

  • parameters (dict) – inference parameters

Returns:

the predictions

Return type:

pd.DataFrame

pauli(operators: list[str | int], qbits: int = 2, pauli_weight: int = 2, sigma_sq: dict[str, float] = {}, sigma_sq_optimization: dict[str, float] = {}, seed: int = 42, target_operator: list[str | int] = []) → AsyncQcogClient

Select PauliModel for the training.

async preloaded_data(guid: str) → AsyncQcogClient

Retrieve a dataset that was previously uploaded from guid.

Parameters:

guid (str) – guid of a previously uploaded dataset

Returns:

itself

Return type:

AsyncQcogClient

async preloaded_model(guid: str) → AsyncQcogClient

Preload a model from a guid.

async preloaded_training_parameters(guid: str, rebuild: bool = False) → AsyncQcogClient

Retrieve preexisting training parameters payload.

Parameters:

  • guid (str) – model guid

  • rebuild (bool) – if True, will initialize the class “model” (ex: pauli or ensemble) from the payload

Returns:

itself

Return type:

AsyncQcogClient

async status() → str

Fetch the status of the training request.

async train(batch_size: int, num_passes: int, weight_optimization: GradOptimizationParameters | AdamOptimizationParameters | AnalyticOptimizationParameters | EmptyDictionary, get_states_extra: LOBPCGFastStateParameters | PowerIterStateParameters | EIGHStateParameters | EIGSStateParameters | NPEIGHStateParameters | GradStateParameters | EmptyDictionary) → AsyncQcogClient

Start a training job.

For a fresh “to train” model properly configured and initialized trigger a training request.

Parameters:

  • batch_size (int) – The number of samples to use in each training batch.

  • num_passes (int) – The number of passes through the dataset.

  • weight_optimization (NotRequiredWeightParams) – optimization parameters for the weights

  • get_states_extra (NotRequiredStateParams) – optimization parameters for the states

Return type:

AsyncQcogClient

property version: str

Qcog version.

async wait_for_training(poll_time: int = 60) → AsyncQcogClient

Wait for training to complete.

Parameters:

poll_time (int) – status checks intervals in seconds

Returns:

itself

Return type:

AsyncQcogClient