Metadata-Version: 2.2
Name: pylibsparseir
Version: 0.5.2
Summary: Python bindings for the libsparseir library
Maintainer: SpM-lab
License: MIT License
         
         Copyright (c) 2024 SpM-lab
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://github.com/SpM-lab/libsparseir
Project-URL: Documentation, https://github.com/SpM-lab/libsparseir
Project-URL: Repository, https://github.com/SpM-lab/libsparseir
Project-URL: Issues, https://github.com/SpM-lab/libsparseir/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy
Description-Content-Type: text/markdown

# Python bindings for libsparseir

This is a low-level binding for the [libsparseir](https://github.com/SpM-lab/libsparseir) library.

## Requirements

- Python >= 3.10
- CMake (for building the C++ library)
- C++11 compatible compiler
- numpy

### Optional Dependencies

- **OpenBLAS** (recommended for better performance)
  - macOS: `brew install openblas`
  - Ubuntu/Debian: `sudo apt install libopenblas-dev`
  - CentOS/RHEL: `sudo yum install openblas-devel`

## Build

### Install Dependencies and Build

**Option 1: Automatic build (recommended)**
```bash
# Build will automatically run prepare_build.py if needed
uv build
```

**Option 2: Manual preparation**
```bash
# First, prepare the build by copying necessary files from parent directory
python3 prepare_build.py

# Then build the package
uv build
```

This will:
- Copy source files (`src/`, `include/`, `cmake/`) from the parent libsparseir directory
- Build the C++ libsparseir library using CMake with BLAS support
- Create both source distribution (sdist) and wheel packages

### Development Build

For development:

```bash
# Install in development mode (will auto-prepare if needed)
uv sync
```

**Note for CI/CD**: In CI environments, you must run `prepare_build.py` before building:

```bash
# In CI/CD scripts
cd python
python3 prepare_build.py
uv build
```

See `.github-workflows-example.yml` for a complete GitHub Actions example.

### Build with OpenBLAS Support

OpenBLAS support is enabled by default in the build configuration. The build system will automatically detect OpenBLAS if it's installed in standard locations.

If OpenBLAS is installed in a custom location, you may need to set additional environment variables:

```bash
export CMAKE_PREFIX_PATH="/path/to/openblas"
python3 prepare_build.py
uv build
```

### Clean Build Artifacts

To remove build artifacts and files copied from the parent directory:

```bash
uv run clean
```

This will remove:
- Build directories: `build/`, `dist/`, `*.egg-info`
- Copied source files: `include/`, `src/`, `cmake/` (copied by `prepare_build.py`)
- Compiled libraries: `pylibsparseir/*.so`, `pylibsparseir/*.dylib`, `pylibsparseir/*.dll`
- Cache directories: `pylibsparseir/__pycache__`

### Build Process Overview

The build process works as follows:

1. **File Preparation**: `prepare_build.py` copies necessary files from the parent libsparseir directory:
   - Source files (`../src/` → `src/`)
   - Header files (`../include/` → `include/`)
   - CMake configuration (`../cmake/` → `cmake/`)

2. **Package Building**: `uv build` or `uv sync` uses scikit-build-core to:
   - Configure CMake with BLAS support enabled
   - Compile the C++ library with dynamic BLAS symbol lookup (for NumPy compatibility)
   - Package everything into distributable wheels and source distributions

3. **Installation**: The built package includes the compiled shared library and Python bindings

**Why File Copying?**: The `prepare_build.py` script copies files from the parent directory instead of using symbolic links to ensure:
- Cross-platform compatibility (Windows doesn't handle symlinks well)
- Proper inclusion in source distributions (sdist)
- Clean separation between the main C++ library and Python bindings

## Performance Notes

### BLAS Support

This package supports BLAS libraries for improved linear algebra performance:

- **With OpenBLAS**: Significant performance improvements for matrix operations
- **Without BLAS**: Uses Eigen's built-in implementations (still efficient, but slower for large matrices)

The build system will automatically detect and use OpenBLAS if available. You can verify BLAS support by checking the build output for messages like:

```
BLAS support enabled
Found OpenBLAS at: /opt/homebrew/opt/openblas
```

### Troubleshooting

**Build fails with missing source files:**
```bash
# Make sure to run prepare_build.py first
python3 prepare_build.py
uv build
```

**Build fails with "Could NOT find BLAS":**
```bash
# Install OpenBLAS first
brew install openblas  # macOS
sudo apt install libopenblas-dev  # Ubuntu

# Then build with proper CMake path
export CMAKE_PREFIX_PATH="/path/to/openblas"
python3 prepare_build.py
uv build
```

**OpenBLAS not detected automatically:**
```bash
# Set CMake prefix path manually
export CMAKE_PREFIX_PATH="/usr/local/opt/openblas"  # or your OpenBLAS path
python3 prepare_build.py
uv build
```

**Clean rebuild:**
```bash
# Remove all copied files and build artifacts
uv run clean
python3 prepare_build.py
uv build
```

**Verify BLAS support in built package:**
```python
import pylibsparseir
# Check build logs for "BLAS support enabled" message
# BLAS symbols are resolved dynamically through NumPy at runtime
```
