beampower 1.0.3__tar.gz

beampower-1.0.3/BUILDING_WHEELS.md

@@ -0,0 +1,328 @@
+# Building and Distributing BeamPower Wheels
+
+This guide explains how to build, test, and distribute pre-compiled binary wheels for the `beampower` package so users don't need to compile the C/CUDA code.
+
+## Overview
+
+Instead of requiring users to have compilers and the CUDA toolkit installed, `beampower` is now distributed as pre-built binary wheels. Users can simply run:
+
+```bash
+pip install beampower
+```
+
+## Building Wheels Locally
+
+### Prerequisites
+
+- Python 3.8+
+- `build` package: `pip install build wheel`
+- For CPU wheels: GCC/Clang compiler, OpenMP
+- For GPU wheels: NVIDIA CUDA Toolkit, NVIDIA cuDNN
+
+### Build CPU Wheel
+
+```bash
+# Build the CPU library first
+make clean
+make python_CPU
+
+# Create the wheel
+python -m build --wheel
+```
+
+### Build GPU Wheel
+
+```bash
+# Build the GPU library (requires CUDA)
+make clean
+make python_GPU
+
+# Create the wheel
+python -m build --wheel
+```
+
+### Build Both CPU and GPU in the Same Wheel
+
+```bash
+make clean
+make  # builds both CPU and GPU
+
+python -m build --wheel
+```
+
+The resulting `.whl` file will be in the `dist/` directory.
+
+## Automated Building with GitHub Actions (Recommended)
+
+For cross-platform, multi-architecture builds, use the included GitHub Actions workflow.
+
+### Setup
+
+1. Ensure you have a GitHub repository for beampower
+2. Add the `.github/workflows/build-wheels.yml` workflow file (see template below)
+3. Push to GitHub
+
+### Workflow Template
+
+Create `.github/workflows/build-wheels.yml`:
+
+```yaml
+name: Build and publish wheels
+
+on:
+  push:
+    tags:
+      - 'v*'  # Build on version tags
+  workflow_dispatch:  # Allow manual builds
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build wheel
+        # For Ubuntu: sudo apt-get install gcc make libomp-dev
+        # For macOS: brew install libomp (if needed)
+    
+    - name: Build CPU library
+      run: |
+        make clean
+        make python_CPU
+    
+    - name: Build wheel
+      run: python -m build --wheel
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        path: ./dist/*.whl
+    
+    - name: Publish to PyPI
+      if: startsWith(github.ref, 'refs/tags/')
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        pip install twine
+        twine upload dist/*.whl --skip-existing
+
+  build_wheels_gpu:
+    name: Build GPU wheels (CUDA)
+    runs-on: ubuntu-latest
+    container: nvidia/cuda:11.8.0-devel-ubuntu22.04
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Install dependencies
+      run: |
+        apt-get update
+        apt-get install -y python3 python3-pip make gcc g++ git
+        python3 -m pip install --upgrade pip build wheel
+    
+    - name: Build GPU library
+      run: |
+        make clean
+        make python_GPU
+    
+    - name: Build wheel
+      run: python3 -m build --wheel
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        path: ./dist/*.whl
+    
+    - name: Publish to PyPI
+      if: startsWith(github.ref, 'refs/tags/')
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        python3 -m pip install twine
+        twine upload dist/*.whl --skip-existing
+```
+
+### Using cibuildwheel (Advanced Alternative)
+
+For maximum compatibility across Python versions and architectures, consider using `cibuildwheel`:
+
+```yaml
+name: Build wheels
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build_wheels:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+      - name: Upload wheels
+        uses: actions/upload-artifact@v3
+        with:
+          path: dist/*.whl
+```
+
+## Publishing to PyPI
+
+### Option 1: Automated Publishing via GitHub Actions
+
+1. Create a PyPI API token at https://pypi.org/account/
+2. Add it to GitHub secrets as `PYPI_API_TOKEN`
+3. Push a version tag: `git tag v1.0.3 && git push --tags`
+4. GitHub Actions will automatically build and publish wheels
+
+### Option 2: Manual Publishing
+
+```bash
+# Build all wheels locally
+make clean
+make python_CPU
+python -m build --wheel
+
+# Install twine
+pip install twine
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+### Option 3: Test PyPI First
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Then test installation:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ beampower
+```
+
+## Platform-Specific Considerations
+
+### Linux (CPU)
+- Uses `gcc`, `make`, and OpenMP
+- `.so` files target Linux x86_64
+
+### Linux (GPU)
+- Requires NVIDIA CUDA Toolkit
+- Builds `.so` files with CUDA support
+- Docker/container recommended for reproducibility
+
+### macOS
+- Use `clang` (Apple Silicon) or `gcc` (Intel)
+- Generates `.so` or `.dylib` files
+- May need `brew install libomp`
+
+### Windows
+- Requires MinGW or Microsoft Visual C++
+- Generates `.pyd` files
+- More complex; recommend focusing on Linux/macOS first
+
+## Verifying Wheels
+
+After building, verify the wheel contents:
+
+```bash
+# List contents
+unzip -l dist/beampower-1.0.3-py3-none-any.whl
+
+# Should include:
+# - beampower/__init__.py
+# - beampower/beampower.py
+# - beampower/core.py
+# - beampower/lib/beamform_cpu.so (or .pyd, .dylib)
+# - beampower/lib/beamform_gpu.so (optional)
+```
+
+Test installation:
+
+```bash
+pip install --force-reinstall dist/beampower-1.0.3-py3-none-any.whl
+python -c "import beampower; print(beampower.__version__)"
+```
+
+## Troubleshooting
+
+### Missing `.so` files in wheel
+
+Ensure `MANIFEST.in` includes:
+```
+recursive-include beampower/lib *.so
+recursive-include beampower/lib *.pyd
+recursive-include beampower/lib *.dylib
+```
+
+And run `make` before `python -m build --wheel`.
+
+### "ModuleNotFoundError: No module named 'beampower.lib'"
+
+The `.so` files weren't included in the wheel. Rebuild using the correct MANIFEST.in.
+
+### CUDA not found when building GPU
+
+Ensure `nvcc` is in your PATH:
+```bash
+export PATH=/usr/local/cuda/bin:$PATH
+which nvcc
+```
+
+### Different Python versions
+
+Build wheels for each supported Python version:
+
+```bash
+for python_version in 3.8 3.9 3.10 3.11 3.12; do
+    python${python_version} -m build --wheel
+done
+```
+
+## Distribution Channels
+
+1. **PyPI (Python Package Index)** - Recommended for public packages
+2. **GitHub Releases** - Good for alpha/beta versions
+3. **Private PyPI Server** - For internal/proprietary packages
+4. **Conda-Forge** - For conda users
+5. **Direct downloads** - For enterprise customers
+
+## Post-Release
+
+After publishing:
+
+1. Tag the release: `git tag v1.0.3`
+2. Create GitHub Release with notes
+3. Announce on relevant channels (email, forums, etc.)
+4. Update documentation links
+5. Monitor for installation issues
+
+## References
+
+- [Python Packaging Guide](https://packaging.python.org/)
+- [Wheel Documentation](https://wheel.readthedocs.io/)
+- [setuptools Documentation](https://setuptools.pypa.io/)
+- [cibuildwheel Documentation](https://cibuildwheel.readthedocs.io/)

beampower-1.0.3/LICENSE

@@ -0,0 +1,21 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 Eric Beaucé
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU 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 General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+For the full license text, see: https://www.gnu.org/licenses/gpl-3.0.html

beampower-1.0.3/MANIFEST.in

@@ -0,0 +1,24 @@
+# Manifest file for Python distribution
+# Include source files for reference
+include beampower/src/beamform.c
+include beampower/src/beamform_cpu.h
+include beampower/src/beamform.cu
+include beampower/src/beamform_gpu.h
+
+# Include Python files
+include beampower/__init__.py
+include beampower/beampower.py
+include beampower/core.py
+
+# Include pre-built shared libraries (critical for distribution)
+recursive-include beampower/lib *.so
+recursive-include beampower/lib *.pyd
+recursive-include beampower/lib *.dylib
+
+# Include documentation and build files
+include LICENSE
+include Makefile
+include README.md
+include setup.py
+include pyproject.toml
+include BUILDING_WHEELS.md

beampower-1.0.3/Makefile

@@ -0,0 +1,93 @@
+# DIRECTORIES
+maindir=beampower
+srcdir=$(maindir)/src
+libdir=$(maindir)/lib
+
+# Automatic platform detection
+UNAME_S := $(shell uname -s)
+UNAME_M := $(shell uname -m)
+
+# Define compilers
+NVCC=nvcc
+
+# Auto-detect C compiler based on platform
+ifeq ($(UNAME_S),Darwin)
+    # macOS: prefer clang for ARM64, gcc for Intel
+    ifeq ($(UNAME_M),arm64)
+        CC=clang
+    else
+        CC=gcc
+    endif
+else
+    # Linux and others: use gcc
+    CC=gcc
+endif
+
+# Define commands
+all: $(libdir)/beamform_cpu.so $(libdir)/beamform_gpu.so
+python_CPU: $(libdir)/beamform_cpu.so
+python_GPU: $(libdir)/beamform_gpu.so
+.SUFFIXES: .c .cu
+
+# -----------------------------------------------
+#                CPU FLAGS
+# -----------------------------------------------
+COPTIMFLAGS_CPU=-O3
+
+# Auto-detect OpenMP configuration for macOS and Linux
+ifeq ($(UNAME_S),Darwin)
+    # macOS: Priority order - venv/conda (with -fopenmp=libomp) > brew libomp (with paths) > system
+    
+    # Check for venv/conda first
+    VENV_PATHS := $(shell python -c "import sys, os; is_venv = hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix); in_conda = 'CONDA_PREFIX' in os.environ; prefix = os.environ.get('CONDA_PREFIX', sys.prefix) if (is_venv or in_conda) else ''; print(prefix if prefix else '')")
+    
+    ifneq ($(VENV_PATHS),)
+        # In venv/conda: use -fopenmp=libomp with venv paths
+        CFLAGS_CPU=-fopenmp=libomp -L$(VENV_PATHS)/lib -I$(VENV_PATHS)/include -fPIC -ftree-vectorize -march=native -std=c99
+        LDFLAGS_CPU=-shared -fuse-ld=lld
+    else
+        # Not in venv/conda: check for brew libomp
+        ifeq ($(UNAME_M),arm64)
+            BREW_LIBOMP_PATH := /opt/homebrew/opt/libomp
+        else
+            BREW_LIBOMP_PATH := /usr/local/opt/libomp
+        endif
+        
+        ifeq ($(shell [ -d $(BREW_LIBOMP_PATH) ] && echo 1 || echo 0),1)
+            # Use brew libomp with explicit linking (GitHub Actions)
+            # Don't use -fopenmp flag; instead explicitly link with -lomp
+            CFLAGS_CPU=-L$(BREW_LIBOMP_PATH)/lib -I$(BREW_LIBOMP_PATH)/include -fPIC -ftree-vectorize -march=native -std=c99
+            LDFLAGS_CPU=-L$(BREW_LIBOMP_PATH)/lib -lomp -shared
+        else
+            # Fall back to system OpenMP
+            CFLAGS_CPU=-fopenmp -fPIC -ftree-vectorize -march=native -std=c99
+            LDFLAGS_CPU=-shared
+        endif
+    endif
+else
+    # Linux and Unix-like systems
+    CFLAGS_CPU=-fopenmp -fPIC -ftree-vectorize -march=native -std=c99
+    LDFLAGS_CPU=-shared
+endif
+
+# -----------------------------------------------
+#              GPU FLAGS
+# -----------------------------------------------
+COPTIMFLAGS_GPU=-O3
+CFLAGS_GPU=-Xcompiler "-fopenmp -fPIC -march=native -ftree-vectorize" -Xlinker -lgomp
+ARCHFLAG=-gencode arch=compute_70,code=sm_70\
+         -gencode arch=compute_75,code=sm_75\
+         -gencode arch=compute_80,code=sm_80
+
+LDFLAGS_GPU=--shared
+
+# build for python
+$(libdir)/beamform_cpu.so: $(srcdir)/beamform.c
+	$(CC) $(COPTIMFLAGS_CPU) $(CFLAGS_CPU) $(LDFLAGS_CPU) $< -o $@
+
+$(libdir)/beamform_gpu.so: $(srcdir)/beamform.cu
+	$(NVCC) $(COPTIMFLAGS_GPU) $(CFLAGS_GPU) $(ARCHFLAG) $(LDFLAGS_GPU) $< -o $@
+
+clean:
+	rm -f $(libdir)/*.so
+

beampower-1.0.3/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: beampower
+Version: 1.0.3
+Summary: Package for beamforming/backprojection.
+Author: William Frank, Léonard Seydoux
+Author-email: Eric Beaucé <ebeauce@ldeo.columbia.edu>
+Maintainer: William Frank, Léonard Seydoux
+Maintainer-email: Eric Beaucé <ebeauce@ldeo.columbia.edu>
+License: GPL-3.0
+Project-URL: GitHub, https://github.com/ebeauce/beampower
+Project-URL: Documentation, https://ebeauce.github.io/beampower
+Project-URL: Issues, https://github.com/ebeauce/beampower/issues
+Keywords: earthquake detection,backprojection,beamforming
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.5
+Dynamic: license-file
+
+# Welcome to the __beampower__ repository!
+
+<p align="center">
+<img src="data/beampower_logo.png" width=350>
+</p><br><br><br><br>
+
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![](https://img.shields.io/github/commit-activity/w/ebeauce/beampower)
+![](https://img.shields.io/github/last-commit/ebeauce/beampower)
+![](https://img.shields.io/github/stars/ebeauce/beampower?style=social)
+
+### About the package
+`beampower` is a package for beamforming (or backprojection) of seismic signal for event detection and location. The Python wrapper
+can call the C (CPU) or CUDA-C (GPU) implementation. See the documentation at [https://ebeauce.github.io/beampower/](https://ebeauce.github.io/beampower/).
+
+
+## Installation
+
+The simplest way to use BeamPower:
+
+```bash
+pip install beampower
+```
+
+GPU support is included if available.
+
+## Learn More
+
+- **Documentation**: https://ebeauce.github.io/beampower/
+- **Tutorials**: See the notebooks in the `notebooks/` folder
+  - Download seismic data
+  - Pre-process waveforms
+  - Calculate travel times
+  - Locate events
+
+## For Developers
+
+**Clone and install locally:**
+
+```bash
+git clone https://github.com/ebeauce/beampower.git
+cd beampower
+
+# Build the libraries FIRST (required for local development)
+make clean
+make  # builds both CPU and GPU libraries
+
+# Then install
+pip install .
+```
+
+**If you modify C or CUDA code:**
+
+```bash
+# For C code changes:
+make clean
+make python_CPU
+
+# For CUDA code changes:
+make clean
+make python_GPU
+
+# For both:
+make clean
+make
+
+# Then reinstall to pick up changes:
+pip install --force-reinstall .
+```
+
+
+## Reference
+Please, if you use this package for your research, cite:
+
+Beaucé, Eric and Frank, William B. and Seydoux, Léonard and Poli, Piero and Groebner, Nathan
+and van der Hilst, Robert D. and Campillo, Michel (2023). BPMF: A Backprojection and Matched‐Filtering Workflow for Automated Earthquake Detection and Location. *Seismological Research Letters*. DOI: [https://doi.org/10.1785/0220230230](https://doi.org/10.1785/0220230230).

beampower-1.0.3/README.md

@@ -0,0 +1,77 @@
+# Welcome to the __beampower__ repository!
+
+<p align="center">
+<img src="data/beampower_logo.png" width=350>
+</p><br><br><br><br>
+
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![](https://img.shields.io/github/commit-activity/w/ebeauce/beampower)
+![](https://img.shields.io/github/last-commit/ebeauce/beampower)
+![](https://img.shields.io/github/stars/ebeauce/beampower?style=social)
+
+### About the package
+`beampower` is a package for beamforming (or backprojection) of seismic signal for event detection and location. The Python wrapper
+can call the C (CPU) or CUDA-C (GPU) implementation. See the documentation at [https://ebeauce.github.io/beampower/](https://ebeauce.github.io/beampower/).
+
+
+## Installation
+
+The simplest way to use BeamPower:
+
+```bash
+pip install beampower
+```
+
+GPU support is included if available.
+
+## Learn More
+
+- **Documentation**: https://ebeauce.github.io/beampower/
+- **Tutorials**: See the notebooks in the `notebooks/` folder
+  - Download seismic data
+  - Pre-process waveforms
+  - Calculate travel times
+  - Locate events
+
+## For Developers
+
+**Clone and install locally:**
+
+```bash
+git clone https://github.com/ebeauce/beampower.git
+cd beampower
+
+# Build the libraries FIRST (required for local development)
+make clean
+make  # builds both CPU and GPU libraries
+
+# Then install
+pip install .
+```
+
+**If you modify C or CUDA code:**
+
+```bash
+# For C code changes:
+make clean
+make python_CPU
+
+# For CUDA code changes:
+make clean
+make python_GPU
+
+# For both:
+make clean
+make
+
+# Then reinstall to pick up changes:
+pip install --force-reinstall .
+```
+
+
+## Reference
+Please, if you use this package for your research, cite:
+
+Beaucé, Eric and Frank, William B. and Seydoux, Léonard and Poli, Piero and Groebner, Nathan
+and van der Hilst, Robert D. and Campillo, Michel (2023). BPMF: A Backprojection and Matched‐Filtering Workflow for Automated Earthquake Detection and Location. *Seismological Research Letters*. DOI: [https://doi.org/10.1785/0220230230](https://doi.org/10.1785/0220230230).

beampower-1.0.3/beampower/__init__.py

@@ -0,0 +1,14 @@
+"""
+beampower is a Python package wrapping a C and CUDA-C implementation
+of beamforming, sometimes also called back-projection.  
+
+If you have any question, don't hesitate contacting me at: 
+ebeauce@ldeo.columbia.edu
+"""
+
+__all__ = ["load_library", "beamform"]
+
+from .core import load_library
+from .beampower import beamform
+
+__version__ = "1.0.3"