Compilation Guide

Building Contents

• Summary
• Disclaimer
• Structure
• Supported systems
• 0. Dependencies
• 1. Download
• 2. Compile the core
• 3. Compile the Python bindings
• 4. Provide feedback
• Concluding notes for developers

Summary

1. Install a modern compiler. Newest Xcode with command-line tools is good, as is GCC 4.9. The GCC 5 range requires -fpermissive, I believe.
2. $PACKAGE_MANAGER install automake autoconf libtool boost eigen boost-python, pip install numpy
   • on Debian-family Linux distros (e.g., Ubuntu, Linux Mint), eigen goes by libeigen3-dev; if you want to use apt-get to install boost, you'll need to replace boost and boost-python with libboost-all-dev and libboost-python-dev, respectively
3. git clone https://github.com/bertiniteam/b2 --recursive
4. cd b2/core
5. autoreconf -fi && ./configure && make -j && make -j check && make install, having preceded this with libtoolize on linux.
6. cd ../python && ./configure && make -j && make install && python test/test_all.py
7. File an issue, update this wiki guide, tell a dev how it went, or solve some polynomials.
8. Drink your favorite beverage with a friend.

Disclaimer

Bertini 2 is in active development. Interface may change. Although many of the core capabilities are present, performance needs some serious improvement, and there are probably issues. That said, you can help us improve Bertini 2 if you try it out. As of this time (2016.11.01), there is not yet a black box executable in the style of Bertini 1, although there is a parser for the INPUT section of Bertini input files.

If you just want to sit down right now and solve some polynomials, please use Bertini 1.x... and consider getting involved in Bertini2 as a tester!

Structure

Bertini 2 is written with extensibility and integration in mind. To this end, Bertini2 currently consists of two parts:

1. a computational core library written mainly in C++.
2. an interactive system written from Python.

The third major part, a command-line program consuming and producing files is incoming.

This paradigm has several important traits:

• The blackbox executable is standalone and non-interactive, ensuring that it can continue to run on queued systems, in which all input from the console (think std::cin) is ignored and the program simple takes empty input everywhere. Bertini 1.x currently has several interactive modes, which are inaccessible if the program is called in a queue. Hence, we are moving this interactivity to a Python front end to ensure these modes are available even on a supercomputer, without awkward hacks.
• The core is scriptable. By using Python as the front end, all algorithms will be callable from Python scripts. Hence, an option for Bertini 2 input format will be a .py file. Legacy-style Bertini Classic input files will continue to be fully supported, but future algorithm implementations are not guaranteed to be available without moving to the new system. We do guarantee all functionality from Bertini 1 will be implemented and exposed into every mode of Bertini 2.
• All algorithms will be available with convenient user wrappers or layers of indirection. As a consequence of integrating with Python, Bertini itself will provide the necessary Python layer, exposing classes and methods to Python. This will remove a considerable barrier to entry for development of applications using Bertini2 for many users. The major burden becomes one of learning Python, rather than template C++. Of course, the cost will be in performance.

The file structure divides the files into several parts, along these lines:

• /b2
• /b2/core
• /b2/python

Each of these has its own include, src, and test, as well as their own documentation. We acknowledge that documentation could be improved, and welcome your help in doing that.

Supported systems

Supported platforms as of this writing include GNU Linux, Unix, and Mac OSX. Windows support is promised and upcoming. We welcome help getting compiling and testing on Windows, particularly if you know CMake and Visual Studio well.

0. Dependencies

Bertini 2 is written in modern C++, using no few libraries to help us developers focus on the algebraic geometry rather than already-solved problems in C++. These libraries are available under their respective licenses. See the /b2/licenses folder in the repo.

Please please please use a package manager for your installed libraries. It's there for a reason. On MacOS, use Homebrew or MacPorts, both of which are tested. On Ubuntu, you have apt-get and aptitude. On other flavors, you have yum. On Windows, there's Chocolatey, which is getting there but doesn't have everything Bertini2 needs. Should you choose to install all your libraries from source, this is your deal. Choose wisely. [hint: The package manager is the wooden cup.]

1. A compiler capable of the C++14 extensions.

• Linux: GCC 4.9.3 works well, but consumes a lot of memory. I love Clang.
• Mac: Apple's Clang packaged with XCode works well. If you are on a Mac, you also need the command-line tools, xcode-select --install.
  Consider using a newer version of GCC than 4.x. Particularly, I would love to see people move to GCC 7 in anticipation of C++17, which I will freely use in Bertini2.

2. Boost. Minimum version is 1.58. Versions including and after 1.61 will let you compile using expression templates for multiple precision floating point real computations, a valuable optimization. If you patch Boost.Multiprecision, you can enable them in earlier versions as well.
3. Boost Python, in case it didn't come with Boost. For the love of all that is holy, please use a package manager.
4. Eigen. Minimum version is 3.2.X, where the minimum tested X is about 5. The beta of the upcoming version 3.3 currently builds successfully, too.
5. Current GNU Autotools. You need libtool, automake, and autoconf. The default versions of these on most platforms are insufficient, so go get them from your favorite package manager. Building using CMake is not set up yet, but if you want to set it up for us, please contribute! Here are recommended versions for the Autotools:

• Libtool -- > 2.4.6 appears to be good to go.
• Automake -- > 1.13
• Autoconf -- > 2.6.8

Notes on dependencies

• You must have a compiler compatible with C++14 installed. Recent GCC and Clang both support C++14. For installation of gcc-4.9 on Ubuntu, see this link. Again, consider using newer versions of compilers, to take advantage of recent optimization and extensions.

1. Download

Either clone (recursive if building python bindings) from the official repo, or just download a tarball.

git clone https://github.com/bertiniteam/b2 --recursive

2. Compile the core

The core is the library against which other products will link. Engage in the standard build process for any software built using the autotools. If you hate the autotools, please contribute your favorite build system.

First, configure.

1. Move to the core cd b2/core
2. Configure to compile.
3. Linux users, first libtoolize. If libtoolize fails, either you're on Mac and don't have to, or don't have libtool installed. The -vfi flags are for (v)erbose, (f)orce, and (i)nstall. The v is optional. You only have to do this once, unless you delete your clone of the repo.
4. All users autoreconf -vfi to generate the ./configure script. If this step fails, you almost certainly have outdated autotools software, most namely automake, autoconf, and libtool. Update your tools as necessary. This is notably true if you see error: possibly undefined macro: AC_ENABLE_STATIC during autoreconf.
5. Then ./configure --your-options.

Useful configure options:

• --disable-thread_local Mac users may want to use this flag, because Apple's Clang did not implement this C++11 keyword until Fall 2016. If your XCode install is at least as new as October 2016, you should be able to omit this flag.
• CPPFLAGS="-I/opt/local/include" LDFLAGS="-L/opt/local/lib" MacPorts users will want these, probably, since /opt/local isn't in the standard set of places to look for headers or libraries, and this is the default MacPorts location.
• --disable-expression_templates Users who want to use Boost versions 1.56-1.60 will want to do this, unless you patch your Boost install. Patching is easy, and involves only three modifications, and no re-compilation. Patching notes are here, Dani's post from May 31, 2016

Second, compile.

1. make -j numthreads -- Use of multiple threads is suggested, if you have enough memory. GCC tends to use at least 1GB per thread while compiling Bertini2. Four threads brings my Dell laptop to its knees. I can do at least six on my Mac with Clang, which can be around 250-500 MB per thread, depending on the file. That said, that machine has 16GB ram. Get more ram for your machine.
2. make check -- Optional but helpful. This compiles the test suites, runs them, and saves the results to log files. Currently, several failing tests are present, so expect a few failures.

The tests are listed in b2/core/test/available-tests.txt.

They are built using the Boost.UnitTest library, and can produce a variety of output files, and be run in a variety of modes. These options are not documented here. Instead, consult the Boost.UnitTest documentation for instructions. You can also invoke --help on the test exectubles.

To build the test modules, just make them. E.g., make b2_class_test or make tracking_basics_test.

The test modules are set up to be run as part of the traditional make check method. To build and run all tests, simply make check. If you get failures, please let a dev know.

3. make install -- Install the core to wherever you set prefix to be, typically /usr/local.

This is about the end of compilation of the core. No useful executable is currently offered, though we expect to have one completed soon (Spring 2017).

3. Compile the Python bindings

Again, first configure.

1. Move to the core cd b2/python
2. Configure to compile. Linux users, first libtoolize. Then autoreconf -fi to generate the ./configure script. Finally ./configure --your-options. Remember that you can ask for --help.

If you did not clone recursively, you will likely see an error for missing Minieigen files (particularly minieigen/src/common.hpp). The error contains the command you should run to pick up this dependency, git submodule update --init. This should clone Minieigen into b2/python/minieigen.

Second, compile.

1. make -j numthreads -- Use of multiple threads is again suggested, if you have enough memory. The Python bindings take even more memory than the core does, so if your computer struggled with the core, use fewer threads now.
2. make install -- Install the bindings to wherever ./configure determined the place for installed Python modules is.
3. cd test && python test_all.py -- Optionally, run the tests.

The tests require NumPy, which you should install using your package manager. pip install numpy should get you there.

4. Provide feedback

Please help us improve the compiling and installing process by giving feedback, by way of

• filing issues (very strongly preferred), or
• email to a developer (address deliberately not given here... Contact info at the official wiki).

===

Concluding notes for developers

If you add files to the project, or wish to add a compiled program, etc, you modify the b2/core/Makefile.am, and a b2/core/path/to/Makemodule.am file, or possibly create a Makemodule.am file at the correct location. If you need help with this, please contact Daniel Brake [email protected]

Please do not commit autotools-built files to the repository, including the configure script, any file in the created b2/core/config/ folder, or the others. There is a chance you may have to add a m4 macro or something, and this is ok. Do what you need, but commit only the source files, not generated files.

Please maintain this file by editing it as necessary.