Spaces:
Running
Running
MilesCranmer
commited on
Commit
•
bc32cd3
1
Parent(s):
43bfe9e
Make docs builder copy README
Browse files- .github/workflows/docs.yml +1 -0
- docs/README.md +0 -170
.github/workflows/docs.yml
CHANGED
@@ -34,6 +34,7 @@ jobs:
|
|
34 |
run: npm install -g docsify
|
35 |
- name: "Build API docs"
|
36 |
run: |
|
|
|
37 |
pydoc-markdown --build --site-dir build -vv
|
38 |
cp docs/build/content/docs/api*.md docs/
|
39 |
for f in docs/api*.md; do mv "$f" "$f.bkup" && cat "$f.bkup" | sed '1,4d' > "$f" && rm "$f.bkup"; done
|
|
|
34 |
run: npm install -g docsify
|
35 |
- name: "Build API docs"
|
36 |
run: |
|
37 |
+
cp README.md docs/
|
38 |
pydoc-markdown --build --site-dir build -vv
|
39 |
cp docs/build/content/docs/api*.md docs/
|
40 |
for f in docs/api*.md; do mv "$f" "$f.bkup" && cat "$f.bkup" | sed '1,4d' > "$f" && rm "$f.bkup"; done
|
docs/README.md
DELETED
@@ -1,170 +0,0 @@
|
|
1 |
-
[//]: # (Logo:)
|
2 |
-
|
3 |
-
<img src="https://raw.githubusercontent.com/MilesCranmer/PySR/master/pysr_logo.svg" width="400" />
|
4 |
-
|
5 |
-
**PySR: parallel symbolic regression built on Julia, and interfaced by Python.**
|
6 |
-
|
7 |
-
Uses regularized evolution, simulated annealing, and gradient-free optimization.
|
8 |
-
|
9 |
-
| **Docs** | **pip** |
|
10 |
-
|---|---|
|
11 |
-
|[![Documentation Status](https://readthedocs.org/projects/pysr/badge/?version=latest)](https://pysr.readthedocs.io/en/latest/?badge=latest)|[![PyPI version](https://badge.fury.io/py/pysr.svg)](https://badge.fury.io/py/pysr)|
|
12 |
-
|
13 |
-
(pronounced like *py* as in python, and then *sur* as in surface)
|
14 |
-
|
15 |
-
If you find PySR useful, please cite it using the citation information given in [CITATION.md](https://github.com/MilesCranmer/PySR/blob/master/CITATION.md).
|
16 |
-
If you've finished a project with PySR, please let me know and I may showcase your work here!
|
17 |
-
|
18 |
-
|
19 |
-
### Test status:
|
20 |
-
| **Linux** | **Windows** | **macOS (intel)** | **Docker** | **Coverage** |
|
21 |
-
|---|---|---|---|---|
|
22 |
-
|[![Linux](https://github.com/MilesCranmer/PySR/actions/workflows/CI.yml/badge.svg)](https://github.com/MilesCranmer/PySR/actions/workflows/CI.yml)|[![Windows](https://github.com/MilesCranmer/PySR/actions/workflows/CI_Windows.yml/badge.svg)](https://github.com/MilesCranmer/PySR/actions/workflows/CI_Windows.yml)|[![macOS](https://github.com/MilesCranmer/PySR/actions/workflows/CI_mac.yml/badge.svg)](https://github.com/MilesCranmer/PySR/actions/workflows/CI_mac.yml)|[![Docker](https://github.com/MilesCranmer/PySR/actions/workflows/CI_docker.yml/badge.svg)](https://github.com/MilesCranmer/PySR/actions/workflows/CI_docker.yml)|[![Coverage Status](https://coveralls.io/repos/github/MilesCranmer/PySR/badge.svg?branch=master&service=github)](https://coveralls.io/github/MilesCranmer/PySR)|
|
23 |
-
|
24 |
-
|
25 |
-
Check out [SymbolicRegression.jl](https://github.com/MilesCranmer/SymbolicRegression.jl) for
|
26 |
-
the pure-Julia backend of this package.
|
27 |
-
|
28 |
-
Symbolic regression is a very interpretable machine learning algorithm
|
29 |
-
for low-dimensional problems: these tools search equation space
|
30 |
-
to find algebraic relations that approximate a dataset.
|
31 |
-
|
32 |
-
One can also
|
33 |
-
extend these approaches to higher-dimensional
|
34 |
-
spaces by using a neural network as proxy, as explained in
|
35 |
-
[2006.11287](https://arxiv.org/abs/2006.11287), where we apply
|
36 |
-
it to N-body problems. Here, one essentially uses
|
37 |
-
symbolic regression to convert a neural net
|
38 |
-
to an analytic equation. Thus, these tools simultaneously present
|
39 |
-
an explicit and powerful way to interpret deep models.
|
40 |
-
|
41 |
-
|
42 |
-
*Backstory:*
|
43 |
-
|
44 |
-
Previously, we have used
|
45 |
-
[eureqa](https://www.creativemachineslab.com/eureqa.html),
|
46 |
-
which is a very efficient and user-friendly tool. However,
|
47 |
-
eureqa is GUI-only, doesn't allow for user-defined
|
48 |
-
operators, has no distributed capabilities,
|
49 |
-
and has become proprietary (and recently been merged into an online
|
50 |
-
service). Thus, the goal
|
51 |
-
of this package is to have an open-source symbolic regression tool
|
52 |
-
as efficient as eureqa, while also exposing a configurable
|
53 |
-
python interface.
|
54 |
-
|
55 |
-
|
56 |
-
# Installation
|
57 |
-
PySR uses both Julia and Python, so you need to have both installed.
|
58 |
-
|
59 |
-
Install Julia - see [downloads](https://julialang.org/downloads/), and
|
60 |
-
then instructions for [mac](https://julialang.org/downloads/platform/#macos)
|
61 |
-
and [linux](https://julialang.org/downloads/platform/#linux_and_freebsd).
|
62 |
-
(Don't use the `conda-forge` version; it doesn't seem to work properly.)
|
63 |
-
|
64 |
-
You can install PySR with:
|
65 |
-
```bash
|
66 |
-
pip3 install pysr
|
67 |
-
python3 -c 'import pysr; pysr.install()'
|
68 |
-
```
|
69 |
-
The second line will install and update the required Julia packages, including
|
70 |
-
`PyCall.jl`.
|
71 |
-
|
72 |
-
|
73 |
-
Most common issues at this stage are solved
|
74 |
-
by [tweaking the Julia package server](https://github.com/MilesCranmer/PySR/issues/27).
|
75 |
-
to use up-to-date packages.
|
76 |
-
|
77 |
-
# Introduction
|
78 |
-
|
79 |
-
Let's create a PySR example. First, let's import
|
80 |
-
numpy to generate some test data:
|
81 |
-
```python
|
82 |
-
import numpy as np
|
83 |
-
|
84 |
-
X = 2 * np.random.randn(100, 5)
|
85 |
-
y = 2.5382 * np.cos(X[:, 3]) + X[:, 0] ** 2 - 0.5
|
86 |
-
```
|
87 |
-
We have created a dataset with 100 datapoints, with 5 features each.
|
88 |
-
The relation we wish to model is $2.5382 \cos(x_3) + x_0^2 - 0.5$.
|
89 |
-
|
90 |
-
Now, let's create a PySR model and train it.
|
91 |
-
PySR's main interface is in the style of scikit-learn:
|
92 |
-
```python
|
93 |
-
from pysr import PySRRegressor
|
94 |
-
model = PySRRegressor(
|
95 |
-
niterations=5,
|
96 |
-
populations=8,
|
97 |
-
binary_operators=["+", "*"],
|
98 |
-
unary_operators=[
|
99 |
-
"cos",
|
100 |
-
"exp",
|
101 |
-
"sin",
|
102 |
-
"inv(x) = 1/x", # Custom operator (julia syntax)
|
103 |
-
],
|
104 |
-
model_selection="best",
|
105 |
-
loss="loss(x, y) = (x - y)^2", # Custom loss function (julia syntax)
|
106 |
-
)
|
107 |
-
```
|
108 |
-
This will set up the model for 5 iterations of the search code, which contains hundreds of thousands of mutations and equation evaluations.
|
109 |
-
|
110 |
-
Let's train this model on our dataset:
|
111 |
-
```python
|
112 |
-
model.fit(X, y)
|
113 |
-
```
|
114 |
-
Internally, this launches a Julia process which will do a multithreaded search for equations to fit the dataset.
|
115 |
-
|
116 |
-
Equations will be printed during training, and once you are satisfied, you may
|
117 |
-
quit early by hitting 'q' and then \<enter\>.
|
118 |
-
|
119 |
-
After the model has been fit, you can run `model.predict(X)`
|
120 |
-
to see the predictions on a given dataset.
|
121 |
-
|
122 |
-
You may run:
|
123 |
-
```python
|
124 |
-
print(model)
|
125 |
-
```
|
126 |
-
to print the learned equations:
|
127 |
-
```python
|
128 |
-
PySRRegressor.equations = [
|
129 |
-
pick score Equation MSE Complexity
|
130 |
-
0 0.000000 3.5082064 2.710828e+01 1
|
131 |
-
1 0.964260 (x0 * x0) 3.940544e+00 3
|
132 |
-
2 0.030096 (-0.47978288 + (x0 * x0)) 3.710349e+00 5
|
133 |
-
3 0.840770 ((x0 * x0) + cos(x3)) 1.600564e+00 6
|
134 |
-
4 0.928380 ((x0 * x0) + (2.5313091 * cos(x3))) 2.499724e-01 8
|
135 |
-
5 >>>> 13.956461 ((-0.49999997 + (x0 * x0)) + (2.5382001 * cos(... 1.885665e-13 10
|
136 |
-
]
|
137 |
-
```
|
138 |
-
This arrow in the `pick` column indicates which equation is currently selected by your
|
139 |
-
`model_selection` strategy for prediction.
|
140 |
-
(You may change `model_selection` after `.fit(X, y)` as well.)
|
141 |
-
|
142 |
-
`model.equations` is a pandas DataFrame containing all equations, including callable format
|
143 |
-
(`lambda_format`),
|
144 |
-
SymPy format (`sympy_format`), and even JAX and PyTorch format
|
145 |
-
(both of which are differentiable).
|
146 |
-
|
147 |
-
Note that `PySRRegressor` stores the state of the last search, and will restart from where you left off the next time you call `.fit()`. This will cause problems if significant changes are made to the search parameters (like changing the operators). You can run `model.reset()` to reset the state.
|
148 |
-
|
149 |
-
There are several other useful features such as denoising (e.g., `denoising=True`),
|
150 |
-
feature selection (e.g., `select_k_features=3`).
|
151 |
-
For a summary of features and options, see [this docs page](https://pysr.readthedocs.io/en/latest/docs/options/).
|
152 |
-
You can see the full API at [this page](https://pysr.readthedocs.io/en/latest/docs/api-documentation/).
|
153 |
-
|
154 |
-
|
155 |
-
# Docker
|
156 |
-
|
157 |
-
You can also test out PySR in Docker, without
|
158 |
-
installing it locally, by running the following command in
|
159 |
-
the root directory of this repo:
|
160 |
-
```bash
|
161 |
-
docker build --pull --rm -f "Dockerfile" -t pysr "."
|
162 |
-
```
|
163 |
-
This builds an image called `pysr`. If you have issues building (for example, on Apple Silicon),
|
164 |
-
you can emulate an architecture that works by including: `--platform linux/amd64`.
|
165 |
-
You can then run this with:
|
166 |
-
```bash
|
167 |
-
docker run -it --rm -v "$PWD:/data" pysr ipython
|
168 |
-
```
|
169 |
-
which will link the current directory to the container's `/data` directory
|
170 |
-
and then launch ipython.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|