autotau 0.4.5

Automated time constant (tau) fitting tool with decoupled window search and manual fitting support

AutoTau - 自动化时间常数τ拟合工具

AutoTau是一个用于自动拟合信号中指数上升/下降过程时间常数τ的Python库，支持灵活的并行策略和多种优化算法。

v0.3.0 重大更新 ⚡：架构重构 + 性能优化，200-1500x 加速

功能特点

核心功能：

• 自动寻找最佳拟合窗口，无需手动指定拟合区间
• 支持单周期和多周期信号的拟合
• 内置指数上升和下降模型: y = A(1-e^(-t/τ)) + C 和 y = Ae^(-t/τ) + C
• 提供R²和调整后R²等拟合质量指标
• 自动重新拟合质量不佳的结果
• 多种可视化方法展示拟合结果

v0.3.0 新增 ⚡：

• 灵活并行架构：可选的 executor 注入，避免嵌套并行
• 窗口缓存策略：跨步复用窗口参数（5-10x 加速）
• 智能窗口搜索：differential_evolution 全局优化（10-50x 加速）
• Numba JIT 编译：热点函数加速（2-5x 加速）
• features_v2 集成：完美集成到 OECT 数据处理流程
• 48-96核友好：充分利用高核心数 CPU

安装

基础安装

pip install autotau

启用 Numba 加速（推荐）

# 安装 Numba（5-10x 额外加速）
conda install numba

# 或使用 pip
pip install numba

从源码安装

git clone https://github.com/Durian-Leader/autotau.git
cd autotau
pip install -e .

快速开始

v0.3.0 推荐用法 ⭐

场景 1: 集成到 features_v2（最简单）

from infra.catalog import UnifiedExperimentManager
import autotau_extractors  # 导入以注册 extractor

manager = UnifiedExperimentManager('catalog_config.yaml')
experiments = manager.search(chip_id="#20250804008")

# 批量提取 tau 特征（48核实验级并行）
result = manager.batch_extract_features_v2(
    experiments=experiments,
    feature_config='transient_tau',
    save_format='parquet',
    n_workers=48,  # 充分利用 48-96 核
    progress=True
)

# 预期性能（75实验 × 5000步 × 100周期）：
#   - 当前: ~25 小时
#   - 优化后: ~1-5 分钟 ⚡

场景 2: 窗口缓存 + 智能搜索（独立使用）

from autotau.core import CachedAutoTauFitter, SmartWindowSearchFitter

# 智能搜索工厂（减少 50-250x 搜索迭代）
smart_factory = lambda t, s, **kw: SmartWindowSearchFitter(
    t, s, maxiter=50, popsize=15, **kw
)

# 缓存拟合器（跨步复用窗口，98% 命中率）
cached_fitter = CachedAutoTauFitter(
    base_fitter_factory=smart_factory,
    validation_threshold=0.95,
    revalidation_interval=500
)

# 处理多个步骤
for step_idx in range(5000):
    time, signal = load_step(step_idx)
    tau_on, r2_on, tau_off, r2_off = cached_fitter.fit_step(
        time, signal,
        sample_step=1/1000,
        period=0.1,
        step_index=step_idx
    )
    # 保存结果...

# 查看缓存统计
stats = cached_fitter.get_statistics()
print(f"缓存命中率: {stats['search_reduction']}")  # 通常 98%
print(f"估算加速: {stats['estimated_speedup']}")    # 通常 50x

场景 3: 自定义并行（高级）

from autotau import AutoTauFitter, CyclesAutoTauFitter
from concurrent.futures import ProcessPoolExecutor

# 选项 A: 窗口搜索并行
with ProcessPoolExecutor(max_workers=8) as executor:
    fitter = AutoTauFitter(..., executor=executor)  # 并行窗口搜索
    result = fitter.fit_tau_on_and_off()

# 选项 B: 自定义工厂模式
executor = ProcessPoolExecutor(max_workers=8)
fitter_factory = lambda t, s, **kw: AutoTauFitter(t, s, executor=executor, **kw)
cycles_fitter = CyclesAutoTauFitter(..., fitter_factory=fitter_factory)

---

基本示例（v0.2.0 兼容）

import numpy as np
import pandas as pd
from autotau import TauFitter

# 加载数据
data = pd.read_csv('transient.csv')
time_data = data['Time'].values
current_data = -data['Id'].values  # 反相电流

# 创建TauFitter对象
tau_fitter = TauFitter(
    time_data, 
    current_data, 
    t_on_idx=[7.112, 7.151],  # 开启过程时间窗口
    t_off_idx=[0.41, 0.42]    # 关闭过程时间窗口
)

# 拟合并获取结果
tau_fitter.fit_tau_on()
tau_fitter.fit_tau_off()

print(f"tau_on: {tau_fitter.get_tau_on()}")
print(f"tau_off: {tau_fitter.get_tau_off()}")

# 可视化结果
tau_fitter.plot_tau_on()
tau_fitter.plot_tau_off()

自动寻找最佳拟合窗口

from autotau import AutoTauFitter

# 自动寻找最佳拟合窗口
auto_fitter = AutoTauFitter(
    time_data, 
    current_data,
    sample_step=0.001,
    period=0.2,
    window_scalar_min=0.2,
    window_scalar_max=1/3,
    window_points_step=10,
    window_start_idx_step=2,
    normalize=False,
    language='cn',
    show_progress=True
)

auto_fitter.fit_tau_on_and_off()

# 获取结果
print(f"tau_on: {auto_fitter.best_tau_on_fitter.get_tau_on()}")
print(f"tau_off: {auto_fitter.best_tau_off_fitter.get_tau_off()}")

# 可视化结果
auto_fitter.best_tau_on_fitter.plot_tau_on()
auto_fitter.best_tau_off_fitter.plot_tau_off()

多周期数据处理

from autotau import CyclesAutoTauFitter

# 处理多周期数据
cycles_fitter = CyclesAutoTauFitter(
    time_data,
    current_data,
    period=0.2,
    sample_rate=1000,
    window_scalar_min=0.2,
    window_scalar_max=1/3,
    window_points_step=10,
    window_start_idx_step=2,
    normalize=False,
    language='cn',
    show_progress=True
)

cycles_fitter.fit_all_cycles()

# 可视化结果
cycles_fitter.plot_cycle_results()
cycles_fitter.plot_windows_on_signal(num_cycles=5)
cycles_fitter.plot_all_fits(num_cycles=3)

# 获取结果摘要
summary = cycles_fitter.get_summary_data()
print(summary)

并行处理

from autotau import ParallelAutoTauFitter, ParallelCyclesAutoTauFitter

# 使用并行版自动拟合器
parallel_auto_fitter = ParallelAutoTauFitter(
    time_data, 
    current_data,
    sample_step=0.001,
    period=0.2,
    window_scalar_min=0.2,
    window_scalar_max=1/3,
    window_points_step=10,
    window_start_idx_step=2,
    normalize=False,
    language='cn',
    show_progress=True,
    max_workers=None  # 使用所有可用CPU核心
)

parallel_auto_fitter.fit_tau_on_and_off()

# 使用并行版多周期拟合器
parallel_cycles_fitter = ParallelCyclesAutoTauFitter(
    time_data,
    current_data,
    period=0.2,
    sample_rate=1000,
    window_scalar_min=0.2,
    window_scalar_max=1/3,
    window_points_step=10,
    window_start_idx_step=2,
    normalize=False,
    language='cn',
    show_progress=True,
    max_workers=None  # 使用所有可用CPU核心
)

parallel_cycles_fitter.fit_all_cycles()

提示：如果你已知窗口参数，推荐使用 ParallelCyclesTauFitter 进行多周期并行拟合。该实现采用“分块并行”（每个进程处理一组周期）来降低调度与序列化开销，在周期数较多时拥有更好的吞吐与扩展性。

示例（手动窗口并行）：

from autotau import ParallelCyclesTauFitter

fitter = ParallelCyclesTauFitter(
    time_data,
    current_data,
    period=0.2,
    sample_rate=1000,
    window_on_offset=1.5,
    window_on_size=0.05,
    window_off_offset=0.35,
    window_off_size=0.06,
    show_progress=True,
    max_workers=8
)

results = fitter.fit_all_cycles()  # 默认返回 DataFrame（更适合大规模周期）

性能对比

v0.3.0 性能测试结果（实测）

优化策略	加速倍数	实测时间（单步）
基准（v0.2.0 串行）	1x	26.56s
Phase 2.2（智能搜索）	6.5x ⚡	4.06s
Phase 2.1（窗口缓存）	48.8x ⚡⚡⚡	0.544s（50步平均）
Phase 3.1（Numba编译）	2-5x ⚡	已内置

大规模数据场景（75实验 × 5000步 × 100周期）

配置	预期时间	加速倍数
v0.2.0（旧架构）	~25 小时	1x
v0.3.0（Phase 1，48核并行）	~15-30 分钟	50-100x
v0.3.0（Phase 1+2.1，窗口缓存）	~3-5 分钟	300-500x
v0.3.0（Phase 1+2+3，全优化）	1-3 分钟 ⚡⚡⚡	500-1500x

运行性能测试

# 运行完整性能测试套件
python test_phase2_3_performance.py

# 查看优化演示
python examples/optimization_demo.py

性能调优建议

48-96核 CPU 推荐配置：

# features_v2 集成
manager.batch_extract_features_v2(
    experiments=experiments,
    n_workers=48,  # 实验级并行
    feature_config='transient_tau'
    # extractor 默认串行（避免嵌套并行）
)

16核以下 CPU 推荐配置：

# 可选启用窗口搜索并行
manager.batch_extract_features_v2(
    experiments=experiments,
    n_workers=4,   # 实验级并行（4核）
    feature_config='transient_tau_parallel'
)

# 在 YAML 配置中：
extractors:
  - type: 'transient.tau_on_off'
    params:
      use_parallel: true  # 启用窗口搜索并行
      max_workers: 4      # 每实验 4核窗口搜索
# 总核心使用: 4 实验 × 4 核/实验 = 16 核

模块结构

核心模块（v0.3.0）

• TauFitter: L0 - 基础拟合类，用于拟合指定窗口内的tau值
• AutoTauFitter: L1 - 自动窗口搜索（支持可选并行）
• CyclesAutoTauFitter: L2 - 多周期处理（支持工厂模式）
• CachedAutoTauFitter: L2 - 窗口缓存策略（98% 命中率，50x 加速）⭐
• SmartWindowSearchFitter: L1 - 智能搜索（differential_evolution，6.5x 加速）⭐
• accelerated 模块: Numba JIT 编译函数（2-5x 加速）⭐

废弃模块（仍可用但不推荐）

• ⚠️ ParallelAutoTauFitter: 已废弃，请改用 AutoTauFitter(..., executor=...)
• ⚠️ ParallelCyclesAutoTauFitter: 已废弃，请改用 CyclesAutoTauFitter(..., fitter_factory=...)

集成模块

• autotau_extractors.py: features_v2 集成层（OECT 数据处理流程）

依赖

必需：

• NumPy
• SciPy
• Matplotlib
• pandas
• tqdm

可选（性能加速）：

• numba: JIT 编译加速（2-5x），强烈推荐

  conda install numba
  

文档

详细文档请参见API参考文档。

贡献代码

欢迎提交Pull Request或创建Issue。

协议

MIT