> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json post /ai/postprocess_skqd_samples
openapi: 3.1.0
info:
  title: Haiqu API
  summary: Haiqu RESTful API service.
  description: Cloud service providing the access to Haiqu cloud runtime
  contact:
    name: Haiqu Inc.
    url: https://haiqu.ai/
    email: info@haiqu.ai
  version: 1.5.0
servers: []
security: []
paths:
  /ai/postprocess_skqd_samples:
    post:
      summary: Postprocess Skqd Samples
      description: >-
        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.
      operationId: postprocess_skqd_samples
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextSKQDSubmitModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobActionModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextSKQDSubmitModel:
      properties:
        experiment_id:
          type: string
          title: Experiment Id
        h1e:
          items:
            items:
              type: number
            type: array
          type: array
          title: H1E
          description: One-body integrals as a `norb` x `norb` matrix.
        h2e:
          items:
            items:
              items:
                items:
                  type: number
                type: array
              type: array
            type: array
          type: array
          title: H2E
          description: >-
            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:
          type: integer
          minimum: 1
          title: Norb
          description: Number of spatial orbitals.
        nelec:
          prefixItems:
            - type: integer
            - type: integer
          type: array
          maxItems: 2
          minItems: 2
          title: Nelec
          description: Alpha and beta electron counts as `[n_alpha, n_beta]`.
        results:
          anyOf:
            - items:
                additionalProperties:
                  type: number
                type: object
              type: array
            - type: 'null'
          title: Results
          description: >-
            Measured bitstring counts per batch. Provide this or `run_job_id`,
            not both.
        run_job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Job Id
          description: >-
            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:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Shots
          description: >-
            Shots behind the supplied results. Derived from the run job when
            `run_job_id` is used.
        name:
          type: string
          title: Name
          default: SKQD Postprocessing
        params:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Params
          description: >-
            Optional overrides: `samples_per_batch`, `num_batches`,
            `max_iterations`, `symmetrize_spin`, `configuration_recovery`,
            `seed`.
      type: object
      required:
        - experiment_id
        - h1e
        - h2e
        - norb
        - nelec
      title: ContextSKQDSubmitModel
      description: |-
        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.
      examples:
        - 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
    ContextJobActionModel:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        context:
          type: string
          title: Context
      type: object
      required:
        - job_id
        - status
        - context
      title: ContextJobActionModel
      description: >-
        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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````