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 and up. For biggest profit, use the most modern compiler you can.
2. $PACKAGE_MANAGER install gmp mpfr automake autoconf libtool boost eigen boost-python3, pip3 install numpy
   • on Debian-family Linux distros (e.g., Ubuntu, Linux Mint), eigen goes by libeigen3-dev; if you want to use apt 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 8 && make -j 8 check && make install, having preceded this with libtoolize on linux.
6. cd ../python && autoreconf -fi && ./configure && make -j 4 && make install && pip3 install --upgrade . && python3 test/test_all.py
7. Solve some polynomials, file an issue, update this wiki guide, tell a dev how it went, or dance naked.
8. Drink your favorite beverage with a friend.

Disclaimer

Bertini 2 is in active development. Interface continues to 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 (2017.09.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. It would not be hard for you to implement your own little black box.

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, Bertini2 itself will provide the necessary Python layer, exposing classes and methods to Python. This removes a considerable barrier to entry for development of applications using Bertini2 for many users. The major burden is one of learning Python, rather than template C++. Of course, the cost is 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 to install and aptitude to search. 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 6 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.9. 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 at least 1.71, and ./configure will fail if this requirement is not satisfied.

• Versions before 1.71 are missing complex numbers in the Multiprecision library.
• Versions before 1.65 fail to compile PyBertini, since Boost.Multiprecision is missing some hyperbolic trig functions.
• Versions including and before 1.61 fail to compile because of missing isnan overloads.
• Additionally, before 1.61 expression templates didn't work correctly without patching.
  Use 1.71 or higher. A minimum version increase will happen again when we introduce expression templates for complex's.
  Ubuntu users: 20.04 LTS gives you 1.71 when you use apt.

3. Boost.Python, in case it didn't come with Boost. For the love of all that is holy, please use a package manager. Keeping the Python lib in line with the Boost.Python lib can be a pain to do manually. Make sure it is set up using Python3 -- Silviana does not test Python2. Python2 died in 2020. Make the switch now.
4. Eigen. Version 3.3.x includes some important improvements particularly on the correctness of real/complex type through SVD and a few other decompositions. Minimum version is 3.2.X, where the minimum tested X is about 5. Note that the LTS Ubuntu 14.04 Eigen dist is a beta version (3.2.92 as of this writing), and should not be used. If this is no longer the case, please inform Silviana.
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.68

Notes on dependencies

• You must have a compiler compatible with C++14 installed. Recent GCC and Clang both support C++14. Again, consider using newer versions of compilers, to take advantage of recent optimization and extensions. All linked libraries must be compiled with the same compiler, of course.

1. Download

Clone (recursive if building python bindings) from the official repo.

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

I do not recommend downloading as a zip, for b2 or any git repo at all.

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. 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. The -vfi flags are for (v)erbose, (f)orce, and (i)nstall. The v is optional.
5. Then ./configure --your-options.

Useful configure options:

• 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.
• --enable-forbid_mixed_arithmetic You can disable mixed arithmetic between doubles and mpfr's. If you want to forbid to multiple a double and a variable-precision number, enable this flag.
• --enable-unity_build Turn on unity-style building, better for a low-thread environment. possible values yes and no.

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. Get more ram for your machine if parallel compiling doesn't work well.
2. make check -- Optional but helpful. This compiles all test suites, runs them, and saves the results to log files. With Boost 1.71-1.76, I expect two failures in b2_class_test. These come from Boost.Multiprecision issues #207 and #308, which are not yet resolved as of 2021-05-03.

The available test suites 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 (Spring 2021).

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 raw Python-C++ bindings _pybertini to wherever ./configure determined the place for installed Python modules is.
3. pip3 install --upgrade . -- install the final wrapper layer for pybertini.
4. 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 Silviana Amethyst.

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.