fcmaes 2.1.0__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. {fcmaes-2.1.0 → fcmaes-2.2.0}/AGENTS.md +2 -2
  2. {fcmaes-2.1.0 → fcmaes-2.2.0}/CHANGELOG.md +187 -0
  3. {fcmaes-2.1.0 → fcmaes-2.2.0}/CMakeLists.txt +2 -0
  4. {fcmaes-2.1.0 → fcmaes-2.2.0}/PKG-INFO +21 -1
  5. {fcmaes-2.1.0 → fcmaes-2.2.0}/README.adoc +64 -28
  6. {fcmaes-2.1.0 → fcmaes-2.2.0}/README.md +20 -0
  7. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/acmaesoptimizer.cpp +72 -13
  8. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/acma_bindings.cpp +32 -19
  9. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/de_bindings.cpp +17 -13
  10. fcmaes-2.2.0/_fcmaescpp/bindings/jso_bindings.cpp +82 -0
  11. fcmaes-2.2.0/_fcmaescpp/bindings/jso_bindings.hpp +9 -0
  12. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/module.cpp +2 -0
  13. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/crfmnes.cpp +4 -2
  14. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/daoptimizer.cpp +20 -10
  15. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/deoptimizer.cpp +4 -2
  16. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/acmaesoptimizer.hpp +3 -2
  17. fcmaes-2.2.0/_fcmaescpp/include/callback_context.hpp +18 -0
  18. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/evaluator.h +37 -15
  19. fcmaes-2.2.0/_fcmaescpp/include/jsooptimizer.hpp +78 -0
  20. fcmaes-2.2.0/_fcmaescpp/jsooptimizer.cpp +275 -0
  21. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/pgpe.cpp +26 -15
  22. {fcmaes-2.1.0 → fcmaes-2.2.0}/ai-context.md +49 -3
  23. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/__init__.py +2 -0
  24. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/_fcmaes_ext.pyi +18 -2
  25. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/cmaes.py +72 -6
  26. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/cmaescpp.py +26 -3
  27. fcmaes-2.2.0/fcmaes/jso.py +331 -0
  28. fcmaes-2.2.0/fcmaes/jsocpp.py +74 -0
  29. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/optimizer.py +106 -20
  30. {fcmaes-2.1.0 → fcmaes-2.2.0}/pyproject.toml +1 -1
  31. {fcmaes-2.1.0 → fcmaes-2.2.0}/.gitignore +0 -0
  32. {fcmaes-2.1.0 → fcmaes-2.2.0}/LICENSE +0 -0
  33. {fcmaes-2.1.0 → fcmaes-2.2.0}/RELEASING.md +0 -0
  34. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/CMakeLists.txt +0 -0
  35. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/acma_bindings.hpp +0 -0
  36. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/bite_bindings.cpp +0 -0
  37. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/bite_bindings.hpp +0 -0
  38. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/common.hpp +0 -0
  39. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/crfmnes_bindings.cpp +0 -0
  40. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/crfmnes_bindings.hpp +0 -0
  41. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/da_bindings.cpp +0 -0
  42. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/da_bindings.hpp +0 -0
  43. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/de_bindings.hpp +0 -0
  44. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/gil_utils.hpp +0 -0
  45. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/gtop_bindings.cpp +0 -0
  46. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/gtop_bindings.hpp +0 -0
  47. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/mode_bindings.cpp +0 -0
  48. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/mode_bindings.hpp +0 -0
  49. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/ndarray_utils.hpp +0 -0
  50. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/pareto_bindings.cpp +0 -0
  51. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/pareto_bindings.hpp +0 -0
  52. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/pgpe_bindings.cpp +0 -0
  53. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/bindings/pgpe_bindings.hpp +0 -0
  54. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/biteoptimizer.cpp +0 -0
  55. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/gtop.cpp +0 -0
  56. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGS.h +0 -0
  57. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSB.h +0 -0
  58. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/BFGSMat.h +0 -0
  59. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/BKLDLT.h +0 -0
  60. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/Cauchy.h +0 -0
  61. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/LineSearchBacktracking.h +0 -0
  62. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/LineSearchBracketing.h +0 -0
  63. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/LineSearchMoreThuente.h +0 -0
  64. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/LineSearchNocedalWright.h +0 -0
  65. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/Param.h +0 -0
  66. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/LBFGSpp/SubspaceMin.h +0 -0
  67. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/biteaux.h +0 -0
  68. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/biteopt.h +0 -0
  69. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/biteopt_asktell.h +0 -0
  70. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/biteoptimizer.hpp +0 -0
  71. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/biteort.h +0 -0
  72. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/crfmnesoptimizer.hpp +0 -0
  73. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/daoptimizer.hpp +0 -0
  74. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/deopt.h +0 -0
  75. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/deoptimizer.hpp +0 -0
  76. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/gtop.hpp +0 -0
  77. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/modeoptimizer.hpp +0 -0
  78. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/nmsopt.h +0 -0
  79. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/paretoarchive.hpp +0 -0
  80. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/paretofront2d.h +0 -0
  81. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/pcg_extras.hpp +0 -0
  82. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/pcg_random.hpp +0 -0
  83. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/pcg_uint128.hpp +0 -0
  84. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/pgpeoptimizer.hpp +0 -0
  85. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/smaesopt.h +0 -0
  86. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/include/spheropt.h +0 -0
  87. {fcmaes-2.1.0 → fcmaes-2.2.0}/_fcmaescpp/modeoptimizer.cpp +0 -0
  88. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/_native.py +0 -0
  89. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/advretry.py +0 -0
  90. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/astro.py +0 -0
  91. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/bitecpp.py +0 -0
  92. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/crfmnes.py +0 -0
  93. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/crfmnescpp.py +0 -0
  94. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/dacpp.py +0 -0
  95. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/de.py +0 -0
  96. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/decpp.py +0 -0
  97. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/diversifier.py +0 -0
  98. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/evaluator.py +0 -0
  99. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/journal.py +0 -0
  100. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/mapelites.py +0 -0
  101. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/mode.py +0 -0
  102. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/modecpp.py +0 -0
  103. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/moretry.py +0 -0
  104. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/multiretry.py +0 -0
  105. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/pareto.py +0 -0
  106. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/pgpecpp.py +0 -0
  107. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/pygmoretry.py +0 -0
  108. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/retry.py +0 -0
  109. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/test_cma.py +0 -0
  110. {fcmaes-2.1.0 → fcmaes-2.2.0}/fcmaes/testfun.py +0 -0
@@ -3,7 +3,7 @@
3
3
  This repository is **fcmaes**, a Python 3.10+ library of gradient-free
4
4
  optimizers with a C++17 backend exposed through nanobind:
5
5
 
6
- - scalar: BiteOpt, DE, CMA-ES, CR-FM-NES, PGPE, Dual Annealing, and parallel
6
+ - scalar: BiteOpt, DE, jSO, CMA-ES, CR-FM-NES, PGPE, Dual Annealing, and parallel
7
7
  retry;
8
8
  - multi-objective: MODE and the exact two-objective archive `fcmaes.pareto`;
9
9
  - quality diversity: MAP-Elites and the Diversifier.
@@ -32,7 +32,7 @@ python -m pip install pytest # the tests' only extra depende
32
32
  cd .. && python -m pytest fast-cma-es/tests -q # outside the checkout, so the installed extension is imported
33
33
  ```
34
34
 
35
- Native archive tests (CMake, GCC or Clang):
35
+ Native archive and jSO tests (CMake, GCC or Clang):
36
36
 
37
37
  ```bash
38
38
  cmake -S tests/native -B build-native -DCMAKE_BUILD_TYPE=Release
@@ -7,6 +7,193 @@ publishes that version to PyPI.
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.2.0] - 2026-11-20
11
+
12
+ Behaviour changes: PGPE (`pgpecpp`, `PGPE_C`, `Pgpe_cpp` and the
13
+ Diversifier's `'PGPE'` solver) gives different results than 2.1.0 with
14
+ `normalize=True` and bounds other than `[-1, 1]`, and returns the best
15
+ evaluated point and its objective value instead of an unevaluated point and
16
+ a rank value. Seeded C++ runs after other runs in the same process now
17
+ reproduce the first run in a fresh process. `de_cma`, `da_cma`, `bite_cma`
18
+ and `cma_bite` called directly through `Sequence.minimize` run their CMA-ES
19
+ stage again. The default `repair_z=False` keeps the CMA-ES update of 2.1.0;
20
+ `retry.minimize` and `advretry.minimize` results are unchanged except
21
+ through these fixes. See Fixed for the details.
22
+
23
+ ### Added
24
+
25
+ - Stock jSO for bounded continuous scalar optimization. `fcmaes.jso` and
26
+ `fcmaes.jsocpp` expose `minimize` and synchronous `Jso` ask/tell with a
27
+ hard evaluation cap and optional process-parallel objective evaluation.
28
+ `Jso_python` and `Jso_cpp` support retry, and `optimizer.jso_cma` starts
29
+ CMA-ES from the native jSO incumbent with a nominal 40/60 budget split.
30
+ - Links to the eight CRN/CFD simulator optimization lessons, distinguishing their native Rust/command execution from this package's in-process Python API.
31
+ - [Prompt-driven optimization tutorials](https://github.com/dietmarwo/optimization-jobs/tree/main/tutorials/agentic) demonstrate the shared agent workflow with native Rust application workers. Python objectives continue to use this package in process; these tutorials do not add a worker to fast-cma-es.
32
+ - CMA-ES option `repair_z` (default `False`) for samples that the bound
33
+ repair moved onto the bounds. The mean follows their repaired (evaluated)
34
+ points either way. With `False`, the update of 2.1.0, the evolution paths
35
+ and the rank-mu / active covariance update use the random vector `z` of
36
+ the unrepaired sample; `True` recomputes `z` from the repaired point.
37
+ Available on `cmaescpp.minimize` (single-threaded and with `workers > 1,
38
+ delayed_update=False`), `cmaescpp.ACMA_C` and `cmaes.Cmaes` (ask and
39
+ `tell(ys)`), `optimizer.Cma_cpp`, `optimizer.Cma_python` and the sequences
40
+ `optimizer.de_cma`, `jso_cma`, `da_cma`, `bite_cma` and `cma_bite`, e.g.
41
+ `advretry.minimize(..., optimizer=de_cma(1500, repair_z=True))`.
42
+ `cmaes.minimize` (used by `Cma_python`), `tell(ys, xs)`, `tell_one` and the
43
+ delayed-update paths have always derived `z` from the evaluated points and
44
+ are not affected.
45
+ - **Default:** in 2,400 matched pairs on 12 application objectives (in
46
+ fcmaes-rust, at about 63,000 evaluations per run), `False` won more
47
+ often for standalone bounded CMA-ES (222 wins against 149, 13 ties), as
48
+ the second stage of DE→CMA (217 against 62) and jSO→CMA (205 against
49
+ 75), at exactly equal work (166 against 49) and in coordinated DE→CMA
50
+ retry (74 against 43). At a quarter of that budget coordinated retry
51
+ had leaned toward `True` (72 against 58). On a 171-variable truss
52
+ jSO→CMA reached a median of 394.5 with `False` against 420.4 with
53
+ `True`. `True` was clearly better where samples keep being clipped and
54
+ the step size inflates (a 118-variable neural controller: median loss
55
+ 0.137 against 1.13).
56
+ - **When to try `True`:** runs that stop early far from the optimum with
57
+ the step-size stop (status 3 or 5), optima on or outside the bounds, and
58
+ samples clipped throughout the run. On `sum(x)` and on a sphere with half
59
+ its optimum outside `[-1,1]^20` (popsize 16, 20,000 evaluations),
60
+ `cmaescpp.minimize` reaches -19.8..-20.0 (optimum -20) and 10.3..10.7
61
+ (optimum 10) with `True`, -14.2..-16.0 and 14.5..16.9 with `False`.
62
+
63
+ ### Changed
64
+
65
+ - The jSO tutorial and `ai-context.md` state the result of the coordinated-retry
66
+ test in fcmaes-rust: with `advretry`, `jso_cma` was better than `de_cma` on
67
+ none of eight GTOP problems and significantly worse on Sagas and Messenger
68
+ full ([table](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/algorithm-portfolio.md#why-jso-is-in)).
69
+ - The READMEs and `ai-context.md` link the
70
+ [algorithm portfolio of fcmaes-rust](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/algorithm-portfolio.md), which records how the scalar
71
+ algorithms were selected and the measurements behind each decision.
72
+ - README: links the [overview of the 18 related repositories](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/repositories.md).
73
+ - The READMEs point to [experiment-craft](https://github.com/dietmarwo/experiment-craft),
74
+ which runs reproducible campaigns of the Rust job workers.
75
+ - The READMEs open with the fast-cma-es banner (`tutorials/img/fast-cma-es.png`)
76
+ instead of the animated logo; `README.md`, the PyPI description, links it by
77
+ absolute URL. The tutorials keep `logo.gif`.
78
+
79
+ ### Fixed
80
+
81
+ - CMA-ES active covariance update: it rescales the worst samples by ratios
82
+ of their `z` norms and divided by zero when a sample was told at exactly
83
+ the mean (`z = 0`), e.g. a sample clipped onto a mean that lies on a
84
+ bound, whose `z` is derived from its point. In the C++ backend this put
85
+ NaN into the covariance matrix and the run stopped (status 2): on one
86
+ variable in `[0,1]` started at 0 (sigma 0.15, popsize 31), `ACMA_C` with
87
+ `repair_z=True` or with `tell(ys, xs)` (which now updates from the points,
88
+ see below) stopped after 31 evaluations, and
89
+ `cmaescpp.minimize` with `repair_z=True` on an optimum at the start bound
90
+ after 62 to 93. Now the negative part is skipped in such a generation
91
+ (zero or non-finite norm); otherwise results are unchanged. The Python
92
+ backend replaced a zero norm by 1e-30, which kept the matrix finite but
93
+ divided by zero (RuntimeWarning) when all these norms were zero; it now
94
+ skips the same way, which changes results only in that case.
95
+ - `cmaescpp.ACMA_C.tell(ys, xs)` right after an `ask()` updated from the
96
+ `z` of the asked samples instead of the supplied points `xs`.
97
+ - `optimizer.Cma_cpp` with `sdevs=None` passed NaN step sizes to CMA-ES,
98
+ which stopped after two generations (62 evaluations at popsize 31) with
99
+ the value of a failed evaluation (1.8e308). `Sequence.minimize` passes
100
+ `sdevs=None` unless the caller supplies step sizes, so a direct call such
101
+ as `de_cma(...).minimize(fun, bounds)` skipped the CMA-ES stage of
102
+ `de_cma`, `da_cma`, `bite_cma` and `cma_bite`. `Cma_cpp` uses 0.1, its
103
+ default for `sdevs`, in that case. `retry.minimize` and
104
+ `advretry.minimize` always pass step sizes; their results are unchanged.
105
+ `Sequence.minimize` raised `UnboundLocalError` when its first stage
106
+ returned an infinite or NaN value; it keeps the first stage's point and
107
+ does not let a NaN value replace a result.
108
+ - C++ optimizers: a run with a fixed seed could give a different result
109
+ depending on what ran before it in the same process. The normal samplers
110
+ shared one `std::normal_distribution` object per source file (a
111
+ namespace-scope `static` in `evaluator.h` and one in `daoptimizer.cpp`,
112
+ present since at least 2.0.0). That object caches the second value of each
113
+ generated pair, so after a run with an odd number of normal draws the next
114
+ run started with the cached value of the earlier run instead of a value
115
+ from its own seed. Ask/tell objects stepped alternately or in different
116
+ Python threads affected each other the same way (in threads also a data
117
+ race). Each optimizer instance now owns its normal distribution. Affected:
118
+ CMA-ES (`cmaescpp.minimize`, `ACMA_C`), DE with `x0` and `input_sigma`
119
+ (`decpp.minimize`, `DE_C`), CR-FM-NES (`crfmnescpp.minimize`,
120
+ `CRFMNES_C`), PGPE (`pgpecpp.minimize`, `PGPE_C`) and the optimizer
121
+ sequences built on them. Dual Annealing draws normal values in pairs, so
122
+ its single-threaded results were not affected; it gets its own
123
+ distribution too. BiteOpt and MODE do not use the shared object. The
124
+ first run in a fresh process gives the same results as before; a later
125
+ run with the same seed reproduces the first instead of depending on the
126
+ runs before it.
127
+ - PGPE result: `pgpecpp.minimize` (and `optimizer.Pgpe_cpp`) returned an `x`
128
+ that was never evaluated, usually uninitialized memory (e.g. values like
129
+ `4.7e-315` or `6.9e-310`), and with the default `use_ranking=True` a `fun`
130
+ that was a rank value (e.g. `-0.4375` for popsize 16), not an objective
131
+ value. `PGPE_C.result()` with `use_ranking=True` returned the same rank
132
+ value as `fun` and the best point of the first generation as `x`. Both now
133
+ return the best evaluated point (decoded, inside the bounds) and its
134
+ objective value, with and without ranking. The evaluated points and the
135
+ number of evaluations are unchanged; for the stop criterion see the
136
+ `stop_fitness` entry below. Present in 2.0.0 and 2.1.0.
137
+ - PGPE start point: ADAM, which updates the center of the search
138
+ distribution, started from the raw `x0` while the center is kept in
139
+ normalized coordinates (the bounds mapped to `[-1, 1]`). After the first
140
+ generation the center jumped from the normalized `x0` to the raw `x0`
141
+ read as a normalized point: with `x0 = 1` on `[-5, 5]` the center of the second
142
+ generation lay between 4.25 and 5.75 (samples clipped to 5) instead of
143
+ within 0.75 of 1, so the search lost its start point and could
144
+ stay on a bound. Affected: every run of `pgpecpp.minimize`, `PGPE_C`,
145
+ `optimizer.Pgpe_cpp` and the Diversifier's `'PGPE'` solver with
146
+ `normalize=True` (the default) and bounds other than `[-1, 1]`, including
147
+ the random start points of `retry` and the guesses of `advretry`. ADAM
148
+ starts from the normalized `x0`; results of such runs differ from 2.1.0.
149
+ Runs with `normalize=False`, without bounds or with bounds `[-1, 1]`
150
+ evaluate the same points as before. Present in 2.0.0 and 2.1.0.
151
+ - PGPE `stop_fitness`: with `use_ranking=True` (the default of
152
+ `pgpecpp.minimize` and `optimizer.Pgpe_cpp`) it was compared with the best
153
+ rank value instead of the best objective value. The best rank value is
154
+ `-(0.5 - 1/popsize)` in every generation (`-0.4375` for popsize 16,
155
+ `-0.46875` for 32), so a `stop_fitness` above it stopped the run after
156
+ the first generation and a lower one never stopped it. It is compared with
157
+ the best objective value found, as with `use_ranking=False`. This fix
158
+ does not change runs with the default `stop_fitness=-inf` or with
159
+ `use_ranking=False`.
160
+ `PGPE_C` has no stop test. Present in 2.0.0 and 2.1.0.
161
+ - `cmaescpp.minimize` or `decpp.minimize` called from two Python threads at
162
+ the same time hung forever, and so did a CMA-ES objective that itself
163
+ calls `cmaescpp.minimize` (and a DE objective calling `decpp.minimize`).
164
+ Each of the two bindings stored the Python objective in one global
165
+ pointer guarded by a mutex that a call took while holding the GIL; the
166
+ running call needed the GIL for its next objective evaluation. Each call
167
+ now keeps its objective in its own per-call context, which also reaches
168
+ the worker threads of `workers > 1`, so such calls complete and each uses
169
+ its own objective. Results of a single call are unchanged. Present in
170
+ 2.0.0 and 2.1.0.
171
+ - `cmaescpp.minimize` and `decpp.minimize` with `workers > 1` read freed
172
+ memory: the queue between the optimizer and its evaluator threads
173
+ returned a reference to an element it had just removed (a
174
+ heap-use-after-free that AddressSanitizer reports in every such run). On
175
+ Linux this went unnoticed; on Windows two such calls running at the same
176
+ time crashed with an access violation or heap corruption. The queue now
177
+ returns a copy. The evaluation counter, the terminate flag and the stop
178
+ flag of the evaluator, written by several evaluator threads, are atomic
179
+ (ThreadSanitizer reported data races on them). Results of
180
+ single-threaded calls are unchanged. The queue code is the same in
181
+ 2.0.0 and 2.1.0.
182
+ - Tutorial text and figures that disagreed:
183
+ - Scheduling: the SBM BiteOpt section showed the single-thread `Bite1.png`; it now shows `sbmBite32.png`.
184
+ - UAV: `uav_reward.png` was a screenshot of six image-viewer windows whose legends covered the leading bars. It is redrawn from the Multi-UAV benchmark CSVs with the same means.
185
+ - Claims corrected to match the plots and tables they describe: OneForAll MMKP timing, TopTrumps random search at 20 s, EvoJax (cartpole hard, brax, waterworld, waterworld MA and the larger-budget runs), MINLP best run and Employee solve times.
186
+ - PAGMO notes a mislabelled axis and empty legend counters.
187
+ - CryptoTrading no longer shows the first run's plot as the second run's.
188
+ - Section levels in `README.adoc` and seven tutorials skipped levels. Asciidoctor reported 86 "section title out of sequence" warnings, and the HTML went from `h1` straight to `h3`/`h4`. The levels now close the gaps and keep the original nesting. `scripts/build_docs.py` prints Asciidoctor warnings and fails on them (`--failure-level WARN`), so new ones stop the documentation build.
189
+ - Broken GitHub links in the tutorials and the examples API page:
190
+ - Files that were removed from this repository (`ascent.cpp`, `gcldecpp.py`, the old `Results.adoc`) now link to their last version.
191
+ - The missing `Filter.adoc` link points to the filtering exercise in `Hospital.adoc`.
192
+ - VRPTW and fcmaes-java links use their current branch and path.
193
+ - pykep links point to the 2.6.4 release that the tutorials use.
194
+ - Moved upstream files (GillesPy2, MOBOpt, floris) and the pymoo URL are corrected.
195
+ - Two attributions to repositories that no longer exist keep their names without a dead link.
196
+
10
197
  ## [2.1.0] - 2026-10-22
11
198
 
12
199
  Behaviour changes: MODE (`modecpp` and `mode`) gives different results than
@@ -87,6 +87,7 @@ add_library(fcmaes_backend STATIC
87
87
  _fcmaescpp/daoptimizer.cpp
88
88
  _fcmaescpp/deoptimizer.cpp
89
89
  _fcmaescpp/gtop.cpp
90
+ _fcmaescpp/jsooptimizer.cpp
90
91
  _fcmaescpp/modeoptimizer.cpp
91
92
  _fcmaescpp/pgpe.cpp
92
93
  )
@@ -105,6 +106,7 @@ nanobind_add_module(_fcmaes_ext NOMINSIZE
105
106
  _fcmaescpp/bindings/da_bindings.cpp
106
107
  _fcmaescpp/bindings/de_bindings.cpp
107
108
  _fcmaescpp/bindings/gtop_bindings.cpp
109
+ _fcmaescpp/bindings/jso_bindings.cpp
108
110
  _fcmaescpp/bindings/mode_bindings.cpp
109
111
  _fcmaescpp/bindings/pgpe_bindings.cpp
110
112
  _fcmaescpp/bindings/pareto_bindings.cpp
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.2
2
2
  Name: fcmaes
3
- Version: 2.1.0
3
+ Version: 2.2.0
4
4
  Summary: Parallel gradient-free optimization for Python: black-box, multi-objective and quality-diversity search.
5
5
  Keywords: optimization,black-box,gradient-free,parallel,CMA-ES,multi-objective,quality-diversity
6
6
  Author-Email: Dietmar Wolz <drdietmarwolz@yahoo.de>
@@ -40,8 +40,14 @@ Provides-Extra: jit
40
40
  Requires-Dist: numba; extra == "jit"
41
41
  Description-Content-Type: text/markdown
42
42
 
43
+ <p align="center">
44
+ <img src="https://raw.githubusercontent.com/dietmarwo/fast-cma-es/master/tutorials/img/fast-cma-es.png" alt="fast-cma-es: gradient-free optimization for Python">
45
+ </p>
46
+
43
47
  # fcmaes
44
48
 
49
+ > **One of 18 related repositories.** The [repository overview](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/repositories.md) shows what each one does and how they connect.
50
+
45
51
  A Python 3 gradient-free optimization library.
46
52
 
47
53
  **Choosing an optimization tool?** Start with the
@@ -58,12 +64,18 @@ this Python package does not include an MCP server.
58
64
  - [C++ API](https://dietmarwo.github.io/fast-cma-es/cpp_documentation.html)
59
65
  - [Examples API](https://dietmarwo.github.io/fast-cma-es/examples_documentation.html)
60
66
  - [Native Rust implementation](https://github.com/dietmarwo/fcmaes-rust) (with PyO3 API for Python users)
67
+ - [The algorithm portfolio](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/algorithm-portfolio.md) of fcmaes-rust: which gradient-free algorithms were selected, which were benchmarked and left out, and the measurements behind each decision
61
68
  - [Optimization jobs](https://github.com/dietmarwo/optimization-jobs): durable jobs and an MCP server for AI agents, with fcmaes-rust workers
69
+ - [experiment-craft](https://github.com/dietmarwo/experiment-craft): reproducible campaigns of those jobs (parameter sweeps, dependent steps, budgets and reports); it drives the Rust workers, not this package, and is in early development
62
70
  - [AI agent context](https://github.com/dietmarwo/fast-cma-es/blob/master/ai-context.md): how an AI agent chooses, configures and validates fcmaes optimizers ([AGENTS.md](https://github.com/dietmarwo/fast-cma-es/blob/master/AGENTS.md) for coding agents)
63
71
 
64
72
 
65
73
 
66
74
 
75
+ [Prompt-driven optimization tutorials](https://github.com/dietmarwo/optimization-jobs/tree/main/tutorials/agentic) demonstrate the shared agent workflow with native Rust application workers. Python objectives continue to use this package in process; these tutorials do not add a worker to fast-cma-es.
76
+
77
+ The [eight CRN/CFD simulator lessons](https://github.com/dietmarwo/optimization-jobs/blob/main/tutorials/simulators/README.md) connect stochastic calibration, sensitivities, oscillator searches, source-allocation LP, sensor MIP and coupled-flow validation to complete campaigns. Their runnable examples use native Rust bindings and existing command/scalar-worker routes; they do not add a worker to this package.
78
+
67
79
  ## Installation
68
80
 
69
81
  ```bash
@@ -83,6 +95,14 @@ See the [full README](https://github.com/dietmarwo/fast-cma-es/blob/master/READM
83
95
  for the requirements, the [changelog](https://github.com/dietmarwo/fast-cma-es/blob/master/CHANGELOG.md) for what changed, and
84
96
  [RELEASING.md](https://github.com/dietmarwo/fast-cma-es/blob/master/RELEASING.md) for the release process.
85
97
 
98
+ ## jSO and jSO→CMA-ES
99
+
100
+ Use `fcmaes.jso` for the Python implementation or `fcmaes.jsocpp` for the
101
+ C++ backend. Both support bounded continuous optimization with a hard jSO
102
+ evaluation cap, variable-length ask/tell batches, and parallel objective
103
+ evaluation through Python processes. `fcmaes.optimizer.jso_cma` uses jSO
104
+ to start CMA-ES. See [jSO usage and parameters](tutorials/Jso.adoc).
105
+
86
106
  ## Exact 2D Pareto archive
87
107
 
88
108
  `fcmaes.pareto.ParetoArchive2D` keeps all nondominated evaluations of a
@@ -4,6 +4,8 @@
4
4
 
5
5
  = fcmaes - a Python 3 gradient-free optimization library
6
6
 
7
+ image::fast-cma-es.png[fast-cma-es: gradient-free optimization for Python,align=center]
8
+
7
9
  *Choosing an optimization tool?* Start with the
8
10
  https://github.com/dietmarwo/optimization-jobs/blob/main/ai-context.md[shared solver-selection and agent guide] or the
9
11
  https://dietmarwo.github.io/optimization-jobs/[optimization ecosystem overview].
@@ -11,12 +13,14 @@ Use fcmaes for Python black-box objectives, parallel retry, Pareto search
11
13
  and quality diversity. The guide also routes to native Rust optimization,
12
14
  LP/MIP, smooth nonlinear solvers and durable MCP jobs. This Python package
13
15
  does not include an MCP server.
16
+ https://github.com/dietmarwo/experiment-craft[experiment-craft] runs
17
+ reproducible campaigns of those jobs (parameter sweeps, dependent steps,
18
+ budgets and reports); it drives the Rust workers, not this package, and is in
19
+ early development.
14
20
 
15
21
  link:https://pepy.tech/projects/fcmaes[image:https://static.pepy.tech/badge/fcmaes[PyPI Downloads]]
16
22
  https://gitter.im/fast-cma-es/community[image:https://badges.gitter.im/Join%20Chat.svg[]]
17
23
 
18
- image::logo.gif[]
19
-
20
24
  fcmaes extends https://docs.scipy.org/doc/scipy/reference/optimize.html[scipy optimize] with additional optimization methods, fast {cpp}/Eigen-based implementations, and a coordinated parallel retry mechanism.
21
25
  It supports multi-threaded use of several gradient-free
22
26
  https://dietmarwo.github.io/fast-cma-es/fcmaes_documentation.html[algorithms] partly implemented in https://dietmarwo.github.io/fast-cma-es/cpp_documentation.html[{cpp}].
@@ -26,7 +30,7 @@ The https://dietmarwo.github.io/fast-cma-es/[documentation book] combines the AP
26
30
 
27
31
  Detailed benchmark results are available in the book's https://dietmarwo.github.io/fast-cma-es/tutorials/Performance.html[performance chapter].
28
32
 
29
- === Features
33
+ == Features
30
34
 
31
35
  - Built for optimization problems that are difficult to solve and benefit from modern many-core CPUs.
32
36
  - Supports parallel fitness evaluation and several parallel retry strategies.
@@ -35,12 +39,12 @@ Detailed benchmark results are available in the book's https://dietmarwo.github.
35
39
  - Includes the multi-objective and constrained optimizer MODE. It combines ideas from Differential Evolution and NSGA-II and supports parallel function evaluation. It also uses https://www.jstage.jst.go.jp/article/tjpnsec/11/2/11_18/_article/-char/en/[enhanced multiple constraint ranking], which improves constraint handling in engineering design problems.
36
40
  - Supports quality-diversity methods, including CVT-map-elites, a CMA-ES emitter, and the new "diversifier" meta-algorithm based on CVT-map-elites archives.
37
41
  - Offers a selection of efficient single-objective optimizers.
38
- - Provides an ask-tell interface for CMA-ES, CR-FM-NES, DE, MODE, and PGPE.
42
+ - Provides an ask-tell interface for CMA-ES, CR-FM-NES, DE, jSO, MODE, and PGPE.
39
43
 
40
- === Update: Native Rust implementation of fcmaes
44
+ == Update: Native Rust implementation of fcmaes
41
45
  See https://github.com/dietmarwo/fcmaes-rust[fcmaes-rust]. This repo is an alternative both for Rust and Python users as it provides a PyO3 API. See https://github.com/dietmarwo/fcmaes-rust/blob/main/examples/python/test_cma.py[python example].
42
46
 
43
- === Update (2.0.2): Ask Tell interface for BiteOpt
47
+ == Update (2.0.2): Ask Tell interface for BiteOpt
44
48
 
45
49
  The native BiteOpt backend now also provides an ask/tell interface through `bitecpp.Bite_C`.
46
50
  This makes it possible to parallelize a single BiteOpt optimization run:
@@ -59,31 +63,31 @@ So the rule of thumb is:
59
63
  - For cheap objective functions, prefer the standard sequential BiteOpt run or parallel retry.
60
64
  - For expensive objective functions, BiteOpt ask/tell can be a very practical way to parallelize one optimization run across several cores or workers.
61
65
 
62
- === Update: Split-Brain Automated Design of Stochastic Biochemical Circuits
66
+ == Update: Split-Brain Automated Design of Stochastic Biochemical Circuits
63
67
 
64
68
  https://github.com/dietmarwo/autoresearch-circuit[autoresearch-circuit] applies the same split-brain pattern to biochemical circuit design, inspired by the https://www.biorxiv.org/content/10.1101/2025.01.27.635147v1[CircuiTree] paper. An LLM proposes circuit topology — which genes regulate which. fcmaes tunes the kinetic rates against a noisy stochastic simulator. A validation stage stress-tests the result with knockouts, knockdowns, and parameter jitter. Structure and numbers stay separated, each handled by the right tool.
65
69
 
66
- === Update: The Split-Brain Pattern For Agentic Search
70
+ == Update: The Split-Brain Pattern For Agentic Search
67
71
  https://github.com/dietmarwo/autoresearch-trading[autoresearch-trading] applies Karpathys https://github.com/karpathy/autoresearch[autoresearch]-idea to trading algorithm optimization.
68
72
  LLMs are good at structure. Classical optimizers are good at searching numbers.
69
73
  So I built a system that separates the two. I think this pattern goes beyond trading.
70
74
  Anywhere you have a simulator and a mix of logic + tunable numbers, this approach may be useful.
71
75
 
72
- === Update: Open Source AI Optimization Assistant
76
+ == Update: Open Source AI Optimization Assistant
73
77
  See https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/Assistant.adoc[Optimization Assistant] How to set up, configure and use an open source AI optimization assistant specialized for fcmaes.
74
78
 
75
- === Update: A real case in aging research
79
+ == Update: A real case in aging research
76
80
  See https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/Simulation.adoc[Moran Process] Optimize a Moran Process. Check out if you have to optimize parameters for an expensive simulation. Includes a detailed comparison with Optuna.
77
81
 
78
- === Update: How to compute π-groups for dimensional analysis
82
+ == Update: How to compute π-groups for dimensional analysis
79
83
  See https://github.com/dietmarwo/BuckinghamExamples[BuckinghamExamples] Reveal the underlying structure of physical models by using evolutionary algorithms to fit continuous powers that maximize data collapse R^2^
80
84
  under variance constraints.
81
85
 
82
- === Update: How to compute weighted spherical t-designs
86
+ == Update: How to compute weighted spherical t-designs
83
87
 
84
88
  See https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/SphericalTDesign.adoc[Spherical t-design] Shows how to compute weighted spherical t-designs to optimize laser fusion reactor designs.
85
89
 
86
- === Update: Interaction between AI code generation and optimization
90
+ == Update: Interaction between AI code generation and optimization
87
91
 
88
92
  LLMs can help to generate code implementing a trading strategy. It can even propose ways to optimize the final return.
89
93
  https://github.com/dietmarwo/fast-cma-es/blob/master/examples/prophet_opt.py[prophet_opt.py] shows:
@@ -92,10 +96,35 @@ https://github.com/dietmarwo/fast-cma-es/blob/master/examples/prophet_opt.py[pro
92
96
  - How to identify the parameters to optimize using the AI.
93
97
  - How the parameter optimization process can be automated efficiently utilizing trading simulations executed in parallel.
94
98
 
95
- === Changes in version 2.1.0:
99
+ == Changes in version 2.2.0:
96
100
 
97
101
  The full list, with earlier versions, is in https://github.com/dietmarwo/fast-cma-es/blob/master/CHANGELOG.md[CHANGELOG.md].
98
102
 
103
+ - New jSO (`fcmaes.jso`, `fcmaes.jsocpp`): adaptive differential evolution
104
+ with a hard evaluation cap, ask/tell and retry support, and the sequence
105
+ `optimizer.jso_cma`, which starts CMA-ES from the jSO incumbent. In
106
+ coordinated retry (`advretry`) `de_cma` stays the better choice.
107
+ - CMA-ES option `repair_z` (default `False`, the update of 2.1.0): `True`
108
+ lets the evolution paths and the covariance follow samples that the bound
109
+ repair moved onto the bounds. Try it when runs stop early with the step-size
110
+ stop or when optima lie on or outside the bounds.
111
+ - PGPE: the result is the best evaluated point and its objective value, ADAM
112
+ starts from the normalized `x0`, and `stop_fitness` compares objective
113
+ values. PGPE results with bounds other than `[-1, 1]` differ from 2.1.0.
114
+ - C++ optimizers: a seeded run no longer depends on the runs before it in
115
+ the same process, and `cmaescpp.minimize` / `decpp.minimize` no longer hang
116
+ when called from two threads or from inside their own objective. With
117
+ `workers > 1` they no longer read freed memory (crashes on Windows).
118
+ - CMA-ES: a sample told at exactly the mean no longer puts NaN into the
119
+ covariance; `ACMA_C.tell(ys, xs)` after `ask()` updates from `xs`;
120
+ `Cma_cpp` with `sdevs=None` uses 0.1 instead of NaN step sizes, so sequences
121
+ such as `de_cma(...).minimize(fun, bounds)` run their CMA-ES stage.
122
+ - Tutorials: figures and claims that disagreed are corrected, section levels
123
+ are fixed and broken links repaired; the READMEs link the algorithm
124
+ portfolio of fcmaes-rust and experiment-craft.
125
+
126
+ == Changes in version 2.1.0:
127
+
99
128
  - MODE (`modecpp`, `mode`): SBX can expand beyond the parents, polynomial
100
129
  mutation no longer pins variables at their lower bound, levels are true
101
130
  non-dominated fronts, crowding uses all objectives, and a point is feasible
@@ -122,7 +151,7 @@ shared solver-selection guide of the five fcmaes and craft repositories.
122
151
  - Releases: a tag must match the version in `pyproject.toml`, and CI installs
123
152
  the source distribution and runs the tests on it.
124
153
 
125
- === Changes from version 2.0.0:
154
+ == Changes from version 2.0.0:
126
155
 
127
156
  - Switch from ctypes C++ binding to nanobind.
128
157
  - MacOS fully supported - including ARM.
@@ -130,7 +159,7 @@ the source distribution and runs the tests on it.
130
159
  - Improved type annotations
131
160
  - Improved test coverage
132
161
 
133
- === Changes from version 1.6.3:
162
+ == Changes from version 1.6.3:
134
163
 
135
164
  - Logging now based on loguru. All examples are adapted.
136
165
  - New dependency: loguru. `numba` is optional and mainly used as a speedup for MAP-Elites and some examples.
@@ -138,7 +167,7 @@ the source distribution and runs the tests on it.
138
167
  https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/ESAChallenge.adoc[ESAChallenge].
139
168
  - You can define an initial population as guess for multi objective optimization.
140
169
 
141
- === Changes from version 1.4.0:
170
+ == Changes from version 1.4.0:
142
171
 
143
172
  - Pure Python versions of the algorithms are now usable also for parallel retry. Pure Python features:
144
173
  Algorithms: CMA-ES, CR-FM-NES, DE, MODE (multiple objective), Map-Elites+Diversifier (quality diversity). All
@@ -159,7 +188,12 @@ Since fcmaes has a different focus (parallel optimizations and parallel fitness
159
188
  algorithms to https://github.com/google/evojax/tree/main/evojax/algo[EvoJax] which utilizes https://github.com/google/jax[JAX]
160
189
  for GPU/TPU execution.
161
190
 
162
- === Optimization algorithms
191
+ == Optimization algorithms
192
+
193
+ The https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/algorithm-portfolio.md[algorithm portfolio] of fcmaes-rust records how the
194
+ scalar algorithms were selected: which are in, which were benchmarked and left out,
195
+ and the measurements behind each decision. The algorithms it shares with this package
196
+ are BiteOpt, DE, jSO, CMA-ES, CR-FM-NES, PGPE and Dual Annealing.
163
197
 
164
198
  To utilize modern many-core processors all single-objective algorithms should be used with the parallel retry for cheap fitness functions, otherwise use parallel function evaluation.
165
199
 
@@ -176,6 +210,8 @@ Can also be applied to single-objective problems with constraints. Supports mixe
176
210
  - Differential Evolution: Implemented both in https://github.com/dietmarwo/fast-cma-es/blob/master/fcmaes/de.py[Python] and in https://github.com/dietmarwo/fast-cma-es/blob/master/_fcmaescpp/deoptimizer.cpp[{cpp}]. Additional concepts implemented are
177
211
  https://www.researchgate.net/publication/309179699_Differential_evolution_for_protein_folding_optimization_based_on_a_three-dimensional_AB_off-lattice_model[temporal locality], stochastic reinitialization of individuals based on their age and oscillating CR/F parameters. Provides an ask/tell interface and supports parallel function evaluation. Supports mixed integer problems (see https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/FluidDynamics.adoc[CFD] for details)
178
212
 
213
+ - jSO: Adaptive differential evolution with success-history memory and a shrinking population. `fcmaes.jso` is the Python implementation and `fcmaes.jsocpp` uses the {cpp} backend. Both honor a hard jSO evaluation budget. Use `optimizer.jso_cma` to refine the jSO incumbent with CMA-ES. See the https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/Jso.adoc[jSO tutorial].
214
+
179
215
  - CMA-ES: Implemented both in https://github.com/dietmarwo/fast-cma-es/blob/master/fcmaes/cmaes.py[Python] and in https://github.com/dietmarwo/fast-cma-es/blob/master/_fcmaescpp/acmaesoptimizer.cpp[{cpp}]. Provides an ask/tell interface and supports parallel function evaluation. Good option for low number of decision variables (< 500).
180
216
 
181
217
  - CR-FM-NES: Fast Moving Natural Evolution Strategy for High-Dimensional Problems, see
@@ -196,9 +232,9 @@ parallel function evaluation.
196
232
  - Expressions: There are two operators for constructing expressions over optimization algorithms: Sequence and random choice.
197
233
  Not only the single objective algorithms above, but also scipy and NLopt optimization methods and custom algorithms can be used for defining algorithm expressions.
198
234
 
199
- === Installation
235
+ == Installation
200
236
 
201
- ==== Linux
237
+ === Linux
202
238
 
203
239
  * `pip install fcmaes`
204
240
 
@@ -207,7 +243,7 @@ Not only the single objective algorithms above, but also scipy and NLopt optimiz
207
243
  Wheels are built by the release CI. If no matching wheel is available for your
208
244
  platform or Python version, `pip` falls back to a source build.
209
245
 
210
- ==== Windows
246
+ === Windows
211
247
 
212
248
  * `pip install fcmaes`
213
249
 
@@ -225,7 +261,7 @@ The Linux subsystem can read/write NTFS, so you can do your development on a NTF
225
261
  If performance of the fitness function is an issue and you don't want to use the Linux subsystem for Windows,
226
262
  think about using the fcmaes java port: https://github.com/dietmarwo/fcmaes-java[fcmaes-java].
227
263
 
228
- ==== MacOS
264
+ === MacOS
229
265
 
230
266
  * `pip install fcmaes`
231
267
 
@@ -233,7 +269,7 @@ The nanobind-based native backend now supports macOS as part of the wheel build
233
269
  If no matching wheel is available for your Python version or architecture, `pip`
234
270
  falls back to a source build.
235
271
 
236
- ==== From source
272
+ === From source
237
273
 
238
274
  Building from source needs:
239
275
 
@@ -261,7 +297,7 @@ cd .. && python -m pytest fast-cma-es/tests -q # run the tests outside the che
261
297
  distribution the same way. https://github.com/dietmarwo/fast-cma-es/blob/master/RELEASING.md[RELEASING.md]
262
298
  describes how releases are built and published.
263
299
 
264
- === Usage
300
+ == Usage
265
301
 
266
302
  Usage is similar to https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html[scipy.optimize.minimize].
267
303
 
@@ -288,7 +324,7 @@ ret = retry.minimize(fun, bounds, optimizer=Sequence([De_cpp(50000), Cma_cpp(500
288
324
  Here https://github.com/dietmarwo/fast-cma-es/blob/master/examples you find more examples.
289
325
  Check the https://github.com/dietmarwo/fast-cma-es/blob/master/tutorials/README.adoc[tutorials] for more details.
290
326
 
291
- === Dependencies
327
+ == Dependencies
292
328
 
293
329
  Runtime:
294
330
 
@@ -314,7 +350,7 @@ Example dependencies:
314
350
 
315
351
  - pykep: https://esa.github.io/pykep/[pykep]. Install with 'pip install pykep'.
316
352
 
317
- === Documentation
353
+ == Documentation
318
354
 
319
355
  The GitHub Pages workflow builds this README, all AsciiDoc tutorials, and the
320
356
  three maintained HTML API references as one navigable site:
@@ -342,7 +378,7 @@ short entry point for coding agents. To choose between fcmaes and the sibling
342
378
  LP/MIP, NLP and job-API projects, start at the
343
379
  https://github.com/dietmarwo/optimization-jobs/blob/main/ai-context.md[optimization-jobs entry point].
344
380
 
345
- === Packaging and release
381
+ == Packaging and release
346
382
 
347
383
  - Pull requests and branch pushes build wheels on Linux, Windows, and macOS.
348
384
  - A manual GitHub Actions run with `publish_target=testpypi` publishes to TestPyPI.
@@ -350,7 +386,7 @@ https://github.com/dietmarwo/optimization-jobs/blob/main/ai-context.md[optimizat
350
386
  - CI also installs the source distribution and runs the tests on it.
351
387
  - CI releases use Trusted Publishing, so no long-lived PyPI API token is required in GitHub Actions.
352
388
 
353
- === Citing
389
+ == Citing
354
390
 
355
391
  [source]
356
392
  ----
@@ -1,5 +1,11 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/dietmarwo/fast-cma-es/master/tutorials/img/fast-cma-es.png" alt="fast-cma-es: gradient-free optimization for Python">
3
+ </p>
4
+
1
5
  # fcmaes
2
6
 
7
+ > **One of 18 related repositories.** The [repository overview](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/repositories.md) shows what each one does and how they connect.
8
+
3
9
  A Python 3 gradient-free optimization library.
4
10
 
5
11
  **Choosing an optimization tool?** Start with the
@@ -16,12 +22,18 @@ this Python package does not include an MCP server.
16
22
  - [C++ API](https://dietmarwo.github.io/fast-cma-es/cpp_documentation.html)
17
23
  - [Examples API](https://dietmarwo.github.io/fast-cma-es/examples_documentation.html)
18
24
  - [Native Rust implementation](https://github.com/dietmarwo/fcmaes-rust) (with PyO3 API for Python users)
25
+ - [The algorithm portfolio](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/algorithm-portfolio.md) of fcmaes-rust: which gradient-free algorithms were selected, which were benchmarked and left out, and the measurements behind each decision
19
26
  - [Optimization jobs](https://github.com/dietmarwo/optimization-jobs): durable jobs and an MCP server for AI agents, with fcmaes-rust workers
27
+ - [experiment-craft](https://github.com/dietmarwo/experiment-craft): reproducible campaigns of those jobs (parameter sweeps, dependent steps, budgets and reports); it drives the Rust workers, not this package, and is in early development
20
28
  - [AI agent context](https://github.com/dietmarwo/fast-cma-es/blob/master/ai-context.md): how an AI agent chooses, configures and validates fcmaes optimizers ([AGENTS.md](https://github.com/dietmarwo/fast-cma-es/blob/master/AGENTS.md) for coding agents)
21
29
 
22
30
 
23
31
 
24
32
 
33
+ [Prompt-driven optimization tutorials](https://github.com/dietmarwo/optimization-jobs/tree/main/tutorials/agentic) demonstrate the shared agent workflow with native Rust application workers. Python objectives continue to use this package in process; these tutorials do not add a worker to fast-cma-es.
34
+
35
+ The [eight CRN/CFD simulator lessons](https://github.com/dietmarwo/optimization-jobs/blob/main/tutorials/simulators/README.md) connect stochastic calibration, sensitivities, oscillator searches, source-allocation LP, sensor MIP and coupled-flow validation to complete campaigns. Their runnable examples use native Rust bindings and existing command/scalar-worker routes; they do not add a worker to this package.
36
+
25
37
  ## Installation
26
38
 
27
39
  ```bash
@@ -41,6 +53,14 @@ See the [full README](https://github.com/dietmarwo/fast-cma-es/blob/master/READM
41
53
  for the requirements, the [changelog](https://github.com/dietmarwo/fast-cma-es/blob/master/CHANGELOG.md) for what changed, and
42
54
  [RELEASING.md](https://github.com/dietmarwo/fast-cma-es/blob/master/RELEASING.md) for the release process.
43
55
 
56
+ ## jSO and jSO→CMA-ES
57
+
58
+ Use `fcmaes.jso` for the Python implementation or `fcmaes.jsocpp` for the
59
+ C++ backend. Both support bounded continuous optimization with a hard jSO
60
+ evaluation cap, variable-length ask/tell batches, and parallel objective
61
+ evaluation through Python processes. `fcmaes.optimizer.jso_cma` uses jSO
62
+ to start CMA-ES. See [jSO usage and parameters](tutorials/Jso.adoc).
63
+
44
64
  ## Exact 2D Pareto archive
45
65
 
46
66
  `fcmaes.pareto.ParetoArchive2D` keeps all nondominated evaluations of a