free-fermion-lib 1.2.2

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, quantum physics utilities, and advanced distance measures for quantum state analysis. The library includes statistical and quantum distance measures for characterizing quantum states and their proximity to classical, stabilizer, or free-fermion subspaces. 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_distance_measures: Quantum state distance measures and entropy functions

  • Stabilizer Rényi Entropy (SRE) for quantifying magic resources
  • Fermionic Anti-Flatness (FAF) for measuring deviation from free-fermion behavior
  • Statistical distance measures: Total variation, Jensen-Shannon divergence, Bhattacharyya coefficient
  • Information-theoretic measures: Kullback-Leibler divergence, Rényi entropy, linear entropy
  • Quantum distance measures: Trace distance for density matrices
  • Fermionic covariance distribution analysis

• 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

Statistical Distance Measures

The ff_distance_measures module provides a comprehensive suite of distance measures for quantum state analysis:

Quantum-Specific Measures:

• Stabilizer Rényi Entropy (SRE): Quantifies "magic" or non-stabilizer resources in quantum states
• Fermionic Anti-Flatness (FAF): Measures deviation from free-fermion (Gaussian) behavior
• Trace Distance: Standard quantum distance measure between density matrices

Statistical Distance Measures:

• Jensen-Shannon Divergence: Symmetric, bounded version of KL divergence
• Total Variation Distance: L1-based distance between probability distributions
• Bhattacharyya Coefficient: Similarity measure between distributions
• Kullback-Leibler Divergence: Information-theoretic divergence measure

Entropy Measures:

• Rényi Entropy: Generalized entropy with tunable parameter α
• Linear Entropy: Efficient measure of mixedness for quantum states

These measures are fundamental tools for characterizing quantum states and their proximity to classical, stabilizer, or free-fermion subspaces in quantum many-body systems.

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)

Distance Measures and Quantum State Analysis

from ff.ff_distance_measures import SRE, FAF, jensen_shannon_divergence, trace_distance
import numpy as np

# Compute Stabilizer Rényi Entropy for a quantum state
rho = np.eye(4) / 4  # Maximally mixed 2-qubit state
sre_value = SRE(rho, a=2)
print(f"Stabilizer Rényi Entropy: {sre_value}")

# Compute Fermionic Anti-Flatness
faf_value = FAF(rho, k=2)
print(f"Fermionic Anti-Flatness: {faf_value}")

# Compare two probability distributions
p = np.array([0.5, 0.3, 0.2])
q = np.array([0.4, 0.4, 0.2])
js_div = jensen_shannon_divergence(p, q)
print(f"Jensen-Shannon Divergence: {js_div}")

# Compute trace distance between density matrices
rho1 = np.array([[0.7, 0], [0, 0.3]])
rho2 = np.array([[0.6, 0], [0, 0.4]])
td = trace_distance(rho1, rho2)
print(f"Trace Distance: {td}")

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_distance_measures	SRE()	Compute Stabilizer Rényi Entropy
ff_distance_measures	FAF()	Compute Fermionic Anti-Flatness
ff_distance_measures	stabilizer_distribution()	Compute stabilizer probability distribution
ff_distance_measures	jensen_shannon_divergence()	Compute Jensen-Shannon divergence
ff_distance_measures	total_variation_distance()	Compute total variation distance
ff_distance_measures	trace_distance()	Compute trace distance between density matrices
ff_distance_measures	relative_entropy()	Compute Kullback-Leibler divergence
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