Qiskit Code Assistant MCP Server

List all models currently loaded in memory. Args: filter_type: Optional filter by env_type or model name prefix Returns: Dict with list of loaded models.

Create a PermutationGym environment for learning qubit routing with SWAP gates. Use this to create an RL environment that learns to implement arbitrary qubit permutations using minimal SWAP gates on constrained coupling maps. Args: coupling_map: Custom coupling map as list of [qubit1, qubit2] edges. Example: [[0,1], [1,2], [2,3]] for a linear chain. preset: Hardware preset name (use instead of coupling_map). Options: "ibm_heron_r1", "ibm_heron_r2", "ibm_nighthawk", "grid_3x3", "grid_5x5", "linear_5", "linear_10" Returns: Dict with env_id, env_type, num_qubits, action_space_size on success. Note: Either coupling_map OR preset must be provided, not both.

Create a LinearFunctionGym environment for learning CNOT synthesis. The environment learns to decompose linear Boolean functions into efficient quantum circuits using CNOT gates. Args: coupling_map: Custom coupling map as list of [qubit1, qubit2] edges. preset: Hardware preset name (e.g., "ibm_nighthawk", "grid_3x3") basis_gates: Optional list of basis gates (default: ["cx"]) Returns: Dict with env_id, environment info on success.

Create a CliffordGym environment for learning Clifford circuit synthesis. The environment learns to synthesize optimal implementations of Clifford group elements using a customizable gate set. Args: num_qubits: Number of qubits for the environment coupling_map: Custom coupling map (optional) preset: Hardware preset name (optional) gateset: Custom gate set. Can be: - List of gate names: ["H", "S", "CX"] (applied to all qubits/edges) - List of dicts: [{"gate": "H", "qubits": [0]}, {"gate": "CX", "qubits": [0, 1]}] Returns: Dict with env_id, environment info on success.

List all active RL environments. Returns: Dict with list of environments and their info.

Get detailed information about a specific environment. Args: env_id: Environment ID Returns: Dict with environment details.

Delete an environment. Args: env_id: Environment ID to delete Returns: Dict with deletion status.

Start training an RL agent on a created environment. This initiates training that learns to synthesize optimal circuits. Args: env_id: Environment ID from create_*_env_tool algorithm: RL algorithm to use: - "ppo": Proximal Policy Optimization (recommended, faster) - "alphazero": AlphaZero-style MCTS (better for complex problems) policy: Neural network policy architecture: - "basic": Simple feedforward network (faster, good for small problems) - "conv1d": 1D convolutional network (better for larger problems) num_iterations: Number of training iterations. Default: 100 tensorboard_experiment: Name for TensorBoard logging (optional) background: If True, run training in background and return immediately. Use get_training_status_tool to poll progress, or wait_for_training_tool to block until done. Default: False (synchronous). Returns: If background=False: Dict with session_id, model_id, training metrics. If background=True: Dict with session_id for polling. Use wait_for_training_tool or get_training_status_tool to check progress. Note: For long training runs (>100 iterations), set background=True to avoid timeouts, then use wait_for_training_tool to get results.

Train multiple environments in sequence. Useful for training models across multiple topologies or subtopologies extracted from hardware. Args: env_ids: List of environment IDs to train algorithm: RL algorithm to use policy: Neural network policy architecture num_iterations: Number of iterations per environment tensorboard_prefix: Prefix for TensorBoard experiment names background: If True, start all training in background and return immediately. Use get_training_status_tool or wait_for_training_tool to monitor. Returns: If background=False: Dict with results for each environment. If background=True: Dict with session_ids for polling progress. Note: For batch training with many environments, set background=True to avoid timeouts. Training sessions run in parallel background threads.

Get the status and metrics of a training session. Args: session_id: Training session ID Returns: Dict with session status, progress, and metrics.

Get detailed training metrics from TensorBoard logs. Returns the progression of difficulty, success rate, and reward throughout training. Use this after training completes to understand how well the model trained and what difficulty level it reached. Args: session_id: Training session ID Returns: Dict with: - metrics: Full progression data (difficulty, success, reward by step) - final_difficulty: The highest difficulty level reached - final_success: The final success rate achieved - final_success_percent: Success rate as percentage string Example: After training completes with session_id, call this to see: - Did it reach high difficulty levels? (good generalization) - Is success rate near 100%? (reliable synthesis)

Wait for a background training session to complete. Blocks until training completes, fails, or times out. Use this after starting training with background=True. Args: session_id: Training session ID to wait for timeout: Maximum time to wait in seconds (default: 600 = 10 minutes) Returns: Dict with final training status. If completed, includes model_id for synthesis. Example workflow: 1. start_training_tool(env_id, background=True) -> session_id 2. wait_for_training_tool(session_id) -> model_id 3. synthesize_*_tool(model_id, ...) -> circuit

Stop a training session. Args: session_id: Training session ID to stop Returns: Dict with stop status.

List all training sessions. Returns: Dict with list of training sessions.

List available TensorBoard experiments from past training runs. Returns a list of experiment names that can be used with get_tensorboard_metrics_tool to view historical training metrics. Returns: Dict with list of experiment names (newest first).

Get training metrics from TensorBoard logs for historical runs. Use this to read metrics from past training runs that are no longer in the active session list. Use list_tensorboard_experiments_tool to see available experiments. Args: experiment_name: Name of the TensorBoard experiment (e.g., "linear_function_train_0001_abc123"). tensorboard_path: Direct path to TensorBoard logs (alternative to name). Returns: Dict with metrics progression (difficulty, success, reward by step) and final values. Example: 1. list_tensorboard_experiments_tool() -> see available experiments 2. get_tensorboard_metrics_tool(experiment_name="linear_function_...") -> metrics

Start TensorBoard to visualize training metrics. Launches TensorBoard as a background process using the configured QISKIT_GYM_TENSORBOARD_DIR as the log directory. Args: port: The port to run TensorBoard on (default: 6006) Returns: Dict with status and TensorBoard URL on success. Note: Use stop_tensorboard_tool to stop the TensorBoard process when done.

Stop the running TensorBoard process. Terminates the TensorBoard process that was started with start_tensorboard_tool. Returns: Dict with status message indicating whether TensorBoard was stopped.

Check the status of the TensorBoard process. Returns whether TensorBoard is running and on which port. Returns: Dict with running status, port, and URL if running.

Synthesize an optimal quantum circuit for a qubit permutation. Uses a trained PermutationGym model to find an optimal SWAP gate sequence that implements the desired qubit permutation on the coupling map. Args: model_id: ID of a loaded PermutationGym model permutation: Target permutation as list of qubit indices. Example: [2, 0, 1] means qubit 0 -> position 2, qubit 1 -> position 0 num_searches: Number of search attempts. Higher = better results. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), depth, gate counts, etc.

Synthesize an optimal quantum circuit for a linear Boolean function. Uses a trained LinearFunctionGym model to find an optimal CNOT circuit. Args: model_id: ID of a loaded LinearFunctionGym model linear_function: NxN binary matrix representing the linear function. Entry [i][j]=1 means output i depends on input j (XOR). num_searches: Number of search attempts. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), metrics on success.

Synthesize an optimal quantum circuit for a Clifford operation. Uses a trained CliffordGym model to find an optimal Clifford implementation. Args: model_id: ID of a loaded CliffordGym model clifford_tableau: Clifford tableau in standard (2N+1 x 2N) format, or dict with "destab" and "stab" matrices. num_searches: Number of search attempts. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), metrics on success.

Save a trained model to disk. Save by session_id (from just-completed training) or model_id (loaded model). Args: session_id: Training session ID (from start_training result) model_id: Model ID (alternative to session_id) model_name: Name to save as (defaults to auto-generated) Returns: Dict with save status and file paths.

Load a saved model from disk. Args: model_name: Name of the model to load Returns: Dict with model_id and model info.

List all models saved to disk. Returns: Dict with list of saved models.

Delete a model. Args: model_name: Name of the model to delete delete_files: If True, also delete saved files from disk Returns: Dict with deletion status.

Get detailed information about a model. Args: model_id: Model ID (for loaded models) model_name: Model name (can also check saved models on disk) Returns: Dict with model details.

Create a custom coupling map. Args: edges: Custom edges as [[q1, q2], ...] (mutually exclusive with topology) topology: Topology type ("grid", "line") (mutually exclusive with edges) num_qubits: Number of qubits (for line topology) rows: Number of rows (for grid topology) cols: Number of columns (for grid topology) bidirectional: Whether edges are bidirectional (default: True) Returns: Dict with coupling map info and edges.

Extract connected subtopologies of N qubits from a hardware preset. Use this to find all unique connected subgraphs of a specified size from a larger coupling map. Essential for training RL models on subtopologies of real quantum hardware like IBM Nighthawk. Args: preset: Hardware preset name (e.g., "ibm_nighthawk", "ibm_heron_r1") edges: Custom coupling map edges (alternative to preset) num_qubits: Number of qubits for subtopologies (default: 4) max_subtopologies: Maximum number of subtopologies to return (default: 50) Returns: Dict with list of subtopologies, each containing edges and metadata.

List available subtopology shapes for a given hardware and qubit count. Summarizes the types of subtopologies available (line, grid, star, etc.) without returning all edges. Args: preset: Hardware preset name num_qubits: Number of qubits for subtopologies Returns: Dict with shape counts and example subtopologies.

Get the exact coupling map from a fake IBM backend (no credentials needed). Use this to get exact IBM Quantum hardware topologies without needing IBM Quantum credentials. This is the recommended way to get accurate topologies for offline development. Args: backend_name: Backend name (e.g., "ibm_fez", "ibm_brisbane", "ibm_boston", "ibm_sherbrooke"). Use list_available_fake_backends to see all options. Returns: Dict with exact coupling map edges that can be used with create_*_env tools. Example: 1. get_fake_backend_coupling_map_tool("ibm_fez") -> edges 2. create_clifford_env_tool(num_qubits=..., coupling_map=edges)

List all available fake backends for offline topology access. Returns a list of IBM Quantum backends that have fake versions available in qiskit-ibm-runtime. These provide exact coupling maps without needing IBM Quantum credentials. Returns: Dict with list of backends, their qubit counts, and usage instructions.

Generate a random permutation for testing synthesis. Args: num_qubits: Number of qubits Returns: Dict with random permutation.

Generate a random invertible linear function for testing. Args: num_qubits: Number of qubits Returns: Dict with random linear function matrix.

Generate a random Clifford element for testing. Args: num_qubits: Number of qubits Returns: Dict with random Clifford tableau.

Convert a QPY circuit to human-readable QASM3 format. Use this tool to view the contents of a QPY circuit output from synthesis tools (like synthesize_permutation, synthesize_linear_function, synthesize_clifford) in a human-readable OpenQASM 3.0 format. Args: circuit_qpy: Base64-encoded QPY circuit string (from synthesis output) Returns: Dict with 'status' and 'qasm3' (the human-readable circuit string).

Convert a QASM3 (or QASM2) circuit to base64-encoded QPY format. Use this tool to convert human-readable QASM circuits to QPY format, which preserves full circuit fidelity. The QPY output can be used with synthesis tools that may require circuit input. Args: circuit_qasm: OpenQASM 3.0 or 2.0 circuit string Returns: Dict with 'status' and 'circuit_qpy' (base64-encoded QPY string).

Run a quantum circuit using the Qiskit Runtime EstimatorV2 primitive. The Estimator primitive computes expectation values of observables for quantum circuits. This is essential for variational quantum algorithms (VQE, QAOA), quantum chemistry simulations, and any application requiring expectation value estimation. Error Mitigation: This function includes built-in error mitigation techniques enabled by default: - Resilience Levels: Automatic error mitigation strategies - ZNE (Zero Noise Extrapolation): Extrapolates to zero-noise limit Args: circuit: The quantum circuit to execute. Accepts multiple formats: - OpenQASM 3.0 string (recommended): ``` OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; h q[0]; cx q[0], q[1]; ``` - OpenQASM 2.0 string (legacy, auto-detected) - Base64-encoded QPY binary (for tool chaining with transpiler output) The circuit can be parameterized (use parameter_values to bind). observables: Observable(s) to measure expectation values. Accepts: - Single Pauli string: "IIXY" (identity on qubits 0,1; X on 2; Y on 3) - List of Pauli strings: ["IIXY", "ZZII", "XXYY"] - Weighted Hamiltonian as list of (Pauli, coefficient) tuples: [("IIXY", 0.5), ("ZZII", -0.3), ("XXYY", 0.2)] Pauli strings use: I (identity), X, Y, Z for each qubit position. parameter_values: Values for parameterized circuits. If the circuit has parameters (e.g., rotation angles), provide a list of float values in the same order as circuit.parameters. Optional if circuit has no parameters. backend_name: Name of the IBM Quantum backend (e.g., 'ibm_brisbane'). If not provided, uses the least busy operational backend. circuit_format: Format of the circuit input. Options: - "auto" (default): Automatically detect format - "qasm3": OpenQASM 3.0/2.0 text format - "qpy": Base64-encoded QPY binary format optimization_level: Qiskit transpilation optimization level (0-3). Default is 1. Higher levels may produce better circuits but take longer. - 0: No optimization - 1: Light optimization (default, good balance) - 2: Heavy optimization - 3: Highest optimization (slowest) resilience_level: Error mitigation resilience level (0-2). Default is 1. - 0: No error mitigation - 1: Light error mitigation (default, recommended) - 2: Heavy error mitigation (slower but more accurate) zne_mitigation: Enable Zero Noise Extrapolation (ZNE). Default is True. ZNE extrapolates results to the zero-noise limit for better accuracy. zne_noise_factors: Noise amplification factors for ZNE. Default is (1, 1.5, 2). Only used if zne_mitigation is True. Returns: Job submission status including: - job_id: Use with get_job_status_tool to check completion - backend: The backend where the circuit will run - error_mitigation: Summary of enabled error mitigation techniques - message: Status message - note: Information about retrieving results Note: Jobs run asynchronously. Use get_job_status_tool to monitor progress, then get_job_results_tool to retrieve expectation values when complete. Example observables: - Single Z measurement on qubit 0: "Z" - Z on qubits 0 and 1: "ZZ" - Hamiltonian H = 0.5*X₀X₁ - 0.3*Z₀Z₁: [("XX", 0.5), ("ZZ", -0.3)]

Transpile a quantum circuit using Qiskit's preset pass managers. Takes a quantum circuit and transpiles it to match target hardware constraints while optimizing for depth and gate count. IMPORTANT: Optimization level 3 can be very slow for large circuits (100+ qubits or 1000+ gates). Consider using level 2 for faster results with good quality. Args: circuit: Quantum circuit as QASM3 string, base64-encoded QPY, or QASM2 string. Maximum supported: 100 qubits, 10000 gates. For QASM2, set circuit_format="qasm3" (it will auto-detect and parse QASM2). optimization_level: Optimization level (0-3): - 0: No optimization, just maps to basis gates (fastest) - 1: Light optimization (default mapping, simple optimizations) - 2: Medium optimization (noise-adaptive layout) [default, recommended] - 3: Heavy optimization (best results, can be very slow for large circuits) basis_gates: Target basis gates. Can be: - A list of gate names (e.g., ["cx", "id", "rz", "sx", "x"]) - A preset name: "ibm_default", "ibm_eagle", "ibm_heron", "generic_clifford_t", "ion_trap", "superconducting" - None for no basis gate restriction coupling_map: Qubit connectivity. Can be: - A list of [control, target] pairs (e.g., [[0, 1], [1, 2]]) - A topology name: "linear", "ring", "grid", "full" - None for all-to-all connectivity initial_layout: Optional initial qubit layout as list of physical qubit indices. Length must match the number of qubits in the circuit. seed_transpiler: Random seed for reproducibility circuit_format: Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3". When "qasm3" is specified, QASM2 is also accepted as a fallback. Returns: Dictionary with original and transpiled circuit info, and optimization metrics

Analyze a quantum circuit without transpiling it. Provides detailed information about circuit structure, gate counts, and metrics useful for understanding circuit complexity. Args: circuit: Quantum circuit as QASM3 string, base64-encoded QPY, or QASM2 string. circuit_format: Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3". When "qasm3" is specified, QASM2 is also accepted as a fallback. Returns: Dictionary with circuit analysis including gate counts, depth, and categorization

Compare transpilation results across all optimization levels (0-3). Useful for understanding the trade-off between compilation time and circuit quality for a specific circuit. WARNING: This runs transpilation 4 times. For large circuits, this can be slow. Args: circuit: Quantum circuit as QASM3 string, base64-encoded QPY, or QASM2 string. circuit_format: Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3". When "qasm3" is specified, QASM2 is also accepted as a fallback. Returns: Dictionary comparing depth, size, and gate counts across all levels

Load a quantum circuit from an OpenQASM 2.0 or 3.0 string. Parses the QASM input, returns the circuit as base64-encoded QPY along with metadata (qubit count, gate counts, depth) so you can reason about the circuit before deciding what to do next. Args: qasm_string: The OpenQASM source code (2.0 or 3.0) qasm_version: Which parser to use: - "auto" (default): Try QASM 3.0 first, fall back to QASM 2.0 - "3.0": Only use the QASM 3.0 parser - "2.0": Only use the QASM 2.0 parser Returns: Dict with 'status', 'circuit_qpy' (base64-encoded QPY), 'qasm_version_detected', 'num_qubits', 'num_clbits', 'depth', 'size', 'width', 'operation_counts', and 'total_operations'.

Export a Qiskit circuit to OpenQASM format. Converts a base64-encoded QPY circuit to human-readable OpenQASM text. Supports both QASM 3.0 and QASM 2.0 output. Note that some circuits with non-standard gates may not be expressible in QASM 2.0. Args: circuit_qpy: Base64-encoded QPY circuit string (from other tool outputs) qasm_version: Target QASM version: - "3.0" (default): Export as OpenQASM 3.0 - "2.0": Export as OpenQASM 2.0 Returns: Dict with 'status', 'qasm_string', 'qasm_version', 'num_qubits', and 'depth'.

Set up IBM Quantum account with credentials. If token is not provided, will attempt to use QISKIT_IBM_TOKEN environment variable or saved credentials from ~/.qiskit/qiskit-ibm.json

List available IBM Quantum backends.

Find the least busy operational backend.

Get detailed properties of a specific backend. Args: backend_name: Name of the backend (e.g., 'ibm_brisbane') Returns: Backend properties including: - num_qubits: Number of qubits on the backend - simulator: Whether this is a simulator backend - operational: Current operational status - pending_jobs: Number of jobs in the queue - processor_type: Processor family (e.g., 'Eagle r3', 'Heron') - backend_version: Backend software version - basis_gates: Native gates supported (e.g., ['cx', 'id', 'rz', 'sx', 'x']) - coupling_map: Qubit connectivity as list of [control, target] pairs - max_shots: Maximum shots per circuit execution - max_experiments: Maximum circuits per job Note: For time-varying calibration data (T1, T2, gate errors, faulty qubits), use get_backend_calibration_tool instead. For detailed connectivity analysis (adjacency list, bidirectional check) or fake backend support, use get_coupling_map_tool instead.

Delete a saved IBM Quantum account from disk. WARNING: This permanently removes credentials from ~/.qiskit/qiskit-ibm.json. The operation cannot be undone. Use list_saved_accounts_tool() first to verify the account name before deletion. Args: account_name: Name of the saved account to delete (e.g., 'ibm_quantum_platform'). Use list_saved_accounts_tool() to find available names.

Get calibration data for a backend including T1, T2 times and error rates. Args: backend_name: Name of the backend (e.g., 'ibm_brisbane') qubit_indices: Optional list of specific qubit indices to get data for. If not provided, returns data for the first 10 qubits. Returns: Calibration data including: - T1 and T2 coherence times (in microseconds) - Qubit frequency (in GHz) - Readout errors for each qubit - Gate errors for common gates (x, sx, cx, etc.) - faulty_qubits: List of non-operational qubit indices - faulty_gates: List of non-operational gates with affected qubits - Last calibration timestamp Note: For static backend info (processor_type, backend_version, quantum_volume), use get_backend_properties_tool instead.

Get the coupling map (qubit connectivity) for an IBM Quantum backend. Supports both real backends (requires credentials) and fake backends (no credentials). Use 'fake_' prefix for offline testing without IBM Quantum credentials. Args: backend_name: Name of the backend. Examples: - Real backends: 'ibm_brisbane', 'ibm_fez' (requires credentials) - Fake backends: 'fake_brisbane', 'fake_sherbrooke' (no credentials needed) Returns: Coupling map details including: - num_qubits: Total qubit count - edges: List of [control, target] qubit connection pairs - bidirectional: Whether all connections work in both directions - adjacency_list: Neighbor mapping for each qubit (key: qubit index as string) - source: 'fake_backend' if using a fake backend (only present for fake backends) Use cases: - Identify physically connected qubits for circuit optimization - Plan qubit assignments to minimize SWAP gates - Understand backend architecture for advanced optimization - Test circuit routing offline with fake backends Note: For processor type and other backend info, use get_backend_properties_tool.

Find optimal linear qubit chains for quantum experiments. Algorithmically identifies the best qubit chains based on coupling map connectivity and calibration data. Essential for experiments requiring linear qubit arrangements (e.g., variational algorithms, error correction). Args: backend_name: Name of the backend (e.g., 'ibm_brisbane') chain_length: Number of qubits in the chain (default: 5, range: 2-20) num_results: Number of top chains to return (default: 5, max: 20) metric: Scoring metric to optimize: - "two_qubit_error": Minimize sum of CX/ECR gate errors (default) - "readout_error": Minimize sum of measurement errors - "combined": Weighted combination of gate errors, readout, and coherence Returns: Ranked chains with detailed metrics: - chains: List of chain results, each containing: - rank: Position in ranking (1 = best) - qubits: Ordered list of qubit indices in the chain - score: Total score (lower is better) - qubit_details: T1, T2, readout_error for each qubit - edge_errors: Two-qubit gate error for each connection - total_chains_found: Total number of valid chains discovered - faulty_qubits: List of qubit indices excluded from chains Use cases: - Select qubits for variational quantum algorithms (VQE, QAOA) - Plan linear qubit layouts for error correction experiments - Identify high-fidelity qubit paths for state transfer - Optimize qubit selection for 1D physics simulations

Find optimal qubit subgraphs for Quantum Volume experiments. Unlike linear chains, Quantum Volume benefits from densely connected qubit sets where qubits can interact with minimal SWAP operations. This tool finds connected subgraphs and ranks them by connectivity and calibration quality. Args: backend_name: Name of the backend (e.g., 'ibm_brisbane') num_qubits: Number of qubits in the subgraph (default: 5, range: 2-10) num_results: Number of top subgraphs to return (default: 5, max: 20) metric: Scoring metric to optimize: - "qv_optimized": Balanced scoring for QV (connectivity + errors + coherence) - "connectivity": Maximize internal edges and minimize path lengths - "gate_error": Minimize total two-qubit gate errors on internal edges Returns: Ranked subgraphs with detailed metrics: - subgraphs: List of subgraph results, each containing: - rank: Position in ranking (1 = best) - qubits: List of qubit indices in the subgraph (sorted) - score: Total score (lower is better) - internal_edges: Number of edges within the subgraph - connectivity_ratio: internal_edges / max_possible_edges - average_path_length: Mean shortest path between qubit pairs - qubit_details: T1, T2, readout_error for each qubit - edge_errors: Two-qubit gate error for each internal edge - total_subgraphs_found: Total number of connected subgraphs discovered - faulty_qubits: List of qubit indices excluded from subgraphs Use cases: - Select optimal qubits for Quantum Volume experiments - Find densely connected regions for random circuit sampling - Identify high-quality qubit clusters for variational algorithms - Plan qubit allocation for algorithms requiring all-to-all connectivity

List user's recent jobs.

Get status of a specific job.

Get measurement results from a completed quantum job. Retrieves the measurement outcomes (counts) from a job that has finished execution. The job must be in DONE status to retrieve results. Use this tool after a job submitted with run_sampler_tool has completed. First check the job status with get_job_status_tool, then retrieve results when the job status is DONE. Args: job_id: ID of the completed job (returned by run_sampler_tool) Returns: Dictionary containing: - status: "success", "pending", or "error" - job_id: The job ID - job_status: Current status of the job - counts: Dictionary of measurement outcomes and their counts (e.g., {"00": 2048, "11": 2048} for a Bell state) - shots: Total number of shots executed - backend: Name of the backend used - execution_time: Quantum execution time in seconds (if available) - message: Status message Example workflow: 1. Submit job: result = run_sampler_tool(circuit, backend_name) 2. Get job_id from result 3. Check status: status = get_job_status_tool(job_id) 4. When DONE: results = get_job_results_tool(job_id) 5. Analyze counts in results["counts"]

Cancel a specific job.

List all IBM Quantum accounts saved on disk. Returns account information from ~/.qiskit/qiskit-ibm.json including account names and channels. Useful for checking available accounts before initializing the service or before deleting an account. Tokens are masked for security.

Get information about the currently active IBM Quantum account. Returns details about the account being used in the current session, including channel, instance, and name. This is the account used for all quantum operations. Tokens are masked for security.

Get the Cloud Resource Name (CRN) of the currently active instance. Returns the instance identifier determining which quantum backends and resources are accessible. Important for users with access to multiple instances.

List all IBM Quantum instances available to the active account. Returns information about all instances (organizations, projects, or service plans) the user has access to, including CRN, plan type, and name. Each instance provides access to different quantum backends with different quotas.

Get usage statistics and quota information for the active instance. Returns detailed metrics including job counts, quantum runtime consumption, quota limits, and billing period information. Useful for monitoring resource utilization and planning job submissions.

Run a quantum circuit using the Qiskit Runtime SamplerV2 primitive. The Sampler primitive executes quantum circuits and returns measurement outcome samples. This is the primary way to run quantum circuits on IBM Quantum hardware. Error Mitigation (enabled by default): - Dynamical Decoupling: Suppresses decoherence during idle periods - Twirling: Randomizes errors into stochastic noise for better results Args: circuit: The quantum circuit to execute. Accepts multiple formats: - OpenQASM 3.0 string (recommended): ``` OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; c = measure q; ``` - OpenQASM 2.0 string (legacy, auto-detected) - Base64-encoded QPY binary (for tool chaining with transpiler output) Must include measurement operations to produce results. backend_name: Name of the IBM Quantum backend (e.g., 'ibm_brisbane'). If not provided, uses the least busy operational backend. shots: Number of measurement shots (repetitions). Default is 4096. Higher values give more statistical accuracy. circuit_format: Format of the circuit input. Options: - "auto" (default): Automatically detect format - "qasm3": OpenQASM 3.0/2.0 text format - "qpy": Base64-encoded QPY binary format dynamical_decoupling: Enable dynamical decoupling to suppress decoherence during idle periods. Default is True (recommended). dd_sequence: Dynamical decoupling pulse sequence. Options: - "XX": Basic X-X sequence - "XpXm": X+/X- sequence - "XY4": 4-pulse XY sequence (default, most robust) twirling: Enable Pauli twirling on 2-qubit gates to convert coherent errors into stochastic noise. Default is True (recommended). measure_twirling: Enable twirling on measurements for readout error mitigation. Default is True (recommended). Returns: Job submission status including: - job_id: Use with get_job_status_tool to check completion - backend: The backend where the circuit will run - shots: Number of shots requested - error_mitigation: Summary of enabled techniques Note: Jobs run asynchronously. Use get_job_status_tool to monitor progress. Results contain measurement bitstrings and their occurrence counts.

Search across the entire Qiskit documentation for relevant content. Use this as the primary entry point to discover documentation pages. Returns a small set of ranked results, each with a short query-centered snippet plus its title, URL, and section. This keeps the response compact for repeated use inside an agent. To read a page in full, pass a result's URL to get_page_tool. Args: query: Search query string (e.g., 'error mitigation', 'QuantumCircuit', 'transpiler optimization'). More specific queries yield better results. scope: Search scope filter (case-sensitive). Valid values: 'all' — Search everything (default) 'documentation' — Guides and general docs 'api' — API reference pages only 'learning' — Learning resources and tutorials 'tutorials' — Tutorial content only top_k: Maximum number of results to return. Left unset, snippet mode returns up to 5 and full mode returns every match. An explicit value is capped at 10 in snippet mode; full mode honors it as-is. detail: Per-result content level. 'snippet' (default) returns a short excerpt, a trimmed field set, and a small ranked subset; 'full' restores the original behavior — every match by default, each with its full page body as 'text' and all original fields (backwards compatible) — heavier, so prefer get_page_tool for a single page. Returns: Matching documentation entries (id, url, title, pageTitle, module, section, and a snippet) plus 'total_results' (grand total of matches), 'returned_results' (count after the top_k cap), and a 'truncated' flag. Use a result's URL with get_page_tool to fetch the full page content.

Fetch a Qiskit documentation page and return its content as markdown. Accepts any URL from the Qiskit documentation site. Use search_docs_tool first to find the right page, or use URLs from the resource lists. Returns documentation in markdown format with pagination support. Default max_length is 20000 chars. Set max_length=0 for unlimited. Use offset to retrieve subsequent pages when has_more is true. This tool can fetch ANY page in the Qiskit documentation, including: - SDK module API references (e.g., 'api/qiskit/circuit') - Individual class pages (e.g., 'api/qiskit/qiskit.circuit.QuantumCircuit') - Addon documentation (e.g., 'api/qiskit-addon-sqd') - Implementation guides (e.g., 'guides/transpile') - Any other documentation page Args: url: Documentation page URL. Accepts: - Full URL: 'https://quantum.cloud.ibm.com/docs/guides/transpile' - Relative path: 'guides/transpile', 'api/qiskit/circuit' max_length: Maximum characters to return (default: 20000, 0 for unlimited) offset: Character offset for pagination (default: 0) Returns: Page content in markdown format with pagination metadata (has_more, next_offset, total_length), or error with suggestion to use search_docs_tool if the page is not found.

Look up a Qiskit or IBM Quantum error code to get its description and solution. Use this when a user encounters a numeric error code from Qiskit or IBM Quantum services. Returns the error message and suggested fix. Read the qiskit-docs://error-codes resource for error code categories. Error code ranges: 1XXX: Validation, transpilation, backend, authorization, job management 2XXX: Backend configuration, booking, data retrieval 3XXX: Job handling, authentication, analytics 4XXX: Session management and job limits 5XXX: Job timeout and cancellation 6XXX: Shot limits, compiler input, control system 7XXX: Instruction and basis gate compatibility 8XXX: Pulse and channel configuration 9XXX: Hardware loading and internal errors Args: code: 4-digit numeric error code as a string (e.g., '1002', '7001'). Must be exactly 4 digits. Returns: Error code details including message, solution, and link to the error registry. Returns error if code format is invalid or not found.

Route a quantum circuit by inserting SWAP operations for backend compatibility. Use this FIRST before other synthesis tools. Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') optimization_level: 1 (fastest, least optimization) to 3 (slowest, most optimization) layout_mode: 'keep' (respect existing layout), 'improve' (refine initial guess), 'optimize' (best for general circuits) optimization_preferences: What to minimize - 'n_cnots', 'n_gates', 'cnot_layers', 'layers', or 'noise'. Can be a list. local_mode: True runs locally (recommended), False uses remote Qiskit Transpiler Service coupling_map: Optional list of qubit pairs representing the backend topology. If provided, overrides the backend's coupling map. Useful for targeting a specific subset of qubits. circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction

AI-powered synthesis for Linear Function circuits (CX and SWAP gate blocks, up to 9 qubits). Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') replace_only_if_better: If True, only replaces sub-circuits when synthesis improves CNOT count local_mode: True runs locally (recommended), False uses remote Qiskit Transpiler Service circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction

AI-powered synthesis for Clifford circuits (H, S, and CX gate blocks, up to 9 qubits). Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') replace_only_if_better: If True, only replaces sub-circuits when synthesis improves CNOT count local_mode: True runs locally (recommended), False uses remote Qiskit Transpiler Service circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction

AI-powered synthesis for Permutation circuits (SWAP gate blocks, supports 27, 33, and 65 qubit blocks). Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') replace_only_if_better: If True, only replaces sub-circuits when synthesis improves CNOT count local_mode: True runs locally (recommended), False uses remote Qiskit Transpiler Service circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction

AI-powered synthesis for Pauli Network circuits (H, S, SX, CX, RX, RY, RZ gate blocks, up to 6 qubits). Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') replace_only_if_better: If True, only replaces sub-circuits when synthesis improves CNOT count local_mode: True runs locally (recommended), False uses remote Qiskit Transpiler Service circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction

Transpile a circuit using a hybrid pass manager combining Qiskit heuristics with AI-powered passes. This provides end-to-end transpilation that leverages both classical heuristic optimization and AI-based optimization for routing and synthesis in a single unified pipeline. Args: circuit: Input quantum circuit as QASM 3.0 string or base64-encoded QPY backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez') ai_optimization_level: Optimization level (1-3) for AI components. Higher = better results but slower. optimization_level: Optimization level (1-3) for heuristic components. ai_layout_mode: Layout selection strategy: - 'keep': Respect existing layout (for specific qubit requirements) - 'improve': Use prior layout as starting point - 'optimize': Best for general circuits (default) Note: If initial_layout is provided with 'optimize', it automatically converts to 'improve' to leverage the user-provided layout. initial_layout: Optional list of physical qubit indices specifying where to place virtual qubits. For example, [0, 1, 5, 6, 7] maps virtual qubit 0 to physical qubit 0, virtual qubit 1 to physical qubit 1, etc. coupling_map: Optional list of qubit pairs representing the backend topology. If provided, overrides the backend's coupling map. Useful for targeting a specific subset of qubits. circuit_format: Format of the input circuit - 'qasm3' (default) or 'qpy' (base64-encoded QPY for full circuit fidelity) Returns: Dict with: - status: 'success' or 'error' - circuit_qpy: Base64-encoded QPY format (for chaining with other tools) - original_circuit: Metrics dict (num_qubits, depth, size, two_qubit_gates) - optimized_circuit: Metrics dict for the optimized circuit - improvements: Dict with depth_reduction and two_qubit_gate_reduction