Metadata-Version: 2.1
Name: pycego
Version: 1.3.0
Summary: C++->python wrapper of C++11 Evolutionary Global Optimization (CEGO)
Author-Email: Ian Bell <ian.bell@nist.gov>
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# CEGO

CEGO (pronounced *sea-go*) is C++11 Evolutionary Global Optimization.  This library is used to:

* Solve unconstrained global optimization problems (Soft bound constraints can be added to the objective function as needed)
* The input variables can be constrained to be integers (see [PressureVesselOptimization](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/PressureVesselOptimization.ipynb)  )

It allows for:

* A flexible C++11 architecture for doing parallel global optimization with multithreading
    * Also allows for new evolutionary optimization techniques to be specified with a minimum of code
    * Uses the age-layered approach
* A fundamental C++ datatype (``CEGO::numberish``) that can be either an integer or a floating double precision value
* Python wrappers of the core of the library (single-threaded)

The C++ API documentation (generated by [doxygen](http://www.doxygen.nl/) ) is [available here](CEGO-1.0-doxygen.pdf)

Automated Tests on Github Actions: [![build and run tests](https://github.com/usnistgov/CEGO/actions/workflows/runcatch.yml/badge.svg)](https://github.com/usnistgov/CEGO/actions/workflows/runcatch.yml)

## Examples:

Try it in your browser: [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/usnistgov/CEGO/master)

Statically rendered examples are provided as Jupyter notebooks served on nbviewer ([link to folder](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks?flush_cache=true)), roughly sorted in terms of complexity of the example:

* [Hundred-digit challenge](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/HundredDigit.ipynb) (Simple 2D optimization problem)
* [Griewangk](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/Griewangk.ipynb) (10-dimensional double precision optimization)
* [PressureVesselOptimization](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/PressureVesselOptimization.ipynb) (MINLP optimization of pressure vessel mass)
* [SpringOptimization](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/SpringOptimization.ipynb) (MINLP optimization of spring mass)
* [Inverse Gaussian bumps](https://nbviewer.jupyter.org/github/usnistgov/CEGO/tree/master/notebooks/InverseBumps.ipynb) (inverse modeling with Gaussian bumps)

## License

*MIT licensed (see LICENSE for specifics), not subject to copyright in the USA. Foreign Rights Reserved, Secretary of Commerce.

## Dependencies

* Unmodified [Eigen](https://eigen.tuxfamily.org/dox/) for matrix operations
* Unmodified [nlohmann::json](https://github.com/nlohmann/json) for JSON management
* Unmodified [pybind11](https://github.com/pybind/pybind11) for C++ <-> Python interfacing
* Unmodified [ThreadPool2](https://github.com/stfx/ThreadPool2) for thread pooling

## Contributing/Getting Help

If you would like to contribute to ``CEGO`` or report a problem, please open a pull request or submit an issue.  Especially welcome would be additional tests.  

If you want to discuss or request assistance, please open an issue.

To get started, you should check out the Jupyter notebooks in the notebooks folder; they demonstrate some of the capabilities of CEGO.

## Installation


### Prerequisites

You will need:

* cmake (on windows, install from cmake, on linux ``sudo apt install cmake`` should do it, on OSX, ``brew install cmake``)
* Python (the anaconda distribution is used by the authors)
* a compiler (on windows, Visual Studio 2015+ (express version is fine), g++ on linux/OSX)

If on linux you use Anaconda and end up with an error something like
```
ImportError: /home/theuser/anaconda3/bin/../lib/libstdc++.so.6: version `GLIBCXX_3.4.20' not found (required by /home/theuser/anaconda3/lib/python3.6/site-packages/CEGO.cpython-35m-x86_64-linux-gnu.so)
```
it can be sometimes fixed by installing ``libgcc`` with conda: ``conda install libgcc``.  [This is due to an issue in Anaconda](https://github.com/ContinuumIO/anaconda-issues/issues/483)

## To install in one line from github (easiest)

This will download the sources into a temporary directory and build and install the python extension so long as you have the necessary prerequisites:
```
pip install git+git://github.com/usnistgov/CEGO.git
```

### From a cloned repository

Alternatively, you can clone (recursively!) and run the ``setup.py`` script

```
git clone --recursive https://github.com/usnistgov/CEGO
cd CEGO
python setup.py install
```

to install, or 

```
python setup.py develop
```

to use a locally-compiled version for testing.  If you want to build a debug version, you can do so with

```
python setup.py build -g develop
```
With a debug build, you can step into the debugger to debug the C++ code, for instance.  

### Cmake build

Starting in the root of the repo (a debug build with the default compiler, here on linux):

``` 
git clone --recursive https://github.com/usnistgov/CEGO
cd CEGO
mkdir build
cd build
cmake ..
cmake --build .
```
For those using Anaconda on Linux, please use the following for cmake:
```
mkdir build
cd build
cmake .. -DPYTHON_EXECUTABLE=`which python`
cmake --build .
```
For Visual Studio 2015 (64-bit) in release mode, you would do:
``` 
git clone --recursive https://github.com/usnistgov/CEGO
cd CEGO
mkdir build
cd build
cmake .. -G "Visual Studio 14 2015 Win64"
cmake --build . --config Release
```

If you need to update your submodules (pybind11 and friends)

```
git submodule update --init
```

For other options, see the cmake docs


## Debugging

* ``lstopo`` from the hwloc package can tell you the physical configuration of the cores
* ``taskset --cpu-list 0-23 nohup ./Main &`` will run on the first 24 threads (or you could split up in a different way)