-
Notifications
You must be signed in to change notification settings - Fork 35
Compilation Guide
- 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
- 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.
-
$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 useapt
to install boost, you'll need to replaceboost
andboost-python
withlibboost-all-dev
andlibboost-python-dev
, respectively
- on Debian-family Linux distros (e.g., Ubuntu, Linux Mint), eigen goes by
git clone https://github.com/bertiniteam/b2 --recursive
cd b2/core
-
autoreconf -fi && ./configure && make -j 8 && make -j 8 check && make install
, having preceded this withlibtoolize
on linux. cd ../python && ./configure && make -j 4 && make install && pip3 install --upgrade . && python3 test/test_all.py
- Solve some polynomials, file an issue, update this wiki guide, tell a dev how it went, or dance naked.
- Drink your favorite beverage with a friend.
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!
Bertini 2 is written with extensibility and integration in mind. To this end, Bertini2 currently consists of two parts:
- a computational core library written mainly in C++.
- 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 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.
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.]
- 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.9. Particularly, I would love to see people move to GCC 7 in anticipation of C++17, which I will freely use in Bertini2.
-
Boost. Minimum version is at least 1.62. 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.62 or higher. A minimum version increase will happen again when we introduce expression templates for complex's.
Ubuntu users: 16.04 LTS gives you 1.58 when you useapt
. This is insufficient, and you must either build Boost from source, or receive newer builds from another source. This is beyond this wiki, but a quick google search will get you there. - 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.
- 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 Dani Brake.
- Current GNU Autotools. You need
libtool
,automake
, andautoconf
. The default versions of these on most platforms are insufficient, so go get them from your favorite package manager.
Building usingCMake
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
- 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.
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.
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.
- Move to the core
cd b2/core
- Configure to compile.
- Linux users, first
libtoolize
. If libtoolize fails, either you're on Mac and don't have to, or don't havelibtool
installed. You only have to do this once, unless you delete your clone of the repo. - All users
autoreconf -vfi
to generate the./configure
script. If this step fails, you almost certainly have outdated autotools software, most namelyautomake
,autoconf
, andlibtool
. Update your tools as necessary. This is notably true if you seeerror: possibly undefined macro: AC_ENABLE_STATIC
duringautoreconf
. The-vfi
flags are for(v)
erbose,(f)
orce, and(i)
nstall. Thev
is optional. - 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 of Boost. Patching notes are here, Dani's post from May 31, 2016. -
--disable-forbid_mixed_arithmetic
We have disabled mixed arithmetic between doubles and mpfr's. If you want to be able to multiple a double and a variable-precision number, disable this verboten interaction. The double-negative in this option name is deliberate, since you should probably not do this, unless you like aggravating noise at about the 16th digit. -
--enable-unity_build
Turn on unity-style building, better for a low-thread environment. possible valuesyes
andno
.
Second, compile.
-
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. -
make check
-- Optional but helpful. This compiles all test suites, runs them, and saves the results to log files. I expect no 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.
-
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 2018).
Again, first configure.
- Move to the core
cd b2/python
- Configure to compile. Linux users, first
libtoolize
. Thenautoreconf -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.
-
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. -
make install
-- Install the bindings to wherever./configure
determined the place for installed Python modules is. -
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.
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).
===
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 Dani Brake at [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.