Metadata-Version: 2.4
Name: free-fermion-lib
Version: 1.1.0
Summary: A comprehensive Python library for free fermion systems
Home-page: https://github.com/jdwhitfield/free-fermion-lib
Author: James D. Whitfield
Author-email: "James D. Whitfield" <James.D.Whitfield@dartmouth.edu>
License: MIT
Project-URL: Homepage, https://github.com/jdwhitfield/free-fermion-lib
Project-URL: Documentation, https://free-fermion-lib.readthedocs.io/
Project-URL: Repository, https://github.com/jdwhitfield/free-fermion-lib
Project-URL: Bug Reports, https://github.com/jdwhitfield/free-fermion-lib/issues
Keywords: quantum physics,free fermions,combinatorics,graph theory,pfaffian,quantum computing,linear algebra,symplectic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Free Fermion Library

[![PyPI version](https://img.shields.io/pypi/v/free-fermion-lib.svg)](https://pypi.org/project/free-fermion-lib/)
[![Python versions](https://img.shields.io/pypi/pyversions/free-fermion-lib.svg)](https://pypi.org/project/free-fermion-lib/)
[![Build Status](https://github.com/jdwhitfield/free-fermion-lib/workflows/CI/badge.svg)](https://github.com/jdwhitfield/free-fermion-lib/actions)
[![Downloads](https://img.shields.io/pypi/dm/free-fermion-lib.svg)](https://pypi.org/project/free-fermion-lib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/free-fermion-lib/badge/?version=latest)](https://free-fermion-lib.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/jdwhitfield/free-fermion-lib/branch/main/graph/badge.svg)](https://codecov.io/gh/jdwhitfield/free-fermion-lib)

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](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
- [Documentation](#documentation)
- [Examples](#examples)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [Development](#development)
- [Citation](#citation)
- [License](#license)
- [Contact](#contact)

## Installation

### From PyPI (Recommended)

```bash
pip install free-fermion-lib
```

### From Source

```bash
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:

```bash
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

```python
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`](https://free-fermion-lib.readthedocs.io/en/latest/api.html#ff-lib-module)**: 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`](https://free-fermion-lib.readthedocs.io/en/latest/api.html#ff-combinatorics-module)**: Combinatorial matrix functions
  - Pfaffian computation via combinatorial formula
  - Hafnian computation
  - Permanent and determinant calculations
  - Sign of permutation functions

- **[`ff_graph_theory`](https://free-fermion-lib.readthedocs.io/en/latest/api.html#ff-graph-theory-module)**: 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`](https://free-fermion-lib.readthedocs.io/en/latest/api.html#ff-utils-module)**: Common utility functions
  - Matrix cleaning and formatting
  - Random bitstring generation
  - Direct sum operations
  - Pretty printing with numerical precision control

## Documentation

📚 **[Full Documentation](https://free-fermion-lib.readthedocs.io/)**

- [Installation Guide](https://free-fermion-lib.readthedocs.io/en/latest/installation.html)
- [Quick Start Tutorial](https://free-fermion-lib.readthedocs.io/en/latest/quickstart.html)
- [API Reference](https://free-fermion-lib.readthedocs.io/en/latest/api.html)
- [Examples and Tutorials](https://free-fermion-lib.readthedocs.io/en/latest/examples.html)
- [Contributing Guide](https://free-fermion-lib.readthedocs.io/en/latest/contributing.html)

## Examples

### Basic Pfaffian Computation

```python
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

```python
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

```python
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](https://free-fermion-lib.readthedocs.io/en/latest/api.html).

### 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](https://free-fermion-lib.readthedocs.io/en/latest/contributing.html) for details.

<!--
### Quick Contributing Steps

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/your-username/free-fermion-lib.git
   cd free-fermion-lib
   ```
3. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-feature-name
   ```
4. **Install development dependencies**:
   ```bash
   pip install -e ".[dev]"
   ```
5. **Make your changes** and add tests
6. **Run the test suite**:
   ```bash
   pytest
   ```
7. **Check code formatting**:
   ```bash
   black src/ tests/
   flake8 src/ tests/
   ```
8. **Commit and push** your changes
9. **Submit a pull request**
-->

### Development Guidelines

- Follow [PEP 8](https://pep8.org/) 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](https://github.com/jdwhitfield/free-fermion-lib/issues) page.

## Development

### Setting Up Development Environment

```bash
# 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

```bash
# 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

```bash
# Format code
black src/ tests/

# Check code style
flake8 src/ tests/

# Type checking
mypy src/
```

### Building Documentation

```bash
# 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
```

<!--
### Performance Testing

```bash
# Run performance benchmarks
pytest tests/test_performance.py -v

# Profile specific functions
python -m cProfile -s cumulative your_script.py
```
-->
## Citation

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

```bibtex
@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},
}
```

<!--
### Related Publications

If this library contributes to your research, please also consider citing the foundational work:

- Whitfield, J.D. et al. "Free fermion systems and quantum computation." *Journal of Quantum Physics* (2025).
-->

## License

This project is licensed under the MIT License - see the [LICENSE](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: [James.D.Whitfield@dartmouth.edu](mailto:James.D.Whitfield@dartmouth.edu)
🏛️ Institution: Dartmouth College
🌐 Website: [https://github.com/jdwhitfield](https://github.com/jdwhitfield)

### Support

- 📖 **Documentation**: [free-fermion-lib.readthedocs.io](https://free-fermion-lib.readthedocs.io/)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/jdwhitfield/free-fermion-lib/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/jdwhitfield/free-fermion-lib/discussions)
- 📧 **Email Support**: For academic collaborations and research inquiries

---

<div align="center">

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

[![GitHub stars](https://img.shields.io/github/stars/jdwhitfield/free-fermion-lib.svg?style=social&label=Star)](https://github.com/jdwhitfield/free-fermion-lib)
[![GitHub forks](https://img.shields.io/github/forks/jdwhitfield/free-fermion-lib.svg?style=social&label=Fork)](https://github.com/jdwhitfield/free-fermion-lib/fork)

</div>
