opytimark 3.0.0__tar.gz → 3.0.2__tar.gz

{opytimark-3.0.0 → opytimark-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opytimark
-Version: 3.0.0
+Version: 3.0.2
 Summary: Python Optimization Benchmarking Functions
 Author-email: Gustavo Rosa <gustavo.rosa@unesp.br>
 License-Expression: Apache-2.0
@@ -43,6 +43,14 @@ Opytimark supports Python 3.11 or newer. Read the full API reference at
 
 ## Installation
 
+Opytimark is published on PyPI. Add it to a project managed by uv with:
+
+```bash
+uv add opytimark
+```
+
+For a consumer installation in an existing Python environment, pip is also supported:
+
 ```bash
 pip install opytimark
 ```
@@ -60,8 +68,24 @@ print(value)
 
 More examples are available in [`examples/`](examples).
 
+## Reproducibility
+
+Imports do not reset NumPy's random state. For reproducible noisy or randomized
+benchmarks, call `np.random.seed(your_seed)` explicitly before the experiment.
+
+The 3.0.1 CEC conditioning, group-rotation, and composition corrections
+change some fitness values relative to 3.0.0. See
+[numerical behavior](docs/numerical_behavior.rst) before comparing old and new
+optimization results.
+
+Library diagnostics use Python logging rather than writing to standard output.
+Applications control log handlers, output streams, and levels.
+
 ## Development
 
+Follow the [project conventions](CONVENTIONS.md) when changing Python code,
+scientific documentation, or tests.
+
 Install [uv](https://docs.astral.sh/uv/), clone the repository, then run:
 
 ```bash

{opytimark-3.0.0 → opytimark-3.0.2}/README.md

@@ -14,6 +14,14 @@ Opytimark supports Python 3.11 or newer. Read the full API reference at
 
 ## Installation
 
+Opytimark is published on PyPI. Add it to a project managed by uv with:
+
+```bash
+uv add opytimark
+```
+
+For a consumer installation in an existing Python environment, pip is also supported:
+
 ```bash
 pip install opytimark
 ```
@@ -31,8 +39,24 @@ print(value)
 
 More examples are available in [`examples/`](examples).
 
+## Reproducibility
+
+Imports do not reset NumPy's random state. For reproducible noisy or randomized
+benchmarks, call `np.random.seed(your_seed)` explicitly before the experiment.
+
+The 3.0.1 CEC conditioning, group-rotation, and composition corrections
+change some fitness values relative to 3.0.0. See
+[numerical behavior](docs/numerical_behavior.rst) before comparing old and new
+optimization results.
+
+Library diagnostics use Python logging rather than writing to standard output.
+Applications control log handlers, output streams, and levels.
+
 ## Development
 
+Follow the [project conventions](CONVENTIONS.md) when changing Python code,
+scientific documentation, or tests.
+
 Install [uv](https://docs.astral.sh/uv/), clone the repository, then run:
 
 ```bash

opytimark-3.0.2/opytimark/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+from logging import NullHandler
+
+from opytimark.logging import get_logger
+
+__version__ = "3.0.2"
+
+_logger = get_logger(__name__)
+if not any(isinstance(handler, NullHandler) for handler in _logger.handlers):
+    _logger.addHandler(NullHandler())

{opytimark-3.0.0 → opytimark-3.0.2}/opytimark/core/__init__.py

@@ -1,4 +1,5 @@
-"""A core package for all common opytimark modules."""
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
 
 from opytimark.core.benchmark import Benchmark
 from opytimark.core.cec_benchmark import CECBenchmark, CECCompositeBenchmark

opytimark-3.0.2/opytimark/core/benchmark.py

@@ -0,0 +1,296 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+from numpy.typing import ArrayLike
+
+import opytimark.utils.exception as e
+from opytimark.typing import BenchmarkValue
+
+
+class _Missing:
+    def __repr__(self) -> str:
+        return "<default>"
+
+
+_MISSING = _Missing()
+
+
+def _validate_type(name: str, value: object, expected_type: type) -> None:
+    if not isinstance(value, expected_type):
+        raise e.TypeError(
+            f"`{name}` must be of type {expected_type.__name__}, but got {value!r} ({type(value).__name__})."
+        )
+
+
+class Benchmark:
+    """
+    Base class for callable benchmarks with validated, mutable metadata.
+
+    """
+
+    _defaults: tuple[str, int, bool, bool, bool, bool, bool] = ("Benchmark", 1, False, False, False, False, False)
+
+    def __init__(
+        self,
+        name: str | _Missing = _MISSING,
+        dims: int | _Missing = _MISSING,
+        continuous: bool | _Missing = _MISSING,
+        convex: bool | _Missing = _MISSING,
+        differentiable: bool | _Missing = _MISSING,
+        multimodal: bool | _Missing = _MISSING,
+        separable: bool | _Missing = _MISSING,
+    ) -> None:
+        """Initialize benchmark metadata using the subclass defaults for omitted arguments.
+
+        Args:
+            name: Benchmark identifier used in diagnostics and CEC data-file selection.
+            dims: Dimension metadata interpreted by the benchmark's input validator.
+            continuous: Whether the benchmark is continuous.
+            convex: Whether the benchmark is convex.
+            differentiable: Whether the benchmark is differentiable.
+            multimodal: Whether the benchmark has multiple modes.
+            separable: Whether coordinates can be optimized independently.
+
+        Raises:
+            TypeError: A metadata value has the wrong type.
+            ValueError: The dimension count is below -1 or equal to zero.
+
+        Notes:
+            Omitted values come from the subclass's `_defaults` tuple.
+            Explicit values, including None, pass through property validation.
+            Validators may require an exact size, impose an upper bound, or select supported CEC rotations.
+
+        """
+
+        supplied = (
+            name,
+            dims,
+            continuous,
+            convex,
+            differentiable,
+            multimodal,
+            separable,
+        )
+
+        for field, value, default in zip(
+            (
+                "name",
+                "dims",
+                "continuous",
+                "convex",
+                "differentiable",
+                "multimodal",
+                "separable",
+            ),
+            supplied,
+            self._defaults,
+        ):
+            setattr(self, field, default if value is _MISSING else value)
+
+    @property
+    def name(self) -> str:
+        """Return the benchmark identifier.
+
+        Returns:
+            Validated benchmark name.
+
+        """
+
+        return self._name
+
+    @name.setter
+    def name(self, name: str) -> None:
+        """Set the benchmark identifier.
+
+        Args:
+            name: Benchmark name used in diagnostics.
+
+        Raises:
+            TypeError: The name is not a string.
+
+        """
+
+        _validate_type("name", name, str)
+
+        self._name = name
+
+    @property
+    def dims(self) -> int:
+        """Return the benchmark's dimension metadata.
+
+        Returns:
+            Positive dimension metadata or -1 for a variable-dimensional benchmark.
+
+        """
+
+        return self._dims
+
+    @dims.setter
+    def dims(self, dims: int) -> None:
+        """Set the benchmark's dimension metadata.
+
+        Args:
+            dims: Positive dimension metadata or -1 for a variable-dimensional benchmark.
+
+        Raises:
+            TypeError: The dimension count is not an integer.
+            ValueError: The dimension count is below -1 or equal to zero.
+
+        """
+
+        _validate_type("dims", dims, int)
+        if not (dims >= -1 and dims != 0):
+            raise e.ValueError(f"`dims` must be -1 or a positive integer, but got {dims!r}.")
+
+        self._dims = dims
+
+    @property
+    def continuous(self) -> bool:
+        """Return whether the benchmark is continuous.
+
+        Returns:
+            True when the benchmark is marked continuous.
+
+        """
+
+        return self._continuous
+
+    @continuous.setter
+    def continuous(self, continuous: bool) -> None:
+        """Set the benchmark's continuity flag.
+
+        Args:
+            continuous: Whether the benchmark is continuous.
+
+        Raises:
+            TypeError: The continuity flag is not a boolean.
+
+        """
+
+        _validate_type("continuous", continuous, bool)
+
+        self._continuous = continuous
+
+    @property
+    def convex(self) -> bool:
+        """Return whether the benchmark is convex.
+
+        Returns:
+            True when the benchmark is marked convex.
+
+        """
+
+        return self._convex
+
+    @convex.setter
+    def convex(self, convex: bool) -> None:
+        """Set the benchmark's convexity flag.
+
+        Args:
+            convex: Whether the benchmark is convex.
+
+        Raises:
+            TypeError: The convexity flag is not a boolean.
+
+        """
+
+        _validate_type("convex", convex, bool)
+
+        self._convex = convex
+
+    @property
+    def differentiable(self) -> bool:
+        """Return whether the benchmark is differentiable.
+
+        Returns:
+            True when the benchmark is marked differentiable.
+
+        """
+
+        return self._differentiable
+
+    @differentiable.setter
+    def differentiable(self, differentiable: bool) -> None:
+        """Set the benchmark's differentiability flag.
+
+        Args:
+            differentiable: Whether the benchmark is differentiable.
+
+        Raises:
+            TypeError: The differentiability flag is not a boolean.
+
+        """
+
+        _validate_type("differentiable", differentiable, bool)
+
+        self._differentiable = differentiable
+
+    @property
+    def multimodal(self) -> bool:
+        """Return whether the benchmark has multiple modes.
+
+        Returns:
+            True when the benchmark is marked multimodal.
+
+        """
+
+        return self._multimodal
+
+    @multimodal.setter
+    def multimodal(self, multimodal: bool) -> None:
+        """Set the benchmark's multimodality flag.
+
+        Args:
+            multimodal: Whether the benchmark has multiple modes.
+
+        Raises:
+            TypeError: The multimodality flag is not a boolean.
+
+        """
+
+        _validate_type("multimodal", multimodal, bool)
+
+        self._multimodal = multimodal
+
+    @property
+    def separable(self) -> bool:
+        """Return whether coordinates can be optimized independently.
+
+        Returns:
+            True when the benchmark is marked separable.
+
+        """
+
+        return self._separable
+
+    @separable.setter
+    def separable(self, separable: bool) -> None:
+        """Set the benchmark's separability flag.
+
+        Args:
+            separable: Whether coordinates can be optimized independently.
+
+        Raises:
+            TypeError: The separability flag is not a boolean.
+
+        """
+
+        _validate_type("separable", separable, bool)
+
+        self._separable = separable
+
+    def __call__(self, x: ArrayLike) -> BenchmarkValue:
+        """Evaluate the benchmark through a concrete implementation.
+
+        Args:
+            x: Numeric coordinates supplied to the benchmark.
+
+        Returns:
+            Benchmark value produced by a subclass implementation.
+
+        Raises:
+            NotImplementedError: The base benchmark has no numerical implementation.
+
+        """
+
+        raise NotImplementedError("`Benchmark.__call__` must be implemented by a subclass.")

opytimark-3.0.2/opytimark/core/cec_benchmark.py

@@ -0,0 +1,240 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+import opytimark.utils.decorator as d
+import opytimark.utils.loader as ld
+from opytimark.core.benchmark import _MISSING, Benchmark, _Missing, _validate_type
+from opytimark.typing import BenchmarkValue
+
+
+class CECBenchmark(Benchmark):
+    """
+    Base class for CEC benchmarks backed by auxiliary data.
+
+    """
+
+    _year: str = ""
+    _auxiliary_data: tuple[str, ...] = ()
+
+    def __init__(
+        self,
+        name: str | _Missing = _MISSING,
+        year: str | _Missing = _MISSING,
+        auxiliary_data: Iterable[str] | _Missing = _MISSING,
+        dims: int | _Missing = _MISSING,
+        continuous: bool | _Missing = _MISSING,
+        convex: bool | _Missing = _MISSING,
+        differentiable: bool | _Missing = _MISSING,
+        multimodal: bool | _Missing = _MISSING,
+        separable: bool | _Missing = _MISSING,
+    ) -> None:
+        """Initialize CEC metadata and load the requested auxiliary arrays.
+
+        Args:
+            name: Benchmark name used as the auxiliary-data filename prefix.
+            year: CEC edition identifying the auxiliary-data archive.
+            auxiliary_data: Iterable of auxiliary variable names to load as instance attributes.
+            dims: Required or maximum dimension count for the benchmark's input validator.
+            continuous: Whether the benchmark is continuous.
+            convex: Whether the benchmark is convex.
+            differentiable: Whether the benchmark is differentiable.
+            multimodal: Whether the benchmark has multiple modes.
+            separable: Whether coordinates can be optimized independently.
+
+        Raises:
+            TypeError: A metadata value has the wrong type or auxiliary_data is not iterable.
+            ValueError: The dimension count or auxiliary data is invalid.
+            OSError: Requested auxiliary data cannot be read or downloaded.
+
+        Notes:
+            Omitted arguments use the subclass's `_defaults`, `_year`, and `_auxiliary_data` values.
+            Explicit None values are not treated as omitted.
+            Local auxiliary data takes precedence over bundled data, with remote loading as the final fallback.
+            Mutating metadata after initialization does not reload auxiliary data.
+
+        """
+
+        super().__init__(
+            name,
+            dims,
+            continuous,
+            convex,
+            differentiable,
+            multimodal,
+            separable,
+        )
+
+        self.year = self._year if year is _MISSING else year
+
+        data = self._auxiliary_data if auxiliary_data is _MISSING else auxiliary_data
+        self._load_auxiliary_data(self.name, self.year, data)
+
+    @property
+    def year(self) -> str:
+        """Return the declared CEC edition.
+
+        Returns:
+            Validated CEC edition string.
+
+        """
+
+        return self._year_value
+
+    @year.setter
+    def year(self, year: str) -> None:
+        """Set the CEC edition without reloading auxiliary arrays.
+
+        Args:
+            year: CEC edition identifying the auxiliary-data archive.
+
+        Raises:
+            TypeError: The year is not a string.
+
+        """
+
+        _validate_type("year", year, str)
+
+        self._year_value = year
+
+    def _load_auxiliary_data(self, name: str, year: str, data: Iterable[str]) -> None:
+        for variable in data:
+            setattr(self, variable, ld.load_cec_auxiliary(f"{name}_{variable}", year))
+
+
+class CECCompositeBenchmark(CECBenchmark):
+    """
+    Base class for shifted, scaled, and rotated CEC composite benchmarks.
+
+    """
+
+    _bias = 1
+
+    def __init__(
+        self,
+        name: str | _Missing = _MISSING,
+        year: str | _Missing = _MISSING,
+        auxiliary_data: Iterable[str] | _Missing = _MISSING,
+        sigma: Sequence[float] | NDArray[Any] = (),
+        l: Sequence[float] | NDArray[Any] = (),
+        functions: Sequence[Callable[[NDArray[Any]], BenchmarkValue]] = (),
+        bias: BenchmarkValue | _Missing = _MISSING,
+        dims: int | _Missing = _MISSING,
+        continuous: bool | _Missing = _MISSING,
+        convex: bool | _Missing = _MISSING,
+        differentiable: bool | _Missing = _MISSING,
+        multimodal: bool | _Missing = _MISSING,
+        separable: bool | _Missing = _MISSING,
+    ) -> None:
+        """Initialize a CEC composition while retaining caller-supplied component objects.
+
+        Args:
+            name: Benchmark name used as the auxiliary-data filename prefix.
+            year: CEC edition identifying the auxiliary-data archive.
+            auxiliary_data: Iterable of auxiliary variable names to load as instance attributes.
+            sigma: Component weight widths in evaluation order.
+            l: Component coordinate scales in evaluation order.
+            functions: Component callables evaluated in the supplied order.
+            bias: Overall additive bias, using the subclass's _bias value when omitted.
+            dims: Dimension metadata retained for compatibility with the shared benchmark constructor.
+            continuous: Whether the benchmark is continuous.
+            convex: Whether the benchmark is convex.
+            differentiable: Whether the benchmark is differentiable.
+            multimodal: Whether the benchmark has multiple modes.
+            separable: Whether coordinates can be optimized independently.
+
+        Raises:
+            TypeError: A metadata value has the wrong type or auxiliary_data is not iterable.
+            ValueError: The dimension count or auxiliary data is invalid.
+            OSError: Requested auxiliary data cannot be read or downloaded.
+
+        Notes:
+            Metadata and auxiliary-data defaults follow CECBenchmark.
+            Component sequences are retained without conversion or length validation.
+            Initialization supplies C = 2000 and the ten historical component biases.
+
+        """
+
+        super().__init__(
+            name,
+            year,
+            auxiliary_data,
+            dims,
+            continuous,
+            convex,
+            differentiable,
+            multimodal,
+            separable,
+        )
+
+        self._initialize_composition(
+            sigma,
+            l,
+            functions,
+            self._bias if bias is _MISSING else bias,
+        )
+
+    def _initialize_composition(
+        self,
+        sigma: Sequence[float] | NDArray[Any],
+        scale: Sequence[float] | NDArray[Any],
+        functions: Sequence[Callable[[NDArray[Any]], BenchmarkValue]],
+        bias: BenchmarkValue,
+    ) -> None:
+        self.sigma = sigma
+        self.l = scale
+        self.f = functions
+        self.bias = bias
+        self.C = 2000
+        self.f_bias = (0, 100, 200, 300, 400, 500, 600, 700, 800, 900)
+
+    @d.check_exact_dimension_and_auxiliary_matrix
+    def __call__(self, x: NDArray[Any]) -> BenchmarkValue:
+        """Evaluate the weighted CEC composition and add its overall bias.
+
+        Args:
+            x: Numeric coordinates with first-axis length 2, 10, 30, or 50.
+
+        Returns:
+            Weighted component fitness plus the overall bias, without converting the result type.
+
+        Raises:
+            SizeError: The input's first-axis length is unsupported.
+
+        Notes:
+            Positional and keyword inputs are normalized without forcing a floating-point dtype.
+            A singleton second axis is removed, other axes are retained, and the input is not mutated.
+            The matching M2, M10, M30, or M50 rotation array is selected as M.
+            Each component is evaluated at its scaled, rotated reference point before its shifted input.
+            Relative exponential weights are attenuated before normalization to avoid numerical underflow.
+
+        """
+
+        return self._evaluate_composition(x) + self.bias
+
+    def _evaluate_composition(self, x: NDArray[Any]) -> BenchmarkValue:
+        dimension = x.shape[0]
+        log_weights = np.zeros(len(self.f))
+        fitness = np.zeros(len(self.f))
+        reference = 5 * np.ones(dimension)
+
+        for index, function in enumerate(self.f):
+            start = index * dimension
+            end = start + dimension
+            shifted = x - self.o[index][:dimension]
+            log_weights[index] = -np.sum(shifted**2) / (2 * dimension * self.sigma[index] ** 2)
+            normalizer = function(np.matmul(reference / self.l[index], self.M[start:end]))
+            fitness[index] = self.C * function(np.matmul(shifted / self.l[index], self.M[start:end])) / normalizer
+
+        # Relative exponentials avoid underflow before weight normalization
+        maximum = np.max(log_weights)
+        weights = np.exp(log_weights - maximum)
+        weights[log_weights != maximum] *= -np.expm1(10 * maximum)
+        weights /= np.sum(weights)
+
+        return np.matmul(weights, fitness + self.f_bias)

opytimark-3.0.2/opytimark/data/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.

opytimark-3.0.2/opytimark/logging.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger without configuring application output.
+
+    Args:
+        name: Fully qualified name of the module requesting the logger.
+
+    Returns:
+        Standard-library logger with application-controlled handlers, levels, and propagation.
+
+    """
+
+    return logging.getLogger(name)

opytimark-3.0.2/opytimark/markers/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2020-2026 Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.