packaging: add svv-accelerated companion wheel and accel extras; auto-prefer accelerators; build both wheels in CI

Author: zasexton

.github/workflows/test-upload.yml

@@ -35,7 +35,10 @@ jobs:
       - name: Upgrade pip, setuptools, wheel
         run: python -m pip install --upgrade setuptools wheel
 
-      - name: Build wheels
+      - name: Build wheels (pure-Python svv)
+        env:
+          # Ensure we do NOT build extensions for the main wheel
+          SVV_BUILD_EXTENSIONS: "0"
         run: cibuildwheel --output-dir dist
 
       - name: Upload artifacts
@@ -62,22 +65,47 @@ jobs:
           name: cibw-sdist
           path: dist/*.tar.gz
 
-  upload_testpypi:
-    needs: [build_wheels, build_sdist]
+
+  build_wheels_accelerated:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macOS-latest, ubuntu-latest, windows-latest]
+    env:
+      CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-*"
+      CIBW_BUILD_VERBOSITY: 3
+      # Install build deps before building each wheel
+      CIBW_BEFORE_BUILD: "pip install -U pip setuptools wheel cython numpy cmake"
+      # Tell setup.py to build the companion 'svv-accelerated' distribution
+      CIBW_ENVIRONMENT: "PIP_NO_CACHE_DIR=1 SVV_ACCEL_COMPANION=1"
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Install cibuildwheel
+        run: pip install --upgrade pip && pip install cibuildwheel
+
+      - name: Build wheels (svv-accelerated)
+        run: cibuildwheel --output-dir dist
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-accelerated-${{ matrix.os }}
+          path: dist
+
+  upload_testpypi_all:
+    needs: [build_wheels, build_wheels_accelerated, build_sdist]
     runs-on: ubuntu-latest
-    steps:    
+    steps:
       - uses: actions/download-artifact@v4
         with:
-          # unpacks all CIBW artifacts into dist/
           pattern: cibw-*
           path: dist
           merge-multiple: true
-
-      - name: Install build dependencies
-        run: |
-          pip install --upgrade pip && pip install twine
-          
-      - name: Upload to TestPyPI
+      - name: Install twine
+        run: pip install --upgrade pip && pip install twine
+      - name: Upload both wheels to TestPyPI
         run: twine upload --repository testpypi dist/*
         env:
           TWINE_USERNAME: __token__

setup.py

@@ -42,6 +42,8 @@ def env_flag(name: str, default: bool = False) -> bool:
         return default
     return str(val).strip().lower() in {"1", "true", "yes", "y", "on"}
 
+ACCEL_COMPANION = env_flag("SVV_ACCEL_COMPANION", False)
+
 def get_filename_without_ext(abs_path):
     base_name = os.path.basename(abs_path)      # e.g. "file.txt"
     file_name_no_ext = os.path.splitext(base_name)[0]  # e.g. "file"
@@ -460,34 +462,40 @@ def get_extra_compile_args():
 
 def _build_extensions():
     """Return list of Extension objects if we are building with accelerators, else []."""
-    build_accel = env_flag("SVV_BUILD_EXTENSIONS", False) or env_flag("SVV_WITH_CYTHON", False)
+    # Two modes:
+    #  - Normal package (svv): build only when explicitly requested via env flag
+    #  - Companion package (svv-accelerated): always build extensions (wheels-only)
+    build_accel = env_flag("SVV_BUILD_EXTENSIONS", False) or env_flag("SVV_WITH_CYTHON", False) or ACCEL_COMPANION
     if not (build_accel and HAS_CYTHON and HAS_NUMPY):
         return []
     include_dirs = [_np.get_include()] if HAS_NUMPY else []
+    prefix = 'svv_accel.' if ACCEL_COMPANION else 'svv.'
+    def mod(name):
+        return prefix + name
     return [
-        Extension('svv.domain.routines.c_allocate', ['svv/domain/routines/c_allocate.pyx'],
+        Extension(mod('domain.routines.c_allocate'), ['svv/domain/routines/c_allocate.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.domain.routines.c_sample', ['svv/domain/routines/c_sample.pyx'],
+        Extension(mod('domain.routines.c_sample'), ['svv/domain/routines/c_sample.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.utils.spatial.c_distance', ['svv/utils/spatial/c_distance.pyx'],
+        Extension(mod('utils.spatial.c_distance'), ['svv/utils/spatial/c_distance.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_angle', ['svv/tree/utils/c_angle.pyx'],
+        Extension(mod('tree.utils.c_angle'), ['svv/tree/utils/c_angle.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_basis', ['svv/tree/utils/c_basis.pyx'],
+        Extension(mod('tree.utils.c_basis'), ['svv/tree/utils/c_basis.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_close', ['svv/tree/utils/c_close.pyx'],
+        Extension(mod('tree.utils.c_close'), ['svv/tree/utils/c_close.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_local_optimize', ['svv/tree/utils/c_local_optimize.pyx'],
+        Extension(mod('tree.utils.c_local_optimize'), ['svv/tree/utils/c_local_optimize.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_obb', ['svv/tree/utils/c_obb.pyx'],
+        Extension(mod('tree.utils.c_obb'), ['svv/tree/utils/c_obb.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_update', ['svv/tree/utils/c_update.pyx'],
+        Extension(mod('tree.utils.c_update'), ['svv/tree/utils/c_update.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.tree.utils.c_extend', ['svv/tree/utils/c_extend.pyx'],
+        Extension(mod('tree.utils.c_extend'), ['svv/tree/utils/c_extend.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.simulation.utils.close_segments', ['svv/simulation/utils/close_segments.pyx'],
+        Extension(mod('simulation.utils.close_segments'), ['svv/simulation/utils/close_segments.pyx'],
                   include_dirs=include_dirs, language='c++'),
-        Extension('svv.simulation.utils.extract', ['svv/simulation/utils/extract.pyx'],
+        Extension(mod('simulation.utils.extract'), ['svv/simulation/utils/extract.pyx'],
                   include_dirs=include_dirs, language='c++'),
     ]
 
@@ -517,7 +525,10 @@ def read_version():
                'Operating System :: Unix',
                'Operating System :: MacOS']
 
-PACKAGES = find_packages(include=['svv', 'svv.*'])
+if ACCEL_COMPANION:
+    PACKAGES = find_packages(include=['svv_accel']) or ['svv_accel']
+else:
+    PACKAGES = find_packages(include=['svv', 'svv.*'])
 
 
 def parse_requirements(path="requirements.txt"):
@@ -535,8 +546,8 @@ def parse_requirements(path="requirements.txt"):
 
 REQUIREMENTS = parse_requirements()
 _build_accel_flag = env_flag("SVV_BUILD_EXTENSIONS", False) or env_flag("SVV_WITH_CYTHON", False)
-# Filter out Cython from runtime requirements unless explicitly building extensions
-if not _build_accel_flag:
+if not _build_accel_flag and not ACCEL_COMPANION:
+    # For the main package, filter out Cython unless explicitly requested
     REQUIREMENTS = [r for r in REQUIREMENTS if not r.strip().lower().startswith('cython')]
 
 
@@ -549,7 +560,7 @@ def parse_requirements(path="requirements.txt"):
 extensions = _build_extensions()
 
 setup_info = dict(
-    name='svv',
+    name=('svv-accelerated' if ACCEL_COMPANION else 'svv'),
     version=VERSION,
     author='Zachary Sexton',
     author_email='[email protected]',
@@ -562,17 +573,18 @@ def parse_requirements(path="requirements.txt"):
     long_description=DESCRIPTION,
     long_description_content_type="text/markdown",
     ext_modules=cythonize(extensions) if (extensions and HAS_CYTHON) else [],
-    package_data={'svv.bin': ['*']},
+    package_data=( {'svv.bin': ['*']} if not ACCEL_COMPANION else {} ),
+    exclude_package_data=(
+        {"svv": ["*.so", "*.pyd", "*.dylib", "*.dll"]} if not ACCEL_COMPANION else {}
+    ),
     include_package_data=True,
     zip_safe=False,
     install_requires=REQUIREMENTS,
-    extras_require={
-        'all': [
-            'Cython>=3.0.7',
-            'numpy',
-            'cmake>=3.15'
-        ]
-    },
+    extras_require=(
+        # For the main package, make [accel] and [accelerated] pull in the companion wheel
+        {'accel': [f'svv-accelerated=={VERSION}'], 'accelerated': [f'svv-accelerated=={VERSION}']}
+        if not ACCEL_COMPANION else {}
+    ),
     cmdclass={
         'build_ext': DownloadAndBuildExt,
         'bdist_wheel': BDistWheelCmd,

svv/__init__.py

@@ -1 +1,34 @@
-__version__ = "0.0.32"
+__version__ = "0.0.32"
+
+# If the optional companion package with compiled accelerators is installed
+# (svv-accelerated), prefer those modules transparently by aliasing them into
+# svv.* import paths. This lets users simply `pip install svv[accel]` to get
+# faster implementations without changing imports in their code.
+try:
+    import importlib, sys
+    # Try importing the top-level companion namespace first.
+    importlib.import_module('svv_accel')
+    _ACCEL = {
+        'svv.domain.routines.c_allocate': 'svv_accel.domain.routines.c_allocate',
+        'svv.domain.routines.c_sample': 'svv_accel.domain.routines.c_sample',
+        'svv.utils.spatial.c_distance': 'svv_accel.utils.spatial.c_distance',
+        'svv.tree.utils.c_angle': 'svv_accel.tree.utils.c_angle',
+        'svv.tree.utils.c_basis': 'svv_accel.tree.utils.c_basis',
+        'svv.tree.utils.c_close': 'svv_accel.tree.utils.c_close',
+        'svv.tree.utils.c_local_optimize': 'svv_accel.tree.utils.c_local_optimize',
+        'svv.tree.utils.c_obb': 'svv_accel.tree.utils.c_obb',
+        'svv.tree.utils.c_update': 'svv_accel.tree.utils.c_update',
+        'svv.tree.utils.c_extend': 'svv_accel.tree.utils.c_extend',
+        'svv.simulation.utils.close_segments': 'svv_accel.simulation.utils.close_segments',
+        'svv.simulation.utils.extract': 'svv_accel.simulation.utils.extract',
+    }
+    for target, source in _ACCEL.items():
+        try:
+            mod = importlib.import_module(source)
+            sys.modules[target] = mod
+        except Exception:
+            # If a specific accelerator module is missing, leave fallback in place
+            pass
+except Exception:
+    # Companion package not installed; keep pure-Python fallbacks/compiled svv.* if present
+    pass