mcp-quantum/src/types/index.ts

/**
 * CUDA Quantum MCP Server Type Definitions
 * Comprehensive type system for quantum computing operations and MCP integration
 */

import { z } from 'zod';

// ============================
// Core Quantum Types
// ============================

/**
 * Complex number representation for quantum amplitudes
 */
export interface Complex {
  real: number;
  imag: number;
}

/**
 * Quantum state vector containing complex amplitudes
 */
export type StateVector = Complex[];

/**
 * Quantum measurement result containing bit strings and counts
 */
export interface MeasurementCounts {
  [bitString: string]: number;
}

/**
 * Quantum gate parameter types
 */
export type GateParameter = number | Complex;

/**
 * Quantum register specification
 */
export interface QuantumRegister {
  name: string;
  size: number;
  indices?: number[];
}

/**
 * Single qubit reference
 */
export interface Qubit {
  register: string;
  index: number;
}

// ============================
// Quantum Operation Types
// ============================

/**
 * Quantum gate operation
 */
export interface QuantumGate {
  name: string;
  qubits: Qubit[];
  parameters?: GateParameter[];
  controls?: Qubit[];
  adjoint?: boolean;
}

/**
 * Quantum measurement operation
 */
export interface Measurement {
  qubits: Qubit[];
  classical_register?: string;
  basis?: 'Z' | 'X' | 'Y';
}

/**
 * Quantum kernel (circuit) definition
 */
export interface QuantumKernel {
  name: string;
  parameters: KernelParameter[];
  registers: QuantumRegister[];
  operations: (QuantumGate | Measurement)[];
  metadata?: {
    description?: string;
    author?: string;
    created?: string;
  };
}

/**
 * Kernel parameter definition
 */
export interface KernelParameter {
  name: string;
  type: 'int' | 'float' | 'complex' | 'list[int]' | 'list[float]' | 'list[complex]';
  default?: any;
  description?: string;
}

// ============================
// Execution Types
// ============================

/**
 * Quantum execution target configuration
 */
export interface QuantumTarget {
  name: string;
  type: 'simulator' | 'hardware';
  backend: string;
  configuration?: {
    shots?: number;
    noise_model?: string;
    connectivity?: string;
    credentials?: Record<string, string>;
  };
}

/**
 * Quantum job execution parameters
 */
export interface ExecutionParams {
  shots?: number;
  target?: string;
  parameters?: Record<string, any>;
  async?: boolean;
  timeout?: number;
}

/**
 * Quantum execution result
 */
export interface ExecutionResult {
  job_id: string;
  status: 'completed' | 'failed' | 'running' | 'queued';
  result_type: 'sample' | 'observe' | 'state' | 'run';
  data: MeasurementCounts | number | StateVector | any[];
  metadata: {
    shots?: number;
    execution_time?: number;
    target?: string;
    error?: string;
  };
}

// ============================
// Observable Types
// ============================

/**
 * Pauli string for Hamiltonian terms
 */
export interface PauliString {
  paulis: ('I' | 'X' | 'Y' | 'Z')[];
  qubits: number[];
  coefficient: Complex;
}

/**
 * Quantum Hamiltonian operator
 */
export interface Hamiltonian {
  terms: PauliString[];
  metadata?: {
    name?: string;
    description?: string;
  };
}

/**
 * Expectation value result
 */
export interface ExpectationValue {
  value: number;
  variance?: number;
  shots?: number;
}

// ============================
// MCP Tool Schemas
// ============================

/**
 * Zod schema for quantum kernel creation
 */
export const CreateKernelSchema = z.object({
  name: z.string().min(1),
  num_qubits: z.number().int().min(1).max(32),
  parameters: z.array(z.object({
    name: z.string(),
    type: z.enum(['int', 'float', 'complex', 'list[int]', 'list[float]', 'list[complex]']),
    default: z.any().optional(),
  })).optional(),
  description: z.string().optional(),
});

export type CreateKernelInput = z.infer<typeof CreateKernelSchema>;

/**
 * Zod schema for quantum gate application
 */
export const ApplyGateSchema = z.object({
  kernel_name: z.string(),
  gate_name: z.string(),
  qubits: z.array(z.number().int().min(0)),
  parameters: z.array(z.number()).optional(),
  controls: z.array(z.number().int().min(0)).optional(),
  adjoint: z.boolean().optional(),
});

export type ApplyGateInput = z.infer<typeof ApplyGateSchema>;

/**
 * Zod schema for quantum execution
 */
export const ExecuteKernelSchema = z.object({
  kernel_name: z.string(),
  operation: z.enum(['sample', 'observe', 'state', 'run']),
  shots: z.number().int().min(1).max(100000).optional(),
  parameters: z.record(z.any()).optional(),
  hamiltonian: z.array(z.object({
    paulis: z.array(z.enum(['I', 'X', 'Y', 'Z'])),
    qubits: z.array(z.number().int().min(0)),
    coefficient: z.object({
      real: z.number(),
      imag: z.number(),
    }),
  })).optional(),
  target: z.string().optional(),
});

export type ExecuteKernelInput = z.infer<typeof ExecuteKernelSchema>;

/**
 * Zod schema for target configuration
 */
export const SetTargetSchema = z.object({
  target: z.string(),
  configuration: z.record(z.any()).optional(),
});

export type SetTargetInput = z.infer<typeof SetTargetSchema>;

// ============================
// Hardware Backend Types
// ============================

/**
 * Available quantum hardware backends
 */
export const QuantumBackends = {
  // Simulators
  'qpp-cpu': 'CPU State Vector Simulator',
  'qpp-gpu': 'GPU State Vector Simulator (cuQuantum)', 
  'density-matrix-cpu': 'CPU Density Matrix Simulator',
  'tensor-network': 'Tensor Network Simulator',
  
  // Hardware Providers
  'ionq': 'IonQ Quantum Processors',
  'quantinuum': 'Quantinuum H-Series',
  'quantum_machines': 'Quantum Machines Platform',
  'infleqtion': 'Infleqtion Quantum Processors',
  'iqm': 'IQM Quantum Processors',
  'oqc': 'Oxford Quantum Computing',
  'pasqal': 'Pasqal Neutral Atom Computers',
} as const;

export type QuantumBackend = keyof typeof QuantumBackends;

/**
 * Hardware provider configurations
 */
export interface HardwareProviderConfig {
  provider: QuantumBackend;
  credentials: {
    api_key?: string;
    url?: string;
    username?: string;
    password?: string;
  };
  configuration: {
    device?: string;
    shots?: number;
    optimization_level?: number;
    error_mitigation?: boolean;
  };
}

// ============================
// Python Bridge Types
// ============================

/**
 * Python function call specification
 */
export interface PythonCall {
  module: string;
  function: string;
  args: any[];
  kwargs?: Record<string, any>;
}

/**
 * Python bridge response
 */
export interface PythonResponse {
  success: boolean;
  result?: any;
  error?: string;
  traceback?: string;
}

// ============================
// Utility Types
// ============================

/**
 * Server configuration
 */
export interface ServerConfig {
  port: number;
  host: string;
  python_path: string;
  default_target: QuantumBackend;
  max_qubits: number;
  max_shots: number;
  gpu_enabled: boolean;
  log_level: 'debug' | 'info' | 'warn' | 'error';
}

/**
 * Job status tracking
 */
export interface JobStatus {
  id: string;
  status: 'queued' | 'running' | 'completed' | 'failed';
  created_at: Date;
  started_at?: Date;
  completed_at?: Date;
  error?: string;
}

export default {
  CreateKernelSchema,
  ApplyGateSchema,
  ExecuteKernelSchema,
  SetTargetSchema,
  QuantumBackends,
};