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

Async Qcog Client.

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.123', httpclient: IRequestClient | None = None, dataclient: IDataClient | None = None) → AsyncQcogClient

Instantiate a new Qcog client.

This client is meant to work in an async context.

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

  • httpclient (ABCRequestClient | None) – an optional http client to use instead of the default

  • dataclient (ABCDataClient | None) – an optional data client to use instead of the default

async data(data: DataFrame) → AsyncQcogClient

Upload a dataset.

Parameters:

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

Return type:

QcogClient

property dataset: dict

Return the dataset.

ensemble(*args: Any, **kwargs: Any) → AsyncQcogClient

Select Ensemble model.

Parameters:

  • operators (list[str | int]) – List of operators

  • dim (int, default=16) – Dimension

  • num_axes (int, default=4) – Number of axes

  • sigma_sq (dict, default=None) – Sigma squared

  • sigma_sq_optimization (dict, default=None) – Sigma squared optimization

  • seed (int, default=42) – Seed

  • target_operator (list[str | int], default=None) – Target operator

Return type:

AsyncQcogClient

async get_loss() → list[list[int | float | Any]] | None

Return the loss matrix.

Returns:

the loss matrix

Return type:

Matrix

async inference(data: DataFrame, parameters: InferenceParameters | None) → DataFrame | Any

From a trained model query an inference.

Parameters:

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

  • parameters (dict) – inference parameters

Returns:

the inference result

Return type:

pd.DataFrame | Any

property inference_result: dict

Return the inference result.

property model: ModelPauliParameters | ModelEnsembleParameters | ModelGeneralParameters | ModelPytorchParameters

Return the model.

pauli(*args: Any, **kwargs: Any) → AsyncQcogClient

Select Pauli model.

Parameters:

  • operators (list[str | int]) – List of operators

  • qbits (int, default=2) – Number of qbits

  • pauli_weight (int, default=2) – Pauli weight

  • sigma_sq (dict, default=None) – Sigma squared

  • sigma_sq_optimization (dict, default=None) – Sigma squared optimization

  • seed (int, default=42) – Seed

  • target_operator (list[str | int], default=None) – Target operator

Return type:

AsyncQcogClient

async preloaded_data(guid: str) → AsyncQcogClient

Retrieve a dataset that was previously uploaded from guid.

Parameters:

guid (str) – guid of a previously uploaded dataset

Return type:

QcogClient

async preloaded_model(guid: str) → AsyncQcogClient
async preloaded_model(guid: str, *, pytorch_model_name: str | None = None) → AsyncQcogClient
async preloaded_model(*, pytorch_model_name: str | None = None, force_reload: bool = False) → AsyncQcogClient

Retrieve a preexisting trained model.

Parameters:

  • guid (str | None) – trained model identifier. If you are working on a pytorch model, you also need to run preload_pt_model to load the model architecture, or you can provide pytorch_model_name parameter with the name of the model. If no guid is provided and you are working with a pytorch model, the client will try to load the latest trained model.

  • pytorch_model_name (str | None) – the name of the PyTorch model. This is the identifier that you used when you uploaded the model using pytorch method. It should be provided if no model architecture is loaded.

  • force_reload (bool | None) – If true will fetch the latest models at every request.

Return type:

QcogClient

async preloaded_pt_model(model_name: str) → AsyncQcogClient

Retrieve a preexisting PyTorch model.

Parameters:

model_name (str) – model name

Return type:

QcogClient

async preloaded_training_parameters(guid: str) → AsyncQcogClient

Retrieve preexisting training parameters payload.

Parameters:

guid (str) – model guid

Returns:

itself

Return type:

QcogClient

async progress() → dict

Return the current status of the training.

Returns:

the current status of the training guid : str training_completion : int current_batch_completion : int status : TrainingStatus

Return type:

dict

async pytorch(model_name: str, model_path: str) → AsyncQcogClient

Select PyTorch model.

Parameters:

  • model_name (str) – the name of the model

  • model_path (str) – the path to the model

Return type:

AsyncQcogClient

property pytorch_model: dict

Return the Pytorch model.

property pytorch_trained_models: list[dict]

Return the list of Pytorch trained models.

async status() → TrainingStatus

Return the current status of the training.

Returns:

the current status of the training

Return type:

TrainingStatus

async train(batch_size: int, num_passes: int, weight_optimization: AnalyticOptimizationParameters | AdamOptimizationParameters | GradOptimizationParameters | 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

async train_pytorch(training_parameters: dict) → AsyncQcogClient

Train PyTorch model.

Run a training session for a PyTorch model. The training session should be run against a valid Pytorch model and dataset previously selected.

Use .data(…) and .pytorch(…) to set the model and dataset.

Parameters:

training_parameters (dict) – the training parameters as specified in the train function of the provided model

Return type:

AsyncQcogClient

property trained_model: dict

Return the trained model.

property training_parameters: dict

Return the training parameters.

async upload_data(data: DataFrame, dataset_id: str) → AsyncQcogClient

Upload data as a stream.

property version: str

Qcog version.

async wait_for_training(poll_time: int = 60) → None

Wait for training to complete.

Note

This function is blocking

Parameters:

poll_time (int:) – status checks intervals in seconds

Returns:

itself

Return type:

QcogClient