orivex 0.1.0__tar.gz

orivex-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, The orivex authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orivex-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: orivex
+Version: 0.1.0
+Summary: A selective and fast exploratory landscape analysis engine.
+Author-email: Wojciech Achtelik <wachtelik@gmail.com>
+Maintainer-email: Wojciech Achtelik <wachtelik@gmail.com>
+License: MIT
+Project-URL: Homepage, https://helix-agh.github.io/orivex/
+Project-URL: Documentation, https://helix-agh.github.io/orivex/
+Project-URL: Repository, https://github.com/helix-agh/orivex
+Project-URL: Issues, https://github.com/helix-agh/orivex/issues
+Keywords: exploratory landscape analysis,ela,black-box optimization,benchmarking,bbob,feature extraction,numpy,pytorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.7; extra == "docs"
+Requires-Dist: mkdocs-gen-files<0.6,>=0.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]<2,>=1.0; extra == "docs"
+Requires-Dist: pymdown-extensions<11,>=10.15; extra == "docs"
+Requires-Dist: ruff>=0.16.3; extra == "docs"
+Provides-Extra: torch
+Requires-Dist: torch>=2.3; extra == "torch"
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.100; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Provides-Extra: benchmark
+Requires-Dist: ioh<0.4,>=0.3.14; extra == "benchmark"
+Requires-Dist: matplotlib>=3.8; extra == "benchmark"
+Requires-Dist: numdifftools>=0.9.41; extra == "benchmark"
+Requires-Dist: pandas>=2.2; extra == "benchmark"
+Requires-Dist: pyDOE<0.4,>=0.3.8; extra == "benchmark"
+Requires-Dist: SALib<1.5,>=1.4.5; extra == "benchmark"
+Requires-Dist: scikit-learn>=1.5; extra == "benchmark"
+Requires-Dist: threadpoolctl>=3.6; extra == "benchmark"
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: pre-commit>=4.5; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.16.3; extra == "dev"
+Requires-Dist: torch>=2.3; extra == "dev"
+Requires-Dist: ty>=0.0.74; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-light.png">
+    <img alt="orivex" src="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-light.png" width="440">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>A selective and fast engine for exploratory landscape analysis.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10+-blue.svg"></a>
+  <img alt="Status: pre-release" src="https://img.shields.io/badge/status-pre--release-orange.svg">
+  <img alt="Backends: NumPy and PyTorch" src="https://img.shields.io/badge/backends-NumPy%20%7C%20PyTorch-informational.svg">
+</p>
+
+<p align="center">
+  <a href="https://helix-agh.github.io/orivex/">Documentation</a> ·
+  <a href="https://helix-agh.github.io/orivex/getting-started/quickstart/">Quick start</a> ·
+  <a href="https://helix-agh.github.io/orivex/api/">API reference</a> ·
+  <a href="https://helix-agh.github.io/orivex/development/contributing/">Contributing</a>
+</p>
+
+**orivex** is a successor to [`pflacco`](https://github.com/Reiyan/pflacco)
+for exploratory landscape analysis (ELA). Compute individually selected features from sampled
+points and objective values, with shared intermediates, explicit costs, and versioned definitions.
+A NumPy/SciPy core is complemented by an optional differentiable PyTorch backend.
+
+## Installation
+
+Python 3.10 or newer is required. Install from PyPI:
+
+```bash
+pip install orivex
+```
+
+Add the optional differentiable PyTorch backend with `pip install "orivex[torch]"`.
+
+To work from a checkout instead:
+
+```bash
+git clone https://github.com/helix-agh/orivex.git
+cd orivex
+uv sync
+```
+
+With pip, run `python -m pip install -e .` (add `".[torch]"` for the PyTorch backend).
+
+## Quick start
+
+```python
+import numpy as np
+
+from orivex import LandscapeSample, compute
+
+rng = np.random.default_rng(42)
+x = rng.uniform(-5.0, 5.0, size=(200, 2))
+y = np.sum(x**2, axis=1)
+sample = LandscapeSample(x, y, lower=[-5.0, -5.0], upper=[5.0, 5.0])
+
+result = compute(sample, ["ela_distr.skewness", "nbc.nn_nb.mean_ratio"])
+for name, item in result.values.items():
+    print(name, item.value, item.status.value)
+```
+
+Objective values are min-max normalized by default. Pass `y_normalization=None` to use raw
+canonical objectives. Undefined features return an `invalid` status with an explanation.
+
+## Documentation
+
+Read the **[documentation](https://helix-agh.github.io/orivex/)** for installation, feature
+selection, normalization, fitness-distance conventions, PyTorch support, and API reference.
+The [feature overview](https://helix-agh.github.io/orivex/features/), [contributing guide](https://helix-agh.github.io/orivex/development/contributing/),
+and [benchmark guide](https://helix-agh.github.io/orivex/development/benchmarks/) are also available.
+
+Preview the documentation locally:
+
+```bash
+uv sync --extra docs
+uv run --no-sync mkdocs serve
+```
+
+See [documentation development](https://helix-agh.github.io/orivex/development/documentation/) for strict builds and deployment.
+
+## License
+
+orivex is licensed under the [MIT License](https://github.com/helix-agh/orivex/blob/main/LICENSE.txt).

orivex-0.1.0/README.md

@@ -0,0 +1,89 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-light.png">
+    <img alt="orivex" src="https://raw.githubusercontent.com/helix-agh/orivex/main/assets/orivex-lockup-light.png" width="440">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>A selective and fast engine for exploratory landscape analysis.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10+-blue.svg"></a>
+  <img alt="Status: pre-release" src="https://img.shields.io/badge/status-pre--release-orange.svg">
+  <img alt="Backends: NumPy and PyTorch" src="https://img.shields.io/badge/backends-NumPy%20%7C%20PyTorch-informational.svg">
+</p>
+
+<p align="center">
+  <a href="https://helix-agh.github.io/orivex/">Documentation</a> ·
+  <a href="https://helix-agh.github.io/orivex/getting-started/quickstart/">Quick start</a> ·
+  <a href="https://helix-agh.github.io/orivex/api/">API reference</a> ·
+  <a href="https://helix-agh.github.io/orivex/development/contributing/">Contributing</a>
+</p>
+
+**orivex** is a successor to [`pflacco`](https://github.com/Reiyan/pflacco)
+for exploratory landscape analysis (ELA). Compute individually selected features from sampled
+points and objective values, with shared intermediates, explicit costs, and versioned definitions.
+A NumPy/SciPy core is complemented by an optional differentiable PyTorch backend.
+
+## Installation
+
+Python 3.10 or newer is required. Install from PyPI:
+
+```bash
+pip install orivex
+```
+
+Add the optional differentiable PyTorch backend with `pip install "orivex[torch]"`.
+
+To work from a checkout instead:
+
+```bash
+git clone https://github.com/helix-agh/orivex.git
+cd orivex
+uv sync
+```
+
+With pip, run `python -m pip install -e .` (add `".[torch]"` for the PyTorch backend).
+
+## Quick start
+
+```python
+import numpy as np
+
+from orivex import LandscapeSample, compute
+
+rng = np.random.default_rng(42)
+x = rng.uniform(-5.0, 5.0, size=(200, 2))
+y = np.sum(x**2, axis=1)
+sample = LandscapeSample(x, y, lower=[-5.0, -5.0], upper=[5.0, 5.0])
+
+result = compute(sample, ["ela_distr.skewness", "nbc.nn_nb.mean_ratio"])
+for name, item in result.values.items():
+    print(name, item.value, item.status.value)
+```
+
+Objective values are min-max normalized by default. Pass `y_normalization=None` to use raw
+canonical objectives. Undefined features return an `invalid` status with an explanation.
+
+## Documentation
+
+Read the **[documentation](https://helix-agh.github.io/orivex/)** for installation, feature
+selection, normalization, fitness-distance conventions, PyTorch support, and API reference.
+The [feature overview](https://helix-agh.github.io/orivex/features/), [contributing guide](https://helix-agh.github.io/orivex/development/contributing/),
+and [benchmark guide](https://helix-agh.github.io/orivex/development/benchmarks/) are also available.
+
+Preview the documentation locally:
+
+```bash
+uv sync --extra docs
+uv run --no-sync mkdocs serve
+```
+
+See [documentation development](https://helix-agh.github.io/orivex/development/documentation/) for strict builds and deployment.
+
+## License
+
+orivex is licensed under the [MIT License](https://github.com/helix-agh/orivex/blob/main/LICENSE.txt).

orivex-0.1.0/pyproject.toml

@@ -0,0 +1,118 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orivex"
+version = "0.1.0"
+description = "A selective and fast exploratory landscape analysis engine."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Wojciech Achtelik", email = "wachtelik@gmail.com"}]
+maintainers = [{name = "Wojciech Achtelik", email = "wachtelik@gmail.com"}]
+keywords = [
+    "exploratory landscape analysis",
+    "ela",
+    "black-box optimization",
+    "benchmarking",
+    "bbob",
+    "feature extraction",
+    "numpy",
+    "pytorch",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7,<10",
+    "mkdocs-gen-files>=0.5,<0.6",
+    "mkdocstrings[python]>=1.0,<2",
+    "pymdown-extensions>=10.15,<11",
+    "ruff>=0.16.3",
+]
+torch = [
+    "torch>=2.3",
+]
+test = [
+    "hypothesis>=6.100",
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+benchmark = [
+    "ioh>=0.3.14,<0.4",
+    "matplotlib>=3.8",
+    "numdifftools>=0.9.41",
+    "pandas>=2.2",
+    "pyDOE>=0.3.8,<0.4",
+    "SALib>=1.4.5,<1.5",
+    "scikit-learn>=1.5",
+    "threadpoolctl>=3.6",
+]
+dev = [
+    "hypothesis>=6.100",
+    "pre-commit>=4.5",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.16.3",
+    "torch>=2.3",
+    "ty>=0.0.74",
+]
+
+[project.urls]
+Homepage = "https://helix-agh.github.io/orivex/"
+Documentation = "https://helix-agh.github.io/orivex/"
+Repository = "https://github.com/helix-agh/orivex"
+Issues = "https://github.com/helix-agh/orivex/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+orivex = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+pythonpath = ["src", "tests", "benchmarks"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "ARG", "SIM", "PTH", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["orivex"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ARG"]
+"tests/torch/**" = ["E402"]
+
+[tool.ty.environment]
+python-version = "3.10"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src"]

orivex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

orivex-0.1.0/src/orivex/__init__.py

@@ -0,0 +1,49 @@
+"""Better FLACCO: selective and verified exploratory landscape analysis."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from orivex.api import compute, list_features
+from orivex.capabilities import AutogradSupport, FeatureCapability
+from orivex.normalization import YNormalization
+from orivex.result import BackendName, DeviceType, FloatingDType
+from orivex.sample import LandscapeSample, ObjectiveSense, ObjectiveSenseName
+from orivex.specs import (
+    CostModel,
+    CostTier,
+    FeatureSpec,
+    InputRequirement,
+    InvarianceBehavior,
+    InvarianceClaim,
+    MetricKind,
+    Reference,
+    Transformation,
+)
+
+try:
+    __version__ = version("orivex")
+except PackageNotFoundError:  # Running directly from a source checkout.
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AutogradSupport",
+    "BackendName",
+    "CostModel",
+    "CostTier",
+    "DeviceType",
+    "FeatureCapability",
+    "FeatureSpec",
+    "FloatingDType",
+    "InputRequirement",
+    "InvarianceBehavior",
+    "InvarianceClaim",
+    "LandscapeSample",
+    "MetricKind",
+    "ObjectiveSense",
+    "ObjectiveSenseName",
+    "Reference",
+    "Transformation",
+    "YNormalization",
+    "__version__",
+    "compute",
+    "list_features",
+]

orivex-0.1.0/src/orivex/api.py

@@ -0,0 +1,75 @@
+"""Public convenience API backed by the built-in feature engine."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from orivex.engine import Engine
+from orivex.features.distribution import FEATURES as DISTRIBUTION_FEATURES
+from orivex.features.distribution import INTERMEDIATES as DISTRIBUTION_INTERMEDIATES
+from orivex.features.fitness_distance import FEATURES as FITNESS_DISTANCE_FEATURES
+from orivex.features.fitness_distance import INTERMEDIATES as FITNESS_DISTANCE_INTERMEDIATES
+from orivex.features.information_content import FEATURES as INFORMATION_CONTENT_FEATURES
+from orivex.features.information_content import INTERMEDIATES as INFORMATION_CONTENT_INTERMEDIATES
+from orivex.features.meta_model import FEATURES as META_MODEL_FEATURES
+from orivex.features.meta_model import INTERMEDIATES as META_MODEL_INTERMEDIATES
+from orivex.features.nearest_better import FEATURES as NEAREST_BETTER_FEATURES
+from orivex.features.nearest_better import INTERMEDIATES as NEAREST_BETTER_INTERMEDIATES
+from orivex.normalization import YNormalization
+from orivex.options import FeatureOptions
+from orivex.result import ComputationResult
+from orivex.sample import LandscapeSample
+from orivex.specs import FeatureSpec
+
+DEFAULT_ENGINE = Engine(
+    DISTRIBUTION_FEATURES
+    + META_MODEL_FEATURES
+    + INFORMATION_CONTENT_FEATURES
+    + NEAREST_BETTER_FEATURES
+    + FITNESS_DISTANCE_FEATURES,
+    DISTRIBUTION_INTERMEDIATES
+    + META_MODEL_INTERMEDIATES
+    + INFORMATION_CONTENT_INTERMEDIATES
+    + NEAREST_BETTER_INTERMEDIATES
+    + FITNESS_DISTANCE_INTERMEDIATES,
+)
+
+
+def compute(
+    sample: LandscapeSample,
+    features: str | tuple[str, ...] | list[str],
+    *,
+    rng: np.random.Generator | None = None,
+    workers: int = 1,
+    y_normalization: YNormalization = "minmax",
+    options: FeatureOptions | None = None,
+) -> ComputationResult:
+    """Compute features from canonical objectives, min-max normalized by default.
+
+    ``y_normalization`` is ``"minmax"`` (observed range) or ``None`` (raw canonical
+    objectives). Normalized constant objectives map to zero. The original sample is
+    preserved; preprocessing is recorded
+    separately from mathematical feature definitions in result metadata.
+
+    ``options`` is a nested mapping keyed by feature group, for example
+    ``{"fitness_distance": {"proportion_of_best": 0.25}}``. Omit it to use defaults.
+    Unknown groups and option names are rejected. Fitness-distance features always use
+    Euclidean distances to the best selected observation. Effective options are recorded
+    in ``result.metadata.options`` as an immutable snapshot.
+
+    ``workers=1`` is the predictable default. Pass ``-1`` to let supporting kernels use all
+    available CPUs, or a positive integer to set an upper worker count. Kernels that do not
+    support parallel execution ignore this setting.
+    """
+    return DEFAULT_ENGINE.compute(
+        sample,
+        features,
+        rng=rng,
+        workers=workers,
+        y_normalization=y_normalization,
+        options=options,
+    )
+
+
+def list_features() -> tuple[FeatureSpec, ...]:
+    return tuple(DEFAULT_ENGINE.registry.get(name) for name in DEFAULT_ENGINE.registry.names())

orivex-0.1.0/src/orivex/capabilities.py

@@ -0,0 +1,42 @@
+"""Backend-specific feature implementation capabilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from orivex.result import BackendName, DeviceType, FloatingDType
+
+AutogradSupport: TypeAlias = Literal["smooth", "piecewise", "none"]
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureCapability:
+    """Execution properties that belong to an implementation, not its mathematics."""
+
+    feature_name: str
+    backend: BackendName
+    autograd: AutogradSupport
+    devices: tuple[DeviceType, ...]
+    dtypes: tuple[FloatingDType, ...]
+    notes: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.feature_name:
+            raise ValueError("feature name must not be empty")
+        if self.backend not in ("numpy", "torch"):
+            raise ValueError(f"unsupported backend: {self.backend!r}")
+        if self.autograd not in ("smooth", "piecewise", "none"):
+            raise ValueError(f"unsupported autograd support: {self.autograd!r}")
+        if not self.devices:
+            raise ValueError("at least one device type is required")
+        if not self.dtypes:
+            raise ValueError("at least one floating dtype is required")
+        if any(device not in ("cpu", "cuda", "mps") for device in self.devices):
+            raise ValueError(f"unsupported device types: {self.devices!r}")
+        if any(dtype not in ("float32", "float64") for dtype in self.dtypes):
+            raise ValueError(f"unsupported floating dtypes: {self.dtypes!r}")
+        if len(set(self.devices)) != len(self.devices):
+            raise ValueError("device types must be unique")
+        if len(set(self.dtypes)) != len(self.dtypes):
+            raise ValueError("floating dtypes must be unique")