Installation

Prerequisites

zagar requires Python >= 3.10, and installs NumPy, its only runtime dependency, automatically.

Beyond that, what you need depends on whether a pre-compiled wheel exists for your platform. Starting with 0.2.0, zagar publishes wheels for:

Platform

Python versions

Linux x86-64 (glibc 2.28 or newer)

3.10, 3.11, 3.12

macOS on Apple Silicon

3.10, 3.11, 3.12

Windows x86-64

3.10, 3.11, 3.12

On those, pip install zagar fetches a ready-built extension module and needs no compiler, no CMake and no Boost.

Everywhere else – Intel macOS, Linux on ARM, musl-based Linux such as Alpine, 32-bit Windows, and Python 3.13 or newer – pip falls back to the source distribution and compiles the extension on your machine. Only that path needs:

  • C++17 compatible compiler (GCC >= 7, Clang >= 5, or MSVC >= 2017)

  • CMake >= 3.15

  • Boost (header-only, for multiprecision arithmetic)

Installing Boost

Needed only for a source build, as described above.

macOS (using Homebrew):

brew install boost

Ubuntu/Debian:

sudo apt-get install libboost-dev

Fedora/RHEL:

sudo dnf install boost-devel

Windows (using vcpkg):

vcpkg install boost

Conda (any platform):

conda install -c conda-forge boost

Optional: OpenMP for Parallelization

For parallel computation support via getA12_parallel and getA12_pruning, both of which accept an n_threads argument, install OpenMP:

macOS:

brew install libomp

Ubuntu/Debian:

sudo apt-get install libomp-dev

Fedora/RHEL:

sudo dnf install libomp-devel

Python Users

Example: Installing in a Conda Environment

Here is a complete example of installing zagar in a fresh conda environment:

# Create and activate a new environment
conda create -n zagar-test python=3.11 -y
conda activate zagar-test

# Install Boost (only needed if no wheel matches your platform)
conda install -c conda-forge boost

# Install zagar from PyPI
pip install zagar

# Verify installation
python -c "import zagar; print(zagar.__version__)"

From Source

To install the latest development version:

git clone https://github.com/alanaw1/zagar.git
cd zagar
pip install .

For development (editable install with test dependencies):

pip install -e ".[dev]"

Verifying Installation

After installation, verify that zagar works correctly:

import zagar

# Check version
print(zagar.__version__)

# Test basic functionality
result = zagar.count_binary_matrices([2, 1], [1, 1, 1])
print(result)  # {'number': 3, 'memo_entries': 2}

# Check if OpenMP is available
print(f"OpenMP support: {zagar.has_openmp()}")

SageMath Users

Note

The SageMath interface is current as of 0.1.0 only. The instructions in this section and the examples on the Sage Example page were written and checked against that release. They do not yet cover anything added in 0.2.0 – count_A12, count_A12_dp, log2_A12_asymptotic, classify_case, entropy_bits or densities_from_constraints – and nothing in the test suite verifies them, because doctest cannot execute sage: prompts. Installing 0.2.0 into Sage works as described below, and every 0.1.0 function behaves as shown, but treat the Sage documentation of the new interfaces as outstanding work.

SageMath includes its own Python environment, so zagar must be installed into Sage’s Python rather than your system Python.

Method 2: Using sage.repl.ipython_kernel

If you’re using SageMath in a Jupyter notebook, run a shell command in a cell:

# In a Sage notebook cell, use shell escape
!sage -pip install zagar

Verifying Installation in SageMath

Start a Sage session and test the installation:

sage

Then in the Sage prompt:

sage: import zagar
sage: zagar.__version__
'0.2.0'
sage: zagar.count_binary_matrices([2, 1], [1, 1, 1])
{'number': 3, 'memo_entries': 2}

Using zagar with Sage Types

zagar functions accept standard Python lists. When working with Sage integers or vectors, convert them to Python lists first:

sage: import zagar
sage:
sage: # Sage integers work directly in lists
sage: N = 5
sage: a_vec = [2, 2]
sage: phi0_vec = [1, 1]
sage: phi1_vec = [1, 1]
sage:
sage: result = zagar.getA12(N, a_vec, phi0_vec, phi1_vec)
sage: print(result)
7632
sage:
sage: # For Sage vectors, convert to list
sage: v = vector([1, 2, 3])
sage: python_list = list(v)

The return values from zagar are standard Python integers with arbitrary precision (using Boost.Multiprecision internally), which integrate seamlessly with Sage’s integer arithmetic.

R Users

Coming soon!

Note

The R material is current as of 0.1.0 only. There is no R installation path yet; the examples on the R Example page were written against that release and are not exercised by the test suite. They do not cover the interfaces added in 0.2.0.

Troubleshooting

Boost Not Found

If you see an error like “Boost not found”, ensure Boost is installed and its headers are in a standard location. You can also set the path manually:

# Set Boost include path before installing
export Boost_INCLUDE_DIRS=/path/to/boost/include
pip install .

OpenMP Not Available

If zagar.has_openmp() returns False but you have OpenMP installed:

macOS: Ensure libomp is installed via Homebrew and rebuild:

brew install libomp
pip uninstall zagar
pip install . --no-cache-dir

Linux: Install the OpenMP development package for your distribution.

Compilation Errors

If you encounter C++ compilation errors:

  1. Ensure you have a C++17 compatible compiler

  2. On macOS, ensure Xcode Command Line Tools are installed:

    xcode-select --install
    
  3. On Windows, ensure Visual Studio Build Tools 2017 or later are installed