From e52f90a1ee47e710818a66dadb9935c9b9b88dfd Mon Sep 17 00:00:00 2001
From: Adrian Mak <damarkian@gmail.com>
Date: Tue, 3 Sep 2024 11:53:08 +0800
Subject: [PATCH] added docstring for qeb and updated doc/api-reference

---
 doc/source/api-reference/ansatz.rst |  3 +++
 src/qibochem/ansatz/qeb.py          | 17 +++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/doc/source/api-reference/ansatz.rst b/doc/source/api-reference/ansatz.rst
index b854440..b123103 100644
--- a/doc/source/api-reference/ansatz.rst
+++ b/doc/source/api-reference/ansatz.rst
@@ -23,6 +23,9 @@ Unitary Coupled Cluster
 
 .. autofunction:: qibochem.ansatz.ucc.ucc_ansatz
 
+.. autofunction:: qibochem.ansatz.qeb.qeb_circuit
+
+
 Basis rotation
 --------------
 
diff --git a/src/qibochem/ansatz/qeb.py b/src/qibochem/ansatz/qeb.py
index 2283633..49e5d44 100644
--- a/src/qibochem/ansatz/qeb.py
+++ b/src/qibochem/ansatz/qeb.py
@@ -3,6 +3,23 @@
 from qibo import Circuit, models, gates
 
 def qeb_circuit(n_qubits, excitation, theta=0.0, trotter_steps=1) -> Circuit:
+    r"""
+    Qubit-excitation-based (QEB) circuit corresponding to the unitary coupled-cluster ansatz for a single excitation
+
+    Supports only Jordan-Wigner encoded circuits
+
+    Ref: arXiv:2210.05771
+
+    Args:
+        n_qubits: Number of qubits in the quantum circuit
+        excitation: Iterable of orbitals involved in the excitation; must have an even number of elements
+            E.g. ``[0, 1, 2, 3]`` represents the excitation of electrons in orbitals ``(0, 1)`` to ``(2, 3)``
+        theta: UCC parameter. Defaults to 0.0
+        trotter_steps: Number of Trotter steps; i.e. number of times this ansatz is applied with ``theta`` = ``theta / trotter_steps``. Default: 1
+
+    Returns:
+        Qibo ``Circuit``: Circuit corresponding to a single UCC excitation
+    """
     
     n_orbitals = len(excitation)
     assert n_orbitals % 2 == 0, f"{excitation} must have an even number of items"