From ea309f3d8f613ef89440dc0593b5a4fd5db2bb91 Mon Sep 17 00:00:00 2001 From: Li Jiawei Date: Mon, 15 Jun 2026 00:47:10 +0700 Subject: [PATCH] Rewrite README as a library-facing overview --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 100 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 75aace9..cce2c13 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,122 @@ # MOSADE -MOSADE (Multi-Objective Self-Adaptive Differential Evolution) is a Python -framework for multi-objective optimisation with real-valued decision variables. -It combines multiple differential-evolution mutation strategies, -decomposition-based environmental selection, strategy-level parameter memories, -and epsilon-constraint handling for constrained problems. - -## Repository Contents - -- `src/mosade/algorithm/`: MOSADE, differential-evolution strategies, - decomposition, selection, adaptation, archive management, and baseline - implementations. -- `src/mosade/problems/`: ZDT, DTLZ, WFG, DASCMOP, and real-world CRE benchmark - problems. -- `src/mosade/metrics/`: hypervolume, IGD, IGD+, GD, spread, and spacing. -- `src/mosade/analysis/`: result merging, plotting, sensitivity analysis, and - statistical utilities. -- `configs/`: reproducible experiment configurations. -- `scripts/`: command-line runners and result post-processing utilities. -- `tests/`: unit and smoke tests. -- `figures/`, `tables/`, `validation/`: generated outputs and summary data. - -Raw per-run experiment directories are written to `results/` and are not tracked -by Git because complete benchmark runs can be large. +[![CI](https://github.com/Levvvi/MOSADE/actions/workflows/ci.yml/badge.svg)](https://github.com/Levvvi/MOSADE/actions/workflows/ci.yml) + +**Multi-Objective Self-Adaptive Differential Evolution** — a Python library for +multi-objective optimisation over real-valued decision variables, including +constrained problems. + +MOSADE combines several differential-evolution mutation strategies under an +online, self-adaptive credit-assignment scheme, decomposition-based +environmental selection, per-strategy parameter memories, and ε-constraint +handling for constrained problems. It ships with the standard ZDT, DTLZ and WFG +suites, the constrained DAS-CMOP suite, and real-world CRE problems, together +with the usual quality indicators (HV, IGD, IGD+, GD, spread). + +It also **interoperates with [pymoo](https://pymoo.org)**: the comparison +baselines are pymoo's own algorithm implementations, run on MOSADE's problems +and scored by the same indicators, so head-to-head results are fair by +construction rather than relying on re-implemented competitors. ## Installation +From source (PyPI release forthcoming): + +```bash +git clone https://github.com/Levvvi/MOSADE.git +cd MOSADE +pip install -e . +``` + +Python 3.10 or newer is required. The optional dependency groups are +`analysis` (matplotlib/scipy/pandas for plots and statistics), `baselines` +(pymoo, for the comparison algorithms), and `dev` (pytest, ruff, build). For a +full development install: + ```bash -pip install -e ".[dev,analysis]" +pip install -e ".[dev,analysis,baselines]" ``` -Python 3.10 or newer is required. +## Quick start -## Quick Start +```python +import numpy as np +from mosade.problems import ZDT1 +from mosade.algorithm import MOSADE +from mosade.metrics import hypervolume, igd -Run the default smoke experiment: +# Pick a benchmark problem (or subclass mosade.problems.Problem with your own). +problem = ZDT1(n_var=30) -```bash -python scripts/run_experiment.py +# Run MOSADE. A fixed seed makes the run fully reproducible. (~20 s) +result = MOSADE(pop_size=100, max_evals=25_000, seed=0).run(problem) + +print("non-dominated solutions:", result.F.shape) # (200, 2) +print("function evaluations: ", result.n_evals) # 25030 + +# Score the approximation set against the analytical Pareto front. +pf = problem.pareto_front(200) +print("hypervolume (ref 1.1): ", round(hypervolume(result.F, ref=np.array([1.1, 1.1])), 4)) # ≈ 0.854 +print("IGD: ", round(igd(result.F, pf), 4)) # ≈ 0.013 ``` -Run a specific configuration: +`result.F` and `result.X` are the objective and decision vectors of the final +non-dominated set; `result.history` holds per-generation diagnostics (strategy +usage, parameter memories, convergence snapshots). + +To run a configured experiment from the command line: ```bash python scripts/run_experiment.py --config configs/smoke_test.yaml ``` -Run the test suite: +## What's inside + +- **Algorithms** (`mosade.algorithm`): `MOSADE`, plus `NSGA2` and `MOEAD` + reference implementations and a `PymooAlgorithm` adapter that runs pymoo's + algorithms as fair baselines on MOSADE's own problems. +- **Problems** (`mosade.problems`): ZDT1–4 and ZDT6, DTLZ1–4 and DTLZ7, + WFG1–9, the constrained DAS-CMOP1–9 suite, and real-world CRE problems — all + sharing one `Problem` interface with a `g(x) <= 0` feasibility convention. +- **Metrics** (`mosade.metrics`): `hypervolume`, `igd`, `igd_plus`, `gd`, + `spread`. +- **Reproducibility**: per-run seeding via NumPy's `SeedSequence` (statistically + independent streams, not offset base seeds). See `REPRODUCIBILITY.md`. + +## Benchmarking and reproduction + +The full experiment harness — multi-run benchmarking, statistical comparison +(Wilcoxon signed-rank with Holm correction and Vargha–Delaney A12 effect +sizes), and figure/table generation — lives under `experiments/` (the +`mosade_experiments` package) and is intentionally kept out of the installed +library. See `REPRODUCIBILITY.md` for the recommended workflow. + +## Testing and coverage ```bash -pytest +pytest # full suite +pytest --cov=src/mosade --cov-report=term-missing # with coverage ``` -See `REPRODUCIBILITY.md` for the recommended workflow for reproducing generated -results. +Tests: 286 passed, 5 skipped · line coverage of the shipped library +(`src/mosade`): **89%**, with CI enforcing **≥85%** on Python 3.10, 3.11 and +3.12. The 5 skipped tests are numeric cross-checks that require an optional +external reference package. + +The suite emphasises what matters for a stochastic optimiser: seed-determinism, +structural invariants (population size, decision bounds, constraint +feasibility), indicator correctness against analytically known Pareto fronts, +and regression snapshots — not line coverage for its own sake. + +## Project layout + +``` +src/mosade/ # the installable library: algorithm, problems, metrics, runner +experiments/ # thesis benchmarking and analysis tooling (not packaged) +tests/ # library test suite +configs/ # example experiment configurations +``` + +## License + +Released under the MIT License — see [LICENSE](LICENSE).