* Documentation updates

.github/workflows/config/spelling_allowlist.txt

@@ -75,6 +75,7 @@ POSIX
 PSIRT
 Pauli
 Paulis
+Photonics
 PyPI
 Pygments
 QAOA

docs/sphinx/api/languages/python_api.rst

@@ -56,6 +56,18 @@ Program Construction
     :members:
     :special-members: __str__, __call__
 
+
+.. autoclass:: PhotonicsKernel
+
+    .. automethod:: __call__
+
+    .. .. autofunction:: qudit
+    .. .. autofunction:: plus
+    .. .. autofunction:: phase_shift
+    .. .. autofunction:: beam_splitter
+    .. .. autofunction:: mz
+
+
 .. autofunction:: kernel
 
 Kernel Execution
@@ -227,4 +239,16 @@ MPI Submodule
 .. automethod:: cudaq.mpi::all_gather
 .. automethod:: cudaq.mpi::broadcast
 .. automethod:: cudaq.mpi::is_initialized
-.. automethod:: cudaq.mpi::finalize
+.. automethod:: cudaq.mpi::finalize
+
+ORCA Submodule
+=============================
+
+.. automethod:: cudaq.orca::sample
+
+Photonics Submodule
+=============================
+
+.. automethod:: cudaq.photonics::allocate_qudit
+.. automethod:: cudaq.photonics::apply_operation
+.. automethod:: cudaq.photonics::measure

docs/sphinx/examples/python/providers/photonics_tbi.py

@@ -38,9 +38,9 @@ def TBI(parameters: TBIParameters):
             plus(quds[i])
 
     c = 0
-    for ll in loop_lengths:
-        for i in range(n_modes - ll):
-            beam_splitter(quds[i], quds[i + ll], bs_angles[c])
+    for j in loop_lengths:
+        for i in range(n_modes - j):
+            beam_splitter(quds[i], quds[i + j], bs_angles[c])
             phase_shift(quds[i], ps_angles[c])
             c += 1
 

python/cudaq/__init__.py

@@ -40,13 +40,14 @@
         pass
 
 from .display import display_trace
-from .kernel.kernel_decorator import kernel, PyKernelDecorator
-from .kernel.kernel_builder import make_kernel, QuakeValue, PyKernel
+from .handlers import PhotonicsKernel
 from .kernel.ast_bridge import globalAstRegistry, globalKernelRegistry, globalRegisteredOperations
-from .runtime.sample import sample
+from .kernel.kernel_builder import make_kernel, QuakeValue, PyKernel
+from .kernel.kernel_decorator import kernel, PyKernelDecorator
+from .kernel.register_op import register_operation
 from .runtime.observe import observe
+from .runtime.sample import sample
 from .runtime.state import to_cupy
-from .kernel.register_op import register_operation
 
 from .mlir._mlir_libs._quakeDialects import cudaq_runtime
 

python/cudaq/handlers/photonics_kernel.py

@@ -16,18 +16,45 @@
 
 @dataclass
 class PyQudit:
+    """
+    A data structure to represent `qudit` which models a general d-level 
+    quantum system.
+
+    Args:
+        level (int): An integer representing the level of quantum system to 
+            which this qudit belongs to.
+        id (int): An integer representing the unique identifier for this qudit
+            in the system.
+    """
     level: int
     id: int
 
 
 def check_qudit_type(q):
+    """
+    Utility function to check whether the input argument is instance of 
+    `PyQudit` class.
+
+    Raises:
+        Exception: if input argument is not instance of `PyQudit` class.
+    """
     if not isinstance(q, PyQudit):
         raise Exception(
-            "Invalid quantum type. Use qudit (`qudit(level=N)`) or list of qudits."
+            "Invalid quantum type. Use qudit (`qudit(level=N)`) or a list of qudits."
         )
 
 
 def check_args(q: PyQudit | List[PyQudit]):
+    """
+    Utility function to verify the arguments to a photonic quantum operation.
+
+    Args:
+        q: A single instance or a list of objects of `PyQudit` class.
+
+    Raises:
+        RuntimeError: If the qudit level is not set.
+        Exception: If input argument is not instance of `PyQudit` class.
+    """
     if globalQuditLevel is None:
         raise RuntimeError(
             "Qudit level not set. Define a qudit (`qudit(level=N)`) or list of qudits."
@@ -40,7 +67,21 @@ def check_args(q: PyQudit | List[PyQudit]):
         check_qudit_type(q)
 
 
-def qudit(level: int):
+def qudit(level: int) -> PyQudit:
+    """
+    API to define a d-level qudit in a `PhotonicsKernel`. All the qudits within
+    a kernel are of the same level.
+
+    Args:
+        level (int): An integer representing the level of quantum system.
+    
+    Returns:
+        An instance of `PyQudit`.
+    
+    Raises:
+        RuntimeError: If a qudit of level different than one already defined 
+            in the kernel is requested.
+    """
     global globalQuditLevel
 
     if globalQuditLevel is None:
@@ -53,24 +94,73 @@ def qudit(level: int):
 
 
 def plus(qudit: PyQudit):
+    """
+    Apply plus gate on the input qudit. 
+    U|0> -> |1>, U|1> -> |2>, ..., and U|d> -> |0>
+
+    Args: 
+        qudit: An instance of `PyQudit` class.
+    
+    Raises:
+        RuntimeError: If the qudit level is not set.
+        Exception: If input argument is not instance of `PyQudit` class.
+    """
     check_args(qudit)
     cudaq_runtime.photonics.apply_operation('plusGate', [],
                                             [[qudit.level, qudit.id]])
 
 
 def phase_shift(qudit: PyQudit, phi: float):
+    """
+    Apply phase shift gate.
+    TBD
+    
+    Args:
+        qudit: An instance of `PyQudit` class.
+        phi: A floating point number for the angle.
+
+    Raises:
+        RuntimeError: If the qudit level is not set.
+        Exception: If input argument is not instance of `PyQudit` class.
+    """
     check_args(qudit)
     cudaq_runtime.photonics.apply_operation('phaseShiftGate', [phi],
                                             [[qudit.level, qudit.id]])
 
 
 def beam_splitter(q: PyQudit, r: PyQudit, theta: float):
+    """
+    Apply beam splitter gate.
+    TBD
+    
+    Args:
+        q: An instance of `PyQudit` class TBD.
+        r: An instance of `PyQudit` class TBD.
+        theta: A floating point number for the angle.
+    
+    Raises:
+        RuntimeError: If the qudit level is not set.
+        Exception: If input argument is not instance of `PyQudit` class.
+    """
     check_args([q, r])
     cudaq_runtime.photonics.apply_operation('beamSplitterGate', [theta],
                                             [[q.level, q.id], [r.level, r.id]])
 
 
 def mz(qudits: PyQudit | List[PyQudit], register_name=''):
+    """
+    Measure a single qudit or list of qudits.
+
+    Args:
+        qudits: A single instance or a list of objects of `PyQudit` class.
+    
+    Returns:
+        Measurement results.
+    
+    Raises:
+        RuntimeError: If the qudit level is not set.
+        Exception: If input argument is not instance of `PyQudit` class.
+    """
     check_args(qudits)
     if isinstance(qudits, PyQudit):
         return cudaq_runtime.photonics.measure(qudits.level, qudits.id,
@@ -83,6 +173,17 @@ def mz(qudits: PyQudit | List[PyQudit], register_name=''):
 
 
 class PhotonicsKernel(object):
+    """
+    The `PhotonicsKernel` class serves as to process CUDA-Q kernels for the 
+    `photonics` target.
+    The target must be set to `photonics` prior to defining a `PhotonicsKernel`.
+
+    The quantum operations in this kernel apply to qudits defined by 
+    `qudit(level=N)` or a list of qudits. The qudits within a kernel must be of
+    the same level.
+
+    Allowed quantum operations are: `plus`, `phase_shift`, `beam_splitter`, and `mz`.
+    """
 
     def __init__(self, function):
 

python/extension/CUDAQuantumExtension.cpp

@@ -185,7 +185,7 @@ PYBIND11_MODULE(_quakeDialects, m) {
       [](std::size_t &level) {
         return cudaq::get_execution_manager().allocateQudit(level);
       },
-      py::arg("level"));
+      "Allocate a qudit of given level.", py::arg("level"));
   photonicsSubmodule.def(
       "apply_operation",
       [](const std::string &name, std::vector<double> &params,
@@ -197,6 +197,7 @@ PYBIND11_MODULE(_quakeDialects, m) {
         cudaq::get_execution_manager().apply(name, params, {}, targetInfo,
                                              false, cudaq::spin_op());
       },
+      "Apply the input photonics operation on the target qudits.",
       py::arg("name"), py::arg("params"), py::arg("targets"));
   photonicsSubmodule.def(
       "measure",
@@ -206,7 +207,8 @@ PYBIND11_MODULE(_quakeDialects, m) {
         cudaq::get_execution_manager().returnQudit(qudit);
         return res;
       },
-      py::arg("level"), py::arg("qudit"), py::arg("register_name") = "");
+      "Measure the input qudit(s).", py::arg("level"), py::arg("qudit"),
+      py::arg("register_name") = "");
 
   cudaqRuntime.def("cloneModule",
                    [](MlirModule mod) { return wrap(unwrap(mod).clone()); });