Dense Evolution

Convert a list of gate operations (as used by the graphical circuit builder) into real OpenQASM text, ready to pass to `dense_evolution_run_circuit`. Args: params (BuildCircuitInput): n_qubits, ops (see dense_evolution_list_gates for valid gate names). Returns: str: JSON {"qasm": "..."} on success, or "Error: ..." if the op list is invalid.

Compute the ground-state energy of an arbitrary molecule (not in the catalog) from its atomic symbols and geometry, via the same Hartree-Fock pipeline as the catalog. Small molecules only -- exact dense diagonalization caps out at 12 qubits, rejected before PennyLane runs if the electron/orbital count would exceed that. Args: params (CustomMoleculeInput): symbols, geometry, charge, mapping. len(symbols) must equal len(geometry). Returns: str: JSON with n_qubits, ground_state_energy_hartree, or "Error: ..." if the molecule needs more than 12 qubits.

Compute the ground-state energy at each of several geometries in one call -- e.g. a bond-length dissociation curve or a bond-angle sweep -- instead of calling dense_evolution_custom_molecule_energy once per point. Points are evaluated concurrently against the kernel. A point that fails (e.g. too many qubits for exact diagonalization) is reported with its own error and does not abort the rest of the scan. Args: params (EnergyScanInput): symbols, geometries (list of points, max 50), charge, mapping, labels (optional, one per point). Returns: str: JSON with: { "n_points": int, "results": [{"label": ..., "n_qubits": int, "ground_state_energy_hartree": float} | {"label": ..., "error": str}, ...], "minimum": {"label": ..., "ground_state_energy_hartree": float} | null # over successful points only }

Check whether the local Dense Evolution Composer kernel is running and reachable. Always call this first if unsure whether the kernel is up -- every other tool in this server depends on it. Returns the kernel's dense_evolution version, hostname, and free/total RAM (useful to sanity-check qubit-count limits before requesting a large simulation). Returns: str: JSON with {status, dense_evolution_version, hostname, total_ram_gb, available_ram_gb, ram_percent_free}, or an "Error: ..." string if the kernel is not running.

List every gate the graphical circuit builder (and therefore `dense_evolution_build_circuit`) supports, with their display metadata. Returns: str: JSON gate palette (name, symbol, qubit arity, etc. per gate).

List every molecule in the built-in Hartree-Fock catalog, each with its real qubit count under the requested mapping. Use this to find valid `name` values for `dense_evolution_molecule_energy`, `_mix_molecules`, `_run_vqe`, `_qmmm_forces`, `_md_trajectory`, and `_energy_scan`. Each entry includes a short `id` (e.g. "H2", "LiH", "HeH+") derived from the catalog's full descriptive name -- pass either form to any tool that takes a molecule `name`; the short id is easier to copy exactly across multiple tool calls than the full "H2 (Idrogeno) - R = 0.7414 A [equilibrio reale]"-style string. Args: params (ListMoleculesInput): mapping -- 'jordan_wigner' (default) or 'bravyi_kitaev'. Returns: str: JSON list of {id, full_name, symbols, geometry, charge, n_qubits} per molecule.

List the real Kraus-channel noise models available for `dense_evolution_run_circuit` and the mitigation tools (e.g. depolarizing, amplitude damping, bit-flip). Returns: str: JSON mapping noise model names to their parameters/description.

List the built-in example OpenQASM circuits bundled with the Composer (e.g. Bell state, GHZ, QFT) -- useful as ready-made input for `dense_evolution_run_circuit` without writing QASM by hand. Returns: str: JSON mapping preset names to their OpenQASM source text.

Run a real Velocity-Verlet MD trajectory driven by Hellmann-Feynman forces at every step, for a catalog molecule. Args: params (MdTrajectoryInput): name (short id or full catalog name), n_steps, dt_fs, mapping, recompute_electronic_state (true = true ab-initio MD, capped at 30 steps; false = fixed electronic state, capped at 200 steps). Returns: str: JSON with the trajectory (positions/energies per step). "Error: ..." if n_steps is out of range for the chosen mode.

Run real density-matrix ZNE: Monte-Carlo density-matrix estimate at 1x/2x/3x noise_p, extrapolated and projected onto the nearest physical state, graded by Uhlmann fidelity against the true ideal state. Args: params (MitigateDensityMatrixInput): qasm, noise_model, noise_p, seed. Returns: str: JSON with n_qubits, noise_factors, fidelity_raw, fidelity_corrected.

Run real Zero-Noise Extrapolation: measure a Pauli expectation value at several noise scales under a real Kraus noise channel, then extrapolate back to zero noise. Args: params (MitigateZneInput): qasm, pauli_string, noise_model, noise_p, seed, extrapolation_method. Returns: str: JSON with n_qubits, ideal_expectation, noise_factors, noisy_expectations, zne_extrapolated, extrapolation_method.

Compute H_mix = weight_a*H_a + weight_b*H_b for two catalog molecules that share the same qubit count (same electron space), and diagonalize all three (H_a, H_b, H_mix) for their ground-state energies. Mixing molecules with different qubit counts is physically meaningless and is rejected with a clear error. Args: params (MixMoleculesInput): name_a, name_b (short id or full catalog name), weight_a, weight_b, mapping. Returns: str: JSON with n_qubits, energy_a, energy_b, energy_mixed (all in Hartree).

Compute the exact ground-state energy of a catalog molecule via real Hartree-Fock + Jordan-Wigner/Bravyi-Kitaev Hamiltonian construction and exact dense diagonalization. Args: params (MoleculeEnergyInput): name (short id or full catalog name), mapping. Returns: str: JSON with n_qubits, symbols, geometry, charge, ground_state_energy_hartree. "Error: ..." with a 404-style message if `name` is not in the catalog (call dense_evolution_list_molecules to see valid names/ids).

Compute real Hellmann-Feynman nuclear forces (F = -d<psi|H(R)|psi>/dR via PennyLane autodiff, not finite differences) on a catalog molecule's real Hartree-Fock ground state. Args: params (QmmmForcesInput): name (short id or full catalog name), mapping. Returns: str: JSON with per-atom force vectors and related energetics.

Run real OpenQASM on dense_evolution's DenseSVSimulator (or the MPS backend for large circuits) and return measurement counts, probabilities, and statevector amplitudes. Above the dense backend's safe qubit ceiling (see dense_evolution_system_limits), automatically switches to an MPS top-k-states approximation instead of failing. Large statevectors/probability arrays are truncated to their most significant entries (see 'shown' vs 'total_*' fields) to keep the response usable in an agent's context -- the full histogram is always returned in 'counts' since it's naturally bounded by `shots`. Args: params (RunCircuitInput): qasm, shots, seed, noise_model, noise_p, backend, include_visualizations (see field descriptions). Returns: str: JSON with n_qubits, backend, counts, truncated probabilities/statevector, fidelity_vs_ideal, and (if include_visualizations) paths to saved PNG files. For circuits above the dense limit on the 'mps' backend, returns a differently-shaped {"large_scale": true, "top_k_states": [...], ...} response.

Run real VQE (Adam gradient descent with adjoint differentiation) against a molecule's Jordan-Wigner Hamiltonian, from a fresh random start every call -- not a cached/precomputed result. Can take a while for 'uccsd' ansatz or high maxiter; consider dense_evolution_health's RAM figures and start with a small maxiter/n_layers to gauge cost first. Args: params (RunVqeInput): either `name` (short id or full catalog name) or `symbols`+`geometry` (custom) must be given, plus ansatz_type, n_layers, maxiter, step_size, beta1, beta2, seed. Returns: str: JSON with the optimized energy, convergence history, and optimized parameters. "Error: ..." if neither name nor symbols+geometry is provided, or the molecule is unknown.

Get the maximum qubit count this machine can currently simulate with a dense statevector, computed from actual free RAM right now (not a fixed constant) -- call before requesting a large `dense_evolution_run_circuit`. Returns: str: JSON describing the current safe qubit ceiling for the dense backend.

Run a real predictive-healing pass over a noisy (n_steps, dim) vector sequence -- e.g. VQE convergence telemetry or an MD trajectory. Per step, a Phi-Trigger (dense_evolution.healing) decides whether the change from a local baseline looks like genuine dynamics (kept as-is) or static noise (replaced by the local median). NaN/Inf entries are sanitized first regardless of that decision. Args: params (VectorHealingInput): vectors, radius_baseline. Returns: str: JSON with healed_vectors, fallback_triggered, adaptive_radius_used, reconstruction_error.

Sweep `t1_values` for the traversable-wormhole-inspired teleportation protocol, running both +mu_magnitude and -mu_magnitude at every point -- one call instead of 2*len(t1_values) separate dense_evolution_wormhole_teleportation calls. Returns each point's mutual information for both signs plus their difference (mu<0 minus mu>0 in this project's own convention), the standard readout for the protocol's qualitative signature: a smooth peak in that difference across the sweep (known peak for seed=61/n_majorana=8/k_terms=10/ t0=0.3: around t1≈0.6-0.7). Unlike dense_evolution_energy_scan, points run sequentially, not concurrently: each single teleportation call does real exact diagonalization (or Trotterized circuit execution) of the full joint L+R+P+Q system and takes several seconds on its own (verified: concurrent calls to this specific endpoint crashed the kernel process outright -- a real BLAS/eigh thread-safety issue under this protocol's heavier-than-usual concurrent linear algebra, not present in the lighter Hamiltonian-diagonalization calls energy_scan batches). A full 20-point sweep can take several minutes; start with fewer points to gauge cost. A point that fails does not abort the rest of the sweep; its error is reported alongside the successful points. Args: params (WormholeScanInput): n_majorana, k_terms, J, mu_magnitude, t0, t1_values (list, max 20 points), seed, with_message, backend, n_steps_evolution, n_steps_coupling. Returns: str: JSON with: { "n_points": int, "results": [{"t1": float, "mu_positive": float, "mu_negative": float, "delta": float} | {"t1": float, "error": str}, ...], "peak": {"t1": ..., "delta": ...} | null # point with the largest delta, successful points only }

Find a binary-sparse-SYK random-instance seed suitable for the traversable-wormhole-inspired teleportation protocol (`dense_evolution_wormhole_teleportation`). A uniformly-random seed does NOT reliably show the protocol's sign-dependent teleportation signal -- verified directly across many seeds (some give a clean peak, some the wrong sign for most of a sweep, some are flat noise). arXiv:2604.10090 didn't use an arbitrary instance either: they picked one "selected for favorable commutation properties" among their chosen terms. This tool reproduces that same selection criterion -- screening `n_candidates` seeds by their exact commuting/anticommuting term-pair count and returning the one closest to `target_commuting` -- rather than trusting a random seed. Always call this before `dense_evolution_wormhole_teleportation` / `dense_evolution_wormhole_scan` unless you already have a known-good seed (e.g. 61, for the defaults n_majorana=8/k_terms=10/target=34, the exact match found and used throughout this project's own verification -- see research/wormhole_syk.md). Args: params (WormholeSelectInstanceInput): n_majorana, k_terms, J, n_candidates, target_commuting. Returns: str: JSON {seed, n_majorana, k_terms, commuting, anticommuting, target_commuting} -- pass `seed` straight into dense_evolution_wormhole_teleportation / _wormhole_scan.

Run one point of the real traversable-wormhole-inspired quantum teleportation protocol (Gao-Jafferis-Wall theory, arXiv:2604.10090) on a binary sparse SYK model: two coupled chaotic Hamiltonians (L,R), a message injected into L via a reference-qubit pair (P,Q), a real bilinear L-R coupling exp(i*mu*V), and a readout that is NOT a single-qubit expectation value (which the no-signaling theorem forbids from ever showing this signal) but the mutual information between the reference qubit P and a qubit read out from R. Returns a single mutual-information value for the given mu -- the physically meaningful result is the *difference* between a positive- and negative-mu run at the same (n_majorana, k_terms, seed, t0, t1). Call this tool twice with opposite-sign mu, or use dense_evolution_wormhole_scan to sweep many (t1, mu) combinations in one batched call. Requires a well-selected seed (see dense_evolution_wormhole_select_instance) -- an arbitrary random seed will likely not show a clean signal. Args: params (WormholeTeleportationInput): n_majorana, k_terms, J, mu, t0, t1, seed, with_message, backend, n_steps_evolution, n_steps_coupling. Returns: str: JSON {mutual_information_pt, backend, n_majorana, k_terms, mu, t0, t1, seed, with_message}.