puggles
Fast multi-objective evolutionary optimization for Python — NSGA-II and NSGA-III, with a Rust core. Roughly 7–8× faster than pymoo and 20–30× faster than DEAP and platypus at equal solution quality.
pip install puggles # the optimizers
pip install "puggles[dashboard]" # ...plus the optional live browser dashboard
Prebuilt wheels for Linux, macOS, and Windows; Python 3.9+. No Rust toolchain needed. The core
wheel has no visual code; the dashboard is a separate wheel,
puggles-dashboard, that the [dashboard] extra
installs at the matching version.
Quick start
import puggles as pg
# ZDT1: two conflicting objectives over 10 variables in [0, 1].
def zdt1(x):
g = 1 + 9 * sum(x[1:]) / (len(x) - 1)
return [x[0], g * (1 - (x[0] / g) ** 0.5)]
problem = pg.Problem(
solution_length=10,
number_of_objectives=2,
solution_data_types=[pg.Real(0.0, 1.0)] * 10,
objective_function=zdt1, # must return a LIST, one entry per objective
direction=[-1, -1], # -1 = minimize, 1 = maximize
)
ga = pg.NSGAII(problem, population_size=100, seed=42)
ga.run(10_000) # budget in objective-function evaluations
for s in ga.get_archive(): # the Pareto front
print(s.variables, s.objectives)
Benchmarks
ZDT1, population 100, 10,000 evaluations, Apple M3. IGD lower is better — all libraries converge to the same quality, so the difference is pure algorithm overhead.
| library | ms / run | IGD |
|---|---|---|
| puggles | 31.8 | 0.0051 |
| pymoo | 215.4 | 0.0045 |
| DEAP | 843.4 | 0.0048 |
| platypus | 1062.1 | 0.0108 |
On DTLZ2 (3 objectives), NSGAIII reaches IGD 0.011 — the best of any library measured,
against pymoo's 0.076.
Features
- NSGA-II and NSGA-III (reference-point based; prefer it for 3+ objectives)
- Real, Integer, and Binary decision variables, mixable in one problem
- Constraints — bounds on objective values (
objective_constraints+constraint_operands, e.g.[1.0]with["<"]); feasible solutions always beat infeasible ones - Batch objectives —
batch_objective_function=fevaluates a whole population per call, amortizing the GIL. ~1.8× on an expensive objective; a wash on a cheap one. Works with bothNSGAIIandNSGAIII. - Permutation encoding —
permutation=Truefor ordering problems (TSP, scheduling); uses order crossover and swap mutation so solutions stay valid permutations. - Checkpoint & resume —
ga.save_state()returns JSON,ga.load_state(s)restores it, so long runs survive a restart. - Front-quality metrics —
hypervolume_2d,igd,spacing, andrun_until_hv_converged(...)to stop when the front stops improving instead of at a fixed budget. - Island model —
run_island_model(...)runs independent populations in parallel and merges their fronts (native Rust objectives only; the GIL would serialize Python callables). - Reproducible runs —
seed=42fixes the initial population, crossover, mutation, and selection, so a run repeats exactly. Omit it for fresh randomness each time. - GPU evaluation via
GpuProblemand a WGSL compute shader (experimental; build from source with--features gpu— the PyPI wheels are CPU-only) - Clear errors — invalid bounds or configuration raise
ValueError, not a Rust panic. - Built-in DTLZ1–7 benchmark problems
- Live dashboard (optional add-on) —
callback=pg.Dashboard(ga)shows the evolving front, variables, and convergence in the browser
Permutation example
import puggles as pg
POS = [0.0, 9.0, 3.0, 7.0, 1.0, 5.0, 8.0, 2.0]
tour = lambda x: [sum(abs(POS[int(a)] - POS[int(b)]) for a, b in zip(x, x[1:]))]
problem = pg.Problem(8, 1, [pg.Integer(0, 7)] * 8, tour, permutation=True)
ga = pg.NSGAII(problem, population_size=40, seed=5)
ga.run(6000)
best = min(ga.get_archive(), key=lambda s: s.objectives[0])
print(best.objectives[0], [int(v) for v in best.variables])
Reproducibility
A genetic algorithm is randomised: without a seed, two runs of identical code give different answers (on ZDT1, roughly 10% apart in IGD). Pass a seed to make a run exactly repeatable — essential for publishing a result, writing a regression test, or comparing two parameter settings without measuring noise.
a = pg.NSGAII(problem, seed=42); a.run(10_000)
b = pg.NSGAII(problem, seed=42); b.run(10_000)
# a and b produce identical fronts, down to the last bit
Seeding applies to NSGAIII too. Use it with execution_mode="sequential": multithreaded runs
interleave evaluations non-deterministically, so they are not reproducible even when seeded.
Many objectives
ga = pg.NSGAIII(problem, divisions=12, seed=42) # population derived from the reference points
ga.run(20_000)
Dashboard (optional add-on)
pip install "puggles[dashboard]" adds a live browser view of a run. It shows the Pareto front
in 2-D, 3-D, parallel coordinates or a scatter matrix, plus the decision variables, convergence
and a sortable table of solutions. To use it, pass the dashboard as the callback:
dash = pg.Dashboard(ga, objective_names=["cost", "risk"]) # opens a tab
ga.run(20_000, callback=dash) # live; the page's Stop button ends the run
dash.save("run.pgrun.json.gz") # replay: python -m puggles.dashboard run.pgrun.json.gz
dash.wait() # in a script: keep the page up until Ctrl+C
The add-on can also pause and steer a run, compare runs and seeds, show a known true front, export standalone HTML, and work remotely or in Jupyter. Its README covers all of this. It records natively, straight from the optimizer's Rust solutions, so with a built-in objective the run keeps its full multithreaded speed while you watch it.
Without the add-on, import puggles never loads it. pg.Dashboard, pg.show, pg.load and
pg.reference_front then raise an ImportError that gives the install command. Any other
callable still works as callback=.
Tuning operators
ga = pg.NSGAII(
problem,
population_size=100,
crossover_config=pg.CrossoverConfig(real_crossover="sbx", sbx_distribution_index=20.0),
mutation_config=pg.MutationConfig(real_mutation="polynomial"), # probability=None -> 1/n
)
Leave probability at None unless you have a reason: it defaults to the conventional 1/n
per-gene rate. A rate of 1.0 replaces the whole genome every generation, which is random
search, not evolution.
Status
The NSGA-II and NSGA-III cores across all three encodings are well tested and benchmarked. The GPU evaluator is experimental and untested in CI. One Python-callable problem may be optimized at a time per process — concurrent GAs over different Python objectives in threads are not supported.
Links
- Source, Rust API, and full guide: https://github.com/Entropy314/puggles
- Issues: https://github.com/Entropy314/puggles/issues
License
MIT OR Apache-2.0
Metadata
Release files for puggles 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| puggles-0.3.0.tar.gz | 214.0 kB | Without provenance | Details for puggles-0.3.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| puggles-0.3.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for puggles-0.3.0-cp39-abi3-win_amd64.whl |
| puggles-0.3.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for puggles-0.3.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| puggles-0.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for puggles-0.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| puggles-0.3.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for puggles-0.3.0-cp39-abi3-macosx_11_0_arm64.whl |
| puggles-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for puggles-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 2.7 MB
Release files / puggles-0.3.0.tar.gz
| Download URL | puggles-0.3.0.tar.gz |
|---|---|
| Size | 214.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
caee1495a2aa05e06745e854c90337fb9c3b0ce5bc3348e347957e0adc1bccf0
|
|
BLAKE2b-256 checksum How to use checksums |
b51c98998fe120f5ba601c83621c7816dbac4c33e1b99fc1ccbf2fd4ea7fb94e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / puggles-0.3.0-cp39-abi3-win_amd64.whl
| Download URL | puggles-0.3.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 421.0 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a6b746c4fdd9a0239830b9e0aec1126f98ef75c77d6ceb37881dec766485cc94
|
|
BLAKE2b-256 checksum How to use checksums |
55988d7c9b00187b14596f8eaa763d7972759525a41f134abd5016947e9ee4cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / puggles-0.3.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | puggles-0.3.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 546.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
81f83ec83c8b8453fa28672c235fea5996ab195f7159992274d49b063a7c1d61
|
|
BLAKE2b-256 checksum How to use checksums |
9323a33172229ea0c220d9ca3b20dff26081ce1557624773aed087155fa3a4a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / puggles-0.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | puggles-0.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 530.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
6643e54421d0f9ffc6bff42676f8aec8129480404548d268a3c67165ed49784b
|
|
BLAKE2b-256 checksum How to use checksums |
94ca78736bfa5635e303b0b22107125d2346fa942d03332c4dd5eae304b1dfc9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / puggles-0.3.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | puggles-0.3.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 492.5 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e48f1592251112a6c976b2ad688ebb77460b547dbbdb9d562aedda41a8bb20e6
|
|
BLAKE2b-256 checksum How to use checksums |
ac259423696697fa69729af64051d9fa7a1276aa9a7b7cf51ff6ad383adccce4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / puggles-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | puggles-0.3.0-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 510.6 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
518212d532aafdeb05d08d303b37acaf8394fb5bc54f3f7cb3f1648fcdf81a80
|
|
BLAKE2b-256 checksum How to use checksums |
632128754f5ef26e089988317e36c42c920dd15c947c447561fbecf8d02f000b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for puggles 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.