Metadata-Version: 2.2
Name: arrayfire-binary-python-wrapper
Version: 0.8.0
Summary: ArrayFire Python Wrapper
Keywords: arrayfire,c,python,wrapper,parallel computing,gpu,cpu,opencl,oneapi
Author-Email: ArrayFire <technical@arrayfire.com>, Anton Chernyatevich <chernyatevich.a@gmail.com>
Maintainer-Email: ArrayFire <technical@arrayfire.com>
License: BSD 3-Clause License
         
         Copyright (c) 2023, ArrayFire
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries
Project-URL: Website, http://arrayfire.com
Project-URL: General Documentation, https://arrayfire.org/docs/index.htm
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# arrayfire-binary-python-wrapper

<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 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.

# 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 ***intended User Interface*** that provides a numpy-like layer to execute math and array operations with ArrayFire.
- [`arrayfire-binary-python-wrapper`](https://github.com/arrayfire/arrayfire-binary-python-wrapper) is the thin `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.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 the binary python wrapper:**
```sh
# install binary wrapper from PyPI without binaries
# assumes ArrayFire binaries will be installed on the system in some other manner
pip install arrayfire_binary_python_wrapper 
```

**Install a pre-built wheel:**
```sh
# install binary wrapper with the 3.10 ArrayFire binaries pre-built and included
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:
```
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. 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

The community of ArrayFire developers invites you to build with us if you are
interested and able to write top-performing tensor functions. Together we can
fulfill [The ArrayFire
Mission](https://github.com/arrayfire/arrayfire/wiki/The-ArrayFire-Mission-Statement)
for fast scientific computing for all.

Contributions of any kind are welcome! Please refer to [the
wiki](https://github.com/arrayfire/arrayfire/wiki) and our [Code of
Conduct](33) to learn more about how you can get involved with the ArrayFire
Community through
[Sponsorship](https://github.com/arrayfire/arrayfire/wiki/Sponsorship),
[Developer
Commits](https://github.com/arrayfire/arrayfire/wiki/Contributing-Code-to-ArrayFire),
or [Governance](https://github.com/arrayfire/arrayfire/wiki/Governance).

# Citations and Acknowledgements

If you redistribute ArrayFire, please follow the terms established in [the
license](LICENSE).

ArrayFire development is funded by AccelerEyes LLC and several third parties,
please see the list of [acknowledgements](ACKNOWLEDGEMENTS.md) for an
expression of our gratitude.

# Support and Contact Info

* [Slack Chat](https://join.slack.com/t/arrayfire-org/shared_invite/MjI4MjIzMDMzMTczLTE1MDI5ODg4NzYtN2QwNGE3ODA5OQ)
* [Google Groups](https://groups.google.com/forum/#!forum/arrayfire-users)
* ArrayFire Services:  [Consulting](http://arrayfire.com/consulting)  |  [Support](http://arrayfire.com/download)   |  [Training](http://arrayfire.com/training)

# Trademark Policy

The literal mark "ArrayFire" and ArrayFire logos are trademarks of AccelerEyes
LLC (dba ArrayFire). If you wish to use either of these marks in your own
project, please consult [ArrayFire's Trademark
Policy](http://arrayfire.com/trademark-policy/)
