x-evolution 0.1.35__tar.gz → 0.2.1__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.
- {x_evolution-0.1.35 → x_evolution-0.2.1}/.gitignore +2 -2
- {x_evolution-0.1.35 → x_evolution-0.2.1}/PKG-INFO +78 -9
- {x_evolution-0.1.35 → x_evolution-0.2.1}/README.md +68 -4
- {x_evolution-0.1.35 → x_evolution-0.2.1}/pyproject.toml +14 -8
- x_evolution-0.2.1/tests/test_evolution.py +642 -0
- x_evolution-0.2.1/x_evolution/__init__.py +2 -0
- x_evolution-0.2.1/x_evolution/cma_es.py +736 -0
- {x_evolution-0.1.35 → x_evolution-0.2.1}/x_evolution/x_evolution.py +97 -106
- x_evolution-0.1.35/x_evolution/__init__.py +0 -4
- x_evolution-0.1.35/x_evolution/update_rules.py +0 -554
- {x_evolution-0.1.35 → x_evolution-0.2.1}/LICENSE +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: x-evolution
|
|
3
|
-
Version: 0.1
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: x-evolution
|
|
5
5
|
Project-URL: Homepage, https://pypi.org/project/x-evolution/
|
|
6
6
|
Project-URL: Repository, https://github.com/lucidrains/x-evolution
|
|
@@ -31,20 +31,25 @@ Keywords: artificial intelligence,evolution,evolutionary algorithms
|
|
|
31
31
|
Classifier: Development Status :: 4 - Beta
|
|
32
32
|
Classifier: Intended Audience :: Developers
|
|
33
33
|
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
-
Classifier: Programming Language :: Python :: 3.
|
|
34
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
35
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
35
38
|
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
36
|
-
Requires-Python: >=3.
|
|
39
|
+
Requires-Python: >=3.10
|
|
37
40
|
Requires-Dist: accelerate
|
|
38
41
|
Requires-Dist: beartype
|
|
39
42
|
Requires-Dist: einops>=0.8.0
|
|
40
|
-
Requires-Dist: torch-einops-utils
|
|
43
|
+
Requires-Dist: torch-einops-utils>=0.2.4
|
|
41
44
|
Requires-Dist: torch>=2.4
|
|
45
|
+
Requires-Dist: tqdm
|
|
42
46
|
Requires-Dist: x-mlps-pytorch>=0.2.0
|
|
43
|
-
Requires-Dist: x-transformers>=2.11.23
|
|
44
47
|
Provides-Extra: examples
|
|
48
|
+
Requires-Dist: fire; extra == 'examples'
|
|
45
49
|
Requires-Dist: gymnasium[box2d]>=1.0.0; extra == 'examples'
|
|
46
50
|
Requires-Dist: gymnasium[mujoco]>=1.0.0; extra == 'examples'
|
|
47
51
|
Requires-Dist: gymnasium[other]; extra == 'examples'
|
|
52
|
+
Requires-Dist: x-transformers>=2.11.23; extra == 'examples'
|
|
48
53
|
Provides-Extra: test
|
|
49
54
|
Requires-Dist: pytest; extra == 'test'
|
|
50
55
|
Description-Content-Type: text/markdown
|
|
@@ -96,6 +101,31 @@ evo_strat()
|
|
|
96
101
|
# can also specify checkpoint_every at init and select the one with your favored fitness score for continued policy gradient learning etc
|
|
97
102
|
```
|
|
98
103
|
|
|
104
|
+
## CMA-ES
|
|
105
|
+
|
|
106
|
+
`CMAEvoStrategy` implements full-covariance CMA-ES over a low-rank adapter, so an `(m, n)` weight costs `r * (m + n)` dimensions instead of `m * n`:
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from x_evolution import CMAEvoStrategy
|
|
110
|
+
|
|
111
|
+
cma = CMAEvoStrategy(
|
|
112
|
+
model,
|
|
113
|
+
environment = environment,
|
|
114
|
+
num_generations = 100,
|
|
115
|
+
lora_rank = 1, # None for the full weight update
|
|
116
|
+
freeze_base = True, # False recenters the base every generation
|
|
117
|
+
noise_scale = 1e-2 # std of the induced weight delta
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
cma()
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Pass `sep_cma = True` for diagonal covariance. `params_to_optimize` accepts the same scopes as `EvoStrategy`; pass `scope = 'name'` to update one scope at a time. 1D parameters such as biases are skipped.
|
|
124
|
+
|
|
125
|
+
Set `merge_every = N` with `freeze_base = True` to fold the current residual into the base every `N` generations. Mirror sampling is skipped automatically on the first generation after a merge.
|
|
126
|
+
|
|
127
|
+
`train_lunar.py` switches between the two with `--algorithm es` or `--algorithm cma`.
|
|
128
|
+
|
|
99
129
|
## Distributed
|
|
100
130
|
|
|
101
131
|
Using the CLI from 🤗
|
|
@@ -107,13 +137,13 @@ $ uv run accelerate config
|
|
|
107
137
|
Then
|
|
108
138
|
|
|
109
139
|
```shell
|
|
110
|
-
$ uv run accelerate launch
|
|
140
|
+
$ uv run accelerate launch train_lunar.py
|
|
111
141
|
```
|
|
112
142
|
|
|
113
143
|
Or with `torchrun` (which can do multiple CPU processes for testing)
|
|
114
144
|
|
|
115
145
|
```shell
|
|
116
|
-
$ uv run torchrun --nproc_per_node=<N>
|
|
146
|
+
$ uv run torchrun --nproc_per_node=<N> train_lunar.py --cpu True
|
|
117
147
|
```
|
|
118
148
|
|
|
119
149
|
For a quick demo on LunarLander with 8 processes
|
|
@@ -124,14 +154,16 @@ $ uv run torchrun --nproc_per_node=8 train_lunar.py --cpu True --noise_populatio
|
|
|
124
154
|
|
|
125
155
|
## Sim-to-Real Bipedal Locomotion (Microduck)
|
|
126
156
|
|
|
127
|
-
|
|
157
|
+
Train a command-conditioned walking gait for the [Microduck](https://github.com/pollen-robotics/reachy2_microduck) biped robot from scratch using `EvoStrategy` and `torchrun`. The four driven leg joints follow an inline `CPG`; the policy controls swing, knee scale, phase offsets, and the remaining joint targets.
|
|
128
158
|
|
|
129
|
-
With
|
|
159
|
+
With 8 CPU processes, a stable gait typically emerges within a few hundred generations:
|
|
130
160
|
|
|
131
161
|
```shell
|
|
132
162
|
$ uv run torchrun --nproc_per_node=8 train_microduck.py
|
|
133
163
|
```
|
|
134
164
|
|
|
165
|
+
Training samples random linear and angular velocity commands by default. Evaluations use `--eval_command` (default `0.15,0`); rendered videos show a 3D arrow above the duck's head pointing along the commanded motion. Use `--horizon 800` for 16-second episodes.
|
|
166
|
+
|
|
135
167
|
To render evaluation videos or resume from the saved best checkpoint:
|
|
136
168
|
|
|
137
169
|
```shell
|
|
@@ -200,4 +232,41 @@ Special thanks to [Pollen Robotics 🤗](https://www.pollen-robotics.com/) for t
|
|
|
200
232
|
}
|
|
201
233
|
```
|
|
202
234
|
|
|
235
|
+
```bibtex
|
|
236
|
+
@article{hansen2001completely,
|
|
237
|
+
title = {Completely Derandomized Self-Adaptation in Evolution Strategies},
|
|
238
|
+
author = {Hansen, Nikolaus and Ostermeier, Andreas},
|
|
239
|
+
journal = {Evolutionary Computation},
|
|
240
|
+
year = {2001},
|
|
241
|
+
volume = {9},
|
|
242
|
+
number = {2},
|
|
243
|
+
pages = {159--195},
|
|
244
|
+
doi = {10.1162/106365601750190398}
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
```bibtex
|
|
249
|
+
@inproceedings{ros2008simple,
|
|
250
|
+
title = {A Simple Modification in {CMA-ES} Achieving Linear Time and Space Complexity},
|
|
251
|
+
author = {Ros, Raymond and Hansen, Nikolaus},
|
|
252
|
+
booktitle = {Parallel Problem Solving from Nature ({PPSN X})},
|
|
253
|
+
series = {Lecture Notes in Computer Science},
|
|
254
|
+
volume = {5199},
|
|
255
|
+
pages = {296--305},
|
|
256
|
+
year = {2008},
|
|
257
|
+
doi = {10.1007/978-3-540-87700-4_30}
|
|
258
|
+
}
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
```bibtex
|
|
262
|
+
@inproceedings{akimoto2014comparison,
|
|
263
|
+
title = {Comparison-Based Natural Gradient Optimization in High Dimension},
|
|
264
|
+
author = {Akimoto, Youhei and Auger, Anne and Hansen, Nikolaus},
|
|
265
|
+
booktitle = {Proceedings of the Genetic and Evolutionary Computation Conference ({GECCO})},
|
|
266
|
+
pages = {373--380},
|
|
267
|
+
year = {2014},
|
|
268
|
+
doi = {10.1145/2576768.2598258}
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
203
272
|
*Nothing makes sense except in the light of evolution* - Theodosius Dobzhansky
|
|
@@ -45,6 +45,31 @@ evo_strat()
|
|
|
45
45
|
# can also specify checkpoint_every at init and select the one with your favored fitness score for continued policy gradient learning etc
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
## CMA-ES
|
|
49
|
+
|
|
50
|
+
`CMAEvoStrategy` implements full-covariance CMA-ES over a low-rank adapter, so an `(m, n)` weight costs `r * (m + n)` dimensions instead of `m * n`:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from x_evolution import CMAEvoStrategy
|
|
54
|
+
|
|
55
|
+
cma = CMAEvoStrategy(
|
|
56
|
+
model,
|
|
57
|
+
environment = environment,
|
|
58
|
+
num_generations = 100,
|
|
59
|
+
lora_rank = 1, # None for the full weight update
|
|
60
|
+
freeze_base = True, # False recenters the base every generation
|
|
61
|
+
noise_scale = 1e-2 # std of the induced weight delta
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
cma()
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Pass `sep_cma = True` for diagonal covariance. `params_to_optimize` accepts the same scopes as `EvoStrategy`; pass `scope = 'name'` to update one scope at a time. 1D parameters such as biases are skipped.
|
|
68
|
+
|
|
69
|
+
Set `merge_every = N` with `freeze_base = True` to fold the current residual into the base every `N` generations. Mirror sampling is skipped automatically on the first generation after a merge.
|
|
70
|
+
|
|
71
|
+
`train_lunar.py` switches between the two with `--algorithm es` or `--algorithm cma`.
|
|
72
|
+
|
|
48
73
|
## Distributed
|
|
49
74
|
|
|
50
75
|
Using the CLI from 🤗
|
|
@@ -56,13 +81,13 @@ $ uv run accelerate config
|
|
|
56
81
|
Then
|
|
57
82
|
|
|
58
83
|
```shell
|
|
59
|
-
$ uv run accelerate launch
|
|
84
|
+
$ uv run accelerate launch train_lunar.py
|
|
60
85
|
```
|
|
61
86
|
|
|
62
87
|
Or with `torchrun` (which can do multiple CPU processes for testing)
|
|
63
88
|
|
|
64
89
|
```shell
|
|
65
|
-
$ uv run torchrun --nproc_per_node=<N>
|
|
90
|
+
$ uv run torchrun --nproc_per_node=<N> train_lunar.py --cpu True
|
|
66
91
|
```
|
|
67
92
|
|
|
68
93
|
For a quick demo on LunarLander with 8 processes
|
|
@@ -73,14 +98,16 @@ $ uv run torchrun --nproc_per_node=8 train_lunar.py --cpu True --noise_populatio
|
|
|
73
98
|
|
|
74
99
|
## Sim-to-Real Bipedal Locomotion (Microduck)
|
|
75
100
|
|
|
76
|
-
|
|
101
|
+
Train a command-conditioned walking gait for the [Microduck](https://github.com/pollen-robotics/reachy2_microduck) biped robot from scratch using `EvoStrategy` and `torchrun`. The four driven leg joints follow an inline `CPG`; the policy controls swing, knee scale, phase offsets, and the remaining joint targets.
|
|
77
102
|
|
|
78
|
-
With
|
|
103
|
+
With 8 CPU processes, a stable gait typically emerges within a few hundred generations:
|
|
79
104
|
|
|
80
105
|
```shell
|
|
81
106
|
$ uv run torchrun --nproc_per_node=8 train_microduck.py
|
|
82
107
|
```
|
|
83
108
|
|
|
109
|
+
Training samples random linear and angular velocity commands by default. Evaluations use `--eval_command` (default `0.15,0`); rendered videos show a 3D arrow above the duck's head pointing along the commanded motion. Use `--horizon 800` for 16-second episodes.
|
|
110
|
+
|
|
84
111
|
To render evaluation videos or resume from the saved best checkpoint:
|
|
85
112
|
|
|
86
113
|
```shell
|
|
@@ -149,4 +176,41 @@ Special thanks to [Pollen Robotics 🤗](https://www.pollen-robotics.com/) for t
|
|
|
149
176
|
}
|
|
150
177
|
```
|
|
151
178
|
|
|
179
|
+
```bibtex
|
|
180
|
+
@article{hansen2001completely,
|
|
181
|
+
title = {Completely Derandomized Self-Adaptation in Evolution Strategies},
|
|
182
|
+
author = {Hansen, Nikolaus and Ostermeier, Andreas},
|
|
183
|
+
journal = {Evolutionary Computation},
|
|
184
|
+
year = {2001},
|
|
185
|
+
volume = {9},
|
|
186
|
+
number = {2},
|
|
187
|
+
pages = {159--195},
|
|
188
|
+
doi = {10.1162/106365601750190398}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```bibtex
|
|
193
|
+
@inproceedings{ros2008simple,
|
|
194
|
+
title = {A Simple Modification in {CMA-ES} Achieving Linear Time and Space Complexity},
|
|
195
|
+
author = {Ros, Raymond and Hansen, Nikolaus},
|
|
196
|
+
booktitle = {Parallel Problem Solving from Nature ({PPSN X})},
|
|
197
|
+
series = {Lecture Notes in Computer Science},
|
|
198
|
+
volume = {5199},
|
|
199
|
+
pages = {296--305},
|
|
200
|
+
year = {2008},
|
|
201
|
+
doi = {10.1007/978-3-540-87700-4_30}
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```bibtex
|
|
206
|
+
@inproceedings{akimoto2014comparison,
|
|
207
|
+
title = {Comparison-Based Natural Gradient Optimization in High Dimension},
|
|
208
|
+
author = {Akimoto, Youhei and Auger, Anne and Hansen, Nikolaus},
|
|
209
|
+
booktitle = {Proceedings of the Genetic and Evolutionary Computation Conference ({GECCO})},
|
|
210
|
+
pages = {373--380},
|
|
211
|
+
year = {2014},
|
|
212
|
+
doi = {10.1145/2576768.2598258}
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
152
216
|
*Nothing makes sense except in the light of evolution* - Theodosius Dobzhansky
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "x-evolution"
|
|
3
|
-
version = "0.1
|
|
3
|
+
version = "0.2.1"
|
|
4
4
|
description = "x-evolution"
|
|
5
5
|
authors = [
|
|
6
6
|
{ name = "Phil Wang", email = "lucidrains@gmail.com" }
|
|
7
7
|
]
|
|
8
8
|
readme = "README.md"
|
|
9
|
-
requires-python = ">= 3.
|
|
9
|
+
requires-python = ">= 3.10"
|
|
10
10
|
license = { file = "LICENSE" }
|
|
11
11
|
keywords = [
|
|
12
12
|
'artificial intelligence',
|
|
@@ -19,7 +19,10 @@ classifiers=[
|
|
|
19
19
|
'Intended Audience :: Developers',
|
|
20
20
|
'Topic :: Scientific/Engineering :: Artificial Intelligence',
|
|
21
21
|
'License :: OSI Approved :: MIT License',
|
|
22
|
-
'Programming Language :: Python :: 3.
|
|
22
|
+
'Programming Language :: Python :: 3.10',
|
|
23
|
+
'Programming Language :: Python :: 3.11',
|
|
24
|
+
'Programming Language :: Python :: 3.12',
|
|
25
|
+
'Programming Language :: Python :: 3.13',
|
|
23
26
|
]
|
|
24
27
|
|
|
25
28
|
dependencies = [
|
|
@@ -27,9 +30,9 @@ dependencies = [
|
|
|
27
30
|
"beartype",
|
|
28
31
|
"einops>=0.8.0",
|
|
29
32
|
"torch>=2.4",
|
|
30
|
-
"torch-einops-utils",
|
|
31
|
-
"
|
|
32
|
-
"x-
|
|
33
|
+
"torch-einops-utils>=0.2.4",
|
|
34
|
+
"tqdm",
|
|
35
|
+
"x-mlps-pytorch>=0.2.0"
|
|
33
36
|
]
|
|
34
37
|
|
|
35
38
|
[project.urls]
|
|
@@ -39,9 +42,11 @@ Repository = "https://github.com/lucidrains/x-evolution"
|
|
|
39
42
|
[project.optional-dependencies]
|
|
40
43
|
|
|
41
44
|
examples = [
|
|
45
|
+
"fire",
|
|
42
46
|
"gymnasium[box2d]>=1.0.0",
|
|
43
47
|
"gymnasium[mujoco]>=1.0.0",
|
|
44
|
-
"gymnasium[other]"
|
|
48
|
+
"gymnasium[other]",
|
|
49
|
+
"x-transformers>=2.11.23"
|
|
45
50
|
]
|
|
46
51
|
|
|
47
52
|
test = [
|
|
@@ -71,8 +76,9 @@ allow-direct-references = true
|
|
|
71
76
|
packages = ["x_evolution"]
|
|
72
77
|
|
|
73
78
|
[tool.hatch.build.targets.sdist]
|
|
74
|
-
include = [
|
|
79
|
+
only-include = [
|
|
75
80
|
"x_evolution",
|
|
81
|
+
"tests",
|
|
76
82
|
"README.md",
|
|
77
83
|
"LICENSE",
|
|
78
84
|
"pyproject.toml",
|