pylibsparseir 0.1.0__cp313-cp313-macosx_15_0_arm64.whl → 0.5.2__cp313-cp313-macosx_15_0_arm64.whl

pylibsparseir-0.5.2.dist-info/METADATA

@@ -0,0 +1,215 @@
+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
+```