Skip to content

Updated readme #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Updated readme #58

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aace8ab
Update readme
edwinsolisf Aug 5, 2025
387c39c
Cleanup readme
edwinsolisf Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,54 @@
# arrayfire-binary-python-wrapper
# arrayfire-binary-python-wrapper (WIP)

<p align="center"><a href="http://arrayfire.com/"><img src="http://arrayfire.com/logos/arrayfire_logo_whitebkgnd.png" width="800"></a></p>

[ArrayFire](https://github.com/arrayfire/arrayfire) is a high performance library for parallel computing with an easy-to-use API. It enables users to write scientific computing code that is portable across CUDA, OpenCL and CPU devices.

This project is meant to provide thin Python bindings for the ArrayFire C library. It also decouples releases of the main C/C++ library from the Python library by acting as a intermediate library and only wrapping the provided C calls.
This project is a **work in progress**. This is meant to provide direct Python access for the ArrayFire C library by only wrapping the calls to the C/C++ ArrayFire Library.
This allows the building of large binary wheels only when the underlying ArrayFire version is increased, and the [interface Python library `arrayfire-py`](https://github.com/arrayfire/arrayfire-py) can be developed independently. The package is **not intended** to be used directly and merely exposes the
C functionality required by [`arrayfire-py`](https://github.com/arrayfire/arrayfire-py). This package can exist in two forms, with a bundled binary distribution, or merely as a loader that will load the ArrayFire library from a system or user level install.

This allows the building of large binary wheels only when the underlying ArrayFire version is increased, and the fully-featured Python library can be developed atop independently. The package is not intended to be used directly and merely exposes the
C functionality required by downstream implementations. This package can exist in two forms, with a bundled binary distribution, or merely as a loader that will load the ArrayFire library from a system or user level install.
# Project Details

The ArrayFire Python Project is separated into 3 different parts:
```
arrayfire-py -> arrayfire-binary-python-wrapper -> ArrayFire C Libraries
```
This means that arrayfire with python each of these parts is needed:
- [`arrayfire-py`](https://github.com/arrayfire/arrayfire-py) is the `thin` wrapper that provides the numpy-like interface to do math and array operations. *** This is the intended User Interface ***
- [`arrayfire-binary-python-wrapper`](https://github.com/arrayfire/arrayfire-binary-python-wrapper) is the `binary` wrapper that provides rough direct access to the functions in the C library. Its purpose is to do the handling of finding the C libraries and handling the communication between Python and C datatypes. This package can exist in two forms, with a bundled binary distribution, or merely as a loader that will load the ArrayFire library from a system or user level install.
- [`ArrayFire C Libraries`](https://github.com/arrayfire/arrayfire) are the binaries obtained from compiling the [ArrayFire C/C++ Project](https://github.com/arrayfire/arrayfire)

# Installing

The arrayfire-binary-python-wrapper can be installed from a variety of sources. [Pre-built wheels](https://repo.arrayfire.com/python/wheels/3.9.0/) are available for a number of systems and toolkits. These will include a binary distribution of the ArrayFire libraries. Installing from PyPI directly will only include a wrapper-only, source distribution that will not contain binaries. In this case, wrapper-only installations will require a separate installation of the ArrayFire C/C++ libraries.
The arrayfire-binary-python-wrapper can be installed from a variety of sources. [Pre-built wheels](https://repo.arrayfire.com/python/wheels/3.10.0/) are available for a number of systems and toolkits. These will include a binary distribution of the ArrayFire libraries. Installing from PyPI directly will only include a wrapper-only, source distribution that will not contain binaries. In this case, wrapper-only installations will require a separate installation of the ArrayFire C/C++ libraries.
You can get the ArrayFire C/C++ library from the following sources:

- [Download and install binaries](https://arrayfire.com/download)
- [Build and install from source](https://github.com/arrayfire/arrayfire)


**Install the last stable version of python wrapper:**
**Install the last stable version of the binary python wrapper:**
```
pip install arrayfire-binary-python-wrapper
pip install arrayfire_binary_python_wrapper-0.8.0+af3.10.0-py3-none-linux_x86_64.whl # install required binary wrapper with the 3.10 ArrayFire binaries included
```

**Install a pre-built wheel:**
```
pip install arrayfire-binary-python-wrapper -f https://repo.arrayfire.com/python/wheels/3.9.0/
pip install arrayfire-binary-python-wrapper -f https://repo.arrayfire.com/python/wheels/3.10.0/
```

# Building
The arrayfire-binary-python-wrapper can build wheels in packaged-binary or in system-wrapper modes.
[scikit-build-core](https://github.com/scikit-build/scikit-build-core) is used to provide the python build backend.
The minimal, wrapper-only mode that relies on a system install will be built by default though the regular python build process. For example:
```
pipx run build --wheel
python -m pip install -r dev-requirements.txt
python -m build --wheel
```
Building a full pre-packaged local binary is an involved process that will require referencing the regular ArrayFire [build](https://github.com/arrayfire/arrayfire/wiki/Build-Instructions-for-Linux) [procedures](https://github.com/arrayfire/arrayfire/wiki/Build-Instructions-for-Windows).
Besides the regular ArrayFire CMake configuration, building the binaries is an opt-in process that is set by an environment variable `AF_BUILD_LOCAL_LIBS=1`. Once that environment variable is set, scikit-build-core will take care of cloning ArrayFire, building, and including the necessary binaries.

Besides the regular ArrayFire CMake configuration, building the binaries is an opt-in process that is set by an environment variable `AF_BUILD_LOCAL_LIBS=1`. Once that environment variable is set, scikit-build-core will take care of cloning ArrayFire, building, and including the necessary binaries. You may require specifying certain locations of external packages using `CMAKE_ARGS` to pass them to cmake. We recommend looking at our [docker build](https://github.com/arrayfire/arrayfire-docker/blob/afwheel310/arrayfire/scripts/build_wheel.sh) procedure to build this wheel if you wish to replicate it yourself.


# Contributing
Expand Down