Enhance function call handling to support nested functions (#245)

* Enhance function call handling to support nested functions, improving modularity and reusability in QASM programs. Update tests to validate new functionality.

* update changelog

* restructure changelog

Author: TheGupta2012

CHANGELOG.md

@@ -18,7 +18,27 @@ Types of changes:
 - A new discussion template for issues in pyqasm ([#213](https://github.com/qBraid/pyqasm/pull/213))
 - A github workflow for validating `CHANGELOG` updates in a PR ([#214](https://github.com/qBraid/pyqasm/pull/214))
 - Added `unroll` command support in PYQASM CLI with options skipping files, overwriting originals files, and specifying output paths.([#224](https://github.com/qBraid/pyqasm/pull/224))
+- Added `Duration`,`Stretch` type, `Delay` and `Box` support for `OPENQASM3` code in pyqasm. ([#231](https://github.com/qBraid/pyqasm/pull/231))
+  ###### Example:
+  ```qasm
+  OPENQASM 3.0;
+  include "stdgates.inc";
+  qubit[3] q;
+  duration t1 = 200dt;
+  duration t2 = 300ns;
+  stretch s1;
+  delay[t1] q[0];
+  delay[t2] q[1];
+  delay[s1] q[0], q[2];
+  box [t2] {
+    h q[0];
+    cx q[0], q[1];
+    delay[100ns] q[2];
+  }
+  ```
+- Added a new `QasmModule.compare` method to compare two QASM modules, providing a detailed report of differences in gates, qubits, and measurements. This method is useful for comparing two identifying differences in QASM programs, their structure and operations. ([#233](https://github.com/qBraid/pyqasm/pull/233)) 
 - Added `.github/copilot-instructions.md` to the repository to document coding standards and design principles for pyqasm. This file provides detailed guidance on documentation, static typing, formatting, error handling, and adherence to the QASM specification for all code contributions. ([#234](https://github.com/qBraid/pyqasm/pull/234))
+- Added support for custom include statements in `OPENQASM3` code in pyqasm. This allows users to include custom files or libraries in their QASM programs, enhancing modularity and reusability of code. ([#236](https://github.com/qBraid/pyqasm/pull/236))
 - Added support for `Angle`,`extern` and `Complex` type in `OPENQASM3` code in pyqasm. ([#239](https://github.com/qBraid/pyqasm/pull/239))
   ###### Example:
   ```qasm
@@ -43,31 +63,13 @@ Types of changes:
   extern func6(bit[4]) -> bit[4];
   bit[4] be1 = func6(bd);
   ```
-- Added a new `QasmModule.compare` method to compare two QASM modules, providing a detailed report of differences in gates, qubits, and measurements. This method is useful for comparing two identifying differences in QASM programs, their structure and operations. ([#233](https://github.com/qBraid/pyqasm/pull/233)) 
 
 ### Improved / Modified
 - Added `slots=True` parameter to the data classes in `elements.py` to improve memory efficiency ([#218](https://github.com/qBraid/pyqasm/pull/218))
 - Updated the documentation to include core features in the `README` ([#219](https://github.com/qBraid/pyqasm/pull/219))
 - Added support to `device qubit` resgister consolidation.([#222](https://github.com/qBraid/pyqasm/pull/222))
 - Updated the scoping of variables in `QasmVisitor` using a `ScopeManager`. This change is introduced to ensure that the `QasmVisitor` and the `PulseVisitor` can share the same `ScopeManager` instance, allowing for consistent variable scoping across different visitors. No change in the user API is expected. ([#232](https://github.com/qBraid/pyqasm/pull/232))
-- Added `Duration`,`Stretch` type, `Delay` and `Box` support for `OPENQASM3` code in pyqasm. ([#231](https://github.com/qBraid/pyqasm/pull/231))
-  ###### Example:
-  ```qasm
-  OPENQASM 3.0;
-  include "stdgates.inc";
-  qubit[3] q;
-  duration t1 = 200dt;
-  duration t2 = 300ns;
-  stretch s1;
-  delay[t1] q[0];
-  delay[t2] q[1];
-  delay[s1] q[0], q[2];
-  box [t2] {
-    h q[0];
-    cx q[0], q[1];
-    delay[100ns] q[2];
-  }
-  ```
+- Enhance function call handling by adding support for nested functions. This change allows for more complex function definitions and calls, enabling better modularity and reusability of code within QASM programs. ([#245](https://github.com/qBraid/pyqasm/pull/245))
 
 ### Deprecated
 
@@ -78,10 +80,12 @@ Types of changes:
 - Fixed depth calculation for decomposable gates by computing depth of each constituent quantum gate.([#211](https://github.com/qBraid/pyqasm/pull/211))
 - Optimized statement copying in `_visit_function_call` with shallow-copy fallback to deepcopy and added `max_loop_iters` loop‐limit check in for loops.([#223](https://github.com/qBraid/pyqasm/pull/223))
 
+
 ### Dependencies
 - Add `pillow<11.3.0` dependency for test and visualization to avoid CI errors in Linux builds ([#226](https://github.com/qBraid/pyqasm/pull/226))
 - Added `tabulate` to the testing dependencies to support new comparison table tests. ([#216](https://github.com/qBraid/pyqasm/pull/216))
-
+- Update `docutils` requirement from <0.22 to <0.23 ([#241](https://github.com/qBraid/pyqasm/pull/241))
+- Bumps `actions/download-artifact` version from 4 to 5 ([#243](https://github.com/qBraid/pyqasm/pull/243))
 ### Other
 
 ## Past Release Notes

src/pyqasm/subroutines.py

@@ -456,6 +456,7 @@ def process_quantum_arg(  # pylint: disable=too-many-locals
         cls,
         formal_arg,
         actual_arg,
+        actual_qreg_size_map,
         formal_qreg_size_map,
         duplicate_qubit_map,
         qubit_transform_map,
@@ -468,6 +469,7 @@ def process_quantum_arg(  # pylint: disable=too-many-locals
         Args:
             formal_arg (Qasm3Expression): The formal argument in the function signature.
             actual_arg (Qasm3Expression): The actual argument passed to the function.
+            actual_qreg_size_map (dict): The map of actual quantum register sizes.
             formal_qreg_size_map (dict): The map of formal quantum register sizes.
             duplicate_qubit_map (dict): The map of duplicate qubit registers.
             qubit_transform_map (dict): The map of qubit register transformations.
@@ -504,7 +506,9 @@ def process_quantum_arg(  # pylint: disable=too-many-locals
         # we expect that actual arg is qubit type only
         # note that we ONLY check in global scope as
         # we always map the qubit arguments to the global scope
-        if actual_arg_name not in cls.visitor_obj._global_qreg_size_map:
+        actual_arg_var = cls.visitor_obj._scope_manager.get_from_visible_scope(actual_arg_name)
+
+        if actual_arg_var is None or not actual_arg_var.is_qubit:
             # Check if the actual argument is a qubit register
             is_literal = actual_arg_name is None
             arg_desc = (
@@ -522,7 +526,7 @@ def process_quantum_arg(  # pylint: disable=too-many-locals
             )
 
         actual_qids, actual_qubits_size = Qasm3Transformer.get_target_qubits(
-            actual_arg, cls.visitor_obj._global_qreg_size_map, actual_arg_name
+            actual_arg, actual_qreg_size_map, actual_arg_name
         )
 
         if formal_qubit_size != actual_qubits_size:

src/pyqasm/transformer.py

@@ -343,7 +343,8 @@ def get_branch_params(
     def transform_function_qubits(
         cls,
         q_op: QuantumGate | QuantumBarrier | QuantumReset | QuantumPhase,
-        qubit_map: dict[tuple, tuple],
+        qubit_transform_map: dict[tuple, tuple],
+        qubit_sizes: dict[str, int],
     ) -> list[IndexedIdentifier]:
         """Transform the qubits of a function call to the actual qubits.
 
@@ -356,15 +357,17 @@ def transform_function_qubits(
         Returns:
             None
         """
-        expanded_op_qubits = cls.visitor_obj._get_op_bits(q_op)
+        expanded_op_qubits = cls.visitor_obj._get_op_bits(q_op, function_qubit_sizes=qubit_sizes)
 
         transformed_qubits = []
         for qubit in expanded_op_qubits:
             formal_qreg_name = qubit.name.name
             formal_qreg_idx = qubit.indices[0][0].value
 
             # replace the formal qubit with the actual qubit
-            actual_qreg_name, actual_qreg_idx = qubit_map[(formal_qreg_name, formal_qreg_idx)]
+            actual_qreg_name, actual_qreg_idx = qubit_transform_map[
+                (formal_qreg_name, formal_qreg_idx)
+            ]
             transformed_qubits.append(
                 IndexedIdentifier(
                     Identifier(actual_qreg_name),

src/pyqasm/visitor.py

@@ -218,7 +218,10 @@ def _visit_quantum_register(
 
     # pylint: disable-next=too-many-locals,too-many-branches
     def _get_op_bits(
-        self, operation: Any, qubits: bool = True
+        self,
+        operation: Any,
+        qubits: bool = True,
+        function_qubit_sizes: Optional[dict[str, int]] = None,
     ) -> list[qasm3_ast.IndexedIdentifier]:
         """Get the quantum / classical bits for the operation.
 
@@ -258,19 +261,28 @@ def _get_op_bits(
             else:
                 reg_name = bit.name
 
+            max_register_size = 0
             reg_var = self._scope_manager.get_from_visible_scope(reg_name)
             if reg_var is None:
-                err_msg = (
-                    f"Missing {'qubit' if qubits else 'clbit'} register declaration "
-                    f"for '{reg_name}' in {type(operation).__name__}"
-                )
-                raise_qasm3_error(
-                    err_msg,
-                    error_node=operation,
-                    span=operation.span,
-                )
-            assert isinstance(reg_var, Variable)
-            max_register_size = reg_var.base_size
+                if function_qubit_sizes is None:
+                    err_msg = (
+                        f"Missing {'qubit' if qubits else 'clbit'} register declaration "
+                        f"for '{reg_name}' in {type(operation).__name__}"
+                    )
+                    raise_qasm3_error(
+                        err_msg,
+                        error_node=operation,
+                        span=operation.span,
+                    )
+                # we are trying to replace the qubits inside a nested function
+                assert function_qubit_sizes is not None
+                reg_size = function_qubit_sizes.get(reg_name, None)
+                if reg_size is not None:
+                    max_register_size = reg_size
+
+            if reg_var:
+                assert isinstance(reg_var, Variable)
+                max_register_size = reg_var.base_size
 
             if isinstance(bit, qasm3_ast.IndexedIdentifier):
                 if isinstance(bit.indices[0], qasm3_ast.DiscreteSet):
@@ -293,7 +305,7 @@ def _get_op_bits(
             else:
                 bit_ids = list(range(max_register_size))
 
-            if reg_var.is_alias:
+            if reg_var and reg_var.is_alias:
                 original_reg_name, _ = self._alias_qubit_labels[(reg_name, bit_ids[0])]
                 bit_ids = [
                     self._alias_qubit_labels[(reg_name, bit_id)][1]  # gives (original_reg, index)
@@ -596,14 +608,19 @@ def _visit_reset(self, statement: qasm3_ast.QuantumReset) -> list[qasm3_ast.Quan
         """
         logger.debug("Visiting reset statement '%s'", str(statement))
         if len(self._function_qreg_size_map) > 0:  # atleast in SOME function scope
-            # transform qubits to use the global qreg identifiers
-            statement.qubits = (
-                Qasm3Transformer.transform_function_qubits(  # type: ignore[assignment]
-                    statement,
-                    self._function_qreg_transform_map[-1],
+            # since we may have multiple function scopes, we need to transform the qubits
+            # to use the global qreg identifiers
+            for transform_map, size_map in zip(
+                reversed(self._function_qreg_transform_map), reversed(self._function_qreg_size_map)
+            ):
+                statement.qubits = (
+                    Qasm3Transformer.transform_function_qubits(  # type: ignore[assignment]
+                        statement,
+                        transform_map,
+                        size_map,
+                    )
                 )
-            )
-        qubit_ids = self._get_op_bits(statement, True)
+        qubit_ids = self._get_op_bits(statement, qubits=True)
 
         unrolled_resets = []
         for qid in qubit_ids:
@@ -648,17 +665,22 @@ def _visit_barrier(  # pylint: disable=too-many-locals, too-many-branches
         """
         # if barrier is applied to ALL qubits at once, we are fine
         if len(self._function_qreg_size_map) > 0:  # atleast in SOME function scope
-            # transform qubits to use the global qreg identifiers
+            # we have multiple function scopes, so we need to transform the qubits
+            # to use the global qreg identifiers
 
             # since we are changing the qubits to IndexedIdentifiers, we need to supress the
             # error for the type checker
-            barrier.qubits = (
-                Qasm3Transformer.transform_function_qubits(  # type: ignore [assignment]
-                    barrier,
-                    self._function_qreg_transform_map[-1],
+            for transform_map, size_map in zip(
+                reversed(self._function_qreg_transform_map), reversed(self._function_qreg_size_map)
+            ):
+                barrier.qubits = (
+                    Qasm3Transformer.transform_function_qubits(  # type: ignore [assignment]
+                        barrier,
+                        transform_map,
+                        size_map,
+                    )
                 )
-            )
-        barrier_qubits = self._get_op_bits(barrier)
+        barrier_qubits = self._get_op_bits(barrier, qubits=True)
         unrolled_barriers = []
         max_involved_depth = 0
         for qubit in barrier_qubits:
@@ -763,7 +785,7 @@ def _unroll_multiple_target_qubits(
         Returns:
             The list of all targets that the unrolled gate should act on.
         """
-        op_qubits = self._get_op_bits(operation)
+        op_qubits = self._get_op_bits(operation, qubits=True)
         if len(op_qubits) <= 0 or len(op_qubits) % gate_qubit_count != 0:
             raise_qasm3_error(
                 f"Invalid number of qubits {len(op_qubits)} for operation {operation.name.name}",
@@ -981,7 +1003,7 @@ def _visit_custom_gate_operation(
         gate_name: str = operation.name.name
         gate_definition: qasm3_ast.QuantumGateDefinition = self._custom_gates[gate_name]
         op_qubits: list[qasm3_ast.IndexedIdentifier] = self._get_op_bits(
-            operation
+            operation, qubits=True
         )  # type: ignore [assignment]
 
         Qasm3Validator.validate_gate_call(operation, gate_definition, len(op_qubits))
@@ -1223,12 +1245,14 @@ def _visit_generic_gate_operation(  # pylint: disable=too-many-branches, too-man
         ):
             # we are in SOME function scope
             # transform qubits to use the global qreg identifiers
-            operation.qubits = (
-                Qasm3Transformer.transform_function_qubits(  # type: ignore [assignment]
-                    operation,
-                    self._function_qreg_transform_map[-1],
+            for transform_map, size_map in zip(
+                reversed(self._function_qreg_transform_map), reversed(self._function_qreg_size_map)
+            ):
+                operation.qubits = (
+                    Qasm3Transformer.transform_function_qubits(  # type: ignore [assignment]
+                        operation, transform_map, size_map
+                    )
                 )
-            )
 
         operation.qubits = self._get_op_bits(operation, qubits=True)  # type: ignore
 
@@ -2176,6 +2200,11 @@ def _visit_function_call(
         duplicate_qubit_detect_map: dict = {}
         qubit_transform_map: dict = {}  # {(formal arg, idx) : (actual arg, idx)}
         formal_qreg_size_map: dict = {}
+        actual_qreg_size_map: dict = (
+            self._function_qreg_size_map[-1]
+            if self._function_qreg_size_map
+            else self._global_qreg_size_map
+        )
 
         quantum_vars, classical_vars = [], []
         for actual_arg, formal_arg in zip(statement.arguments, subroutine_def.arguments):
@@ -2190,6 +2219,7 @@ def _visit_function_call(
                     Qasm3SubroutineProcessor.process_quantum_arg(
                         formal_arg,
                         actual_arg,
+                        actual_qreg_size_map,
                         formal_qreg_size_map,
                         duplicate_qubit_detect_map,
                         qubit_transform_map,

tests/qasm3/subroutines/test_subroutines.py

@@ -277,31 +277,41 @@ def my_function(qubit a, float[32] b) {
     check_single_qubit_rotation_op(result.unrolled_ast, 2, [0, 0], [3.14, 6.28], "rx")
 
 
-@pytest.mark.skip(reason="Not implemented nested functions yet")
 def test_function_call_from_within_fn():
     """Test that a function call from within another function is correctly converted."""
     qasm_str = """OPENQASM 3.0;
     include "stdgates.inc";
-
-    def my_function(qubit q1) {
+    def my_function(qubit q1, float[32] a) {
         h q1;
+        rx(a) q1;
         return;
     }
 
-    def my_function_2(qubit[2] q2) {
-        my_function(q2[1]);
+    def my_function_2(qubit[2] q2, float[32] param) {
+        my_function(q2[1], param);
         return;
     }
+
+    def my_function_3(qubit[2] q3) {
+        float[32] a = 3.14;
+        my_function_2(q3, a);
+        my_function(q3[1], a);
+        return;
+    }
+
     qubit[2] q;
-    my_function_2(q);
+    float[32] r = 3.14;
+    my_function_2(q, r);
+    my_function_3(q);
     """
 
     result = loads(qasm_str)
     result.unroll()
     assert result.num_clbits == 0
     assert result.num_qubits == 2
 
-    check_single_qubit_gate_op(result.unrolled_ast, 1, [1], "h")
+    check_single_qubit_gate_op(result.unrolled_ast, 3, [1, 1, 1], "h")
+    check_single_qubit_rotation_op(result.unrolled_ast, 3, [1] * 3, [3.14] * 3, "rx")
 
 
 @pytest.mark.skip(reason="Bug: qubit in function scope conflicts with global scope")