Skip to main content

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=f evaluates a whole population per call, amortizing the GIL. ~1.8× on an expensive objective; a wash on a cheap one. Works with both NSGAII and NSGAIII.
  • Permutation encoding — permutation=True for 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, and run_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=42 fixes the initial population, crossover, mutation, and selection, so a run repeats exactly. Omit it for fresh randomness each time.
  • GPU evaluation via GpuProblem and 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.

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)

Source distribution for puggles 0.3.0
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)

Table of built distributions (wheels) for puggles 0.3.0
File Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page