Metadata-Version: 2.4
Name: flqtb
Version: 0.1.0
Summary: Floquet engineering for tight-binding models on top of pythtb 2.0+
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/flqtb
Project-URL: Repository, https://github.com/yourusername/flqtb
Project-URL: Issues, https://github.com/yourusername/flqtb/issues
Keywords: tight-binding,floquet,pythtb,condensed-matter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pythtb>=2.0.0
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

# flqtb — Floquet Tight-Binding on pythtb 2.0+

基于 [pythtb](https://www.physics.rutgers.edu/pythtb/) 2.0.0+ 的 Floquet 紧束缚模型扩展，使用高频 Magnus 展开计算圆偏振光驱动下的有效静态哈密顿量。

## 核心公式

含时哈密顿量通过 Peierls 替换引入光场：

$$
H(t) = \sum_i \epsilon_i c_i^\dagger c_i + \sum_{\langle ij \rangle} t_{ij} e^{-i \mathbf{A}(t) \cdot \mathbf{d}_{ij}} c_i^\dagger c_j + \text{h.c.}
$$

对圆偏振光：

$$
\mathbf{A}(t) = A_0 \left[ \mathbf{e}_1 \cos(\omega t) + \eta \, \mathbf{e}_2 \sin(\omega t) \right]
$$

其中 $(\mathbf{e}_1, \mathbf{e}_2, \mathbf{n})$ 构成右手正交基，$\mathbf{n}$ 即 `direction`，$\eta = \pm 1$ 控制手性。

有效哈密顿量（高频展开）：

$$
H_{\text{eff}} = H^{(0)} + \sum_{n=1}^{n_{\max}} \frac{[H^{(-n)}, H^{(n)}]}{n \, \omega}
$$

$H^{(n)}$ 是 $H(t)$ 的第 $n$ 阶傅里叶分量。

## 安装

发布到 PyPI 后：

```bash
pip install flqtb
```

开发安装：

```bash
git clone https://github.com/yourusername/flqtb.git
cd flqtb
pip install -e ".[dev]"
```

## 快速开始

```python
import numpy as np
from pythtb import Lattice
from flqtb import FloquetModel

# 构建石墨烯晶格
lat = Lattice(
    lat_vecs=[[1.0, 0.0], [0.5, np.sqrt(3)/2]],
    orb_vecs=[[0.0, 0.0], [1/3, 2/3]],
    periodic_dirs=[0, 1]
)

# 创建模型
model = FloquetModel(lat)
model.set_hop(-1.0, 0, 1, [0, 0])

# 开启圆偏振光驱动（默认 xy 平面，η=+1）
model.set_drive(A0=1.5, omega=5.0, eta=1)

# 计算能带
kpts = np.linspace(0, 1, 50)
kpath = np.column_stack([kpts, np.zeros_like(kpts)])
evals = model.solve_ham(k_pts=kpath)
```

## API

### `FloquetModel(lattice, spinful=False)`

继承自 `pythtb.TBModel`。构造方式与 `TBModel` 完全一致：

```python
model = FloquetModel(lat, spinful=False)   # 推荐
```

### `model.set_drive(A0, omega, eta=1, n_max=1, direction=None)`

配置圆偏振驱动。

| 参数 | 说明 |
|------|------|
| `A0` | 矢量势振幅（自然单位 $e = \hbar = 1$） |
| `omega` | 驱动频率 $\omega$，需远大于带宽 |
| `eta` | $\eta = \pm 1$，手性 |
| `n_max` | 包含的最大 Floquet 谐波阶数 $n_{\max}$，通常 $1$ 足够 |
| `direction` | 光的传播方向，默认 `[0, 0, 1]`（xy 平面偏振） |

### `model.hamiltonian(k_pts=None, flatten_spin_axis=False, **params)`

构造 Floquet 有效哈密顿量。支持：

- 单点 / 多点 k 输入
- 1D `np.linspace` 扫描
- 参数扫描（如 `t=[0.0, 1.0, 2.0]`）
- `spinful=True` 时的 `flatten_spin_axis`

### `model.solve_ham(...)`

与 `pythtb.TBModel.solve_ham` 签名相同，自动使用 Floquet 有效哈密顿量。

### `model.clear_drive()`

移除驱动，恢复静态哈密顿量。

## 手性约定

$\eta = +1$ 时，电场在偏振平面内按 $\mathbf{e}_1 \to \mathbf{e}_2 \to -\mathbf{e}_1 \to -\mathbf{e}_2$ 旋转；$\eta = -1$ 时反向。

默认 `direction=[0, 0, 1]` 对应 $\mathbf{e}_1 = \hat{x}, \mathbf{e}_2 = \hat{y}$，因此 $\eta = +1$ 为从 $+z$ 方向观察的逆时针旋转。

## 测试

```bash
python -m pytest test_flqtb.py -v
```

测试覆盖：静态 fallback、$J_0$ 重整化、傅里叶系数与 FFT 对比、厄米性、k 点扫描、参数扫描、自旋模型、3D 传播方向、`n_max=2`、`clear_drive` 等。

## 限制与注意事项

1. **仅支持圆偏振**：不处理线偏振或椭圆偏振。
2. **仅支持 pythtb 2.0.0+**：不兼容旧版 `tb_model` API。
3. **高频近似**：要求 $\omega$ 远大于系统带宽；否则 Magnus 展开失效。
4. **2D 模型**：传播方向必须沿 $z$ 轴，否则不是圆偏振。
5. **在位能驱动**：当前 `set_onsite` 设置的是静态在位能；若需光场调制在位能，需自行扩展。

## 文件说明

```
.
├── src/flqtb/          # 核心包
│   ├── __init__.py
│   └── flqtb.py
├── tests/              # pytest 测试集
│   └── test_flqtb.py
├── examples/           # 示例脚本
│   └── graphene_bands.py
├── pyproject.toml      # 打包配置
├── README.md
├── LICENSE
└── flqtb_formula.md    # 理论手册
```
