helix-agh · WojtAcht · Mar 22, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.0
+
+Third public release adding support for discrete optimization problems via Iterated Local Search (ILS).
+
+### Highlights
+
+- Added a discrete optimization framework with `DiscreteProblem` abstract base class — a generic, stateless interface for defining custom discrete problems.
+- Added `BitstringProblem` base class providing out-of-the-box `random_solution()`, `local_search()`, `perturb()`, and `solution_id()` for binary-encoded problems, with configurable first-improvement (stochastic) and best-improvement (deterministic) hill climbing.
+- Added built-in problem implementations:
+  - `NumberPartitioning`: Number Partitioning Problem with configurable hardness parameter `k`, random instance generation via `instance_seed`, or explicit weights.
+  - `OneMax`: Simple maximization benchmark with O(1) delta evaluation.
+- Added `ILSSampler` and `ILSSamplerConfig` for constructing LONs from discrete problems via Iterated Local Search, with configurable stopping criteria (`n_iter_no_change`, `max_iter`) and equal-acceptance moves.
+- Discrete and continuous sampling produce the same trace format (`[run, fit1, node1, fit2, node2]`), so `LON.from_trace_data()`, `CMLON`, metrics, and visualization all work unchanged.
+
+### API and Behavior Changes
+
+- Package now exports `DiscreteProblem`, `BitstringProblem`, `NumberPartitioning`, `OneMax`, `ILSSampler`, `ILSSamplerConfig`, and `ILSResult`.
+- Internal module structure reorganized: continuous sampling moved to `lonkit.continuous.sampling`, discrete modules under `lonkit.discrete.problems` and `lonkit.discrete.sampling`.
+
+### Documentation
+
+- Updated user guide and API docs to cover the discrete framework, ILS sampling, and built-in problems.
+- Added discrete quick-start example to README.
+
 ## 0.2.0
 
 Second public release adding multiprocessing to Basin-Hopping sampling procedure.

diff --git a/README.md b/README.md
@@ -6,13 +6,14 @@
 [![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**
+**Local Optima Networks**
 
-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.
+lonkit is a Python library for constructing, analyzing, and visualizing Local Optima Networks (LONs) for both continuous and discrete 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
+- **Basin-Hopping Sampling**: Efficient exploration of continuous fitness landscapes using configurable Basin-Hopping
+- **Iterated Local Search**: Discrete LON construction via ILS with built-in problems (Number Partitioning, OneMax)
 - **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
@@ -103,6 +104,40 @@ result = sampler.sample(rastrigin, domain)
 lon = sampler.sample_to_lon(result)
 ```
 
+## Discrete Optimization Problems
+
+lonkit also supports Local Optima Networks for discrete optimization problems using Iterated Local Search (ILS).
+
+### Quick Start (Discrete)
+
+```python
+from lonkit import NumberPartitioning, ILSSampler, ILSSamplerConfig, LONVisualizer
+
+# Define problem instance
+problem = NumberPartitioning(n=20, k=0.5, instance_seed=1)
+
+# Configure and run ILS sampling
+config = ILSSamplerConfig(n_runs=50, n_iter_no_change=100, seed=42)
+sampler = ILSSampler(config)
+result = sampler.sample(problem)
+
+# Build LON and CMLON
+lon = sampler.sample_to_lon(result)
+cmlon = lon.to_cmlon()
+
+# Compute metrics
+print(lon.compute_metrics())
+print(cmlon.compute_metrics())
+
+# Visualize
+viz = LONVisualizer()
+viz.plot_2d(cmlon, output_path="npp_cmlon.png")
+```
+
+### Custom Discrete Problems
+
+You can define your own discrete problem by subclassing `DiscreteProblem`. For bitstring problems, inherit from `BitstringProblem` instead it provides `random_solution()`, `local_search()`, `perturb()`, and `solution_id()` out of the box. You only need to implement `evaluate()`.
+
 ## Documentation
 
 For full documentation, visit: [https://helix-agh.github.io/lonkit](https://helix-agh.github.io/lonkit)

diff --git a/docs/api/discrete.md b/docs/api/discrete.md
@@ -0,0 +1,43 @@
+# Discrete Module
+
+## Problems
+
+::: lonkit.discrete.problems.problem.DiscreteProblem
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.discrete.problems.bitstring.BitstringProblem
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.discrete.problems.bitstring.NumberPartitioning
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.discrete.problems.bitstring.OneMax
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Sampling
+
+::: lonkit.discrete.sampling.ILSSamplerConfig
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.discrete.sampling.ILSSampler
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - sample
+        - sample_to_lon
+
+::: lonkit.discrete.sampling.ILSResult
+    options:
+      show_root_heading: true
+      show_source: true
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -8,7 +8,7 @@ Complete API documentation for lonkit.
 
 ## Modules
 
-lonkit is organized into three main modules:
+lonkit is organized into the following modules:
 
 ### [LON Module](lon.md)
 
@@ -18,13 +18,27 @@ Data structures for Local Optima Networks.
 - [`CMLON`](lon.md#lonkit.lon.CMLON) - Compressed Monotonic LON
 - [`LONConfig`](lon.md#lonkit.lon.LONConfig) - Configuration for LON construction
 
-### [Sampling Module](sampling.md)
+### [Continuous Sampling Module](sampling.md)
 
-Basin-Hopping sampling for LON construction.
+Basin-Hopping sampling for continuous 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
+- [`compute_lon()`](sampling.md#lonkit.continuous.sampling.compute_lon) - High-level convenience function
+- [`BasinHoppingSampler`](sampling.md#lonkit.continuous.sampling.BasinHoppingSampler) - Sampling class
+- [`BasinHoppingSamplerConfig`](sampling.md#lonkit.continuous.sampling.BasinHoppingSamplerConfig) - Configuration
+- [`BasinHoppingResult`](sampling.md#lonkit.continuous.sampling.BasinHoppingResult) - Sampling result container
+- [`StepSizeEstimator`](sampling.md#lonkit.continuous.step_size.StepSizeEstimator) - Step size estimation
+- [`StepSizeEstimatorConfig`](sampling.md#lonkit.continuous.step_size.StepSizeEstimatorConfig) - Step size estimator configuration
+
+### [Discrete Module](discrete.md)
+
+Iterated Local Search sampling and built-in discrete problems.
+
+- [`DiscreteProblem`](discrete.md#lonkit.discrete.problems.problem.DiscreteProblem) - Abstract base for discrete problems
+- [`BitstringProblem`](discrete.md#lonkit.discrete.problems.bitstring.BitstringProblem) - Base class for bitstring problems
+- [`NumberPartitioning`](discrete.md#lonkit.discrete.problems.bitstring.NumberPartitioning) - Number Partitioning Problem
+- [`OneMax`](discrete.md#lonkit.discrete.problems.bitstring.OneMax) - OneMax benchmark
+- [`ILSSampler`](discrete.md#lonkit.discrete.sampling.ILSSampler) - ILS sampling class
+- [`ILSSamplerConfig`](discrete.md#lonkit.discrete.sampling.ILSSamplerConfig) - ILS configuration
 
 ### [Visualization Module](visualization.md)
 

diff --git a/docs/api/sampling.md b/docs/api/sampling.md
@@ -1,24 +1,41 @@
-# Sampling Module
+# Continuous Sampling Module
 
-::: lonkit.sampling.compute_lon
+::: lonkit.continuous.sampling.compute_lon
     options:
       show_root_heading: true
       show_source: true
 
-::: lonkit.sampling.BasinHoppingSamplerConfig
+::: lonkit.continuous.sampling.BasinHoppingSamplerConfig
     options:
       show_root_heading: true
       show_source: true
 
-::: lonkit.sampling.BasinHoppingSampler
+::: lonkit.continuous.sampling.BasinHoppingSampler
     options:
       show_root_heading: true
       show_source: true
       members:
         - sample
         - sample_to_lon
 
-::: lonkit.sampling.BasinHoppingResult
+::: lonkit.continuous.sampling.BasinHoppingResult
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Step Size Estimation
+
+::: lonkit.continuous.step_size.StepSizeEstimatorConfig
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.continuous.step_size.StepSizeEstimator
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: lonkit.continuous.step_size.StepSizeResult
     options:
       show_root_heading: true
       show_source: true
diff --git a/docs/api/step_size.md b/docs/api/step_size.md
@@ -1,16 +1,16 @@
 # Step Size Module
 
-::: lonkit.step_size.StepSizeEstimator
+::: lonkit.continuous.step_size.StepSizeEstimator
     options:
       show_root_heading: true
       show_source: true
 
-::: lonkit.step_size.StepSizeEstimatorConfig
+::: lonkit.continuous.step_size.StepSizeEstimatorConfig
     options:
       show_root_heading: true
       show_source: true
 
-::: lonkit.step_size.StepSizeResult
+::: lonkit.continuous.step_size.StepSizeResult
     options:
       show_root_heading: true
       show_source: true
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -53,7 +53,7 @@ import lonkit
 print(lonkit.__version__)
 ```
 
-You should see the version number (e.g., `0.1.0`).
+You should see the version number (e.g., `0.3.0`).
 
 ## Troubleshooting
 

diff --git a/docs/index.md b/docs/index.md
@@ -4,11 +4,11 @@ description: lonkit - Python library for constructing, analyzing, and visualizin
 
 # lonkit
 
-**Local Optima Networks for Continuous Optimization**
+**Local Optima Networks**
 
 ![lonkit](assets/icon.png){ width="100%" }
 
-lonkit is a Python library for constructing, analyzing, and visualizing Local Optima Networks (LONs) for continuous optimization problems.
+lonkit is a Python library for constructing, analyzing, and visualizing Local Optima Networks (LONs) for both continuous and discrete optimization problems.
 
 ## What are Local Optima Networks?
 
@@ -26,7 +26,13 @@ Local Optima Networks (LONs) are graph-based models that capture the global stru
 
     ---
 
-    Efficient exploration of fitness landscapes using configurable Basin-Hopping with customizable perturbation strategies
+    Efficient exploration of continuous fitness landscapes using configurable Basin-Hopping with customizable perturbation strategies
+
+- **Iterated Local Search**
+
+    ---
+
+    Discrete LON construction via ILS with built-in problems (Number Partitioning, OneMax) and custom problem support
 
 - **LON Construction**