Merge branch 'main' into qaoa

Author: roie-d-classiq

.github/scripts/join_qmod_metadata.py

@@ -1,20 +1,39 @@
-#!/usr/bin/env python3
+#! /usr/bin/env python3
 import json
+import logging
 import re
 import sys
 from pathlib import Path
 from typing import List
 
+# Order matters: higher-priority suffixes first
+QMOD_DICT = {".qmod": "native", ".ipynb": "python"}
 
-def _get_qmod_path_for_metadata(metadata_path: Path) -> Path:
-    # Each metadata file has the same name as the qmod file, but with a .json extension,
-    # so we replace the extension with qmod
-    qmod_path = metadata_path.parent / (Path(metadata_path.stem).stem + ".qmod")
-    if not qmod_path.exists():
-        raise RuntimeError(
-            f"Could not find qmod file for metadata file {metadata_path} at {qmod_path}"
-        )
-    return qmod_path
+
+def _get_qmod_path_for_metadata(metadata_path: Path) -> tuple[Path, str] | None:
+    """
+    Locate a .qmod or .ipynb file corresponding to the given metadata file.
+
+    The metadata file is expected to have a .metadata.json suffix (e.g.,
+    "example.metadata.json"). This function strips the .metadata.json suffix
+    to get the base name, then looks for a matching .qmod or .ipynb file in
+    the same directory (e.g., "example.qmod" or "example.ipynb").
+
+    Files are checked in QMOD_DICT order:
+    (.qmod, native),
+    then (.ipynb, python).
+
+    Returns the matched file path and its dialect, or `None` if no match exists.
+    """
+    meta_data_base_name = f"{metadata_path.parent / Path(metadata_path.stem).stem}"
+
+    for suffix, dialect in QMOD_DICT.items():
+        print(f"base name: {meta_data_base_name}{suffix}")
+        if Path(f"{meta_data_base_name}{suffix}").exists():
+            return Path(f"{meta_data_base_name}{suffix}"), dialect
+
+    # it is the libraries responsibility to ensure that each metadata file has a corresponding qmod/ipynb file
+    return None
 
 
 def _is_json(data: str) -> bool:
@@ -29,12 +48,12 @@ def _is_json(data: str) -> bool:
     return True
 
 
-def _get_qmod_type(qmod_path: Path) -> str:
-    data = qmod_path.read_text()
-    if _is_json(data):
-        return "json"
-    else:
-        return "standalone"
+def _enrich_metadata_with_qmod_info(
+    single_metadata: dict, qmod_data: tuple[Path, str], directory: Path
+) -> None:
+    qmod_path, dialect = qmod_data
+    single_metadata["path"] = str(qmod_path.relative_to(directory))
+    single_metadata["qmod_dialect"] = dialect
 
 
 def join_metadata_files(directory: Path, exclude_file: Path) -> List[dict]:
@@ -46,16 +65,12 @@ def join_metadata_files(directory: Path, exclude_file: Path) -> List[dict]:
             continue
         with metadata_path.open() as fobj:
             single_metadata = json.load(fobj)
-        qmod_path = _get_qmod_path_for_metadata(metadata_path)
-        single_metadata["path"] = str(qmod_path.relative_to(directory))
-        if single_metadata.get("qmod_dialect") is None:
-            try:
-                qmod_type = _get_qmod_type(qmod_path)
-            except Exception as exc:
-                raise RuntimeError(
-                    f"Qmod {qmod_path} is not a valid qmod file"
-                ) from exc
-            single_metadata["qmod_dialect"] = qmod_type
+
+        qmod_data = _get_qmod_path_for_metadata(metadata_path)
+        if qmod_data is None:
+            continue
+
+        _enrich_metadata_with_qmod_info(single_metadata, qmod_data, directory)
         metadata.append(single_metadata)
     return metadata
 
@@ -69,6 +84,9 @@ def generate_unified_metadata_file(qmod_directory: str, metadata_filename: str)
 
 
 if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+    )
     qmod_dir_path = sys.argv[1]
     metadata_file = sys.argv[2]
     generate_unified_metadata_file(

.internal/docs/qmod-reference/api-reference/functions/open_library/bit_operations.md

@@ -0,0 +1,16 @@
+---
+search:
+    boost: 2.610
+---
+
+<!-- spell-checker: disable -->
+<!-- prettier-ignore-start -->
+::: classiq.open_library.functions.bit_operations
+    options:
+        show_if_no_docstrings: false
+        members:
+            - cyclic_shift_left
+            - cyclic_shift_right
+            - bitwise_negate
+<!-- prettier-ignore-end -->
+<!-- spell-checker: enable -->

.internal/docs/qmod-reference/api-reference/functions/open_library/modular_arithmetics.md

@@ -0,0 +1,27 @@
+---
+search:
+    boost: 2.610
+---
+
+<!-- spell-checker: disable -->
+<!-- prettier-ignore-start -->
+::: classiq.open_library.functions.modular_arithmetics
+    options:
+        show_if_no_docstrings: false
+        members:
+            - modular_add_inplace
+            - modular_negate_inplace
+            - modular_subtract_inplace
+            - modular_double_inplace
+            - modular_add_constant_inplace
+            - modular_multiply
+            - modular_square
+            - modular_multiply_constant
+            - modular_multiply_constant_inplace
+            - modular_to_montgomery_inplace
+            - modular_montgomery_to_standard_inplace
+            - modular_inverse_inplace
+            - kaliski_iteration
+            - modular_rsub_inplace
+<!-- prettier-ignore-end -->
+<!-- spell-checker: enable -->

.internal/docs/qmod-reference/api-reference/functions/open_library/modular_exponentiation.md

@@ -376,7 +376,7 @@ operation, which is flagged as an error.
         allocate(q2)
         H(
             q2
-        )  # Error - The computation sequence of the local variable 'q2' includes a non-permutation operation
+        )  # Error - The local variable 'q2' cannot be automatically uncomputed because it is mutated by a non-permutation operation.
         CX(q2, q1)
     ```
 
@@ -387,7 +387,7 @@ operation, which is flagged as an error.
       q2: qbit;
       allocate(q1);
       allocate(q2);
-      H(q2); // Error - The computation sequence of the local variable 'q2' includes a non-permutation operation
+      H(q2); // Error - The local variable 'q2' cannot be automatically uncomputed because it is mutated by a non-permutation operation.
       CX(q2, q1);
     }
     ```
@@ -417,7 +417,7 @@ of `x_transform` are declared _non-const_.
         allocate(aux)
         x_transform(
             p, aux
-        )  # Error - The computation sequence of the local variable 'aux' includes an operation which mutates the parameter 'p'
+        )  # Error - The local variable 'aux' cannot be automatically uncomputed because it is mutated by an operation which also mutates the parameter 'p'.
     ```
 
 === "Native"
@@ -432,7 +432,7 @@ of `x_transform` are declared _non-const_.
       aux: qbit;
       allocate(p);
       allocate(aux);
-      x_transform(p, aux); // Error - The computation sequence of the local variable 'aux' includes an operation which mutates the parameter 'p'
+      x_transform(p, aux); // Error - The local variable 'aux' cannot be automatically uncomputed because it is mutated by an operation which also mutates the parameter 'p'.
     }
     ```
 
@@ -455,7 +455,7 @@ the variable `p`.
         allocate(aux)
         CX(
             p, aux
-        )  # Error - The computation sequence of the local variable 'aux' includes a circular dependency with the variable 'p'
+        )  # Error - The local variable 'aux' cannot be automatically uncomputed because it forms a circular dependency with the variable 'p'.
         CX(aux, p)
     ```
 
@@ -466,7 +466,7 @@ the variable `p`.
       aux: qbit;
       allocate(p);
       allocate(aux);
-      CX(p, aux); // Error - The computation sequence of the local variable 'aux' includes a circular dependency with the variable 'p'
+      CX(p, aux); // Error - The local variable 'aux' cannot be automatically uncomputed because it forms a circular dependency with the variable 'p'.
       CX(aux, p);
     }
     ```

.internal/docs/qmod-reference/language-reference/uncomputation.md

@@ -15,6 +15,8 @@
 
 DEFAULT_TIMEOUT_SECONDS: float = 20
 
+ENFORCE_TIMEOUTS: bool = False
+
 
 def main(full_file_paths: Iterable[str]) -> bool:
     return validate_unique_names() and all(map(is_valid_notebook, full_file_paths))
@@ -28,18 +30,22 @@ def is_valid_notebook(file_path: str, automatically_add_timeout: bool = True) ->
     if _does_contain_dash_in_file_name(file_name):
         errors.append(
             "File naming format error:\n"
-            "    Dash (-) is not allowed in file named. please use underscore (_)\n"
+            "    Dash (-) is not allowed in file name. please use underscore (_)\n"
             f"    for example, you may change '{file_path}' to '{file_path.replace('-', '_')}'."
         )
 
     if _does_contain_space_in_file_name(file_name):
         errors.append(
             "File naming format error:\n"
-            "    Space is not allowed in file named. please use underscore (_)\n"
+            "    Space is not allowed in file name. please use underscore (_)\n"
             f"    for example, you may change '{file_path}' to '{file_path.replace(' ', '_')}'."
         )
 
-    if not _is_file_in_timeouts(file_name) and should_notebook_be_tested(file_path):
+    if (
+        ENFORCE_TIMEOUTS
+        and not _is_file_in_timeouts(file_name)
+        and should_notebook_be_tested(file_path)
+    ):
         if automatically_add_timeout:
             _add_file_to_timeouts(file_name)
             errors.append(

.internal/pre_commit_tools/notebook_pre_commit_collection.py

@@ -15,6 +15,8 @@
 
 DEFAULT_TIMEOUT_SECONDS: float = 10
 
+ENFORCE_TIMEOUTS: bool = False
+
 
 def main(full_file_paths: Iterable[str]) -> bool:
     return validate_unique_names() and all(map(is_valid_qmod, full_file_paths))
@@ -32,18 +34,22 @@ def is_valid_qmod(
     if _does_contain_dash_in_file_name(file_name):
         errors.append(
             "File naming format error:\n"
-            "    Dash (-) is not allowed in file named. please use underscore (_)\n"
+            "    Dash (-) is not allowed in file name. please use underscore (_)\n"
             f"    for example, you may change '{file_path}' to '{file_path.replace('-', '_')}'."
         )
 
     if _does_contain_space_in_file_name(file_name):
         errors.append(
             "File naming format error:\n"
-            "    Space is not allowed in file named. please use underscore (_)\n"
+            "    Space is not allowed in file name. please use underscore (_)\n"
             f"    for example, you may change '{file_path}' to '{file_path.replace(' ', '_')}'."
         )
 
-    if not _is_file_in_timeouts(file_name) and should_notebook_be_tested(file_path):
+    if (
+        ENFORCE_TIMEOUTS
+        and not _is_file_in_timeouts(file_name)
+        and should_notebook_be_tested(file_path)
+    ):
         if automatically_add_timeout:
             _add_file_to_timeouts(file_name)
             errors.append(