Postprocess Skqd Samples

curl --request POST \
  --url 'https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "experiment_id": "exp-123",
  "h1e": [
    [
      -1.25,
      0
    ],
    [
      0,
      -0.48
    ]
  ],
  "h2e": [
    [
      [
        [
          0.67,
          0
        ],
        [
          0,
          0.66
        ]
      ],
      [
        [
          0,
          0.18
        ],
        [
          0.18,
          0
        ]
      ]
    ],
    [
      [
        [
          0,
          0.18
        ],
        [
          0.18,
          0
        ]
      ],
      [
        [
          0.66,
          0
        ],
        [
          0,
          0.7
        ]
      ]
    ]
  ],
  "nelec": [
    1,
    1
  ],
  "norb": 2,
  "params": {
    "num_batches": 3,
    "seed": 7
  },
  "run_job_id": "jb-abc123"
}
'

import requests

url = "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY="

payload = {
    "experiment_id": "exp-123",
    "h1e": [[-1.25, 0], [0, -0.48]],
    "h2e": [[[[0.67, 0], [0, 0.66]], [[0, 0.18], [0.18, 0]]], [[[0, 0.18], [0.18, 0]], [[0.66, 0], [0, 0.7]]]],
    "nelec": [1, 1],
    "norb": 2,
    "params": {
        "num_batches": 3,
        "seed": 7
    },
    "run_job_id": "jb-abc123"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    experiment_id: 'exp-123',
    h1e: [[-1.25, 0], [0, -0.48]],
    h2e: [
      [[[0.67, 0], [0, 0.66]], [[0, 0.18], [0.18, 0]]],
      [[[0, 0.18], [0.18, 0]], [[0.66, 0], [0, 0.7]]]
    ],
    nelec: [1, 1],
    norb: 2,
    params: {num_batches: 3, seed: 7},
    run_job_id: 'jb-abc123'
  })
};

fetch('https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'experiment_id' => 'exp-123',
    'h1e' => [
        [
                -1.25,
                0
        ],
        [
                0,
                -0.48
        ]
    ],
    'h2e' => [
        [
                [
                                [
                                                                0.67,
                                                                0
                                ],
                                [
                                                                0,
                                                                0.66
                                ]
                ],
                [
                                [
                                                                0,
                                                                0.18
                                ],
                                [
                                                                0.18,
                                                                0
                                ]
                ]
        ],
        [
                [
                                [
                                                                0,
                                                                0.18
                                ],
                                [
                                                                0.18,
                                                                0
                                ]
                ],
                [
                                [
                                                                0.66,
                                                                0
                                ],
                                [
                                                                0,
                                                                0.7
                                ]
                ]
        ]
    ],
    'nelec' => [
        1,
        1
    ],
    'norb' => 2,
    'params' => [
        'num_batches' => 3,
        'seed' => 7
    ],
    'run_job_id' => 'jb-abc123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY="

	payload := strings.NewReader("{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=")
  .header("Content-Type", "application/json")
  .body("{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "<string>",
  "status": "<string>",
  "context": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

Postprocess Skqd Samples

Diagonalize a molecular Hamiltonian in the subspace spanned by measured samples.

Use this tool to turn sampled bitstrings from a chemistry circuit into an energy estimate. Haiqu builds a configuration subspace from the samples and diagonalizes the Hamiltonian within it, which recovers accuracy that raw sampling loses to noise.

When to Use:

Call this after a sampling run of a chemistry ansatz when the user wants a ground-state energy rather than a measurement distribution.
Call this with run_job_id pointing at the run job that produced the samples, so the counts never pass through the tool call.

Constraints:

Provide exactly one of results or run_job_id.
h1e must be norb x norb and h2e must be a rank-4 norb array; mismatched shapes are rejected with 422.
norb above 12 is rejected because h2e grows as norb**4. Use the Haiqu SDK for larger active spaces.
The job is asynchronous and billable. Poll with get_job_results_and_status.

Notes:

Integrals must come from the same orbital basis and ordering as the circuit that produced the samples, otherwise the energy is meaningless.
num_shots is inferred from the referenced run job when omitted.

Args: user: Authenticated user resolved from the API key. data: Integrals, active-space sizes, and inline results or a job reference. db: Active database session.

Returns: The created job identifier with the next polling step.

Raises: HTTPException: Raised with 400 when neither or both result inputs are given, 402 when the caller cannot submit billable jobs, 404 when the experiment or referenced job is unavailable, 409 when the referenced job has no results, or 422 on shape or size violations.

POST

postprocess_skqd_samples

Postprocess Skqd Samples

curl --request POST \
  --url 'https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "experiment_id": "exp-123",
  "h1e": [
    [
      -1.25,
      0
    ],
    [
      0,
      -0.48
    ]
  ],
  "h2e": [
    [
      [
        [
          0.67,
          0
        ],
        [
          0,
          0.66
        ]
      ],
      [
        [
          0,
          0.18
        ],
        [
          0.18,
          0
        ]
      ]
    ],
    [
      [
        [
          0,
          0.18
        ],
        [
          0.18,
          0
        ]
      ],
      [
        [
          0.66,
          0
        ],
        [
          0,
          0.7
        ]
      ]
    ]
  ],
  "nelec": [
    1,
    1
  ],
  "norb": 2,
  "params": {
    "num_batches": 3,
    "seed": 7
  },
  "run_job_id": "jb-abc123"
}
'

import requests

url = "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY="

payload = {
    "experiment_id": "exp-123",
    "h1e": [[-1.25, 0], [0, -0.48]],
    "h2e": [[[[0.67, 0], [0, 0.66]], [[0, 0.18], [0.18, 0]]], [[[0, 0.18], [0.18, 0]], [[0.66, 0], [0, 0.7]]]],
    "nelec": [1, 1],
    "norb": 2,
    "params": {
        "num_batches": 3,
        "seed": 7
    },
    "run_job_id": "jb-abc123"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    experiment_id: 'exp-123',
    h1e: [[-1.25, 0], [0, -0.48]],
    h2e: [
      [[[0.67, 0], [0, 0.66]], [[0, 0.18], [0.18, 0]]],
      [[[0, 0.18], [0.18, 0]], [[0.66, 0], [0, 0.7]]]
    ],
    nelec: [1, 1],
    norb: 2,
    params: {num_batches: 3, seed: 7},
    run_job_id: 'jb-abc123'
  })
};

fetch('https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'experiment_id' => 'exp-123',
    'h1e' => [
        [
                -1.25,
                0
        ],
        [
                0,
                -0.48
        ]
    ],
    'h2e' => [
        [
                [
                                [
                                                                0.67,
                                                                0
                                ],
                                [
                                                                0,
                                                                0.66
                                ]
                ],
                [
                                [
                                                                0,
                                                                0.18
                                ],
                                [
                                                                0.18,
                                                                0
                                ]
                ]
        ],
        [
                [
                                [
                                                                0,
                                                                0.18
                                ],
                                [
                                                                0.18,
                                                                0
                                ]
                ],
                [
                                [
                                                                0.66,
                                                                0
                                ],
                                [
                                                                0,
                                                                0.7
                                ]
                ]
        ]
    ],
    'nelec' => [
        1,
        1
    ],
    'norb' => 2,
    'params' => [
        'num_batches' => 3,
        'seed' => 7
    ],
    'run_job_id' => 'jb-abc123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY="

	payload := strings.NewReader("{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=")
  .header("Content-Type", "application/json")
  .body("{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/ai/postprocess_skqd_samples?HAIQU_API_KEY=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"experiment_id\": \"exp-123\",\n  \"h1e\": [\n    [\n      -1.25,\n      0\n    ],\n    [\n      0,\n      -0.48\n    ]\n  ],\n  \"h2e\": [\n    [\n      [\n        [\n          0.67,\n          0\n        ],\n        [\n          0,\n          0.66\n        ]\n      ],\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ]\n    ],\n    [\n      [\n        [\n          0,\n          0.18\n        ],\n        [\n          0.18,\n          0\n        ]\n      ],\n      [\n        [\n          0.66,\n          0\n        ],\n        [\n          0,\n          0.7\n        ]\n      ]\n    ]\n  ],\n  \"nelec\": [\n    1,\n    1\n  ],\n  \"norb\": 2,\n  \"params\": {\n    \"num_batches\": 3,\n    \"seed\": 7\n  },\n  \"run_job_id\": \"jb-abc123\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "<string>",
  "status": "<string>",
  "context": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

HAIQU_API_KEY

string

query

required

Body

application/json

Define payload for a sample-based quantum diagonalization job.

Attributes: experiment_id: Parent experiment identifier. h1e: One-body integrals, shape (norb, norb). h2e: Two-body integrals, shape (norb, norb, norb, norb). norb: Number of spatial orbitals. nelec: Alpha and beta electron counts. results: Measured bitstring counts per batch. run_job_id: Run job whose stored results supply results. num_shots: Shots behind the supplied results. name: Optional job name. params: Optional diagonalization parameter overrides.

experiment_id

string

required

h1e

number[][]

required

One-body integrals as a norb x norb matrix.

h2e

number[][][][]

required

Two-body integrals as a rank-4 norb array. This grows as norb**4, so prefer small active spaces when calling through a tool; use the SDK for large ones.

norb

integer

required

Number of spatial orbitals.

Required range: x >= 1

nelec

Nelec · tuple

required

Alpha and beta electron counts as [n_alpha, n_beta].

Show child attributes

results

Results · object[] | null

Measured bitstring counts per batch. Provide this or run_job_id, not both.

Show child attributes

run_job_id

string | null

Run job whose stored measurement results are used as results, so large count dictionaries never have to be passed inline. Provide this or results.

num_shots

integer | null

Shots behind the supplied results. Derived from the run job when run_job_id is used.

name

string

default:SKQD Postprocessing

params

Params · object | null

Optional overrides: samples_per_batch, num_batches, max_iterations, symmetrize_spin, configuration_recovery, seed.

Response

Successful Response

Represent the outcome of a job lifecycle action such as cancel or restart.

Attributes: job_id: Identifier of the affected job. status: Job status after the action was applied. context: Summary of what changed and the recommended next step.

job_id

string

required

status

string

required

context

string

required

⌘I