Attention: Although the Hexed source code is published under the very permissive MIT License, compiled binaries may be linked with OpenCASCADE, causing them to be bound by the LGPL License. If you redistribute compiled binaries, you must observe the terms of this license.

Prerequisites

OS

Currently, Hexed supports only GNU/Linux operating systems. The instructions on this page are targeted at and have been tested on Ubuntu 24.04 (Noble Numbat), but should be easily adapted to other Linux distributions. Support for Windows and Mac OS are planned for future releases.

Python/pip

To install Hexed, you will need Python3, and you will need to be able to install packages with pip. You likely already have those things, but if you don't, you can obtain them with

sudo apt install python3-full

If you don't have root permissions, you can also build Python from source. Also, if this is your first time installing Python packages, you should create a virtual environment (this has always been recommended, but in Ubuntu 24.04 it is now mandatory). You can create and activate a virtual environment with the following commands:

python3 -m venv my_venv

source my_venv/bin/activate

You will have to repeat the source my_venv/bin/activate command every time you open a new terminal, or else you won't be able to use your hexed installation. See this tutorial for more information about Python packages and virtual environments.

Currently, Hexed is installed via a Python package, which includes both a Python library of helper functions and the binaries for the Hexed solver. This could be construed as an abuse of the Python packaging system, but to make the installation as straightforward as possible, I wanted a packaging system that:

nearly everyone already has
can install executables and libraries in the user tree, since not everyone has root permissions on their own machine

Currently, Python packages are the only system that appears to meet these requirements.

Install from Python package (the easy way)

The easiest way to install Hexed is via the Python package with pip:

python3 -m pip install --index-url https://test.pypi.org/simple/ hexedpy

Note: You can't just do pip install hexedpy because, for now, Hexed is only on the TestPyPI, not the real PyPI.

Once you do this, you can run Hexed with the command hexecute. You will also have access to the hexedpy Python module. Unfortunately, due to licensing considerations, this package does not include OpenCASCADE, so you will not be able to import geometry in CAD file formats. For that, you need to build Hexed from source, as explained below.

Building from source (the harder way)

For optimal performance, if you want to modify the source code, or if you need OpenCASCADE support, you will need to build Hexed from source. Even when you do so, Hexed is still installed as a Python wheel, so you will still need pip as explained in Prerequisites. You will also need some basic development tools including git, GCC, and Make. Again, if you're reading this, you probably already have these, but if you don't, you can install them (on Ubuntu) with

sudo apt install build-essential git

Once you have these basic prerequisites, all you have to do is:

git clone https://github.com/ARTLab-GT/hexed.git
cd hexed
git checkout latest_release
python3 build.py

This will create a directory named build in which it will compile the code and create the hexedpy Python wheel, and then it will install the wheel in your current environment.

Notes:

This may take a while, especially the first time (repeat builds should be much faster). If you want to speed it up, see the n_build_procs option.
It will automatically download and build any dependencies you don't already have. See Automatically-installed dependencies below for more information.
If you make changes to the source code, it you should be able to just rerun build.py and it should do a pretty good job of rebuilding/reinstalling the files that were affected by the change. However, occasionally, a repeat build might break. If you encounter inexplicable problems on repeat builds, try deleting the build directory and then rebuilding.

Build options

The build script (build.py) accepts some command line arguments. All arguments except --build_dir are cached in files in the build directory. If you rerun the build, it will remember the values of any previous options you passed until you explicitly override them (by passing the option again with a different value) or delete the build directory. Every option takes the form --option_name=value. The whole option (including value) must be a valid shell token, so if value contains spaces you must escape them or quote it (e.g., --some_option="some value"). Any unrecognized option names are simply ignored, so watch carefully for typos.

The options are listed below. Any options which expect a path can accept an absolute path or a path relative to your current working directory (.). Any options which expect a Boolean value can accept any of the following values, all of which are case insensitive (although otherwise options are case sensitive):

0, false, no, off, n, f all translate to False.
1, true, yes, on, y, t all translate to True.

source_dir

Expects: path
Default: .
Root directory of the source code.

build_dir

Expects: path
Default: ./build
Directory in which compiled binaries will be placed. This is also where cached options are stored. So, if you run the build script multiple times with different build_dirs, then each time you run it in a particular build_dir it will remember the most recent options you used in that build_dir without affecting the options used for other build_dirs. This is why the option --build_dir isn't cached—in order to access the cached options, the script needs to already know the build_dir.

n_build_procs

Expects: Positive integer
Default: 1
When compiling, use up to this many parallel processes. This can significantly speed up the build, but it also uses more memory. You can easily max out your RAM this way, so use caution. As a rule of thumb, I usually use 1 process for every 2 GB of RAM available.

verbose

Expects: Boolean
Default: False
Print additional diagnostic information.

use_system_paths

Expects: Boolean
Default: True
If True, before installing any dependencies, the build script will first search for them in paths typically used by the system to install files. These include

/usr/lib/ for libraries
/usr/include/ and /usr/local/include/ for headers

use_env_paths

Expects: Boolean
Default: True
If True, before installing any dependencies, the build script will first search for them in paths specified by environment variables. These include:

PATH for executables
LIBRARY_PATH, LD_LIBRARY_PATH, and DT_RPATH for libraries
INCLUDE_PATH, and CPLUS_INCLUDE_PATH for headers
CMAKE_PREFIX_PATH and PATH (with the bin suffices removed) for CMake configuration files.

internet

Expects: Boolean
Default: True
If False, the build script will avoid internet usage to install dependencies. As a result, if some dependencies are not available, the build process will fail instead of downloading them. This option is generally only appropriate for repeat builds, where time may be wasted in unnecessary internet access.

build_mode

Expects: release or debug
Default: release
If release, compile flags will be chosen to provide the best possible performance. If debug, compile flags will be chosen to simplify debugging (debug symbols and sanitizers are turned on). This option also influences the default values of some other options below.

max_row_size

Expects: Integer \( \ge \) 2
Default: 8
Maximum row size for simulations. The larger this number, the longer the code will take to compile (although usually most of the time is taken by compiling OCCT). However, attempts to use a row size larger than Hexed was compiled for will result in a runtime exception.

threaded

Expects: Boolean
Default: True
If True, simulations will be parallelized with OpenMP.

n_threads

Expects: Positive integer
Default: maximum supported by the system you're building on
Maximum number of threads used to parallelize the code.

profile

Expects: Boolean
Default: False
If True, compile for profiling with gprof. This will slow down the execution.

use_xdmf

Expects: Boolean
Default: True
If true, compile with the XDMF library to enable writing visualization files in XDMF.

use_tecio

Expects: Boolean
Default: False
If true, compile with Tecplot's TecIO library to enable writing visualization files in .szplt format. This requires TecIO to already be installed on your system—it won't install it automatically.

use_occt

Expects: Boolean
Default: True
If true, compile with the OpenCASCADE library to enable reading geometry from CAD files. The LGPL license will apply to the compiled binaries iff this is option is true.

build_tests

Expects: Boolean
Default: True
Compile unit tests.

run_tests

Expects: Boolean
Default: True if build_mode is debug, otherwise false. If true, run the unit tests immediately after completing the build.

test_args

Expects: Any string
Default: Empty
If non-empty (and run_tests is true), will be passed as command-line arguments to the unit test executable. Unit testing is done with Catch2, so may use this to interact with Catch2's command line interface.

gdb

Expects: Boolean
Default: False
If true (and run_tests is true), rather than running the unit tests directly it will start a GDB session and load the unit test executable.

build_docs

Expects: Boolean
Default: False
If true, build the documentation, when will be placed in the directory build_dir/doc/html. This is primarily for developers who wish to view their changes to the documentation. Users may simply refer to the online documentation.

obsessive_timing

Expects: Boolean
Default: False
Causes Hexed to perform additional timing measurements and print them to the screen on execution. For developers.

build_wheel

Expects: Boolean
Default: True if build_mode is release, otherwise false.
If true, build the wheel for the hexedpy Python package. Otherwise, the Hexed binaries are compiled but not assembled into any type of package. The wheel includes:

The hexedpy Python library
The hexecute executable
All library dependencies of hexecute including the hexed library

install_wheel

Expects: Boolean
Default: True
If build_wheel is true, then install the Python wheel in your current Python environment after building it. If build_wheel is false, has no effect.

architecture

Expects: Architecture name, native, or any
Default: native
CPU architecture to compile for. Compiling for a specific architecture may improve performance on that architecture but makes the executable incompatible with other architectures. native implies that it will compile for the architecture of the machine you're building on. any implies that the executable shall be compatible with any architecture, at the potential cost of performance. Thus far, I have not conducted sufficient investigation to determine to what extent this actually affects performance.

sanitize

Expects: Boolean
Default: True if build_mode is debug, otherwise false If true, compile with sanitizer flags.

Automatically-installed dependencies

Below is a list of source code dependencies of Hexed. The build script will automatically install any which you don't already have in the build tree (not system-wide). If you wish to supply your own version of any of them, simply make sure the header, library, and CMake files can be found in the standard system paths or environment variables. The build script isn't smart enough to check the version (yet), so the versions listed are just the versions that will be installed if the dependency isn't found.

Dependencies of the dependencies are not listed but are also installed automatically. The build script will also automatically obtain dependencies of the build process itself, including Doxygen and some Python packages.