### Install PLANQK Quantum SDK

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Installs or upgrades the PLANQK Quantum SDK using pip. This Python package enables the development and execution of quantum circuits. Requires Python 3.11 or higher.

```shell
pip install --upgrade planqk-quantum
```

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

### Deploy Your Service

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Deploy your PLANQK Service to the PLANQK Platform using the `planqk up` command or by manually uploading a compressed archive.

```APIDOC
## Deploy your service

### Description
This section explains how to deploy your developed PLANQK Service to the PLANQK Platform. You can use the `planqk up` command for direct deployment or `planqk compress` to create a deployable archive for manual upload.

### Method
Command Line

### Endpoint
N/A

### Parameters
N/A

### Request Example
To deploy directly:
```bash
planqk up
```

To compress for manual upload:
```bash
planqk compress
```

### Response
#### Success Response
Upon successful deployment, your service will be available in the [Services](https://platform.planqk.de/services) section of the PLANQK Platform. The `planqk compress` command creates a ZIP file in your project directory.

*Note:* Both `planqk up` and `planqk compress` respect the `.planqkignore` file to exclude specified files and directories from the deployment package.
```

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

### Initialize a New PLANQK Service Project

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Create a new PLANQK Service project using the `planqk init` command. You will be prompted to provide details such as service name, starter template, and resource configuration.

```APIDOC
## Initialize a New PLANQK Service Project

### Description
Create a new PLANQK Service project by running the `planqk init` command. This command will guide you through a series of prompts to configure your project, including its name, starter template, and resource allocation (vCPU and memory).

### Method
Command Line

### Endpoint
N/A

### Parameters
N/A (Interactive prompts)

### Request Example
```bash
planqk init
```

### Response
#### Success Response
A new project directory is created with the specified name, containing all necessary files and configurations, including a `planqk.json` file.

#### Response Example
Project directory structure:
```
my-project/
├── README.md
├── planqk.json
├── src/
│   └── program.py
└── requirements.txt
```

`planqk.json` example:
```json
{
  "name": "my-project",
  "descriptionFile": "README.md",
  "resources": {
    "cpu": 1,
    "memory": 1
  },
  "runtime": "PYTHON_TEMPLATE"
}
```
```

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

### Test Service Locally (Python)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Test your PLANQK Service locally by running the Python script. Ensure you have installed dependencies and configured your access token.

```APIDOC
## Test your service locally (Python)

### Description
This section details how to test your PLANQK Service locally using the Python execution environment. It involves setting up a virtual environment, installing dependencies, configuring your access token, and running the service.

### Method
Command Line & Python Script Execution

### Endpoint
N/A (Local execution)

### Parameters
- **YOUR_PERSONAL_ACCESS_TOKEN_HERE** (string) - Required - Your PLANQK personal access token for authentication.

### Request Example
1. Switch to your project directory:
   ```bash
   cd my-project
   ```
2. Create and activate a virtual environment (example using `uv`):
   ```bash
   uv venv
   uv sync
   source .venv/bin/activate
   ```
3. Modify `src/program.py` to include your access token:
   ```python
   provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
   ```
4. Run your service locally:
   ```bash
   python -m src
   ```

### Response
#### Success Response
A JSON output displaying the results of the service execution, typically including counts and elapsed time.

#### Response Example
```json
{
  "counts": {
    "000": 6,
    "001": 13,
    "010": 19,
    "011": 18,
    "100": 8,
    "101": 14,
    "110": 8,
    "111": 14
  },
  "elapsed_time": 17.837932109832764
}
```
```

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

### Create README File using touch

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/implementations/getting-started.md

This command creates an empty README.md file in your current directory. This file is typically used to provide information about your project or implementation.

```bash
touch README.md
```

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

### Serve PLANQK Service Locally with CLI

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

This command serves the PLANQK service locally using the PLANQK CLI, making it accessible via `http://localhost:8081`. It allows interactive testing through a web UI found at `/docs`, enabling users to send POST requests with JSON payloads and retrieve execution results via GET requests using an execution ID.

```bash
cd my-project
planqk serve
```

```json
{
  "data": { "n_coin_tosses": 2 }
}
```

```json
{
  "counts": {
    "10": 30,
    "11": 25,
    "00": 24,
    "01": 21
  },
  "elapsed_time": 11.129297733306885,
  "_links": {
    "status": {
      "href": "/5b25134c-dd05-47a0-9c12-ff9816074936"
    }
  },
  "_embedded": {
    "status": {
      "id": "5b25134c-dd05-47a0-9c12-ff9816074936",
      "status": "SUCCEEDED",
      "created_at": "2025-03-24 11:16:20",
      "started_at": "2025-03-24 11:16:20",
      "ended_at": "2025-03-24 11:16:32"
    }
  }
}
```

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

### Test Service Locally (PLANQK CLI)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Test your PLANQK Service locally using the PLANQK CLI. This involves starting the local server and interacting with the service via its API endpoints.

```APIDOC
## Test your service locally using PLANQK CLI

### Description
This section describes how to test your PLANQK Service locally using the PLANQK Command Line Interface (CLI). It involves starting a local development server and interacting with your service through its provided API endpoints, including executing the service and retrieving results.

### Method
Command Line & API Interaction

### Endpoint
- `http://localhost:8081/docs` (Swagger UI for API interaction)
- `POST /` (Execute the service)
- `GET /{id}` (Get execution status)
- `GET /{id}/result` (Get execution result)

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for a service execution.

#### Query Parameters
N/A

#### Request Body
##### POST /
- **data** (object) - Required - Input data for the service execution.
  - **n_coin_tosses** (integer) - Required - The number of coin tosses to simulate.

### Request Example
1. Navigate to your project directory:
   ```bash
   cd my-project
   ```
2. Start the local PLANQK server:
   ```bash
   planqk serve
   ```
3. Access the Swagger UI at `http://localhost:8081/docs`.
4. **To execute the service:**
   - Open the `POST /` operation.
   - Click "Try it out".
   - Paste the following JSON into the request body:
     ```json
     {
       "data": { "n_coin_tosses": 2 }
     }
     ```
   - Click "Execute". Copy the returned execution `id`.
5. **To check status:**
   - Open the `GET /{id}` operation.
   - Click "Try it out".
   - Paste the copied `id` into the `id` field.
   - Click "Execute". Check if the status is `SUCCEEDED`.
6. **To retrieve results:**
   - Open the `GET /{id}/result` operation.
   - Click "Try it out".
   - Paste the copied `id` into the `id` field.
   - Click "Execute".

### Response
#### Success Response (POST /)
- **id** (string) - The unique ID of the service execution.

#### Success Response (GET /{id})
- **status** (string) - The current status of the execution (e.g., `SUCCEEDED`, `FAILED`, `RUNNING`).

#### Success Response (GET /{id}/result)
- **counts** (object) - Object containing the results of the service execution.
- **elapsed_time** (number) - The time taken for the execution in seconds.
- **_links** (object) - Links to related resources.
- **_embedded** (object) - Embedded resources, including detailed status information.

#### Response Example (GET /{id}/result)
```json
{
  "counts": {
    "10": 30,
    "11": 25,
    "00": 24,
    "01": 21
  },
  "elapsed_time": 11.129297733306885,
  "_links": {
    "status": {
      "href": "/5b25134c-dd05-47a0-9c12-ff9816074936"
    }
  },
  "_embedded": {
    "status": {
      "id": "5b25134c-dd05-47a0-9c12-ff9816074936",
      "status": "SUCCEEDED",
      "created_at": "2025-03-24 11:16:20",
      "started_at": "2025-03-24 11:16:20",
      "ended_at": "2025-03-24 11:16:32"
    }
  }
}
```

*Press `Ctrl+C` to stop the local server.*
```

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

### Clone PLANQK Repository using Git

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/implementations/getting-started.md

This command clones your PLANQK implementation repository to your local machine. Replace placeholders with your personal access token, user ID, and implementation name. It uses HTTPS with basic authentication.

```bash
git clone https://planqk:<personal-access-token>@git.platform.planqk.de/<your-user-id>/<implementation-name>.git
cd <implementation-name>
```

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

### Add, Commit, and Push Changes using Git

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/implementations/getting-started.md

These Git commands stage all new and modified files, commit them with a message, and then push the commit to the 'main' branch of the remote repository ('origin'). This syncs your local changes with PLANQK.

```bash
git add .
git commit -m "add README"
git push --set-upstream origin main
```

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

### Quantum Coin Toss Example with PLANQK SDK

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

A Python script demonstrating a quantum coin toss circuit using Qiskit and PLANQK Quantum SDK. It creates a circuit, configures a backend (IonQ simulator), transpiles, runs the job, and retrieves the counts. Authentication can be handled via token or CLI login.

```python
from planqk.quantum.sdk import PlanqkQuantumProvider
from qiskit import QuantumCircuit, transpile

n_coin_tosses = 2

circuit = QuantumCircuit(n_coin_tosses)
for i in range(n_coin_tosses):
    circuit.h(i)
circuit.measure_all()

# Use the PLANQK CLI and log in with "planqk login" or set the environment variable PLANQK_PERSONAL_ACCESS_TOKEN.
# Alternatively, you can pass the access token as an argument to the constructor
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")

# Select a quantum backend suitable for the task. All PLANQK supported quantum backends are
# listed at https://app.planqk.de/quantum-backends.
backend = provider.get_backend("azure.ionq.simulator")

# Transpile the circuit ...
circuit = transpile(circuit, backend)
# ... and run it on the backend
job = backend.run(circuit, shots=100)

counts = job.result().get_counts()
```

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

### Local Python Service Testing

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

This code snippet demonstrates how to test a PLANQK service locally using Python. It involves setting up a Python environment, installing dependencies from `requirements.txt`, initializing the `PlanqkQuantumProvider` with an access token, and running the service using `python -m src`. The expected output is a JSON object with results.

```bash
cd my-project
uv venv
uv sync
source .venv/bin/activate
```

```python
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
```

```bash
python -m src
```

```json
{
  "counts": {
    "000": 6,
    "001": 13,
    "010": 19,
    "011": 18,
    "100": 8,
    "101": 14,
    "110": 8,
    "111": 14
  },
  "elapsed_time": 17.837932109832764
}
```

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

### PLANQK Project Configuration File

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

The `planqk.json` file defines the configuration for a PLANQK Service project. It includes metadata like the project name, description file, resource allocation (CPU and memory), and the runtime environment.

```json
{
  "name": "my-project",
  "descriptionFile": "README.md",
  "resources": {
    "cpu": 1,
    "memory": 1
  },
  "runtime": "PYTHON_TEMPLATE"
}
```

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

### Run Qiskit Program with PLANQK Quantum SDK

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Demonstrates how to run a Qiskit quantum circuit on a PLANQK backend using the Python SDK. It shows instantiation of the provider and execution of a circuit. Access tokens can be provided directly or via CLI login.

```python
from planqk.quantum.sdk import PlanqkQuantumProvider
... 
qiskit_circuit = ... # create your Qiskit circuit here
... 
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
result = provider.get_backend("azure.ionq.simulator").run(qiskit_circuit, shots=100).result()
```

```python
from planqk.quantum.sdk import PlanqkQuantumProvider

# Assumes you are logged in via `planqk login` or have set the env variable
provider = PlanqkQuantumProvider()
...
```

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

### Deploy PLANQK Service

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/quickstart.md

Deploys the PLANQK service to the PLANQK Platform using the `planqk up` command. Alternatively, the `planqk compress` command can be used to create a ZIP archive of the project for manual upload. Both commands respect the `.planqkignore` file for excluding specific files and directories.

```bash
planqk up
```

```bash
planqk compress
```

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

### Start and Monitor a Service Execution (TypeScript)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Initializes the PlanQK client, prepares input data and parameters, and starts a new service execution. It then logs the execution ID and initial status. This snippet demonstrates the setup for interacting with PlanQK services.

```typescript
import { PlanqkServiceClient } from '@planqk/planqk-service-sdk';

// Create a client instance
const client = new PlanqkServiceClient(
    "https://your-service-endpoint.planqk.de",
    "your_consumer_key",
    "your_consumer_secret"
);

// Prepare your input data and parameters
const data = { values: [1, 2, 3, 4, 5] };
const params = { algorithm: "quantum_fourier_transform", shots: 1000 };

// Start a service execution
const execution = await client.api().startExecution({ data, params });

console.log(`Execution started with ID: ${execution.id}`);
console.log(`Status: ${execution.status}`);
```

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

### Run a PLANQK Service Execution in Python

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Provides a basic example of using the PLANQK Service SDK in Python to initiate a service execution. It demonstrates creating a client instance, preparing input data and parameters, and starting an execution.

```python
from planqk.service.client import PlanqkServiceClient

# Create a client instance
client = PlanqkServiceClient(
    service_endpoint="https://your-service-endpoint.planqk.de",
    consumer_key="your_consumer_key",
    consumer_secret="your_consumer_secret"
)

# Prepare your input data and parameters
data = {"values": [1, 2, 3, 4, 5]}
params = {"algorithm": "quantum_fourier_transform", "shots": 1000}

# Start a service execution
execution = client.run(request={"data": data, "params": params})
```

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

### PennyLane Integration

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference.md

Guide on integrating the PLANQK SDK with PennyLane, including installation and creating a remote device.

```APIDOC
## PennyLane Integration

### Description
This section explains how to integrate the PLANQK SDK with PennyLane for executing quantum circuits. It covers installation requirements and provides an example of setting up a remote device.

### Installation
To use the SDK with PennyLane, install the `pennylane-qiskit` package:

```bash
pip install pennylane-qiskit==0.36
```

**Note:** Currently, only `pennylane` and `pennylane-qiskit` versions 0.36.0 are supported.

### Creating a Remote Device
To execute a PennyLane circuit on a PLANQK backend, follow these steps:

1.  Retrieve the desired backend using the `PlanqkQuantumProvider`.
2.  Create a `qiskit.remote` device, passing the PLANQK backend to it.

### Request Example
```python
import pennylane as qml
from planqk.provider import PlanqkQuantumProvider

# Initialize the PLANQK provider
provider = PlanqkQuantumProvider()

# Get a specific backend (e.g., Azure IonQ simulator)
backend = provider.get_backend("azure.ionq.simulator")

# Create a remote qiskit device
device = qml.device('qiskit.remote', wires=2, backend=backend, shots=100)

# Define a quantum circuit using the remote device
@qml.qnode(device)
def circuit():
    qml.Hadamard(wires=0)
    qml.CNOT(wires=[0, 1])
    return qml.sample(qml.PauliZ(0)), qml.sample(qml.PauliZ(1))

# Execute the circuit
result = circuit()
print(result)
```

### Response Example
The output will depend on the circuit execution and the backend used. For the example above, it might look like:

```
(array([1., 1.]), array([1., 1.]))
```
```

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

### Install PLANQK API SDK (Python & TypeScript)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-api-reference.md

Instructions for installing the PLANQK API SDK using pip for Python and npm/yarn for TypeScript. Ensures the latest version is used for compatibility.

```bash
pip install --upgrade planqk-api-sdk
```

```bash
npm install @planqk/planqk-api-sdk
# or
yarn add @planqk/planqk-api-sdk
```

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

### Install PLANQK Service SDK with pip (Python)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Installs the PLANQK Service SDK using pip, a standard Python package installer. It is recommended to use a virtual environment for isolation.

```bash
# Create a virtual environment (recommended)
python -m venv planqk-env
source planqk-env/bin/activate  # On Windows: planqk-env\Scripts\activate

# Install the package
pip install planqk-service-sdk
```

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

### Install PLANQK Service SDK with uv (Python)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Installs the PLANQK Service SDK into a Python project using the 'uv' package manager. Requires Python 3.9+ and 'uv' to be installed.

```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Create a new project directory
mkdir my-planqk-project
cd my-planqk-project

# Initialize a new Python project
uv init

# Add the PLANQK Service SDK
uv add planqk-service-sdk

# Run your Python script
uv run python your_script.py

# Add the PLANQK Service SDK to your existing project
uv add planqk-service-sdk

# Or add it to a specific dependency group
uv add --group dev planqk-service-sdk  # for development dependencies
```

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

### Install PLANQK Quantum SDK using pip

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-qiskit-with-planqk-sdk.md

Install the PLANQK Quantum SDK using pip. Ensure Python 3.11 or higher is installed. This command fetches and installs the latest version of the SDK from PyPI.

```bash
pip install planqk-quantum
```

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

### Install PLANQK Quantum Client using pip

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-quantum-client-reference.md

This command installs or upgrades the PLANQK Quantum Client package from PyPI. Ensure you have Python 3.11 or higher installed.

```bash
pip install --upgrade planqk-quantum-client
```

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

### Install and Authenticate PLANQK CLI

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

Installs the PLANQK Command Line Interface (CLI) globally using npm, logs in using a personal access token, and optionally sets an organization context. It also provides commands to verify the current context and list available contexts.

```bash
# Install the CLI globally
npm install -g @planqk/planqk-cli

# Login with your personal access token
planqk login -t your_access_token_here

# Set organization context (optional)
planqk set-context

# Verify current context
planqk get-context

# List available contexts
planqk list-contexts
```

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

### Install PLANQK CLI Globally with npm

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-local-development.md

Installs the PLANQK CLI globally using npm. Ensure Node.js and npm are installed beforehand. This command makes the 'planqk' command available in your terminal.

```bash
npm install -g @anaqor/planqk
```

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

### Initialize PLANQK Project and Environment

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/managed/datapool.md

Initializes a new PLANQK service project using the 'planqk' CLI, creates a virtual environment with 'uv', and installs project dependencies.

```bash
planqk init

cd [user_code]

uv venv
source .venv/bin/activate
uv sync
```

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

### Install PLANQK Service SDK (TypeScript/JavaScript)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Installs the PLANQK Service SDK for TypeScript/JavaScript projects using common package managers like npm, yarn, or pnpm.

```bash
# Using npm
npm install @planqk/planqk-service-sdk

# Using yarn
yarn add @planqk/planqk-service-sdk

# Using pnpm
pnpm add @planqk/planqk-service-sdk
```

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

### Install PLANQK Quantum SDK (Python)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

Installs the PLANQK Quantum SDK for Python, requiring Python 3.11 or higher. It also includes a verification step to import the `PlanqkQuantumProvider` class.

```python
# Requires Python 3.11 or higher
pip install --upgrade planqk-quantum

# Verify installation by importing
from planqk.quantum.sdk import PlanqkQuantumProvider
```

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

### Get PLANQK CLI Help Information

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/cli-reference.md

Retrieves general help information for the PLANQK CLI, listing all available commands. This is useful for understanding the CLI's capabilities.

```bash
planqk help
```

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

### Initialize PLANQK Service Project (Bash)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

This bash script demonstrates the initialization of a new PLANQK service project. It uses the `planqk init` command and outlines the configuration prompts for service name, template, and resource allocation. It also shows the resulting project structure.

```bash
# Initialize new project
planqk init

# Follow prompts to configure:
# - Service name: my-quantum-service
# - Starter template: Python Starter
# - vCPU configuration: 1 vCPU
# - Memory configuration: 1GB

# Navigate to project directory
cd my-quantum-service

# Project structure created:
# ├── src/
# │   ├── __init__.py
# │   └── program.py       # Contains run() method
# ├── input/
# │   ├── data.json
# │   └── params.json
# ├── requirements.txt
# ├── planqk.json          # Service configuration
# ├── .planqkignore
# └── README.md
```

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

### Initialize PLANQK Project

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/automation/introduction.md

Sets up a new project for PLANQK services. This command scaffolds the initial project structure and configuration files, including the crucial 'planqk.json'.

```bash
planqk init
```

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

### Retrieve Execution Results and Logs (TypeScript)

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Demonstrates fetching the final results and logs of a completed PlanQK service execution using the TypeScript SDK. It includes examples for getting the result object and iterating through log entries.

```typescript
// Get the complete result object
const result = await client.api().getResult(execution.id! \
);
console.log(result);

// Access execution logs
const logs = await client.api().getLogs(execution.id! \
);
console.log("Recent logs:");
logs.slice(-5).forEach(log => console.log(log));
```

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

### Example `planqk.json` Configuration

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/planqk-json-reference.md

This JSON snippet demonstrates a complete `planqk.json` file, showcasing all supported configuration properties for a PLANQK service. It includes service identification, resource allocation (CPU, memory, GPU details), and runtime selection.

```json
{
  "name": "my-service",
  "descriptionFile": "README.md",
  "resources": {
    "cpu": 2,
    "memory": 4,
    "gpu": {
      "type": "NVIDIA_TESLA_T4",
      "count": 1
    }
  },
  "runtime": "PYTHON_TEMPLATE",
  "serviceId": "99487f0b-21f0-4256-8335-5179d416dbb4"
}
```

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

### Handle PlanQK SDK Errors in TypeScript

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference-service.md

Illustrates error handling for the PlanQK SDK in TypeScript, including specific handling for API errors. This example assumes the '@planqk/planqk-service-sdk' is installed. It retrieves logs on failure and displays success or error messages.

```typescript
import { PlanqkServiceClient } from '@planqk/planqk-service-sdk';
import { PlanqkServiceApiError } from '@planqk/planqk-service-sdk';

try {
  const client = new PlanqkServiceClient(
      "https://your-service-endpoint.planqk.de",
      "invalid_key",
      "invalid_secret");

  const execution = await client.api().startExecution({ data: {}, params: {} });
  const finalExecution = await waitForCompletion(client, execution.id!); // Assuming waitForCompletion is defined elsewhere

  if (finalExecution.status === "FAILED") {
    const logs = await client.api().getLogs(execution.id!);
    console.log("Execution failed. Recent logs:");
    logs.slice(-10).forEach(log => console.log(log));
  } else {
    const result = await client.api().getResult(execution.id!);
    console.log(`Success: ${JSON.stringify(result)}`);
  }

} catch (error) {
  if (error instanceof PlanqkServiceApiError) {
    console.error(`API Error (${error.statusCode}):`, error.body);
  } else {
    console.error('Error:', error);
  }
}
```

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

### Python Template: Service Output Example

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/managed/runtime-interface.md

Illustrates the expected JSON structure for the main result endpoint (`GET /{id}/result`) when a Python service returns a dictionary. It includes the main output, status, and links for accessing the result and related resources.

```json
{
  "sum": 6,
  "_embedded": {
    "status": {
      // omitted for brevity
    }
  },
  "_links": {
    "self": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result"
    },
    "status": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1"
    },
    "output.json": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result/output.json"
    }
  }
}
```

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

### Integrate PLANQK with PennyLane (Python)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

This code demonstrates how to use PLANQK as a backend for PennyLane quantum circuits. It shows how to get a PLANQK backend, create a PennyLane device pointing to it, define a quantum circuit, and execute it. The example uses a Hadamard and CNOT gate, sampling PauliZ observables.

```python
from planqk.quantum.sdk import PlanqkQuantumProvider
import pennylane as qml

# Get backend from PLANQK
provider = PlanqkQuantumProvider()
backend = provider.get_backend("azure.ionq.simulator")

# Create PennyLane device with PLANQK backend
device = qml.device('qiskit.remote', wires=2, backend=backend, shots=100)

@qml.qnode(device)
def circuit():
    qml.Hadamard(wires=0)
    qml.CNOT(wires=[0, 1])
    return qml.sample(qml.PauliZ(0)), qml.sample(qml.PauliZ(1))

# Execute circuit
result = circuit()
print(result)
# Example output: (array([1, -1, 1, -1, ...]), array([1, -1, 1, -1, ...]))
```

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

### Create and Run Qiskit Circuit

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference.md

This snippet demonstrates how to initialize a quantum circuit, apply Hadamard and CNOT gates, measure the qubits, and then execute the circuit on a backend. It also shows how to retrieve an existing job using its ID.

```python
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure(range(2), range(2))

# Run the circuit on the backend
job = backend.run(circuit, shots=10)

# Retrieve a job by id
job = backend.retrieve_job("6ac422ad-c854-4af4-b37a-efabb159d92e")
```

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

### Install PLANQK CLI using npm

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/cli-reference.md

Installs the PLANQK CLI globally using npm. Ensure Node.js 18 or higher and npm are installed. This command installs the latest version of the CLI.

```bash
npm install -g @planqk/planqk-cli
```

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

### Import PLANQK and Braket Libraries for Quantum Computing

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-quera-mis.md

Imports essential libraries from PLANQK and Braket for quantum computing tasks, including setting up quantum providers, defining atom arrangements, and simulating Hamiltonians. These libraries are foundational for building and running quantum algorithms.

```python
from planqk.quantum.sdk import PlanqkBraketProvider
from braket.ahs.atom_arrangement import AtomArrangement
from braket.ahs.analog_hamiltonian_simulation import AnalogHamiltonianSimulation
from braket.timings.time_series import TimeSeries
from braket.ahs.driving_field import DrivingField
```

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

### Install and Verify PLANQK CLI

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-datapool.md

Installs the PLANQK CLI globally using npm and then verifies the installation by checking the CLI version. Requires Node.js 18+.

```bash
# Install the current CLI
npm install -g @planqk/planqk-cli

# Verify installation
planqk --version
```

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

### Run Qiskit Quantum Circuit with PLANQK Provider

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

Demonstrates how to run a quantum circuit using Qiskit with the PLANQK Quantum SDK. It covers authentication, listing and selecting backends, creating a circuit, transpiling, running the job, and retrieving results. It also shows how to retrieve a job later using its ID.

```python
from planqk.quantum.sdk import PlanqkQuantumProvider
from qiskit import QuantumCircuit, transpile

# Authenticate (uses CLI token if logged in, or provide explicitly)
provider = PlanqkQuantumProvider()
# Or with explicit token: provider = PlanqkQuantumProvider(access_token="YOUR_TOKEN")
# Or with organization: provider = PlanqkQuantumProvider(organization_id="ORG_ID", access_token="TOKEN")

# List available backends
backends = provider.backends()
print(backends)

# Select a backend (IonQ simulator is free)
backend = provider.get_backend("azure.ionq.simulator")

# Create a quantum circuit
circuit = QuantumCircuit(3, 3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure(range(3), range(3))

# Transpile and run
circuit = transpile(circuit, backend)
job = backend.run(circuit, shots=100)

# Check status and get results
print(f"Job ID: {job.job_id()}")
print(f"Status: {job.status()}")
result = job.result()
print(f"Counts: {result.get_counts()}")
# Example output: {'000': 52, '111': 48}
print(f"Memory: {result.get_memory()}")
# Example output: ['000', '111', '000', '111', ...]

# Retrieve job later using its ID
retrieved_job = backend.retrieve_job("6ac422ad-c854-4af4-b37a-efabb159d92e")
print(retrieved_job.result())
```

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

### List and Select Backends with PlanqkQuantumProvider

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference.md

Shows how to list all available PLANQK quantum backends and select a specific backend for use. The available backends can also be found on the PLANQK Platform.

```python
# List all available PLANQK quantum backends
backends = provider.backends()

# Select a certain backend
backend = provider.get_backend("azure.ionq.simulator")
```

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

### Serve PLANQK Service Locally with CLI

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-local-development.md

Starts the PLANQK service locally using the PLANQK CLI. The service will be accessible at http://localhost:8081 once running. This command is essential for local testing and development.

```bash
planqk serve
```

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

### Run Quantum Circuit with Amazon Braket via PLANQK

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

Demonstrates running a quantum circuit using Amazon Braket through the PLANQK SDK. It covers initializing the `PlanqkBraketProvider`, listing available devices, selecting a specific device, creating a Braket circuit, and executing it with a specified number of shots.

```python
from braket.circuits import Circuit
from planqk.quantum.sdk import PlanqkBraketProvider
from planqk.braket.planqk_quantum_task import PlanqkAwsQuantumTask

# Initialize provider
provider = PlanqkBraketProvider()
# Or with explicit auth: provider = PlanqkBraketProvider(access_token="TOKEN", organization_id="ORG_ID")

# List available devices
devices = provider.devices()
print(devices)

# Select device
device = provider.get_device("aws.ionq.forte")

# Create Braket circuit
circuit = Circuit().h(0).cnot(0, 1).cnot(1, 2)

# Execute with 100 shots
task = device.run(circuit, 100)

```

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

### Install uv Package Manager

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/tutorials/tutorial-datapool.md

Installs the uv Python package manager using a curl script for macOS/Linux. It also includes a commented-out command for Windows PowerShell. Verifies installation afterwards.

```bash
# Install uv (if not already installed)
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify uv installation
uv --version
```

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

### Get Service Execution Log

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/managed/openapi.md

Get the log output of a service execution line by line.

```APIDOC
## GET /{id}/log

### Description
Get the log output of a service execution line by line.

### Method
GET

### Endpoint
`/{id}/log`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the service execution.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **log_lines** (array) - An array of strings, where each string is a line from the log.

#### Response Example
```json
{
  "log_lines": [
    "INFO: Service started.",
    "DEBUG: Processing data...",
    "ERROR: Failed to process item X."
  ]
}
```
```

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

### JSON Example: Corridor Assignments

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/workflow/air-traffic-tutorial.md

An example JSON structure representing corridor assignments with their associated flight routes. This format is used by the Air Traffic Visualizer.

```json
[
  {
    "channel": "Corridor 0",
    "routes": [
      {
        "origin": "HEL",
        "destination": "FCO"
      }
    ]
  },
  {
    "channel": "Corridor 1",
    "routes": [
      {
        "origin": "CDG",
        "destination": "OTP"
      },
      {
        "origin": "FCO",
        "destination": "CDG"
      }
    ]
  }
]
```

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

### Execute Braket Circuit on IonQ Forte Device via Planqk

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/sdk-reference.md

This example demonstrates creating a Braket circuit and executing it on the IonQ Forte device provided by Planqk. It shows how to set up the device, define the circuit, run the task, and retrieve its status and results.

```python
from braket.circuits import Circuit
from planqk.quantum.sdk import PlanqkBraketProvider
from planqk.braket.planqk_quantum_task import PlanqkAwsQuantumTask

# Select the IonQ Forte device
device = PlanqkBraketProvider().get_device("aws.ionq.forte")

# Create a Braket circuit
circuit = Circuit().h(0).cnot(0, 1).cnot(1,2)

# Execute the circuit with 100 shots
task = device.run(circuit, 100)

# Monitor task status and get results
print(f"Status: {task.state()}") 
print(f"Result: {task.result()}")
```

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

### JSON Example: Workflow Input Configuration

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/workflow/air-traffic-tutorial.md

An example JSON object defining the input structure for the Air Traffic Management Workflow. It includes flight routes and a map output configuration.

```json
{
  "flightRoutes": [
    {
      "origin": "HEL",
      "destination": "FCO"
    },
    {
      "origin": "BER",
      "destination": "MAD"
    },
    {
      "origin": "CDG",
      "destination": "OTP"
    },
    {
      "origin": "FCO",
      "destination": "CDG"
    },
    {
      "origin": "OTP",
      "destination": "OSL"
    }
  ],
  "map_output": {
    "ref": "datapool",
    "id": "uuid-of-your-datapool"
  }
}
```

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

### Implement Python Template Service (Python)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

This Python code defines the entry point (`run` function) for a PLANQK service using the Python template. It includes Pydantic models for input data and parameters, demonstrates creating a Qiskit quantum circuit, executing it on a PLANQK backend, and returning the results along with elapsed time. The `run` function is designed to be called by the PLANQK runtime.

```python
# src/program.py
from typing import Dict, Any
from pydantic import BaseModel
from planqk.quantum.sdk import PlanqkQuantumProvider
from qiskit import QuantumCircuit, transpile

class InputData(BaseModel):
    n_coin_tosses: int

class InputParams(BaseModel):
    shots: int = 100
    backend_name: str = "azure.ionq.simulator"

def run(data: InputData, params: InputParams) -> Dict[str, Any]:
    """
    Service entrypoint called by PLANQK runtime.

    Input is provided via POST / endpoint as:
    {"data": {"n_coin_tosses": 3}, "params": {"shots": 100, "backend_name": "..."}}

    Returns JSON-serializable dict to GET /{id}/result endpoint.
    """
    import time
    start_time = time.time()

    # Create quantum circuit
    circuit = QuantumCircuit(data.n_coin_tosses)
    for i in range(data.n_coin_tosses):
        circuit.h(i)
    circuit.measure_all()

    # Execute on PLANQK backend
    provider = PlanqkQuantumProvider()
    backend = provider.get_backend(params.backend_name)
    circuit = transpile(circuit, backend)
    job = backend.run(circuit, shots=params.shots)

    result = job.result()
    counts = result.get_counts()

    elapsed_time = time.time() - start_time

    # Return dict is automatically serialized to JSON
    return {
        "counts": counts,
        "elapsed_time": elapsed_time
    }
```

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

### Deploy PLANQK Service to Platform (Bash)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

This bash script provides commands for deploying a PLANQK service. It includes options to deploy the service (`planqk up`), compress it for manual upload (`planqk compress`), list all services, filter services by name, and retrieve all service properties in JSON format.

```bash
# Deploy service (creates or updates)
planqk up

# Or compress for manual upload
planqk compress

# List all services
planqk services

# List services as JSON
planqk services --json

# Filter services by name
planqk services --name "my-quantum-service"

# Get all service properties
planqk services --json --all
```

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

### Get Service Execution Result

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/managed/openapi.md

Get the result of a service execution. The response contains the JSON result from the service (if any). Further, it provides links to download all result files created during the service execution.

```APIDOC
## GET /{id}/result

### Description
Get the result of a service execution. The response contains the JSON result from the service (if any). Further, it provides links to download all result files created during the service execution.

### Method
GET

### Endpoint
`/{id}/result`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the service execution.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **result** (object) - The JSON result from the service.
- **_links** (object) - Links to download result files.

#### Response Example
```json
{
  "result": {
    "output_data": "some value"
  },
  "_links": {
    "download_files": {
      "href": "/execution-id/result/files"
    }
  }
}
```
```

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

### JSON Input Example

Source: https://gitlab.com/planqk-foss/planqk-docs/-/blob/main/src/services/managed/runtime-interface.md

Demonstrates the structure of JSON input data provided to a PLANQK service. The input is mounted as files in `/var/runtime/input`, with top-level properties becoming separate JSON files (e.g., `data.json`, `params.json`).

```json
{
  "data": { "values": [1, 2, 3] },
  "params": { "round_up": true }
}
```

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

### Test PLANQK Service Locally with CLI (Bash)

Source: https://context7.com/planqk-foss/planqk-docs/llms.txt

This bash script outlines the process for testing a PLANQK service locally. It covers starting the development server, accessing interactive API documentation, testing the service via POST requests with sample input, and checking the execution status and results. It also shows how to stop the local server.

```bash
# Start local development server
planqk serve
# Server starts at http://localhost:8081

# Access interactive API docs at http://localhost:8081/docs

# Test POST / endpoint with sample input:
# {
#   "data": { "n_coin_tosses": 2 },
#   "params": { "shots": 100 }
# }

# Response returns execution ID:
# {
#   "id": "5b25134c-dd05-47a0-9c12-ff9816074936",
#   "status": "PENDING"
# }

# Check status with GET /{id}
# Get result with GET /{id}/result when status is SUCCEEDED:
# {
#   "counts": {"00": 24, "01": 21, "10": 30, "11": 25},
#   "elapsed_time": 11.13,
#   "_links": {...},
#   "_embedded": {...}
# }

# Stop server with Ctrl+C
```