free-fermion-lib 1.1.0

A comprehensive Python library for free fermion systems

Free Fermion Library

A comprehensive Python library for working with free fermion quantum systems, providing tools for combinatorial functions, graph theory algorithms, and quantum physics utilities. This work was supported by the U.S. Department of Energy, Office of Basic Energy Sciences, under Award DE-SC0019374 and by Army Research Office grant W911NF2410043.

Table of Contents

• Installation
• Quick Start
• Features
• Documentation
• Examples
• API Reference
• Contributing
• Development
• Citation
• License
• Contact

Installation

From PyPI (Recommended)

pip install free-fermion-lib

From Source

git clone https://github.com/jdwhitfield/free-fermion-lib.git
cd free-fermion-lib
pip install -e .

Development Installation

For development with all optional dependencies:

git clone https://github.com/jdwhitfield/free-fermion-lib.git
cd free-fermion-lib
pip install -e ".[dev,docs]"

Requirements

• Python: >= 3.8
• Core Dependencies:
  • NumPy >= 1.20.0
  • SciPy >= 1.7.0
  • NetworkX >= 2.6.0
  • Matplotlib >= 3.3.0

Quick Start

import numpy as np
import ff

# Generate Jordan-Wigner operators for 3 sites
n_sites = 3
alphas = ff.jordan_wigner_alphas(n_sites)

# Generate a Gaussian state
rho = ff.random_FF_state(n_sites)

# Compute correlation matrix
gamma = ff.compute_2corr_matrix(rho, n_sites, alphas)

# Compute pfaffian of a skew-symmetric matrix
skew_matrix = np.array([[0, 1, -2], [-1, 0, 3], [2, -3, 0]])
pfaffian_value = ff.pf(skew_matrix)

Features

Core Modules

• ff_lib: Core free-fermion functions

  • Jordan-Wigner transformations (Dirac and Majorana fermions)
  • Symplectic free-fermion diagonalization
  • Gaussian state generation and manipulation
  • Fermionic correlation matrix computations
  • Wick's theorem implementation

• ff_combinatorics: Combinatorial matrix functions

  • Pfaffian computation via combinatorial formula
  • Hafnian computation
  • Permanent and determinant calculations
  • Sign of permutation functions

• ff_graph_theory: Graph algorithms and visualization

  • Pfaffian ordering algorithm (FKT algorithm) for planar graphs
  • Perfect matching algorithms
  • Planar graph generation and visualization
  • Dual graph construction

• ff_utils: Common utility functions

  • Matrix cleaning and formatting
  • Random bitstring generation
  • Direct sum operations
  • Pretty printing with numerical precision control

Documentation

📚 Full Documentation

• Installation Guide
• Quick Start Tutorial
• API Reference
• Examples and Tutorials
• Contributing Guide

Examples

Basic Pfaffian Computation

import numpy as np
from ff.ff_combinatorics import pf

# Create a skew-symmetric matrix
matrix = np.array([[0, 1, -2, 3],
                   [-1, 0, 4, -5],
                   [2, -4, 0, 6],
                   [-3, 5, -6, 0]])

# Compute pfaffian
pfaffian_value = pf(matrix)
print(f"Pfaffian: {pfaffian_value}")

Jordan-Wigner Transformation

from ff.ff_lib import jordan_wigner_alphas, build_H, build_op
import numpy as np

# Generate operators for a 4-site system
n_sites = 4
alphas = jordan_wigner_alphas(n_sites)

# Create a hopping Hamiltonian
hopping_matrix = np.diag(np.ones(n_sites-1), 1) + np.diag(np.ones(n_sites-1), -1)
H = build_H(n_sites, hopping_matrix)

H_op = build_op(H,alphas)

Graph Theory Applications

from ff.ff_graph_theory import pfaffian_orientation
import networkx as nx

# Create a planar graph
G = nx.grid_2d_graph(3, 3)
# Find pfaffian orientation
oriented_graph = pfaffian_orientation(G)

API Reference

The complete API documentation is available at free-fermion-lib.readthedocs.io.

Key Functions

Module	Function	Description
ff_lib	jordan_wigner_alphas()	Generate Jordan-Wigner operators
ff_lib	build_H()	Construct Hamiltonian matrices
ff_lib	random_FF_state()	Generate random Gaussian states
ff_combinatorics	pf()	Compute matrix pfaffian
ff_combinatorics	hafnian()	Compute matrix hafnian
ff_graph_theory	pfaffian_orientation()	Find pfaffian orientation of graphs
ff_utils	clean_matrix()	Clean numerical matrices

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Guidelines

• Follow PEP 8 style guidelines
• Add tests for new functionality
• Update documentation for API changes
• Ensure all tests pass before submitting PR
• Use meaningful commit messages

Reporting Issues

Please report bugs and feature requests on our GitHub Issues page.

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/jdwhitfield/free-fermion-lib.git
cd free-fermion-lib

# Install in development mode with all dependencies
pip install -e ".[dev,docs]"

# Install pre-commit hooks (optional but recommended)
pre-commit install

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=ff --cov-report=html

# Run specific test file
pytest tests/test_ff_lib.py

# Run tests in parallel
pytest -n auto

Code Quality

# Format code
black src/ tests/

# Check code style
flake8 src/ tests/

# Type checking
mypy src/

Building Documentation

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation locally
cd docs/
make html

# View documentation
open _build/html/index.html  # macOS
# or
xdg-open _build/html/index.html  # Linux

Citation

If you use this library in your research, please cite:

@software{free_fermion_lib,
  author = {James D. Whitfield},
  title = {Free Fermion Library: A Python package for quantum free fermion systems},
  version = {1.0.0},
  year = {2025},
  url = {https://github.com/jdwhitfield/free-fermion-lib},
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

This project depends on several open-source packages:

• NumPy (BSD License)
• SciPy (BSD License)
• NetworkX (BSD License)
• Matplotlib (PSF License)

Acknowledgments

This work was supported by:

• U.S. Department of Energy, Office of Basic Energy Sciences, under Award DE-SC0019374
• Army Research Office grant W911NF2410043

Special thanks to the contributors and the open-source community.

Contact

James D. Whitfield 📧 Email: [e-mail] 🏛️ Institution: Dartmouth College 🌐 Website: https://github.com/jdwhitfield

Support

• 📖 Documentation: free-fermion-lib.readthedocs.io
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email Support: For academic collaborations and research inquiries

---

Free Fermion Library - Advancing quantum physics research through open-source software