Make some qmod natives great

algorithms/foundational/bernstein_vazirani/bernstein_vazirani.ipynb

@@ -188,7 +188,6 @@
     "    bv_function(SECRET_INT, x)\n",
     "\n",
     "\n",
-    "write_qmod(main, \"bernstein_vazirani\")\n",
     "qprog = synthesize(main)"
    ]
   },
@@ -331,7 +330,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.7"
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,

algorithms/foundational/bernstein_vazirani/bernstein_vazirani.qmod

@@ -1,3 +1,14 @@
+// Bernstein–Vazirani Algorithm for Hidden Bitstring Discovery
+//
+// This example demonstrates the Bernstein–Vazirani (BV) algorithm, a fundamental
+// quantum algorithm that addresses a special case of the hidden-shift problem.
+// The algorithm finds a hidden bitstring `a` encoded in an oracle that implements
+// the function:
+//   f_a(x) = a · x (mod 2)
+// where `a · x` is the bitwise inner product modulo 2, using only a single oracle
+// query. The example below implements the BV algorithm on 5 qubits, where the
+// secret string corresponds to the number 13.
+
 qperm bv_predicate(a: int, const x: qbit[], res: qbit) {
   repeat (i: x.len) {
     if ((floor(a / (2 ** i)) % 2) == 1) {

algorithms/hamiltonian_simulation/hamiltonian_simulation_guide/hamiltonian_simulation_guide.ipynb

@@ -203,7 +203,6 @@
     "    )\n",
     "\n",
     "\n",
-    "write_qmod(main, \"hamiltonian_simulation_guide_trotter\")\n",
     "qprog_trotter = synthesize(main)\n",
     "show(qprog_trotter)"
    ]
@@ -342,7 +341,6 @@
     "    )\n",
     "\n",
     "\n",
-    "write_qmod(main, \"hamiltonian_simulation_guide_qdrift\")\n",
     "qprog_qdrift = synthesize(main)\n",
     "show(qprog_qdrift)"
    ]
@@ -684,7 +682,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,

algorithms/hamiltonian_simulation/hamiltonian_simulation_guide/hamiltonian_simulation_guide_qdrift.qmod

@@ -1,39 +1,46 @@
+// Hamiltonian Simulation using qDRIFT
+
+// This example demonstrates Hamiltonian time evolution using the qDRIFT
+// algorithm, a randomized Hamiltonian simulation method.
+// Given a Hamiltonian H expressed as a sum of Pauli strings, qDRIFT
+// approximates exp(-i * H * t) by randomly sampling terms according to
+// their weights and applying them sequentially.
+// Here, t denotes the total evolution time of the system.
+// The accuracy of the simulation is controlled by the total number of
+// samples applied during the evolution.
+
+// The Hamiltonian to be evolved
+hamiltonian: SparsePauliOp = SparsePauliOp {
+  terms=[
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::Z, index=0 },
+        IndexedPauli { pauli=Pauli::Z, index=1 }
+      ],
+      coefficient=0.3
+    },
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::X, index=0 }
+      ],
+      coefficient=0.7
+    },
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::X, index=1 }
+      ],
+      coefficient=0.2
+    }
+  ],
+  num_qubits=2
+};
+
 qfunc main(output qba: qbit[]) {
   allocate(2, qba);
-  qdrift(SparsePauliOp {
-    terms=[
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::Z,
-            index=0
-          },
-          IndexedPauli {
-            pauli=Pauli::Z,
-            index=1
-          }
-        ],
-        coefficient=0.3
-      },
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::X,
-            index=0
-          }
-        ],
-        coefficient=0.7
-      },
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::X,
-            index=1
-          }
-        ],
-        coefficient=0.2
-      }
-    ],
-    num_qubits=2
-  }, 1, 288, qba);
+  qdrift(
+    hamiltonian,
+    1.0,   // evolution time t
+    288,   // number of samples
+    qba    // quantum variable
+  );
 }

algorithms/hamiltonian_simulation/hamiltonian_simulation_guide/hamiltonian_simulation_guide_trotter.qmod

@@ -1,39 +1,44 @@
+// Hamiltonian Simulation using Suzuki–Trotter Product Formula
+
+// This example demonstrates Hamiltonian time evolution, exp(-i * H * t), using the
+// Suzuki–Trotter (ST) product formula, where the Hamiltonian H is given as a sum of
+// Pauli strings, and t is the evolution time.
+// The ST approximation is characterized by the product-formula order and the number
+// of repetitions (Trotter steps).
+
+// The Hamiltonian to be evolved
+hamiltonian: SparsePauliOp = SparsePauliOp {
+  terms=[
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::Z, index=0 },
+        IndexedPauli { pauli=Pauli::Z, index=1 }
+      ],
+      coefficient=0.3
+    },
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::X, index=0 }
+      ],
+      coefficient=0.7
+    },
+    SparsePauliTerm {
+      paulis=[
+        IndexedPauli { pauli=Pauli::X, index=1 }
+      ],
+      coefficient=0.2
+    }
+  ],
+  num_qubits=2
+};
+
 qfunc main(output qba: qbit[]) {
   allocate(2, qba);
-  suzuki_trotter(SparsePauliOp {
-    terms=[
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::Z,
-            index=0
-          },
-          IndexedPauli {
-            pauli=Pauli::Z,
-            index=1
-          }
-        ],
-        coefficient=0.3
-      },
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::X,
-            index=0
-          }
-        ],
-        coefficient=0.7
-      },
-      SparsePauliTerm {
-        paulis=[
-          IndexedPauli {
-            pauli=Pauli::X,
-            index=1
-          }
-        ],
-        coefficient=0.2
-      }
-    ],
-    num_qubits=2
-  }, 1.0, 1, 10, qba);
+  suzuki_trotter(
+    hamiltonian,
+    1.0,  // evolution time t
+    1,    // product-formula order
+    10,   // number of repetitions (Trotter steps)
+    qba   // quantum variable
+  );
 }

algorithms/qml/quantum_autoencoder/quantum_autoencoder.ipynb

@@ -838,8 +838,6 @@
     "    drop(coded)\n",
     "\n",
     "\n",
-    "write_qmod(main, \"quantum_autoencoder\")\n",
-    "\n",
     "qprog_ae_alt = synthesize(main)\n",
     "show(qprog_ae_alt)"
    ]

algorithms/qml/quantum_autoencoder/quantum_autoencoder.qmod

@@ -1,9 +1,20 @@
+// Quantum Autoencoder (QAE) for Quantum Data Compression
+
+// This example demonstrates the encoder part of a Quantum Autoencoder.
+// The goal is to train a parameterized quantum circuit that compresses
+// information into a smaller subsystem (`coded`) while pushing redundant
+// information into zero-state `trash` qubits.
+
+
+// Define a quantum function that embeds classical data into a quantum state
+// using angle encoding.
 qfunc angle_encoding(exe_params: real[], qbv: qbit[]) {
   repeat (index: exe_params.len) {
     RY(pi * exe_params[index], qbv[index]);
   }
 }
 
+// Define a parameterized (variational) encoder.
 qfunc encoder_ansatz(exe_params: real[], coded: qbit[], trash: qbit[]) {
   x: qbit[];
   within {
@@ -23,6 +34,10 @@ qfunc encoder_ansatz(exe_params: real[], coded: qbit[], trash: qbit[]) {
   }
 }
 
+// The execution parameters are the `input_data` that encodes the classical data
+// and the weights `w` that define the encoder. The model should be trained on a
+// batch of `input_data`, while optimizing the weights such that the `trash`
+// qubits are pushed toward the zero state.
 qfunc main(w: real[10], input_data: real[4], output trash: qbit[2]) {
   coded: qbit[];
   allocate(2, coded);