### Authenticate and Initialize Haiqu SDK

Source: https://docs.haiqu.ai/quickstart/qs_local

Log in and start your first experiment.

```python
from haiqu.sdk import haiqu
  
# Login with your API key
haiqu.login(api_access_key="[PASTE YOUR API KEY HERE]")
  
# Initialize your first experiment
haiqu.init("My First Quantum Experiment")
```

--------------------------------

### Login and Initialize Haiqu SDK

Source: https://docs.haiqu.ai/quickstart/qs_intro

This snippet shows how to log in to the Haiqu SDK using an API key and initialize a new experiment.

```python
from haiqu.sdk import haiqu
  
# Login with your API key
haiqu.login() 
  
# Initialize your first experiment
haiqu.init("My First Quantum Experiment")
```

--------------------------------

### Example VariationalProblem Setup

Source: https://docs.haiqu.ai/reference/qml/variational

This code snippet demonstrates how to set up a VariationalProblem using Qiskit and Haiqu SDK. It defines an ansatz circuit with a parameterized gate and a Pauli observable.

```python
>>> from qiskit import QuantumCircuit
>>> from qiskit.circuit import Parameter
>>> from qiskit.quantum_info import SparsePauliOp
>>> from haiqu.sdk.qml import VariationalProblem
>>> theta = Parameter('θ')
>>> ansatz = QuantumCircuit(2)
>>> ansatz.ry(theta, 0)
>>> ansatz.cx(0, 1)
>>> obs = SparsePauliOp.from_list([("ZZ", 1.0), ("XI", 0.5)])
>>> problem = VariationalProblem(ansatz, obs)
```

--------------------------------

### Create and Run a Quantum Circuit with Error Mitigation

Source: https://docs.haiqu.ai/quickstart/qs_intro

This snippet demonstrates how to create a simple Bell state quantum circuit using Qiskit and execute it with Haiqu SDK, including built-in error mitigation.

```python
from qiskit import QuantumCircuit

# Create a simple Bell state circuit 
pc = QuantumCircuit(2)
pc.h(0)
pc.cx(0, 1)
pc.measure_all()
  
# Execute with built-in error mitigation
job = haiqu.run(qc, shots=1000, device_id="fake_fez", use_mitigation=True)
results = job.result()

print(f"Execution results:", results) 
  
print(f"Circuit executed successfully!")
```

--------------------------------

### NFT Optimizer Options Example

Source: https://docs.haiqu.ai/api-reference/variational

Example demonstrating how to instantiate NFTOptimizerOptions with custom parameters.

```python
from haiqu.sdk.qml import NFTOptimizerOptions
optimizer = NFTOptimizerOptions(maxfev=2048, maxiter=100)
```

--------------------------------

### Install Haiqu SDK via pip

Source: https://docs.haiqu.ai/quickstart/qs_local

We encourage installing Haiqu SDK via pip:

```bash
pip install haiqu-sdk
```

--------------------------------

### State Compression Example

Source: https://docs.haiqu.ai/faq

Example of how to use the state_compression function and access job quality.

```python
job = haiqu.state_compression(circuit=circuit)
compressed_circuit = job.result()

print(job.quality)  # approximation quality on an ideal device
```

--------------------------------

### Create and run your first quantum circuit

Source: https://docs.haiqu.ai/quickstart/qs_local

Build and execute a simple quantum circuit with error mitigation.

```python
from qiskit.circuit.random import random_circuit
pc = random_circuit(num_qubits=8, depth=6, max_operands=4, measure=True)
  
# Execute with built-in error mitigation
job = haiqu.run(qc, shots=1000, device_id="fake_fez", use_mitigation=True)
results = job.result()

print(f"Execution results: {results}")
  
print(f"Circuit executed successfully!")
```

--------------------------------

### Get only transpilation jobs for the current experiment

Source: https://docs.haiqu.ai/reference/core/list

This example filters jobs to retrieve only transpilation jobs for the current experiment.

```python
>>> jobs = haiqu.list_jobs(
...     job_type=haiqu.JobType.TRANSPILATION,
...     widget=False
... )
```

--------------------------------

### Get the most recent run job(s) for a specific circuit and experiment

Source: https://docs.haiqu.ai/reference/core/list

This example retrieves the most recent run job(s) for a specific circuit and experiment.

```python
>>> haiqu.list_jobs(
...     experiment_id="exp-12345678-1234-5678-1234-567812345678",
...     job_type=haiqu.JobType.RUN,
...     circuit="circ-abcdefab-cdef-abcd-efab-cdefabcdefab",
...     widget=False,
... )
[RunJobModel 'Run job 12345678-abcd-efab-1234-5678abcdefab'
 ...
]
```

--------------------------------

### Pretrain Example

Source: https://docs.haiqu.ai/reference/qml/pretrain

This example demonstrates how to use the `haiqu.pretrain` function to pretrain parameters for a variational quantum circuit. It includes setting up a quantum circuit, defining a loss function, creating a `VariationalProblem`, pretraining the circuit, and then using the pretrained parameters to run a simulation.

```python
from qiskit import QuantumCircuit
from qiskit.circuit.library import EfficientSU2
from qiskit.quantum_info import SparsePauliOp
from haiqu.sdk import haiqu
from haiqu.sdk.qml import VariationalProblem
pqc = qiskit.QuantumCircuit(5)
pqc.compose(EfficientSU2(num_qubits=pqc.num_qubits, reps=1), inplace=True)
loss = SparsePauliOp(["ZIIII", "IIZXI"])
problem = VariationalProblem(pqc, loss)
job = haiqu.pretrain(problem, max_time=10)
pretrained_params = job.result()  # accessing the pretrained parameters
haiqu.run([problem.ansatz], observables=[problem.observable], parameters=[pretrained_params],
          device=haiqu.get_device("aer_simulator")).result()  # checking the result
```

--------------------------------

### Get only state compression jobs for the current experiment

Source: https://docs.haiqu.ai/reference/core/list

This example filters jobs to retrieve only state compression jobs for the current experiment.

```python
>>> jobs = haiqu.list_jobs(
...     job_type=haiqu.JobType.COMPRESSION,
...     widget=False
... )
```

--------------------------------

### Generate a circuit

Source: https://docs.haiqu.ai/reference/middleware/compression

This example shows how to generate a random quantum circuit and transpile it to a specific device.

```python
>>> from qiskit.circuit.random import random_circuit
>>> quantum_device = "fake_fez"
>>> qc = random_circuit(num_qubits=50, depth=5, max_operands=4, seed=2025, measure=False)
>>> circuit_fez = haiqu.transpile(qc, device=haiqu.get_device(quantum_device))
>>> print(f"{circuit_fez.analytics.gates_2q} two-qubit gates in the circuit transpiled to a device")
1125 two-qubit gates in the circuit transpiled to a device
```

--------------------------------

### Get Python list of the most recent jobs for the current experiment

Source: https://docs.haiqu.ai/reference/core/list

This example retrieves a Python list of the most recent jobs for the current experiment, excluding the widget display.

```python
>>> jobs = haiqu.list_jobs(widget=False)
[RunJobModel 'Run job ABC',
 TranspilationJobModel 'Transpilation of 2 circuit(s) to device fake_torino',
 StateCompressionJobModel 'State Compression of Circuit-123',
 ...
]
```

--------------------------------

### Example of loading a normal distribution

Source: https://docs.haiqu.ai/reference/data/distribution

This example demonstrates how to use the `distribution_loading` method to prepare a normal distribution and then append the resulting gate to a Qiskit circuit.

```python
>>> num_qubits = 4
>>> job = haiqu.distribution_loading(
...     num_qubits=num_qubits,
...     distribution_name="norm",
...     interval_start=-3,
...     interval_end=3,
...     name=f"Normal distribution ({num_qubits} qubits)",
... )
>>> dl_gate = job.result()  # dl_gate is a Qiskit-compatible gate
>>> fidelity = job.quality
>>> print(f"Normal distribution was loaded with fidelity {fidelity:.6f}")
Normal distribution was loaded with fidelity 0.999484
>>> circuit = qiskit.QuantumCircuit(num_qubits)
>>> circuit.append(dl_gate, range(num_qubits))
>>> circuit.draw()
     ┌────────────────────────────────────────────────────────────┐
q_0: ┤0                                                           ├
     │                                                            │
q_1: ┤1                                                           ├
     │  Haiqucircuit(circ-12345678-1234-5678-1234-567812345678,4) │
q_2: ┤2                                                           ├
     │                                                            │
q_3: ┤3                                                           ├
     └────────────────────────────────────────────────────────────┘
```

--------------------------------

### Show Haiqu SDK Version

Source: https://docs.haiqu.ai/faq

Displays the currently installed version of the Haiqu SDK.

```bash
pip show haiqu-sdk
```

--------------------------------

### Login and Initialize Experiment

Source: https://docs.haiqu.ai/faq

Demonstrates how to log in to the Haiqu SDK using an API key and initialize a new experiment.

```python
from haiqu.sdk import haiqu

# Cloud JupyterLab: API key is pre-configured, no argument needed
haiqu.login()

# Local install: pass your API key explicitly
haiqu.login(api_access_key="YOUR_HAIQU_API_KEY")
```

```python
haiqu.init("My Experiment")
```

--------------------------------

### Example: Creating QUBO from Ising Hamiltonian

Source: https://docs.haiqu.ai/reference/optimization/problem

Demonstrates how to create a QUBO instance from an Ising Hamiltonian represented as a SparsePauliOp. It shows the conversion of a simple ZZ interaction to its QUBO equivalent and prints the constant, linear, and quadratic coefficients.

```python
>>> from qiskit.quantum_info import SparsePauliOp
>>> 
>>> # Create simple Ising Hamiltonian: H = 1.0·Z₀·Z₁ (coupling only)
>>> # This represents interaction between spins: J₀₁·s₀·s₁ with J₀₁ = 1.0
>>> H = SparsePauliOp.from_list([('ZZ', 1.0)])
>>> qubo = QUBO.from_hamiltonian(H, offset=0.0)
>>> 
>>> # The conversion applies: J₀₁·s₀·s₁ = J₀₁·(1-2x₀)·(1-2x₁)
>>> # Expanding: J₀₁ - 2·J₀₁·x₀ - 2·J₀₁·x₁ + 4·J₀₁·x₀·x₁
>>> # With J₀₁ = 1.0:
>>> #   Constant: +1.0
>>> #   Linear x₀: -2.0 (normalized from diagonal Q[0,0])
>>> #   Linear x₁: -2.0 (normalized from diagonal Q[1,1])
>>> #   Quadratic x₀·x₁: +4.0
>>> 
>>> print(qubo._qp.objective.constant)  # 1.0
>>> print(qubo._qp.objective.linear.to_dict())  # {0: -2.0, 1: -2.0}
>>> print(qubo._qp.objective.quadratic.to_dict())  # {(0,1): 4.0}
```

--------------------------------

### OpenAPI Specification for Get Benchmarks

Source: https://docs.haiqu.ai/api-reference/get-benchmarks

OpenAPI specification detailing the GET /help/benchmarks endpoint.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /help/benchmarks:
    get:
      summary: Get Benchmarks
      description: |-
        Get data for benchmarks for key circuit metrics against references.

        Returns:
            list: Benchmarks data.
      operationId: get_benchmarks_help_benchmarks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
```

--------------------------------

### OpenAPI Specification for Get Experiment

Source: https://docs.haiqu.ai/api-reference/get-experiment-1

This OpenAPI specification defines the GET /ai/{experiment_id} endpoint for retrieving experiment details.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /ai/{experiment_id}:
    get:
      summary: Get Experiment
      description: |-
        Get experiment by ID tool.

        Args:
            experiment_id (str): ID of the experiment.
            user (UserModel): User authenticated with api key.

        Returns:
            ContextExperimentModel: Experiment object.
      operationId: get_experiment_by_id
      parameters:
        - name: experiment_id
          in: path
          required: true
          schema:
            type: string
            title: Experiment Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextExperimentModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextExperimentModel:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        creation_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Creation Date
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        circuits_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Circuits Count
          default: 0
        jobs_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Jobs Count
          default: 0
        last_action_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Action Date
        context:
          type: string
          title: Context
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          default: ''
      type: object
      required:
        - id
        - name
        - context
      title: ContextExperimentModel
      description: Experiment model with the context for AI/MCP endpoints.
    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

```

--------------------------------

### Example of using Matrix Product State (MPS) simulator for larger scale experiments

Source: https://docs.haiqu.ai/reference/run/run

This example demonstrates how to use the Matrix Product State (MPS) simulator from Haiqu for running larger scale experiments. It shows how to create a random circuit and configure the MPS simulator with specific options like `method` and `matrix_product_state_max_bond_dimension`.

```python
>>> from qiskit.circuit.random import random_circuit
>>> circuit = random_circuit(num_qubits=20, depth=3, max_operands=3, seed=2025, measure=True)
>>> job = haiqu.run(circuit, device_id="aer_simulator", options={
...                 "method": "matrix_product_state",  # set method to MPS
...                 "matrix_product_state_max_bond_dimension": 16,  # preferably, limit the bonds
...               })
```

--------------------------------

### OpenAPI Specification for Get Job

Source: https://docs.haiqu.ai/api-reference/get-job

This OpenAPI specification defines the GET /jobs/{job_id} endpoint, including its parameters, responses, and security schemes.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /jobs/{job_id}:
    get:
      summary: Get Job
      description: |-
        Unified endpoint to get different types of the jobs.

        Job details could include circuit and other parameters of the job.

        Args:
            job_id (str): ID of the job.
            user (User): User authenticated with api key.

        Returns:
           BaseModel: The Job pydantic model object.
      operationId: get_job_jobs__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    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

```

--------------------------------

### IonQ Cloud Device Options

Source: https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator

Example of how to specify options for running circuits on IonQ Cloud devices.

```json
options = {
    "ionq_api_key": "<YOUR_TOKEN>",
}
```

--------------------------------

### OpenAPI Specification for Get User

Source: https://docs.haiqu.ai/api-reference/get-user

The OpenAPI specification details the Get User endpoint, including its summary, description, parameters, and responses.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /user:
    get:
      summary: Get User
      description: |-
        Get user profile endpoint.

        MVP: Get user by API Key.

        V2:
        Return user profile according to the OAuth2 token supplied.
        If user not exists - verify OAuth token, retrieve user profile from the
        provider and create Haiqu user instance.

        Args:
            access_token (str): Token from OAuth provider, Google, IBM, etc.
            api_access_key (str): Haiqu API key, if user got an invitation with HAIQU_API_KEY.

        Returns:
            UserModel: User profile object.
      operationId: get_user_user_get
      responses:
        '200': 
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserModel'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    UserModel:
      properties:
        email:
          type: string
          title: Email
        username:
          type: string
          title: Username
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        api_access_key:
          type: string
          title: Api Access Key
      type: object
      required:
        - email
        - username
        - first_name
        - last_name
        - api_access_key
      title: UserModel
      description: |-
        User model.

        MVP: Haiqu user is created by Haiqu team, auth with username/password.
        V2: Haiqu API user is OAuth authenticated user from IBM, Google, etc.
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

```

--------------------------------

### Comparing Transpilation Strategies

Source: https://docs.haiqu.ai/faq

Example of how to transpile a circuit with different optimization levels and compare their metrics.

```python
device = haiqu.get_device("fake_torino")

t_opt0 = haiqu.transpile(circuit, device, optimization_level=0)
t_opt3 = haiqu.transpile(circuit, device, optimization_level=3)

haiqu.compare_metrics(t_opt0, t_opt3)
```

--------------------------------

### OpenAPI Specification for Get Analytics

Source: https://docs.haiqu.ai/api-reference/get-analytics

The OpenAPI 3.1.0 specification for the GET /circuits/{circuit_id}/metrics endpoint, detailing its parameters, responses, and data models.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /circuits/{circuit_id}/metrics:
    get:
      summary: Get Analytics
      description: |-
        Get circuit analytics.

        Args:
            circuit_id (str): ID of the circuit.
            user (User): User authenticated with api key.

        Returns:
            CircuitAnalyticsModel: Metrics data.
      operationId: get_analytics_circuits__circuit_id__metrics_get
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
            title: Circuit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitAnalyticsModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    CircuitAnalyticsModel:
      properties:
        qubits:
          type: integer
          title: Qubits
        num_qubits_active:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Qubits Active
        num_parameters:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Parameters
        depth:
          type: integer
          title: Depth
        depth_2q:
          type: integer
          title: Depth 2Q
        gates_1q:
          type: integer
          title: Gates 1Q
        gates_2q:
          type: integer
          title: Gates 2Q
        other_gates:
          anyOf:
            - type: integer
            - type: 'null'
          title: Other Gates
        gates_total:
          type: integer
          title: Gates Total
        other_ops:
          type: integer
          title: Other Ops
        instructions_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Instructions Total
        operations_counts:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Operations Counts
        gate_size_distribution:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Size Distribution
        gate_diversity:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Diversity
        gate_diversity_basis_gates:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Diversity Basis Gates
        gate_count_distribution:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Gate Count Distribution
        program_communication:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Program Communication
          default: N/A
        critical_depth:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Critical Depth
          default: N/A
        entanglement_ratio:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Entanglement Ratio
          default: N/A
        parallelism:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Parallelism
          default: N/A
        liveness_per_qubit:
          anyOf:
            - items: {}
              type: array
            - type: string
            - type: 'null'
          title: Liveness Per Qubit
          default: N/A
        liveness:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Liveness
          default: N/A
        correlation_matrix:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Correlation Matrix
        kl_divergence:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Kl Divergence
          default: N/A
        circuit_normalized:
          anyOf:
            - type: string

```

--------------------------------

### IBM Quantum Device Options

Source: https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator

Example of how to specify options for running circuits on IBM Quantum devices.

```json
options = {
    "ibm_quantum_token": "<YOUR_TOKEN>",
    "ibm_quantum_instance": "<YOUR_INSTANCE>",
}
```

--------------------------------

### OpenAPI Specification for Get Experiment

Source: https://docs.haiqu.ai/api-reference/get-experiment

This OpenAPI specification defines the GET /experiments/{experiment_id} endpoint, including request parameters, response schemas, and security schemes.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /experiments/{experiment_id}:
    get:
      summary: Get Experiment
      description: |-
        Get experiment endpoint.

        Args:
            experiment_id (str): ID of the experiment.
            user (User): User authenticated with api key.

        Returns:
            ExperimentModel: Experiment object.
      operationId: get_experiment_experiments__experiment_id__get
      parameters:
        - name: experiment_id
          in: path
          required: true
          schema:
            type: string
            title: Experiment Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ExperimentModel:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        creation_date:
          type: string
          format: date-time
          title: Creation Date
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        circuits_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Circuits Count
          default: 0
        jobs_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Jobs Count
          default: 0
        last_action_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Action Date
        user_id:
          type: integer
          title: User Id
        user:
          $ref: '#/components/schemas/UserModel'
        metrics:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metrics
          default: {}
      type: object
      required:
        - id
        - name
        - description
        - creation_date
        - user_id
        - user
      title: ExperimentModel
      description: |-
        Experiment model.

        Haiqu experiment is a parent/organizer entity for circuits and jobs.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UserModel:
      properties:
        email:
          type: string
          title: Email
        username:
          type: string
          title: Username
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        api_access_key:
          type: string
          title: Api Access Key
      type: object
      required:
        - email
        - username
        - first_name
        - last_name
        - api_access_key
      title: UserModel
      description: |-
        User model.

        MVP: Haiqu user is created by Haiqu team, auth with username/password.
        V2: Haiqu API user is OAuth authenticated user from IBM, Google, etc.
    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

```

--------------------------------

### OpenAPI Specification for Get Circuit

Source: https://docs.haiqu.ai/api-reference/get-circuit

The OpenAPI 3.1.0 specification for the GET /circuits/{circuit_id} endpoint, including request parameters, response schemas, and component definitions.

```yaml
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.0.0.dev6
servers: []
security: []
paths:
  /circuits/{circuit_id}:
    get:
      summary: Get Circuit
      description: |-
        Get circuit by ID.

        Args:
            circuit_id (str): ID of the circuit.
            user (User): User authenticated with api key.

        Returns:
            CircuitModel: Circuit object.
      operationId: get_circuit_circuits__circuit_id__get
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
            title: Circuit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    CircuitModel:
      properties:
        id:
          type: string
          title: Id
        hash:
          type: string
          title: Hash
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        creation_date:
          type: string
          format: date-time
          title: Creation Date
        user_id:
          type: integer
          title: User Id
        experiment_id:
          type: string
          title: Experiment Id
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        status:
          $ref: '#/components/schemas/CircuitStatus'
        generated:
          type: boolean
          title: Generated
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters
        analytics:
          anyOf:
            - $ref: '#/components/schemas/CircuitAnalyticsModel'
            - type: 'null'
        transpilation_target:
          anyOf:
            - type: string
            - type: 'null'
          title: Transpilation Target
        transpilation_options:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Transpilation Options
        transpiled_circuit_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Transpiled Circuit Ids
        compressed_circuit_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Compressed Circuit Ids
        job_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Job Ids
        qpy:
          anyOf:
            - type: string
            - type: 'null'
          title: Qpy
        evolution:
          anyOf:
            - $ref: '#/components/schemas/CircuitEvolutionModel'
            - type: 'null'
        metrics:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metrics
      type: object
      required:
        - id
        - hash
        - name
        - creation_date
        - user_id
        - experiment_id
        - status
        - generated
      title: CircuitModel
      description: >-
        Haiqu Circuit model for Analytics Workflows.


        Haiqu circuit is a quantum circuit logged in the Haiqu cloud or
        generated by Haiqu tools

        and enriched with analytics data. It wraps Qiskit QuantumCircuit
        (``qpy`` property, in the form of QPY dump)

        and provides additional methods for analytics and visualization.


        Note: that generated circuits (e.g. from data loading or state
        compression) have the QPY dump available only

        on the Haiqu cloud, but they can be still converted to regular Qiskit
        gates and used in other circuits or

        for execution.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CircuitStatus:
      type: string
      enum:
        - Submitted
        - Running analytics computation

```

--------------------------------

### Creating and Simulating State Preparation Circuit

Source: https://docs.haiqu.ai/core_features/data_loading_vect

Constructs a quantum circuit using the HaiquCircuitGate and runs it on a statevector simulator to obtain amplitudes.

```python
# creating a state preparation circuit
# using the constructed HaiquCircuitGate
nc = QuantumCircuit(8)
nc.compose(gate, inplace=True)

# running exact statevector simulator to access amplitudes
sv = haiqu.statevector_run(qc).result()[0]

# plotting the loaded 2D distribution
plt.imshow(np.real(np.resize(sv, (16, 16))), origin="lower")
```

--------------------------------

### OpenAPI Specification for Get Local Job By Hash

Source: https://docs.haiqu.ai/api-reference/get-local-job-by-hash

This OpenAPI specification defines the GET endpoint for retrieving a local job by its hash within a specific experiment.

```yaml
https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/jobs/{job_hash}
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.0.0.dev6
servers: []
security: []
paths:
  /experiments/{experiment_id}/jobs/{job_hash}:
    get:
      summary: Get Local Job By Hash
      description: |-
        Get local job by HASH endpoint.

        Args:
            experiment_id (str): The parent experiment ID.
            job_id (str): ID of the job.
            user (User): User authenticated with api key.

        Returns:
            LocalJobModel: Job object.
      operationId: get_local_job_by_hash_experiments__experiment_id__jobs__job_hash__get
      parameters:
        - name: experiment_id
          in: path
          required: true
          schema:
            type: string
            title: Experiment Id
        - name: job_hash
          in: path
          required: true
          schema:
            type: string
            title: Job Hash
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalJobModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    LocalJobModel:
      properties:
        id:
          type: string
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        user_id:
          type: integer
          title: User Id
        experiment_id:
          type: string
          title: Experiment Id
        status:
          $ref: '#/components/schemas/JobStatus'
        job_type:
          $ref: '#/components/schemas/JobType'
        device_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Device Id
          default: Haiqu OS
        creation_date:
          type: string
          format: date-time
          title: Creation Date
        run_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Run Date
        finish_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finish Date
        logs:
          anyOf:
            - type: string
            - type: 'null'
          title: Logs
        quality:
          anyOf:
            - type: number
            - type: 'null'
          title: Quality
        info:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Info
        time:
          anyOf:
            - type: number
            - type: 'null'
          title: Time
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
            - type: 'null'
          title: Parameters
        hash:
          type: string
          title: Hash
        circuit_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Circuit Id
          default: ''
        backend_name:
          type: string
          title: Backend Name
        results:
          anyOf:
            - type: string
            - type: 'null'
          title: Results
          default: ''
        shot_local:
          anyOf:
            - type: string
            - type: 'null'
          title: Shot Local
          default: ''
        metrics:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metrics
          default: {}
      type: object
      required:
        - id
        - user_id
        - experiment_id
        - status
        - job_type
        - creation_date
        - hash
        - backend_name
      title: LocalJobModel
      description: |-
        Local user-run Job (regular Qiskit job).
        Flow:
            * user run normal Qiskit job
            * they use `haiqu.log(<job|result>)` to send it to Haiqu cloud for analysis.

        Qiskit and IBM runtime has several types of jobs and types of results.
        We do our best to analyze them all.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object

```