docs/composer.md

# Composer

Build a circuit graphically or in OpenQASM, run it on the real
`dense_evolution.DenseSVSimulator`, and see the real statevector,
probabilities, Q-sphere and circuit diagram — the same engine documented
throughout the [API Reference](api/index.md), not a separate demo.

<link rel="stylesheet" href="../assets/composer/style.css" />

<div id="de-composer-root">
  <section class="toolbar">
    <label>Preset

      <select id="preset-select"></select>

    </label>

    <label>Qubits

      <input id="n-qubits" type="number" min="1" max="20" value="2" />

      <span id="qubits-limit-info" class="hint"></span>

    </label>

    <label>Shots

      <input id="shots" type="number" min="1" max="100000" value="1000" step="100" />

    </label>

    <label>Seed

      <input id="seed" type="number" min="0" value="42" />

    </label>

    <label>Noise model

      <select id="noise-model-select"></select>

    </label>

    <label>Noise p

      <input id="noise-p" type="number" min="0" max="1" step="0.01" value="0" style="width: 4.5rem;" />

    </label>

    <label>Backend

      <select id="backend-select">

        <option value="dense">Dense</option>

        <option value="mps">MPS</option>

      </select>

    </label>

    <button id="run-btn" class="btn btn-primary">▶ Run</button>

    <span id="status" class="status"></span>

  </section>


  <section class="row row-hamiltonian">
    <div class="panel panel-hamiltonian">

      <h3>Materiali (tavola periodica, elementi reali Z=1..54 + Au, Pb)</h3>

      <p class="hint">

        Clicca gli elementi per assemblare la lista simboli della molecola

        custom sotto — stesso effetto di scriverli a mano, solo più

        comodo. Qualsiasi combinazione è accettata; il numero di qubit

        reale che ne risulta decide se questo simulatore riesce a

        gestirla (diagonalizzazione esatta/VQE restano nel range ~12

        qubit — un elemento pesante come il piombo darà un errore onesto

        di "troppi qubit", non un risultato finto).

      </p>

      <div id="element-palette" class="palette element-palette"></div>

      <div class="ham-row">

        <button id="element-clear-btn" class="btn btn-ghost">Svuota simboli</button>

      </div>

    </div>

  </section>


  <section class="row row-hamiltonian">
    <div class="panel panel-hamiltonian">

      <h3>Hamiltonian (real molecular, PennyLane Hartree-Fock)</h3>

      <p class="hint">

        Real fermion-to-qubit Hamiltonians, computed on demand. The whole

        catalog is always listed here (each entry shows the real qubit

        count its Hamiltonian needs) — picking one sets Qubits and loads

        its real Hartree-Fock reference circuit into the editor

        automatically. Or specify any small molecule's own atoms/geometry

        directly below.

      </p>

      <div class="ham-row">

        <label>Mix con (stesso qubit count di sopra)

          <select id="ham-mix-select"><option value="">— nessuno —</option></select>

        </label>

        <label>Peso A

          <input id="ham-mix-weight-a" type="number" value="0.5" step="0.1" style="width: 4rem;" />

        </label>

        <label>Peso B

          <input id="ham-mix-weight-b" type="number" value="0.5" step="0.1" style="width: 4rem;" />

        </label>

        <button id="ham-mix-btn" class="btn btn-ghost">Mescola e calcola stato fondamentale</button>

      </div>

      <div class="ham-row">

        <label>Fermion-to-qubit mapping

          <select id="ham-mapping-select">

            <option value="jordan_wigner">Jordan-Wigner</option>

            <option value="bravyi_kitaev">Bravyi-Kitaev</option>

          </select>

        </label>

        <span class="hint">La mappatura non cambia l'energia (spettro identico) — cambia solo la rappresentazione a qubit dell'Hamiltoniana.</span>

      </div>

      <div class="ham-row">

        <label>Catalog molecule (tutte, con qubit richiesti)

          <select id="ham-catalog-select"><option value="">— caricamento... —</option></select>

        </label>

        <button id="ham-catalog-btn" class="btn btn-ghost">Compute ground state</button>

      </div>

      <div class="ham-row">

        <label>Custom molecule — symbols (comma-separated)

          <input id="ham-symbols" type="text" value="H, H" />

        </label>

        <label>Geometry (Å, one atom per line: x,y,z)

          <textarea id="ham-geometry" class="code ham-geometry" spellcheck="false">0.0, 0.0, 0.0

0.0, 0.0, 0.7414</textarea>

        </label>

        <label>Charge

          <input id="ham-charge" type="number" value="0" style="width: 4rem;" />

        </label>

        <button id="ham-custom-btn" class="btn btn-ghost">Compute ground state</button>

      </div>

      <div class="ham-row">

        <label>Genera geometria — forma

          <select id="geom-shape-select">

            <option value="linear">Lineare (catena)</option>

            <option value="triangular">Triangolare (3 atomi, D3h)</option>

            <option value="ring">Anello (poligono regolare)</option>

          </select>

        </label>

        <label>Lunghezza legame (Å)

          <input id="geom-bond-length" type="number" value="1.0" step="0.01" style="width: 5rem;" />

        </label>

        <button id="geom-generate-btn" class="btn btn-ghost">Genera geometria</button>

        <button id="custom-load-circuit-btn" class="btn btn-ghost">Carica circuito HF (custom)</button>

      </div>

      <div id="ham-result" class="ham-result"></div>

    </div>

  </section>


  <section class="row row-hamiltonian">
    <div class="panel panel-hamiltonian">

      <h3>Scan energia — curva vs lunghezza di legame (diagonalizzazione esatta)</h3>

      <p class="hint">

        Ricalcola l'energia di stato fondamentale della molecola custom (i

        simboli inseriti sopra) a più lunghezze di legame in una sola

        richiesta — utile per vedere una curva di dissociazione senza

        rifare "Compute ground state" a mano punto per punto. Ogni punto è

        una diagonalizzazione esatta reale, non un'interpolazione; la forma

        è la stessa usata da "Genera geometria" sopra (lineare, triangolare

        o ad anello), riscalata alla lunghezza di legame di ciascun punto.

      </p>

      <div class="ham-row">

        <label>Forma

          <select id="scan-shape-select">

            <option value="linear">Lineare (catena)</option>

            <option value="triangular">Triangolare (3 atomi, D3h)</option>

            <option value="ring">Anello (poligono regolare)</option>

          </select>

        </label>

        <label>Legame da (Å)

          <input id="scan-bond-from" type="number" value="0.4" step="0.01" style="width: 5rem;" />

        </label>

        <label>Legame a (Å)

          <input id="scan-bond-to" type="number" value="3.0" step="0.01" style="width: 5rem;" />

        </label>

        <label>Punti

          <input id="scan-points" type="number" min="2" max="30" value="9" style="width: 4rem;" />

        </label>

        <button id="scan-btn" class="btn btn-ghost">Calcola curva</button>

      </div>

      <div id="scan-result" class="ham-result"></div>

    </div>

  </section>


  <section class="row row-hamiltonian">
    <div class="panel panel-hamiltonian">

      <h3>VQE — ansatz variazionale reale (dense_evolution.vqe)</h3>

      <p class="hint">

        Genera e ottimizza un vero circuito VQE per la molecola scelta sopra

        (catalogo o custom), parametri trovati da un vero Adam gradient

        descent (differenziazione adjoint, dense_evolution.vqe.run_vqe) —

        nessun angolo fisso, ogni esecuzione riottimizza da capo. Due

        ansatz reali disponibili: <strong>Hardware-efficient</strong>

        (template generico N layer RY+CNOT, tanti parametri, veloce per

        iterazione) o <strong>UCCSD</strong> (eccitazioni fermioniche

        singole/doppie reali della molecola, qml.qchem.excitations — pochi

        parametri, converge in meno iterazioni, ma ogni iterazione è molto

        più pesante perché il circuito decomposto è molto più profondo:

        per LiH/H2O conta minuti, non secondi, per iterazione). Il

        circuito risultante (tradotto in vero OpenQASM dalla decomposizione

        esatta di PennyLane, verificato bit-per-bit contro l'esecuzione su

        dense_evolution) viene caricato nell'editor principale e aggiunto

        alla libreria preset qui sopra.

      </p>

      <div class="ham-row">

        <label>Molecola (catalogo, riusa la selezione sopra) o custom (simboli/geometria sopra)

          <select id="vqe-source-select">

            <option value="catalog">Usa selezione catalogo</option>

            <option value="custom">Usa molecola custom</option>

          </select>

        </label>

        <label>Ansatz

          <select id="vqe-ansatz-select">

            <option value="hardware_efficient">Hardware-efficient</option>

            <option value="uccsd">UCCSD (eccitazioni fermioniche reali)</option>

          </select>

        </label>

        <label>Layer ansatz (solo hardware-efficient)

          <input id="vqe-layers" type="number" min="1" max="20" value="8" style="width: 4rem;" />

        </label>

        <label>Iterazioni Adam (epoche)

          <input id="vqe-maxiter" type="number" min="10" max="1000" value="200" style="width: 5rem;" />

        </label>

      </div>

      <div class="ham-row">

        <label>Adam — Learning rate

          <input id="vqe-step-size" type="number" min="0.0001" max="1" step="0.0001" value="0.1" style="width: 6rem;" />

        </label>

        <label>Adam — beta1

          <input id="vqe-beta1" type="number" min="0" max="0.999" step="0.001" value="0.9" style="width: 5.5rem;" />

        </label>

        <label>Adam — beta2

          <input id="vqe-beta2" type="number" min="0" max="0.9999" step="0.0001" value="0.999" style="width: 6rem;" />

        </label>

        <button id="vqe-btn" class="btn btn-ghost">Genera circuito VQE</button>

      </div>

      <div id="vqe-result" class="ham-result"></div>

    </div>

  </section>


  <section class="row row-hamiltonian">
    <div class="panel panel-hamiltonian">

      <h3>Forze &amp; MD — Hellmann-Feynman reale (dashboard_core.qmmm)</h3>

      <p class="hint">

        Forze nucleari reali sulla molecola scelta sopra:

        F = -d&lt;&psi;|H(R)|&psi;&gt;/dR, con H(R) l'Hamiltoniana

        molecolare reale e differenziabile di PennyLane (metodo "dhf") e

        &psi; lo stato elettronico tenuto fisso (teorema di

        Hellmann-Feynman esatto, non differenze finite). La traiettoria

        MD integra queste forze reali con Velocity-Verlet classico

        (masse atomiche reali, costante di conversione derivata dalle

        costanti CODATA) — "Ricalcola stato elettronico" risolve un vero

        Hartree-Fock ad ogni passo (MD ab-initio vero, molto più

        costoso) invece di tenere fisso lo stato iniziale (approssimazione

        reale e dichiarata, valida vicino alla geometria di partenza).

      </p>

      <div class="ham-row">

        <button id="qmmm-forces-btn" class="btn btn-ghost">Calcola forze (stato attuale)</button>

        <label>Passi MD

          <input id="md-steps" type="number" min="1" max="200" value="20" style="width: 4.5rem;" />

        </label>

        <label>dt (fs)

          <input id="md-dt" type="number" min="0.01" max="5" step="0.01" value="0.5" style="width: 4.5rem;" />

        </label>

        <label>

          <input id="md-recompute" type="checkbox" style="width: auto;" />

          Ricalcola stato elettronico ad ogni passo (ab-initio vero, lento)

        </label>

        <button id="md-trajectory-btn" class="btn btn-ghost">Esegui traiettoria MD</button>

      </div>

      <div id="qmmm-result" class="ham-result"></div>

    </div>

  </section>


  <section class="row row-top">
    <div class="panel panel-palette">

      <h3>Operations</h3>

      <div id="palette" class="palette"></div>

    </div>


    <div class="panel panel-canvas">

      <div class="panel-head">

        <h3>Circuit</h3>

        <button id="clear-btn" class="btn btn-ghost">Clear grid</button>

      </div>

      <div id="grid" class="grid"></div>

    </div>


    <div class="panel panel-code">

      <h3>OpenQASM 2.0</h3>

      <textarea id="qasm" class="code" spellcheck="false"></textarea>

    </div>

  </section>


  <section class="row row-bottom">
    <div class="panel panel-probabilities">

      <h3>Probabilities</h3>

      <img id="histogram-img" class="figure" alt="Probabilities histogram" />

      <div id="histogram-skip-msg" class="hint"></div>

    </div>

    <div class="panel panel-qsphere">

      <h3>Q-sphere</h3>

      <img id="qsphere-img" class="figure" alt="Q-sphere" />

      <div id="qsphere-skip-msg" class="hint"></div>

    </div>

    <div class="panel panel-bloch">

      <h3>Bloch spheres</h3>

      <img id="bloch-img" class="figure" alt="Bloch spheres" />

      <div id="bloch-skip-msg" class="hint"></div>

    </div>

  </section>


  <section class="row row-extra">
    <div class="panel panel-circuit-diagram">

      <h3>Circuit diagram</h3>

      <img id="circuit-img" class="figure" alt="Circuit diagram" />

    </div>

    <div class="panel panel-statevector">

      <h3>Statevector</h3>

      <div id="backend-info" class="hint"></div>

      <div id="fidelity-info" class="hint"></div>

      <table id="statevector-table" class="sv-table">

        <thead><tr><th>state</th><th>re</th><th>im</th><th>|amp|</th><th>phase</th></tr></thead>

        <tbody></tbody>

      </table>

    </div>

  </section>


  <section class="row row-mitigation">
    <div class="panel panel-mitigation">

      <h3>Mitigation — Zero-Noise Extrapolation (real, dense_evolution.zero_noise_extrapolation)</h3>

      <p class="hint">

        Measures a Pauli expectation value on the ideal state and on the

        real noise channel above (each an ensemble average over many

        stochastic Kraus draws), then extrapolates back to zero noise.

        Richardson: exact interpolation through 1×/2×/3× "Noise p".

        Polynomial (degree 2): least-squares fit through 1×..5×, trades a

        little interpolation bias for averaging down statistical noise

        across more scales. Pauli string uses dense_evolution's own qubit

        ordering (position 0 = qubit 0), length must match the circuit's

        qubit count.

      </p>

      <div class="ham-row">

        <label>Pauli string (e.g. ZZ)

          <input id="zne-pauli" type="text" value="ZZ" style="width: 6rem;" />

        </label>

        <label>Extrapolation

          <select id="zne-method-select">

            <option value="richardson">Richardson (3 scale, esatta)</option>

            <option value="polynomial">Polynomial deg. 2 (5 scale, fit)</option>

          </select>

        </label>

        <button id="zne-btn" class="btn btn-ghost">Run ZNE</button>

      </div>

      <div id="zne-result" class="ham-result"></div>

    </div>

  </section>


  <section class="row row-mitigation">
    <div class="panel panel-mitigation">

      <h3>Mitigation — density-matrix ZNE (real, dense_evolution.zne_density_matrix)</h3>

      <p class="hint">

        Builds a real Monte-Carlo density-matrix estimate at 1×/2×/3× the

        "Noise p" above, extrapolates to zero noise, and projects onto the

        nearest physical (positive-semidefinite) state

        (Smolin–Gambetta–Smith). Graded — never fed back in — against the

        true ideal state via real Uhlmann fidelity, so the improvement

        shown is an honest measurement, not a guaranteed number.

      </p>

      <div class="ham-row">

        <button id="zne-matrix-btn" class="btn btn-ghost">Run density-matrix ZNE</button>

      </div>

      <div id="zne-matrix-result" class="ham-result"></div>

    </div>

  </section>

</div>


<script src="../assets/composer/app.js"></script>

!!! note "Runs on your own machine, not a shared server"
    This page is static — every circuit runs on a real local kernel

    (`dense_evolution`'s own `DenseSVSimulator`, driven by `local_site/app/server.py`)

    that you run on your own PC. Nothing here is precomputed or mocked, and

    nothing you run is sent anywhere else. Grab the installer for your OS

    and run it yourself (no site can install or launch anything on your

    machine on its own) — it walks you through what it's about to do

    (install the package, optionally download an offline copy of this

    page, optionally add Desktop/Start Menu/startup shortcuts) before

    doing any of it:

    [Windows (.bat)](assets/installer/install-composer.bat){ download }

    &middot;

    [macOS / Linux (.sh)](assets/installer/install-composer.sh){ download }

    — or by hand: `pip install dense-evolution[composer]` then

    `dense-evolution serve`. Either way, reload this page once it's

    running — the banner above turns green the moment it detects your

    kernel. To remove everything the installer created, run

    [uninstall-composer.bat](assets/installer/uninstall-composer.bat){ download }

    or

    [uninstall-composer.sh](assets/installer/uninstall-composer.sh){ download }.