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¶
From PyPI (Recommended)¶
Install zagar from PyPI with:
pip install zagar
Note
On a platform with a wheel this is all that is required. If no wheel matches
your platform and Python version, pip builds from source instead, and
will stop with an error like this when Boost is missing:
CMake Error at CMakeLists.txt:94 (message):
Boost not found. Please install Boost:
macOS: brew install boost
Ubuntu: sudo apt-get install libboost-dev
conda: conda install -c conda-forge boost
Install Boost first (see Prerequisites above), then retry pip install zagar.
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 1: Using Sage’s pip (Recommended)¶
First, ensure Boost is installed on your system (see Prerequisites above).
Then install zagar using Sage’s built-in pip:
# Install from PyPI
sage -pip install zagar
# Or install from source
git clone https://github.com/alanaw1/zagar.git
cd zagar
sage -pip install .
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:
Ensure you have a C++17 compatible compiler
On macOS, ensure Xcode Command Line Tools are installed:
xcode-select --installOn Windows, ensure Visual Studio Build Tools 2017 or later are installed