Merge pull request #98 from auto-differentiation/feature/python-bindings

Python bindings

.github/workflows/ci.yml

@@ -163,6 +163,7 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{ matrix.config }} \
             -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} \
             -DCMAKE_C_COMPILER=${{ matrix.cc }} \
+            -DXAD_TAPE_REUSE_SLOTS=${{ matrix.reuse_slots }} \
             -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install
       - name: build
         run: |
@@ -262,6 +263,7 @@ jobs:
             -DCMAKE_C_COMPILER=${{ matrix.cc }} \
             -DCMAKE_CXX_FLAGS="${{ matrix.coverage_cxx_flags }}" \
             -DCMAKE_EXE_LINKER_FLAGS="${{ matrix.coverage_ld_flags }}" \
+            -DXAD_TAPE_REUSE_SLOTS=${{ matrix.reuse_slots }} \
             -DCMAKE_INSTALL_PREFIX=${{ env.GITHUB_WORKSPACE }}/install
       - name: build
         run: |

.github/workflows/wheels.yml

@@ -0,0 +1,125 @@
+# builds only on the following conditions:
+# - pull requests into main
+# - OR pushes of tags starting with v*
+# - OR manual dispatch on repo
+# publishes to test pypi if:
+# - in auto-differentiation/XAD repository AND
+#   - pushes of tags starting with v*
+#   - OR manual dispatch on repo
+# publishes to real PyPI if:
+# - publish to Test PyPI worked (with all build conditions above)
+# - and if it's a version tag (starting with v*)
+#
+
+name: Python Wheels
+on: 
+  pull_request:
+    branches:
+      - main
+  push:
+    tags:
+      - v*
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+jobs:
+  build_wheels:
+    name: Wheels
+    strategy:
+      fail-fast: false
+      matrix:
+        buildplat: ["manylinux_x86_64", "musllinux_x86_64", "macosx_x86_64", "win_amd64"]
+        python: ["cp38", "cp39", "cp310", "cp311", "cp312"]
+        include:
+          - buildplat: "manylinux_x86_64"
+            os: ubuntu-20.04
+            python_exe: "$(which python)"
+          - buildplat: "musllinux_x86_64"
+            os: ubuntu-20.04
+            python_exe: "$(which python)"
+          - buildplat: "macosx_x86_64"
+            os: "macos-12"
+            python_exe: "$(which python)"
+          - buildplat: "win_amd64"
+            os: windows-2022
+            python_exe: "python"
+        exclude:
+          # gives "is not a supported wheel on this platform" for some reason
+          - buildplat: "macosx_x86_64"
+            python: "cp38"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x 
+      - name: Build wheels
+        uses: pypa/[email protected]
+        env:
+          CIBW_BUILD: ${{ matrix.python }}-${{ matrix.buildplat }}
+          CIBW_BEFORE_BUILD: pip install poetry && mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release -DXAD_ENABLE_TESTS=OFF -DXAD_ENABLE_PYTHON=ON -DPYTHON_EXECUTABLE=${{ matrix.python_exe }} -DXAD_STATIC_MSVC_RUNTIME=ON && cmake --build . --config Release
+          CIBW_TEST_COMMAND: pytest {package}/tests
+          CIBW_TEST_REQUIRES: pytest
+        with:
+          package-dir: bindings/python
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.python }}-${{ matrix.buildplat }}
+          path: ./wheelhouse/*.whl
+          if-no-files-found: error
+
+  test-publish:
+    needs: build_wheels
+    if: >-
+      github.repository == 'auto-differentiation/XAD' &&
+      (github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')))
+    environment: 
+      name: testpypi
+      url: https://test.pypi.org/p/xad-autodiff
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+      - uses: pypa/[email protected]
+        name: Publish on Test PyPI
+        with:
+          verbose: true
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test-publish
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xad-autodiff
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+      - uses: pypa/[email protected]
+        name: Publish on PyPI
+        with:
+          verbose: true
+          skip-existing: true
+

.gitignore

@@ -395,4 +395,5 @@ Mkfile.old
 dkms.conf
 
 /site
-.venv
+.venv
+CMakeUserPresets.json

CHANGELOG.md

@@ -9,15 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Support for enhanced debugger visualisations in Visual Studio (@dholden3)
+-   Python bindings as [xad-autodiff](https://pypi.org/project/xad-autodiff/)
+-   Added `std::is_signed` trait to `StdCompatibility.hpp` header for consistency
+-   Support for enhanced debugger visualisations in Visual Studio (@dholden3)
 
 ### Changed
 
-### Deprecated
-
-### Removed
-
-### Fixed
+-   Improved documentation for quantlib-xad build
+-   Cleaned up output of Swap Pricer example
 
 ## [1.4.1] - 2024-01-10
 
@@ -77,10 +76,13 @@ This is a patch release to ensure compatibility with QuantLib 1.33.
 
 ### Added
 
--   QuantLib integration by means of the [quantlib-xad](https://github.com/auto-differentiation/quantlib-xad) integration module
+-   QuantLib integration by means of the 
+    [quantlib-xad](https://github.com/auto-differentiation/quantlib-xad) 
+    integration module
 -   Full MacOS support
 -   Better CI pipeline with more platforms and compilers tested
--   Code coverage and quality measured on pull requests and reported in [README.md](README.md)
+-   Code coverage and quality measured on pull requests and reported 
+    in [README.md](README.md)
 -   More tests to improve code coverage
 -   Status badges in [README.md](README.md)
 -   Documentation updates

CMakeLists.txt

@@ -45,12 +45,23 @@ include(SetupOptions)
 
 if(NOT XAD_DOCS_ONLY)
     include(SetupCompiler)
-    add_subdirectory(src)
+    if(XAD_ENABLE_PYTHON)
+        include(SetupPython)
+    endif()
     if(XAD_ENABLE_TESTS)
         include(SetupTesting)
+    endif()
+
+    add_subdirectory(src)
+
+    if(XAD_ENABLE_TESTS)
         add_subdirectory(test)
         add_subdirectory(samples)
     endif()
+
+    if(XAD_ENABLE_PYTHON)
+        add_subdirectory(bindings/python)
+    endif()
 endif()
 
 install(FILES CHANGELOG.md LICENSE.md TYPE DOC)

bindings/python/.gitignore

@@ -0,0 +1,54 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.pyi
+prebuilt_file.txt

bindings/python/CMakeLists.txt

@@ -0,0 +1,35 @@
+##############################################################################
+#   
+#  Python bindings for XAD - poetry-based setup
+#
+#  This file is part of XAD, a comprehensive C++ library for
+#  automatic differentiation.
+#
+#  Copyright (C) 2010-2024 Xcelerit Computing Ltd.
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Affero General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Affero General Public License for more details.
+#
+#  You should have received a copy of the GNU Affero General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#   
+##############################################################################
+
+# build _xad_autodiff binary module
+add_subdirectory(src)
+
+if(XAD_ENABLE_TESTS)
+    add_subdirectory(tests)
+    add_subdirectory(samples)
+endif()
+
+
+
+

bindings/python/README.md

@@ -0,0 +1,90 @@
+[![Python](https://img.shields.io/pypi/pyversions/xad-autodiff.svg)](https://auto-differentiation.github.io/python)
+[![PyPI version](https://badge.fury.io/py/xad-autodiff.svg)](https://pypi.org/project/xad-autodiff/)
+
+
+XAD is a library designed for
+[automatic differentiation](https://auto-differentiation.github.io/aad/),
+aimed at both beginners and advanced users. It is intended for use in
+production environments, emphasizing performance and ease of use. The library
+facilitates the computation of derivatives within computer programs, making
+the process efficient and straightforward for a wide range of mathematical
+functions, from simple arithmetic to complex calculations, ensuring accurate
+and automatic derivative computations.
+
+The Python bindings for XAD offer the following features:
+
+- Support for both forward and adjoint modes at the first order.
+- Strong exception-safety guarantees.
+- High performance, as demonstrated in extensive production use.
+
+For more details and to integrate XAD into your projects, consult the
+comprehensive [documentation](https://auto-differentiation.github.io/python).
+
+## Application Areas
+
+Automatic differentiation has many application areas, for example:
+
+-   **Machine Learning and Deep Learning:** Training neural networks or other
+    machine learning models.
+-   **Optimization:** Solving optimization problems in engineering and finance.
+-   **Numerical Analysis:** Enhancing numerical solution methods for
+    differential equations.
+-   **Scientific Computing:** Simulating physical systems and processes.
+-   **Risk Management and Quantitative Finance:** Assessing and hedging risk in
+    financial models.
+-   **Computer Graphics:** Optimizing rendering algorithms.
+-   **Robotics:** Improving control and simulation of robotic systems.
+-   **Meteorology:** Enhancing weather prediction models.
+-   **Biotechnology:** Modeling biological processes and systems.
+
+## Getting Started
+
+Install:
+
+```text
+pip install xad-autodiff
+```
+
+
+Calculate first-order derivatives in adjoint mode:
+
+```python
+import xad_autodiff.adj_1st as xadj
+
+
+# set independent variables
+x0_ad = xadj.Real(1.0)
+x1_ad = xadj.Real(1.5)
+x2_ad = xadj.Real(1.3)
+x3_ad = xadj.Real(1.2)
+
+with xadj.Tape() as tape:
+    # and register them
+    tape.registerInput(x0_ad)
+    tape.registerInput(x1_ad)
+    tape.registerInput(x2_ad)
+    tape.registerInput(x3_ad)
+
+    # start recording derivatives
+    tape.newRecording()
+
+    # calculate the output
+    y = x0_ad + x1_ad - x2_ad * x3_ad
+
+    # register and seed adjoint of output
+    tape.registerOutput(y)
+    y.derivative = 1.0
+
+    # compute all other adjoints
+    tape.computeAdjoints()
+
+    # output results
+    print(f"y = {y}")
+    print(f"first order derivatives:\n")
+    print(f"dy/dx0 = {x0_ad.derivative}")
+    print(f"dy/dx1 = {x1_ad.derivative}")
+    print(f"dy/dx2 = {x2_ad.derivative}")
+    print(f"dy/dx3 = {x3_ad.derivative}")
+```
+
+For more information, see the [Documentation](https://auto-differentiation.github.io/python).