https://user-images.githubusercontent.com/7593028/188328887-1b6cda72-2f41-439e-ae23-75dd3489bc24.mp4
# PySR: High-Performance Symbolic Regression in Python
PySR uses evolutionary algorithms to search for symbolic expressions which optimize a particular objective.
| **Docs** | **Forums** | **colab demo** |
|:---:|:---:|:---:|
|[](https://astroautomata.com/PySR/)|[](https://github.com/MilesCranmer/PySR/discussions)|[](https://colab.research.google.com/github/MilesCranmer/PySR/blob/master/examples/pysr_demo.ipynb)|
| **pip** | **conda** | **Stats** |
| :---: | :---: | :---: |
|[](https://badge.fury.io/py/pysr)|[](https://anaconda.org/conda-forge/pysr)|
pip: [](https://badge.fury.io/py/pysr)
conda: [](https://anaconda.org/conda-forge/pysr)
|
### Test status
| **Linux** | **Windows** | **macOS** |
|---|---|---|
|[](https://github.com/MilesCranmer/PySR/actions/workflows/CI.yml)|[](https://github.com/MilesCranmer/PySR/actions/workflows/CI_Windows.yml)|[](https://github.com/MilesCranmer/PySR/actions/workflows/CI_mac.yml)|
| **Docker** | **Conda** | **Coverage** |
|[](https://github.com/MilesCranmer/PySR/actions/workflows/CI_docker.yml)|[](https://github.com/MilesCranmer/PySR/actions/workflows/CI_conda_forge.yml)|[](https://coveralls.io/github/MilesCranmer/PySR)|
PySR is built on an extremely optimized pure-Julia backend: [SymbolicRegression.jl](https://github.com/MilesCranmer/SymbolicRegression.jl).
Symbolic regression is a very interpretable machine learning algorithm
for low-dimensional problems: these tools search equation space
to find algebraic relations that approximate a dataset.
One can also
extend these approaches to higher-dimensional
spaces by using a neural network as proxy, as explained in
[2006.11287](https://arxiv.org/abs/2006.11287), where we apply
it to N-body problems. Here, one essentially uses
symbolic regression to convert a neural net
to an analytic equation. Thus, these tools simultaneously present
an explicit and powerful way to interpret deep models.
*Backstory:*
Previously, we have used
[eureqa](https://www.creativemachineslab.com/eureqa.html),
which is a very efficient and user-friendly tool. However,
eureqa is GUI-only, doesn't allow for user-defined
operators, has no distributed capabilities,
and has become proprietary (and recently been merged into an online
service). Thus, the goal
of this package is to have an open-source symbolic regression tool
as efficient as eureqa, while also exposing a configurable
python interface.
## Installation
| [pip](#pip) | [conda](#conda) | [docker](#docker-build) |
|:---:|:---:|:---:|
| Everywhere (recommended) | Linux and Intel-based macOS | Everywhere (if all else fails) |
---
### pip
1. [Install Julia](https://julialang.org/downloads/)
- Alternatively, my personal preference is to use [juliaup](https://github.com/JuliaLang/juliaup#installation), which performs this automatically.
2. Then, run:
```bash
pip install -U pysr
```
3. Finally, to install Julia dependencies:
```bash
python3 -c 'import pysr; pysr.install()'
```
---
### conda
The PySR build in conda includes all required dependencies, so you can install it by simply running:
```bash
conda install -c conda-forge pysr
```
in your desired environment.
However, note that the conda install does not support precompilation of Julia libraries, so the
start time may be slightly slower as the JIT-compilation will be running.
(Once the compilation finishes, there will not be a performance difference though.)
---
### docker build
1. Clone this repo.
2. In the repo, run the build command with:
```bash
docker build -t pysr .
```
3. You can then start the container with an IPython execution with:
```bash
docker run -it --rm pysr ipython
```
For more details, see the [docker section](#docker).
---
### Common issues
Common issues tend to be related to Python not finding Julia.
To debug this, try running `python3 -c 'import os; print(os.environ["PATH"])'`.
If none of these folders contain your Julia binary, then you need to add Julia's `bin` folder to your `PATH` environment variable.
**Running PySR on macOS with an M1 processor:** you should use the pip version, and make sure to get the Julia binary for ARM/M-series processors.
## Introduction
You might wish to try the interactive tutorial [here](https://colab.research.google.com/github/MilesCranmer/PySR/blob/master/examples/pysr_demo.ipynb), which uses the notebook in `examples/pysr_demo.ipynb`.
In practice, I highly recommend using IPython rather than Jupyter, as the printing is much nicer.
Below is a quick demo here which you can paste into a Python runtime.
First, let's import numpy to generate some test data:
```python
import numpy as np
X = 2 * np.random.randn(100, 5)
y = 2.5382 * np.cos(X[:, 3]) + X[:, 0] ** 2 - 0.5
```
We have created a dataset with 100 datapoints, with 5 features each.
The relation we wish to model is $2.5382 \cos(x_3) + x_0^2 - 0.5$.
Now, let's create a PySR model and train it.
PySR's main interface is in the style of scikit-learn:
```python
from pysr import PySRRegressor
model = PySRRegressor(
niterations=40, # < Increase me for better results
binary_operators=["+", "*"],
unary_operators=[
"cos",
"exp",
"sin",
"inv(x) = 1/x",
# ^ Custom operator (julia syntax)
],
extra_sympy_mappings={"inv": lambda x: 1 / x},
# ^ Define operator for SymPy as well
loss="loss(prediction, target) = (prediction - target)^2",
# ^ Custom loss function (julia syntax)
)
```
This will set up the model for 40 iterations of the search code, which contains hundreds of thousands of mutations and equation evaluations.
Let's train this model on our dataset:
```python
model.fit(X, y)
```
Internally, this launches a Julia process which will do a multithreaded search for equations to fit the dataset.
Equations will be printed during training, and once you are satisfied, you may
quit early by hitting 'q' and then \
