luna-quantum 1.0.0__cp312-cp312-macosx_11_0_arm64.whl

luna_quantum/util/active_waiting.py

@@ -0,0 +1,79 @@
+import logging
+from collections.abc import Callable
+from time import sleep
+from typing import ClassVar
+
+from luna_quantum.util.log_utils import Logging
+
+
+class ActiveWaiting:
+    """
+    Provides active waiting functionality using a customizable loop.
+
+    The `ActiveWaiting` class offers a static method to perform a loop with
+    a sleep interval that increases iteratively, allowing the user to
+    regularly check a condition and optionally perform an additional action.
+    """
+
+    _logger: ClassVar[logging.Logger] = Logging.get_logger(__name__)
+
+    @staticmethod
+    def run(
+        loop_check: Callable[[], bool],
+        loop_call: Callable[[], None] | None = None,
+        sleep_time_max: float = 60.0,
+        sleep_time_increment: float = 5.0,
+        sleep_time_initial: float = 5.0,
+    ) -> None:
+        """
+        Execute a loop that checks a condition and optionally performs an action.
+
+        This function executes a loop that repeatedly checks a condition using a
+        callback function. If provided, it will also execute another callback after
+        each sleep period. The sleep time increases incrementally up to a maximum
+        value, starting from an initial sleep time.
+
+        Parameters
+        ----------
+        loop_check : Callable[[], bool]
+            A callable function that returns a boolean. The loop will continue as
+            long as this callable returns True.
+        loop_call : Optional[Callable[[], None]]
+            An optional callable function to be executed after each sleep period.
+            Defaults to None.
+        sleep_time_max : float
+            The maximum sleep time between condition checks. Defaults to 60.0 seconds.
+        sleep_time_increment : float
+            The amount of time to increment the sleep period after each iteration.
+            Defaults to 5.0 seconds.
+        sleep_time_initial : float
+            The initial sleep time before the first condition check. Defaults to
+            5.0 seconds. If invalid (< 0.0), it will be adjusted to the default.
+
+        Raises
+        ------
+        ValueError
+            If `sleep_time_initial`, `sleep_time_increment`, or `sleep_time_max` are
+            non-positive values where a positive value is required.
+        """
+        cur_sleep_time: float
+
+        if sleep_time_initial > 0.0:
+            cur_sleep_time = sleep_time_initial
+        else:
+            cur_sleep_time = 5.0
+            ActiveWaiting._logger.warning(
+                f"Invalid sleep_time_initial: {sleep_time_initial},"
+                f" setting it to default value {cur_sleep_time}"
+            )
+
+        while loop_check():
+            ActiveWaiting._logger.info(
+                f"Sleeping for {cur_sleep_time} seconds. "
+                f"Waiting and checking a function in a loop."
+            )
+            sleep(cur_sleep_time)
+            cur_sleep_time += sleep_time_increment
+            cur_sleep_time = min(cur_sleep_time, sleep_time_max)
+            if loop_call:
+                loop_call()

luna_quantum/util/class_patcher.py

@@ -0,0 +1,164 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, Literal, TypeVar
+
+from luna_quantum.exceptions.patch_class_field_exists_error import (
+    PatchClassFieldExistsError,
+)
+
+T = TypeVar("T")  # To represent the return type of the decorated function
+
+
+def add_to_class(
+    class_: type[Any],
+    method_type: Literal["normal", "static", "class", "property"] = "normal",
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Add a function as a method into a specified class.
+
+    The decorator facilitates adding a function to a class as a method. The
+    method can be of type 'normal' (instance method), 'static', 'class', or
+    'property'. The function metadata is preserved during this process.
+
+    Parameters
+    ----------
+    class_ : Type
+        The class to which the function will be added.
+
+    method_type : {"normal", "static", "class", "property"}, optional
+        The type of method to integrate into the class. Defaults to "normal".
+        - "normal": Adds the function as an instance-level method.
+        - "static": Adds the function as a static method.
+        - "class": Adds the function as a class-level method.
+        - "property": Adds the function as a property.
+
+    Returns
+    -------
+    Callable
+        A callable decorator that, when applied to a function, integrates it
+        as the specified method type into the class.
+
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        # Preserve function metadata
+        @wraps(func)
+        def wrapped_func(*args: Any, **kwargs: Any) -> T:
+            return func(*args, **kwargs)
+
+        # Add the function to the class based on the method type
+        if method_type == "static":
+            setattr(class_, func.__name__, staticmethod(func))  # Add as static method
+        elif method_type == "class":
+            setattr(class_, func.__name__, classmethod(func))  # Add as class method
+        elif method_type == "property":
+            setattr(class_, func.__name__, property(func))  # Add as property
+        else:  # Default is normal (instance-level method)
+            setattr(class_, func.__name__, func)
+
+        return wrapped_func
+
+    return decorator
+
+
+def patch_instance(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "normal" method.
+
+    This function acts as a decorator that adds a new method to the given class.
+    The newly added method behaves as a standard instance method, meaning it
+    has access to the instance (`self`) when called.
+
+    Parameters
+    ----------
+        class_: The class to which the method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the method to be added as its argument.
+    """
+    return add_to_class(class_, "normal")
+
+
+def patch_static(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "static" method.
+
+    This function acts as a decorator that adds a new static method to the given class.
+    The newly added static method does not require an instance of the class to be
+    called.
+
+    Parameters
+    ----------
+        class_: The class to which the static method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the static method to be added as its argument.
+    """
+    return add_to_class(class_, "static")
+
+
+def patch_class(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "class" method.
+
+    This function acts as a decorator that adds a new class method to the given class.
+    The newly added method will have access to the class itself (`cls`) when called.
+
+    Parameters
+    ----------
+        class_: The class to which the class method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the class method to be added as its argument.
+    """
+    return add_to_class(class_, "class")
+
+
+def patch_property(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "property" method.
+
+    This function acts as a decorator that adds a new property to the given class.
+    The decorator converts the given method into a readable property.
+
+    Parameters
+    ----------
+        class_: The class to which the property will be added.
+
+    Returns
+    -------
+        A decorator function that takes the method to be added as a property.
+    """
+    return add_to_class(class_, "property")
+
+
+def patch_field_to_class(
+    class_: type[Any],
+    field_name: str,
+    default_value: Any = None,  # noqa: ANN401 we dont know the type in the decorator
+) -> None:
+    """
+    Add a new field to a class.
+
+    This function allows adding a field with a default value to the given class.
+    If the field already exists in the class, a `PatchClassFieldExistsError` is raised.
+
+    Parameters
+    ----------
+        class_: The class to which the field will be added.
+        field_name: The name of the field to be added.
+        default_value: The default value to assign to the field (optional).
+
+    Raises
+    ------
+        PatchClassFieldExistsError
+            If the class already has a field with the given name.
+    """
+    if hasattr(class_, field_name):
+        raise PatchClassFieldExistsError(
+            class_name=class_.__name__, field_name=field_name
+        )
+    setattr(class_, field_name, default_value)

luna_quantum/util/log_utils.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from functools import wraps
+from typing import TYPE_CHECKING, ClassVar, ParamSpec, TypeVar
+
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.progress import Progress, SpinnerColumn, TaskID, TextColumn
+from rich.theme import Theme
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class Logging:
+    """Utilities for configuring and accessing Luna SDK loggers.
+
+    This class provides static methods to:
+    - Set and retrieve the global logging level for SDK components
+    - Create and configure loggers with Rich formatting
+    - Manage consistent logging behavior across the SDK
+    """
+
+    _log_level: ClassVar[int] = logging.INFO
+
+    @staticmethod
+    def set_level(log_level: int) -> None:
+        """Set the logging level for all SDK loggers.
+
+        Parameters
+        ----------
+        log_level : int
+            Logging level to set (e.g., logging.DEBUG, logging.INFO)
+        """
+        for logger_name in logging.root.manager.loggerDict:
+            if logger_name.startswith("luna_quantum"):  # Only modify SDK loggers
+                logging.getLogger(logger_name).setLevel(log_level)
+
+        Logging._log_level = log_level
+
+    @staticmethod
+    def get_level() -> int:
+        """Return the current logging level for the SDK.
+
+        Returns
+        -------
+        int
+            Current logging level as defined in the logging module
+            (e.g., logging.DEBUG, logging.INFO, etc.)
+        """
+        return Logging._log_level
+
+    @staticmethod
+    def get_logger(name: str) -> logging.Logger:
+        """Get a logger with the specified name and set up a RichHandler for it.
+
+        Parameters
+        ----------
+        name : str
+            Name of the logger to retrieve or create
+
+        Returns
+        -------
+        logging.Logger
+            Configured logger instance with appropriate handlers
+        """
+        logger = logging.getLogger(name)
+        logger.setLevel(Logging._log_level)
+        logger.propagate = False
+
+        if logger.hasHandlers():
+            return logger
+
+        custom_theme = Theme(
+            {
+                "logging.level.debug": "bright_blue",
+                "logging.level.info": "bright_green",
+                "logging.level.warning": "bold bright_yellow",
+                "logging.level.error": "bold bright_red",
+                "logging.level.critical": "bold bright_magenta",
+            }
+        )
+        console = Console(theme=custom_theme)
+        handler = RichHandler(
+            console=console,
+            rich_tracebacks=True,
+            show_time=True,
+            show_level=True,
+            show_path=False,
+            log_time_format="%Y-%m-%d %H:%M:%S",  # ISO 8601 format
+        )
+
+        logger.addHandler(handler)
+        return logger
+
+
+@contextmanager
+def progress_bar(
+    total: int | None, desc: str = "", unit: str = "steps"
+) -> Generator[tuple[Progress, TaskID], None, None]:
+    """Create a progress bar using Rich as a context manager.
+
+    Parameters
+    ----------
+    total: int | None
+        Total number of steps in the progress bar
+    desc: str
+        Description text to display next to the progress bar
+    unit: str
+        Unit label for the progress steps, by default "steps"
+
+    Yields
+    ------
+    tuple[Progress, TaskID]
+        A tuple containing the Progress object and task ID for updating
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=Console(
+            theme=Theme(
+                {
+                    "bar.back": "blue",
+                    "bar.pulse": "bright_blue",
+                }
+            )
+        ),
+        transient=True,
+    ) as progress:
+        task = progress.add_task(f"[blue]{desc}", total=total, unit=unit)
+        yield progress, task  # Yield both progress and task for updates
+
+
+def progress(
+    total: int | None,
+    desc: str = "",
+    unit: str = "steps",
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorate a func with a progress-bar.
+
+    Parameters
+    ----------
+    total: int | None
+        Total number of steps in the progress bar
+    desc: str
+        Description text to display next to the progress bar
+    unit: str
+        Unit label for the progress steps, by default "steps"
+
+    """
+
+    def decorated_func(func: Callable[P, T]) -> Callable[P, T]:
+        @wraps(func)
+        def decorator(*args: P.args, **kwargs: P.kwargs) -> T:
+            with progress_bar(total=total, desc=desc, unit=unit):
+                return func(*args, **kwargs)
+
+        return decorator
+
+    return decorated_func

luna_quantum/util/pretty_base.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class PrettyBase(BaseModel):
+    """Helper class to implement pretty print."""
+
+    def _pretty_print(self, data: dict, indent: int = 0) -> str:  # type: ignore[type-arg]
+        """Return nested dictionaries in a readable YAML-inspired format as a string.
+
+        This format enhances human readability by using a YAML-like structured style.
+
+        Parameters
+        ----------
+        data: dict
+        indent: int
+        """
+        output = ""
+        for key, value in data.items():
+            output += "    " * indent + str(key) + ":"
+            if isinstance(value, dict):
+                if value == {}:
+                    output += " {}\n"
+                else:
+                    output += "\n"
+                    output += self._pretty_print(value, indent + 1)
+            elif isinstance(value, datetime):
+                output += f" {value.strftime('%Y-%m-%d %H:%M:%S (%Z)')}\n"
+            else:
+                output += f" {value}\n"
+        return output
+
+    def __str__(self) -> str:
+        """Override the default object string representation."""
+        data = self.model_dump()
+
+        return self._pretty_print(data)
+
+    @property
+    def head(self) -> str:
+        """Print a truncated version of the pretty print console representation."""
+        limit = 20
+
+        def truncate(data: dict, limit: int) -> tuple[dict, bool]:  # type: ignore[type-arg]
+            if data is None:
+                return None, False
+
+            if isinstance(data, dict):
+                d = {
+                    k: truncate(v, limit)[0]
+                    for i, (k, v) in enumerate(data.items())
+                    if i < limit
+                }
+                return d, len(data) > limit
+            if isinstance(data, list):
+                d = data[:limit]
+                return d, len(data) > limit
+            return data, False
+
+        data = self.model_dump()
+
+        data_truncated, is_truncated = truncate(data, limit)
+
+        return self._pretty_print(data_truncated)

luna_quantum/util/pydantic_utils.py

@@ -0,0 +1,38 @@
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticUtils:
+    """A utility class for operations on Pydantic models."""
+
+    @staticmethod
+    def update_model(to_update: T, other_model: T) -> None:
+        """
+        Update the attributes of a given pydantic model.
+
+        This function works by iterating over the attributes
+        of the second model (provided as input) and assigns the corresponding values
+        to the attributes of the first model.
+
+        Parameters
+        ----------
+        to_update : T
+            The model instance whose attributes need to be updated. This instance
+            will have its attributes overridden with the corresponding values from
+            the other model instance.
+        other_model : T
+            The model instance providing the new values for the update. Its
+            attributes are used to overwrite the attributes of the `to_update`
+            instance.
+
+        Returns
+        -------
+        None
+            This function does not return a value. Instead, it updates the
+            `to_update` instance in place.
+        """
+        for key, value in other_model.model_dump().items():
+            setattr(to_update, key, value)

luna_quantum/utils.py

@@ -0,0 +1,54 @@
+from collections.abc import Iterable
+
+from ._core import Expression, Variable
+
+
+def quicksum(
+    iterable: Iterable[Expression | Variable | int | float],
+    /,
+    start: Expression | None = None,
+) -> Expression:
+    """
+    Create an Expression based on an iterable of Expression, Variable, int or float elements.
+    Note that either the `iterable` must contain at least one `Expression` or `Variable` or
+    the start parameter is set.
+
+    Parameters
+    ----------
+    iterable : Iterable[Expression | Variable | int | float]
+        The iterable of elements to sum up.
+    start : Expression | None, optional
+        The starting value for the summation.
+
+    Returns
+    -------
+    Expression
+        The expression created based on the sum of the iterable elements.
+
+    Raises
+    ------
+    TypeError
+        If the `iterable` does not contain any Expression or Variable.
+        If the `start` is not of type Expression.
+    """
+    items = list(iterable)
+    if start is None:
+        for item in items:
+            if isinstance(item, Expression) or isinstance(item, Variable):
+                start = Expression(env=item._environment)  # type: ignore
+                break
+
+    if start is None:
+        raise TypeError(
+            "iterable must contain at least one Expression or Variable,or 'start' needs to be set."
+        )
+
+    if not isinstance(start, Expression):
+        raise TypeError("start must be of type `Expression`")
+
+    _start: Expression = start
+
+    for item in items:
+        _start += item
+
+    return _start

luna_quantum/utils.pyi

@@ -0,0 +1,35 @@
+from collections.abc import Iterable
+from typing import overload
+
+from aqmodels import Expression, Variable
+
+@overload
+def quicksum(iterable: Iterable[Expression], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[Variable], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[int], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[float], /) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Expression], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Variable], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[int], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[float], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Expression | Variable | float | int],
+    /,
+    start: Expression | None = None,
+) -> Expression: ...

luna_quantum-1.0.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: luna-quantum
+Version: 1.0.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: httpx>=0.28.1,<0.29
+Requires-Dist: numpy>=1
+Requires-Dist: pydantic[email]>=2.11.3,<3
+Requires-Dist: python-dateutil>=2.9.0,<3
+Requires-Dist: rich>=14.0.0
+Requires-Dist: networkx>=3.4.2,<4 ; extra == 'examples'
+Provides-Extra: examples
+License-File: LICENSE
+License-File: NOTICE
+Summary: Python SDK for Aqarios' Luna Platform
+Keywords: aqarios,luna,quantum computing,quantum optimization,optimization,sdk
+Author-email: Aqarios <pypi@aqarios.com>
+License: Apache-2.0
+Requires-Python: >=3.11.0, <4
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://aqarios.com/
+Project-URL: Documentation, https://docs.aqarios.com/
+
+# Luna Quantum SDK
+Luna is a platform developed by [Aqarios](https://aqarios.com/) designed to facilitate access to and utilization of quantum computing for both industry and academia. The SDK serves as a Python wrapper for interfacing with the API, offering a more intuitive means of engaging with the platform. This library grants access to the LunaSolve and LunaQ services.
+
+# Installation
+The package is released on PyPI and can be installed via pip:
+```
+pip install --upgrade luna-quantum
+```
+
+# Getting Started
+For more details and tutorials on how to use the Luna SDK, refer to the documentation located here: [Aqarios Luna](https://docs.aqarios.com/).
+