nasa / bingo

master:

develop:

Description

Bingo is an open source package for performing symbolic regression, though it can be used as a general purpose evolutionary optimization package.

Key Features

• Integrated local optimization strategies
• Parallel island evolution strategy implemented with mpi4py
• Coevolution of fitness predictors

Quick Start

Documentation

Full Documentation Here

Installation

To install Bingo, simply use pip. Unfortunately the pip install is currently not working. Please use source install for the time being.

pip install bingo-nasa

Usage Example

A no-fuss way of using Bingo is by using the scikit-learn wrapper: SymbolicRegressor. Let's setup a test case to show how it works.

Setting Up the Regressor

There are many options that can be set in SymbolicRegressor. Here we set some basic ones including population_size (the number of equations in a population), stack_size (the max number of nodes per equation), and use_simplification (whether to use simplification to speed up equation evaluation and for easier reading). You can see all of SymbolicRegressor's options here.

from bingo.symbolic_regression.symbolic_regressor import SymbolicRegressor
regressor = SymbolicRegressor(population_size=100, stack_size=16,
                              use_simplification=True)

/home/gbomarit/Projects/Genetic_Programming/bingo/bingo/symbolic_regression/__init__.py:31: UserWarning: Could not load C++ modules No module named 'bingocpp.build.bingocpp'
  warnings.warn(f"Could not load C++ modules {import_err}")

Training Data

Here we're just creating some dummy training data from the equation $5.0 X_0^2 + 3.5 X_0$. More on training data can be found in the data formatting guide.

import numpy as np
X_0 = np.linspace(-10, 10, num=30).reshape((-1, 1))
X = np.array(X_0)
y = 5.0 * X_0 ** 2 + 3.5 * X_0

import matplotlib.pyplot as plt
plt.scatter(X, y)
plt.xlabel("X_0")
plt.ylabel("y")
plt.title("Training Data")
plt.show()

Fitting the Regressor

Fitting is as simple as calling the .fit() method.

regressor.fit(X, y)

using 1 processes
 Generating a diverse population took 274 iterations.
archipelago: <class 'bingo.evolutionary_optimizers.island.Island'>
done with opt, best_ind: X_0 + (5.0)((0.49999999999999967)(X_0) + (X_0)(X_0)), fitness: 5.4391466376923e-28
reran CLO, best_ind: X_0 + (5.0)((0.4999999999999999)(X_0) + (X_0)(X_0)), fitness: 5.352980018399097e-28

Getting the Best Individual

best_individual = regressor.get_best_individual()
print("best individual is:", best_individual)

best individual is: X_0 + (5.0)((0.4999999999999999)(X_0) + (X_0)(X_0))

Predicting Data with the Best Individual

You can use the regressor's .predict(X) or the best_individual's .evaluate_equation_at(X) to get its predictions for X.

pred_y = regressor.predict(X)
pred_y = best_individual.evaluate_equation_at(X)

plt.scatter(X, y)
plt.plot(X, pred_y, 'r')
plt.xlabel("X_0")
plt.ylabel("y")
plt.legend(["Actual", "Predicted"])
plt.show()

Source

Installation from Source

For those looking to develop their own features in Bingo.

First clone the repo and move into the directory:

git clone --recurse-submodules https://github.com/nasa/bingo.git
cd bingo

Then make sure you have the requirements necessary to use Bingo:

pip install -r requirements.txt

or

conda install --channel conda-forge --file requirements.txt

(Optional) Then build the c++ performance library BingoCpp:

./.build_bingocpp.sh

Now you should be good to go! You can run Bingo's test suite to make sure that the installation process worked properly:

pytest tests

Add Bingo to your Python path to begin using it from other directories.

export PYTHONPATH="$PYTHONPATH:/path/to/bingo/"

and test it with:

python -c 'import bingo; import bingocpp'

Contributing

1. Fork it (https://github.com/nasa/bingo/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

Citing Bingo

Please consider citing the following reference when using bingo in your works.

MLA:

Randall, David L., et al. "Bingo: a customizable framework for symbolic regression with genetic programming." Proceedings of the Genetic and Evolutionary Computation Conference Companion. 2022.

Bibtex:

@inproceedings{randall2022bingo,
  title={Bingo: a customizable framework for symbolic regression with genetic programming},
  author={Randall, David L and Townsend, Tyler S and Hochhalter, Jacob D and Bomarito, Geoffrey F},
  booktitle={Proceedings of the Genetic and Evolutionary Computation Conference Companion},
  pages={2282--2288},
  year={2022}
}

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Geoffrey Bomarito
• Tyler Townsend
• Jacob Hochhalter
• David Randall
• Ethan Adams
• Kathryn Esham
• Diana Vera

License

Copyright 2018 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. No copyright is claimed in the United States under Title 17, U.S. Code. All Other Rights Reserved.

The Bingo Mini-app framework is licensed under the Apache License, Version 2.0 (the "License"); you may not use this application except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 .

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

bingo's Issues

Feature request: add a comparison of BINGO with other genetic algorithm + symbolic regression packages in the README

The main one that comes to mind is gplearn, which I came across in the following article:

Weng, B.; Song, Z.; Zhu, R.; Yan, Q.; Sun, Q.; Grice, C. G.; Yan, Y.; Yin, W. J. Simple Descriptor Derived from Symbolic Regression Accelerating the Discovery of New Perovskite Catalysts. Nature Communications 2020, 11 (1), 1–8. https://doi.org/10.1038/s41467-020-17263-9.

And of course some others are out there.

Feature request: Show a comparison of Bingo to non-symbolic regression in docs/README

How do you assess whether a physics-regularized fitness function surpass the performance of non-SR state-of-the-art machine learning algorithms (accuracy, uncertainty, extrapolability, interpretability, etc.)?

AGraph.Distance

The Distance function compares row-wise for each element to see if they match. However, how does this reflect to AGraphs with the same equation tree, but with different command arrays. For example let,

command_array_1 = [[LOADX, 0, 0],
                   [LOADX, 1, 1],
                   [LOADC, 0, 0],
                   [MULTI, 0, 2]]

and

command_array_2 = [[LOADX, 0, 0],
                   [LOADC, 0, 0],
                   [MULTI, 0, 1],
                   [LOADX, 1, 1]]

And distance(command_array_1, command_array_2) = 8 since the first row is the same, and the 0 in the 1st column-index of the 2nd row-index is in both arrays. However they both describe an equation f(x) = c_0 * x_0. Should the distance reflect the AGraphs or the command arrays?

Explicit/Implicit TrainingData read access to data

In implicit and explicit training data, the parameters of x and y (or dx_dt for implicit) are passed to the constructor to create a new instance. However, the constructor verifies that the data is shaped correctly. Because the member variables are exposed for both read and write access, this reshaping can be skipped and the data structure can be broken. Add read only properties to the values.

ImportError: libmpi.so.12: cannot open shared object file: No such file or directory

Hi,

I have installed Bingo with the following steps:

conda create -n bingo python=3.8
conda activate bingo
conda install --channel conda-forge --file requirements.txt
./.build_bingocpp.sh
pip install .

The installation was successful, but when I run pytest tests I get the error message:

ImportError: libmpi.so.12: cannot open shared object file: No such file or directory

This seems to be an issue with conda rather than Bingo itself, there is an easy fix by including in the bash:

export LD_LIBRARY_PATH=~/anaconda3/lib:$LD_LIBRARY_PATH

Maybe it would be good to put that in the README file for anybody else having this problem. Notice also that the mpi seems to work only with Python 3.8, otherwise I cannot even install this library.

Add text discription to the repository

Currently, the only place that this repository is described is in the README.md. All that is currently shown in the description field is No description, website, or topics provided. The first line of the README.md could probably work Bingo is an open source package for performing symbolic regression

How to implement seeding with Bingo

How/where in the codebase does this get implemented? I assume that this takes the form of artificially imposing certain equations in the initial population gene pool

relative error for fitness function

Hi there I'm a new bingo user,
sometimes, especially when the value of the fitness function vastly varies, it useful to have relative errors. I saw there are different errors definition, so this functionality might just be added there. or simply when evaluating the fitness function.

Best regards and thanks for the great tool.

Import Fitness Function cpp

Create a fitness function cpp class.