lonkit 0.1.0__tar.gz

lonkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest

lonkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build docs
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

lonkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lonkit
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lonkit-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+paper_results/
+.venv/
+.ruff_cache/
+.mypy_cache/
+paper_reproduction.py
+site/
+CLAUDE.md
+__pycache__/
+.DS_Store

lonkit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - numpy
+          - pandas-stubs
+          - types-Pillow
+        args: [--ignore-missing-imports]

lonkit-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: lonkit
+Version: 0.1.0
+Summary: Local Optima Networks (LONs) for continuous optimization - Python implementation
+Requires-Python: >=3.10
+Requires-Dist: igraph>=0.11.0
+Requires-Dist: imageio>=2.31.0
+Requires-Dist: kaleido>=0.2.1
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.15.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: ioh>=0.3.22; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.7.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings-python>=1.0.0; extra == 'dev'
+Requires-Dist: mkdocstrings>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <img src="docs/assets/icon.png" alt="lonkit" width="800">
+</div>
+
+[![PyPI version](https://badge.fury.io/py/lonkit.svg)](https://pypi.org/project/lonkit/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1Ujl48ffgHg9ck1Hueh59s65OR3Q3BG99?usp=sharing)
+
+**Local Optima Networks for Continuous Optimization**
+
+lonkit is a Python library for constructing, analyzing, and visualizing Local Optima Networks (LONs) for continuous optimization problems. LONs provide a powerful way to understand the structure of fitness landscapes, revealing how local optima are connected and how difficult it may be to find global optima.
+
+## Features
+
+- **Basin-Hopping Sampling**: Efficient exploration of fitness landscapes using configurable Basin-Hopping
+- **LON Construction**: Automatic construction of Local Optima Networks from sampling data
+- **CMLON Support**: Compressed Monotonic LONs for cleaner landscape analysis
+- **Rich Metrics**: Compute landscape metrics including funnel analysis and neutrality
+- **Beautiful Visualizations**: 2D and 3D plots with support for animated GIFs
+
+## Installation
+
+```bash
+pip install lonkit
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/helix-agh/lonkit.git
+cd lonkit
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from lonkit import compute_lon, LONVisualizer, BasinHoppingSamplerConfig
+
+# Define an objective function
+def rastrigin(x: np.ndarray) -> float:
+    return 10 * len(x) + np.sum(x**2 - 10 * np.cos(2 * np.pi * x))
+
+# Construct the LON
+config = BasinHoppingSamplerConfig(
+    n_runs=20,
+    n_iter_no_change=500,
+    seed=42
+)
+lon = compute_lon(
+    rastrigin,
+    dim=2,
+    lower_bound=-5.12,
+    upper_bound=5.12,
+    config=config
+)
+
+metrics = lon.compute_metrics()
+print(f"Number of funnels: {metrics['n_funnels']}")
+print(f"Global funnels: {metrics['n_global_funnels']}")
+
+# Visualize
+viz = LONVisualizer()
+viz.plot_2d(lon, output_path="lon_2d.png")
+viz.plot_3d(lon, output_path="lon_3d.png")
+```
+
+### Compressed Monotonic LONs (CMLONs)
+
+CMLONs are a compressed representation where nodes with equal fitness that are connected get merged. This provides a cleaner view of the landscape's funnel structure.
+
+```python
+# Convert LON to CMLON
+cmlon = lon.to_cmlon()
+
+# Analyze CMLON-specific metrics
+cmlon_metrics = cmlon.compute_metrics()
+```
+
+### Custom Sampling Configuration
+
+```python
+from lonkit import BasinHoppingSampler, BasinHoppingSamplerConfig
+
+config = BasinHoppingSamplerConfig(
+    n_runs=50,                   # Number of independent runs
+    n_iter_no_change=1000,       # Stop after this many consecutive non-improving perturbations
+    step_size=0.05,              # Perturbation size
+    step_mode="percentage",      # "percentage" or "fixed"
+    coordinate_precision=4,      # Precision for identifying optima
+    fitness_precision=None,      # Precision for fitness values (None = full double)
+    seed=42                      # For reproducibility
+)
+
+sampler = BasinHoppingSampler(config)
+
+# Define search domain
+domain = [(-5.12, 5.12), (-5.12, 5.12)]
+
+# Run sampling
+lon = sampler.sample_to_lon(rastrigin, domain)
+```
+
+## Documentation
+
+For full documentation, visit: [https://helix-agh.github.io/lonkit](https://helix-agh.github.io/lonkit)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

lonkit-0.1.0/README.md

@@ -0,0 +1,111 @@
+<div align="center">
+    <img src="docs/assets/icon.png" alt="lonkit" width="800">
+</div>
+
+[![PyPI version](https://badge.fury.io/py/lonkit.svg)](https://pypi.org/project/lonkit/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1Ujl48ffgHg9ck1Hueh59s65OR3Q3BG99?usp=sharing)
+
+**Local Optima Networks for Continuous Optimization**
+
+lonkit is a Python library for constructing, analyzing, and visualizing Local Optima Networks (LONs) for continuous optimization problems. LONs provide a powerful way to understand the structure of fitness landscapes, revealing how local optima are connected and how difficult it may be to find global optima.
+
+## Features
+
+- **Basin-Hopping Sampling**: Efficient exploration of fitness landscapes using configurable Basin-Hopping
+- **LON Construction**: Automatic construction of Local Optima Networks from sampling data
+- **CMLON Support**: Compressed Monotonic LONs for cleaner landscape analysis
+- **Rich Metrics**: Compute landscape metrics including funnel analysis and neutrality
+- **Beautiful Visualizations**: 2D and 3D plots with support for animated GIFs
+
+## Installation
+
+```bash
+pip install lonkit
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/helix-agh/lonkit.git
+cd lonkit
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from lonkit import compute_lon, LONVisualizer, BasinHoppingSamplerConfig
+
+# Define an objective function
+def rastrigin(x: np.ndarray) -> float:
+    return 10 * len(x) + np.sum(x**2 - 10 * np.cos(2 * np.pi * x))
+
+# Construct the LON
+config = BasinHoppingSamplerConfig(
+    n_runs=20,
+    n_iter_no_change=500,
+    seed=42
+)
+lon = compute_lon(
+    rastrigin,
+    dim=2,
+    lower_bound=-5.12,
+    upper_bound=5.12,
+    config=config
+)
+
+metrics = lon.compute_metrics()
+print(f"Number of funnels: {metrics['n_funnels']}")
+print(f"Global funnels: {metrics['n_global_funnels']}")
+
+# Visualize
+viz = LONVisualizer()
+viz.plot_2d(lon, output_path="lon_2d.png")
+viz.plot_3d(lon, output_path="lon_3d.png")
+```
+
+### Compressed Monotonic LONs (CMLONs)
+
+CMLONs are a compressed representation where nodes with equal fitness that are connected get merged. This provides a cleaner view of the landscape's funnel structure.
+
+```python
+# Convert LON to CMLON
+cmlon = lon.to_cmlon()
+
+# Analyze CMLON-specific metrics
+cmlon_metrics = cmlon.compute_metrics()
+```
+
+### Custom Sampling Configuration
+
+```python
+from lonkit import BasinHoppingSampler, BasinHoppingSamplerConfig
+
+config = BasinHoppingSamplerConfig(
+    n_runs=50,                   # Number of independent runs
+    n_iter_no_change=1000,       # Stop after this many consecutive non-improving perturbations
+    step_size=0.05,              # Perturbation size
+    step_mode="percentage",      # "percentage" or "fixed"
+    coordinate_precision=4,      # Precision for identifying optima
+    fitness_precision=None,      # Precision for fitness values (None = full double)
+    seed=42                      # For reproducibility
+)
+
+sampler = BasinHoppingSampler(config)
+
+# Define search domain
+domain = [(-5.12, 5.12), (-5.12, 5.12)]
+
+# Run sampling
+lon = sampler.sample_to_lon(rastrigin, domain)
+```
+
+## Documentation
+
+For full documentation, visit: [https://helix-agh.github.io/lonkit](https://helix-agh.github.io/lonkit)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

lonkit-0.1.0/docs/api/index.md

@@ -0,0 +1,82 @@
+# API Reference
+
+Complete API documentation for lonkit.
+
+## Modules
+
+lonkit is organized into three main modules:
+
+### [LON Module](lon.md)
+
+Data structures for Local Optima Networks.
+
+- [`LON`](lon.md#lonkit.lon.LON) - Local Optima Network representation
+- [`CMLON`](lon.md#lonkit.lon.CMLON) - Compressed Monotonic LON
+- [`LONConfig`](lon.md#lonkit.lon.LONConfig) - Configuration for LON construction
+
+### [Sampling Module](sampling.md)
+
+Basin-Hopping sampling for LON construction.
+
+- [`compute_lon()`](sampling.md#lonkit.sampling.compute_lon) - High-level convenience function
+- [`BasinHoppingSampler`](sampling.md#lonkit.sampling.BasinHoppingSampler) - Sampling class
+- [`BasinHoppingSamplerConfig`](sampling.md#lonkit.sampling.BasinHoppingSamplerConfig) - Configuration
+
+### [Visualization Module](visualization.md)
+
+Plotting and animation tools.
+
+- [`LONVisualizer`](visualization.md#lonkit.visualization.LONVisualizer) - Visualization class
+
+## Quick Reference
+
+### Creating a LON
+
+```python
+from lonkit import compute_lon, BasinHoppingSamplerConfig
+
+# Simple usage
+lon = compute_lon(
+    func=objective_function,
+    dim=2,
+    lower_bound=-5.0,
+    upper_bound=5.0,
+    config=BasinHoppingSamplerConfig(n_runs=20, seed=42)
+)
+```
+
+### Analyzing a LON
+
+```python
+# Basic properties
+print(f"Optima: {lon.n_vertices}")
+print(f"Edges: {lon.n_edges}")
+print(f"Best: {lon.best_fitness}")
+
+# Compute metrics
+metrics = lon.compute_metrics()
+
+# Convert to CMLON
+cmlon = lon.to_cmlon()
+cmlon_metrics = cmlon.compute_metrics()
+```
+
+### Visualizing a LON
+
+```python
+from lonkit import LONVisualizer
+
+viz = LONVisualizer()
+
+# 2D plot
+viz.plot_2d(lon, output_path="lon.png")
+
+# 3D plot
+viz.plot_3d(lon, output_path="lon_3d.png")
+
+# Animation
+viz.create_rotation_gif(lon, output_path="lon.gif")
+
+# All visualizations
+viz.visualize_all(lon, output_folder="./output")
+```

lonkit-0.1.0/docs/api/lon.md

@@ -0,0 +1,41 @@
+# LON Module
+
+::: lonkit.lon.LON
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - from_trace_data
+        - n_vertices
+        - n_edges
+        - vertex_names
+        - vertex_fitness
+        - vertex_count
+        - get_sinks
+        - compute_metrics
+        - to_cmlon
+
+::: lonkit.lon.CMLON
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - from_lon
+        - n_vertices
+        - n_edges
+        - vertex_fitness
+        - vertex_count
+        - get_sinks
+        - get_global_sinks
+        - get_local_sinks
+        - compute_metrics
+
+::: lonkit.lon.LONConfig
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - fitness_aggregation
+        - warn_on_duplicates
+        - max_fitness_deviation
+        - eq_atol

lonkit-0.1.0/docs/api/sampling.md

@@ -0,0 +1,24 @@
+# Sampling Module
+
+::: lonkit.sampling.compute_lon
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.sampling.BasinHoppingSamplerConfig
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.sampling.BasinHoppingSampler
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - sample
+        - sample_to_lon
+
+::: lonkit.sampling.BasinHoppingResult
+    options:
+      show_root_heading: true
+      show_source: true

lonkit-0.1.0/docs/api/visualization.md

@@ -0,0 +1,16 @@
+# Visualization Module
+
+::: lonkit.visualization.LONVisualizer
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - plot_2d
+        - plot_3d
+        - create_rotation_gif
+        - visualize_all
+        - compute_edge_widths
+        - compute_node_sizes
+        - compute_lon_colors
+        - compute_cmlon_colors
+        - get_layout