pysparseir

Python bindings for the libsparseir library, providing efficient sparse intermediate representation for many-body physics calculations.

Overview

pysparseir is a Python wrapper for the libsparseir C++ library, which implements the sparse intermediate representation (IR) method for Green's functions in many-body physics. The library provides efficient tools for working with fermionic and bosonic systems.

Requirements

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

Installation

1. Clone the Repository

git clone --recursive https://github.com/SpM-lab/pysparseir.git
cd pysparseir

Important: Use --recursive to automatically initialize git submodules.

2. Initialize Submodules (if not cloned recursively)

If you forgot to use --recursive when cloning:

git submodule init
git submodule update

3. Install Dependencies and Build

uv sync

This will:

• Install Python dependencies (numpy)
• Build the C++ libsparseir library using CMake
• Install the Python package in development mode

Usage

Basic Example

import pylibsparseir

# Create a logistic kernel
kernel = pylibsparseir.LogisticKernel(1.0)

# Create a regularized bosonic kernel
bose_kernel = pylibsparseir.reg_bose_kernel_new(1.0)

# Get kernel domain
xmin, xmax, ymin, ymax = pylibsparseir.kernel_domain(kernel)
print(f"Kernel domain: x=[{xmin}, {xmax}], y=[{ymin}, {ymax}]")

# Create SVE result
sve = pylibsparseir.sve_result_new(kernel, 1e-12)
size = pylibsparseir.sve_result_get_size(sve)
print(f"SVE result size: {size}")

# Get singular values
svals = pylibsparseir.sve_result_get_svals(sve)
print(f"First few singular values: {svals[:5]}")

Alternative Import

You can also import with an alias:

import pylibsparseir as pysparseir

kernel = pysparseir.LogisticKernel(1.0)

Development

Project Structure

pysparseir/
├── libsparseir/          # C++ library (git submodule)
├── src/
│   └── pylibsparseir/    # Python package
│       ├── __init__.py
│       ├── core.py       # Main wrapper functions
│       ├── constants.py  # Constants
│       └── ctypes_wrapper.py  # ctypes type definitions
├── setup.py              # Build configuration
├── pyproject.toml        # Project metadata
└── README.md

Troubleshooting

Common Issues

1. CMake Error: CMakeLists.txt not found

   git submodule init
   git submodule update

2. ModuleNotFoundError: No module named 'pylibsparseir'

   uv sync --reinstall

3. Symbol not found errors

   • Ensure the C++ library built successfully
   • Check that the shared library files (*.dylib on macOS, *.so on Linux) exist in src/pylibsparseir/

4. Import errors

   • Make sure numpy is installed: uv add numpy
   • Verify Python >= 3.12 is being used

Checking Installation

To verify the installation works:

uv run python -c "import pylibsparseir; print('✓ Installation successful!')"