QuantiaMagica

核心特性

Python 新手入门

第一步：安装 Python

1. 下载Python
   访问 python.org，下载最新版本（推荐3.10以上）
2. 安装时勾选 "Add Python to PATH"
   这一步非常重要！勾选后才能在命令行使用Python
3. 验证安装
   打开命令行（Windows: Win+R 输入 cmd），输入：

   python --version

   看到版本号就说明安装成功了

第二步：安装 QuantiaMagica

# 在命令行中执行以下命令

# 方法1：进入项目目录安装（推荐）
cd QuantiaMagica
pip install -e .

# 方法2：只安装依赖
pip install numpy matplotlib

第三步：创建你的第一个脚本

用任意文本编辑器（记事本、VS Code、PyCharm都可以）创建文件 my_first_adc.py：

# my_first_adc.py - 我的第一个ADC仿真

from quantiamagica import SARADC

# 创建一个10位SAR ADC
adc = SARADC(bits=10, vref=1.0)

# 运行仿真
adc.sim()

# 显示结果
print(f"ENOB: {adc.enob():.2f} bits")

# 画图
adc.plot()

第四步：运行脚本

# 在命令行中
python my_first_adc.py

Python基础语法速查（本API所需）

以下是使用QuantiaMagica所需的所有Python语法，10分钟即可掌握：

1. 变量和数据类型

# 变量赋值：直接写名字 = 值
bits = 12           # 整数 int
vref = 1.0          # 小数 float
name = "SAR-ADC"    # 字符串 str
enabled = True      # 布尔值 True/False

# 科学计数法（ADC仿真常用）
fs = 1e6            # 1×10⁶ = 1000000 (1MHz)
noise = 0.5e-3      # 0.5×10⁻³ = 0.0005 (0.5mV)
fin = 10e3          # 10×10³ = 10000 (10kHz)

# 运算符
a = 10 + 3     # 加法 = 13
b = 10 - 3     # 减法 = 7
c = 10 * 3     # 乘法 = 30
d = 10 / 3     # 除法 = 3.333...
e = 10 // 3    # 整除 = 3
f = 10 % 3     # 取余 = 1
g = 2 ** 10    # 幂运算 = 1024

2. 列表和字典

# 列表 list：用方括号，可索引
coeffs = [0.5, 0.3, 0.2]    # 创建列表
first = coeffs[0]           # 索引从0开始，= 0.5
coeffs.append(0.1)          # 追加元素
length = len(coeffs)        # 长度 = 4

# 字典 dict：键值对，用花括号
params = {'c1': 0.5, 'c2': 0.3, 'amplitude': 0.4}
c1 = params['c1']           # 取值 = 0.5
params['c3'] = 0.2          # 添加新键值

3. 导入模块

# 从模块导入类/函数
from quantiamagica import SARADC              # 导入一个
from quantiamagica import SARADC, Signal     # 导入多个
from quantiamagica import *                   # 导入所有（不推荐）

# 导入整个模块（需要前缀访问）
import numpy as np                            # np是别名
noise = np.random.normal(0, 0.001)           # 使用np.xxx访问

# 常用导入（本API需要）
import numpy as np
from quantiamagica import SARADC, PipelineADC, SigmaDeltaADC
from quantiamagica import SamplingEvent, ComparatorEvent, QuantizerEvent
from quantiamagica.optim import GeneticOptimizer, Gene

4. 创建对象和调用方法

# 创建对象：类名(参数)
adc = SARADC(bits=12, vref=1.0)   # 命名参数
adc = SARADC(12, 1.0)              # 位置参数
adc = SARADC(12)                   # 只传必要参数

# 调用方法：对象.方法名()
adc.sim()                         # 无参数
adc.sim(fin=10e3)                 # 有参数
adc.sim(n_samples=4096, fs=1e6)  # 多个参数

# 获取返回值
result = adc.sim()                # 保存返回对象
enob = adc.enob()                 # 保存返回数字

# 链式调用
adc.sim().report()                # 仿真完直接报告

# 访问属性
bits = adc.bits                   # 读取属性（无括号）

5. 函数定义

# 基本函数
def add(a, b):
    return a + b

result = add(3, 5)  # 调用函数，result = 8

# 带默认参数
def greet(name="World"):
    print(f"Hello, {name}!")

greet()           # Hello, World!
greet("ADC")      # Hello, ADC!

# 适应度函数示例（遗传算法用）
def fitness(params):
    # params是字典，如 {'c1': 0.5, 'c2': 0.3}
    c1 = params['c1']
    c2 = params['c2']
    # ... 计算ENOB ...
    return enob  # 返回适应度值

6. 装饰器（事件系统核心）

# 装饰器：@xxx 放在函数定义上面
# 这是QuantiaMagica事件系统的核心！

from quantiamagica import SARADC, SamplingEvent

adc = SARADC(12)

@adc.on(SamplingEvent)           # ← 装饰器：监听采样事件
def add_noise(event):           # ← 事件处理函数，参数是event
    event.voltage += 0.001       # ← 修改event的属性

# 装饰器的作用：当ADC采样时，自动调用add_noise函数
# 你不需要手动调用add_noise()，只需要运行adc.sim()

adc.sim()  # add_noise会在每次采样时被自动调用

7. 条件判断和循环

# if-elif-else
if enob > 10:
    print("优秀")
elif enob > 8:
    print("良好")
else:
    print("需改进")

# for循环
for i in range(5):        # i = 0, 1, 2, 3, 4
    print(i)

for c in [0.1, 0.2, 0.3]:  # 遍历列表
    print(c)

# 列表推导式（创建列表的简洁写法）
squares = [x**2 for x in range(5)]  # [0, 1, 4, 9, 16]
c_list = [params[f'c{i+1}'] for i in range(5)]  # 提取c1-c5

8. 打印输出（f-string格式化）

# print() 打印到控制台
print("Hello")                      # 普通字符串
print(bits)                         # 打印变量
print("bits =", bits)               # 多个值用逗号

# f-string格式化（推荐）
print(f"ENOB: {enob}")              # {}内放变量
print(f"ENOB: {enob:.2f} bits")    # :.2f 保留2位小数
print(f"SNR: {snr:.1f} dB")         # :.1f 保留1位小数
print(f"fs: {fs:.2e} Hz")           # :.2e 科学计数法
print(f"提升: {improvement:+.2f}")  # :+ 显示正负号

9. NumPy基础（信号处理必备）

import numpy as np

# 创建数组
arr = np.array([1, 2, 3])          # 从列表创建
zeros = np.zeros(10)               # 10个0
ones = np.ones(10)                 # 10个1
t = np.arange(1024)                # [0, 1, 2, ..., 1023]
t = np.arange(0, 1, 0.001)        # 0到1，步长0.001
t = np.linspace(0, 1, 1000)       # 0到1，共1000个点

# 时间轴生成（ADC仿真常用）
n_samples = 4096
fs = 1e6
t = np.arange(n_samples) / fs      # 时间轴（秒）

# 生成正弦波
fin = 10e3                         # 信号频率10kHz
amplitude = 0.4                    # 振幅
offset = 0.5                       # 直流偏置
signal = offset + amplitude * np.sin(2 * np.pi * fin * t)

# 生成随机噪声
noise = np.random.normal(0, 0.001)         # 单个随机数
noise = np.random.normal(0, 0.001, 1024)  # 1024个随机数

# 数学函数
y = np.sin(x)                      # 正弦
y = np.cos(x)                      # 余弦
y = np.abs(x)                      # 绝对值
y = np.sqrt(x)                     # 平方根
y = np.log10(x)                    # log10
y = np.clip(x, 0, 1)               # 裁剪到[0,1]

# 统计函数
m = np.mean(arr)                   # 平均值
s = np.std(arr)                    # 标准差
mx = np.max(arr)                   # 最大值
mn = np.min(arr)                   # 最小值

10. try-except异常处理

# 捕获错误，防止程序崩溃
try:
    enob = evaluate_sd_adc(params)
    if enob <= 0 or np.isnan(enob):
        return -1000  # 返回惩罚值
    return enob
except:
    return -1000  # 出错也返回惩罚值

11. 常见错误解决

完整模板：复制即用

"""
QuantiaMagica ADC仿真模板
========================
复制此文件，修改参数即可运行

使用前请先安装：
    cd QuantiaMagica
    pip install -e .
"""

# ==================== 导入 ====================
import numpy as np
from quantiamagica import SARADC, SamplingEvent, ComparatorEvent

# ==================== 参数设置 ====================
BITS = 12              # ADC位数
VREF = 1.0             # 参考电压 (V)
FS = 1e6               # 采样率 (Hz)
FIN = 10e3             # 信号频率 (Hz)
N_SAMPLES = 4096       # 采样点数
AMPLITUDE = 0.48       # 信号幅度 (V)
OFFSET = 0.5           # 直流偏置 (V)

# 非理想效应参数
THERMAL_NOISE = 0.5e-3     # 热噪声 (V RMS)
COMPARATOR_OFFSET = 1e-3   # 比较器失调 (V)

# ==================== 创建ADC ====================
adc = SARADC(bits=BITS, vref=VREF)

# ==================== 添加非理想效应（可选） ====================
@adc.on(SamplingEvent)
def add_thermal_noise(event):
    """采样时添加热噪声"""
    event.voltage += np.random.normal(0, THERMAL_NOISE)

@adc.on(ComparatorEvent)
def add_comparator_offset(event):
    """比较器失调"""
    event.offset = COMPARATOR_OFFSET

# ==================== 运行仿真 ====================
print("运行仿真...")
result = adc.sim(
    n_samples=N_SAMPLES,
    fs=FS,
    fin=FIN,
    amplitude=AMPLITUDE,
    offset=OFFSET
)

# ==================== 查看结果 ====================
print(f"\n===== 仿真结果 =====")
print(f"ENOB: {adc.enob():.2f} bits")
print(f"SNR:  {adc.snr():.1f} dB")
print(f"SFDR: {adc.sfdr():.1f} dB")
print(f"THD:  {adc.thd():.1f} dB")

# ==================== 可视化 ====================
# 完整报告（推荐）
adc.report()

# 或者单独查看
# adc.plot()           # 时域图
# adc.spectrum()       # 频谱图
# adc.report('static') # INL/DNL

# ==================== 保存数据（可选） ====================
# result.save("output.npz")           # NumPy格式
# result.save("output.csv", format="csv")  # CSV格式

快速开始

最简代码（3行）

from quantiamagica import SARADC

adc = SARADC(bits=12, vref=1.0)  # 创建12位ADC
adc.sim(fin=10e3)                   # 仿真10kHz正弦波
adc.plot()                           # 画图

添加非理想效应（事件监听） - 核心功能

# =============================================================
# 事件驱动是QuantiaMagica的核心！
# 通过监听ADC转换过程中的各个事件，可以轻松添加非理想效应
# =============================================================

from quantiamagica import SARADC, SamplingEvent, ComparatorEvent
import numpy as np

# 第1步：创建ADC实例
adc = SARADC(bits=12, vref=1.0)

# 第2步：用 @adc.on() 装饰器监听事件
# 当ADC采样时，这个函数会被自动调用
@adc.on(SamplingEvent)
def add_thermal_noise(event):
    # event.voltage 是当前采样的电压值
    # 我们给它加上高斯噪声来模拟热噪声
    noise = np.random.normal(0, 0.0005)  # 0.5mV RMS噪声
    event.voltage += noise

# 第3步：监听比较器事件，添加比较器失调
@adc.on(ComparatorEvent)
def add_comparator_offset(event):
    # event.offset 是比较器失调电压
    event.offset = 0.001  # 1mV失调
    # event.noise_sigma 是比较器噪声
    event.noise_sigma = 0.0002  # 0.2mV噪声

# 第4步：运行仿真
adc.sim(n_samples=4096, fs=1e6, fin=10e3)

# 第5步：查看结果
print(f"带非理想效应的ENOB: {adc.enob():.2f} bits")
print(f"SNR: {adc.snr():.1f} dB")

# 画图看效果
adc.spectrum()

获取所有指标

from quantiamagica import SARADC
from quantiamagica.analysis import Analyzer

adc = SARADC(bits=12)
result = adc.sim()

analyzer = Analyzer(result)
print(analyzer.summary())  # 打印所有指标

使用Signal类生成各种信号

from quantiamagica import SARADC, Signal

adc = SARADC(bits=12)

# 正弦波
sig = Signal.sine(n=1024, freq=10e3)

# 方波
sig = Signal.square(n=1024, freq=1e3)

# 三角波
sig = Signal.triangle(n=1024, freq=1e3)

# 扫频信号
sig = Signal.chirp(n=2048, f_start=1e3, f_end=100e3)

# 双音信号（IMD测试）
sig = Signal.two_tone(f1=10e3, f2=11e3)

# 从文件导入
sig = Signal.from_file("my_data.csv")

# 用于仿真
adc.sim(sig)

API 参考

ADC 类型

SARADC - 逐次逼近型ADC

导入: from quantiamagica import SARADC

专用方法:

Pipeline - ADC级联链类 (独立于ADConverter)

导入: from quantiamagica import Pipeline

架构说明：Pipeline是独立的类（不继承ADConverter），用于将多个ADC（SAR/Sigma-Delta）串联成高精度流水线结构。

输入V → [Stage1 ADC] → 残差×gain → [Stage2 ADC] → 残差×gain → [Stage3 ADC] → 合并输出码

属性:

方法:

使用示例:

# 3×8-bit SAR → 24-bit Pipeline
stages = [SARADC(bits=8) for _ in range(3)]
pipeline = Pipeline(stages, gains=[256, 256])

# 也支持Sigma-Delta ADC
sd_stages = [SigmaDeltaADC(order=1, bits=1, osr=16) for _ in range(2)]
sd_pipeline = Pipeline(sd_stages, gains=[16])

ADConverter 基类方法 (所有ADC通用)

以下方法适用于 SARADC（Pipeline类有独立实现）

仿真方法

性能指标方法

可视化方法

report() 方法详解 (推荐使用)

简洁灵活的分析报告API:

# 方式1: 链式调用 (仿真+报告一行完成)
adc.sim().report()                    # 完整报告

# 方式2: 分开调用 (仿真一次，多种报告)
adc.sim()                             # 先仿真
adc.report()                          # 完整报告
adc.report('spectrum')               # 只看频谱图
adc.report('metrics')                # 只打印数字
adc.report(save='fig.pdf')           # 保存PDF

报告类型详解 (what参数)

其他参数

辅助函数 (从quantiamagica导入)

辅助函数代码示例

# ========== 示例1: 一键绘制频谱 ==========
from quantiamagica import SARADC, plot_spectrum

adc = SARADC(bits=12)
result = adc.sim(n_samples=4096)

# 一行代码画频谱！自动计算SNR/ENOB并标注
plot_spectrum(result.output_codes, fs=1e6, title="我的ADC频谱")

# ========== 示例2: 对比两个ADC ==========
from quantiamagica import SARADC, plot_comparison

# 创建两个ADC
adc1 = SARADC(bits=8)
adc2 = SARADC(bits=12)

# 分别仿真
r1 = adc1.sim(n_samples=4096)
r2 = adc2.sim(n_samples=4096)

# 一行代码对比两个频谱！
plot_comparison(
    [r1.output_codes, r2.output_codes],  # 数据列表
    fs=1e6,                              # 采样率
    labels=['8-bit', '12-bit'],         # 标签
    save='comparison.png'               # 保存图片
)

# ========== 示例3: 计算带内SNR (Sigma-Delta/过采样) ==========
from quantiamagica import compute_inband_snr

# 假设你有过采样的ADC输出码
codes = ...  # 你的数据
snr, enob = compute_inband_snr(
    codes,
    bits=4,           # 量化器位数
    fs=1e6,           # 采样率 1MHz
    signal_freq=1e3,  # 信号频率 1kHz
    bandwidth=10e3    # 只计算10kHz带宽内的噪声
)
print(f"带内SNR: {snr:.1f}dB, ENOB: {enob:.2f}bits")

事件系统方法

SAR ADC 事件

导入: from quantiamagica import SamplingEvent, ComparatorEvent, ...

ConversionStartEvent

转换开始时触发

SamplingEvent (可取消)

采样阶段触发，用于添加采样噪声、失调等

CapacitorSwitchEvent (可取消)

电容切换时触发，用于模拟电容失配

ComparatorEvent (可取消)

比较器判决时触发

BitDecisionEvent (可取消)

每位决定后触发

OutputCodeEvent

输出码就绪时触发

ConversionEndEvent

转换结束时触发

Pipeline ADC 事件

导入: from quantiamagica import Pipeline, SARADC, StageEvent, ResidueEvent, InterstageGainEvent

StageEvent

进入新的流水线级时触发

ResidueEvent (可取消)

计算残差电压时触发

InterstageGainEvent (可取消)

级间放大时触发，用于模拟运放非理想特性

Sigma-Delta ADC

导入: from quantiamagica import SigmaDeltaADC, QuantizerEvent

SigmaDeltaADC 类

简洁灵活的Sigma-Delta调制器，内置1阶/2阶CIFB实现，通过QuantizerEvent实现任意拓扑

QuantizerEvent (可取消) - 唯一事件

每个时钟周期触发，提供完整信息实现任意拓扑

使用示例

from quantiamagica import SigmaDeltaADC, QuantizerEvent
import numpy as np

# 1阶1-bit SD，OSR=64
sd = SigmaDeltaADC(order=1, bits=1, osr=64)

# 通过QuantizerEvent添加非理想效应
@sd.on(QuantizerEvent)
def add_nonidealities(event):
    # 积分器泄漏：修改量化器输入
    event.quantizer_input *= 0.999
    # 比较器噪声
    event.noise_sigma = 0.01

# 生成输入信号（amplitude由用户控制，推荐0.3-0.45）
t = np.arange(8192) / 1e6
signal = 0.5 + 0.4 * np.sin(2 * np.pi * 1e3 * t)

# 仿真
sd.sim(signal, fs=1e6)
print(f"ENOB: {sd.enob():.2f}")

# 自定义拓扑示例：完全自定义2阶调制器
my_u1, my_u2 = 0.0, 0.0

@sd.on(QuantizerEvent)
def custom_2nd_order(event):
    global my_u1, my_u2
    x, y_prev = event.input_signal, event.prev_output
    my_u1 = my_u1 + x - y_prev
    my_u2 = my_u2 + my_u1 - 2*y_prev
    event.quantizer_input = my_u2  # 覆盖默认

事件优先级 (EventPriority)

导入: from quantiamagica import EventPriority

Signal 信号类

导入: from quantiamagica import Signal 或 from quantiamagica.signals import Signal

基本信号

测试信号

多频信号

调制信号

噪声信号

导入/导出

信号处理方法

信号属性

遗传算法优化库 (quantiamagica.optim)

高度抽象的遗传算法优化库，支持CUDA/CPU并行计算，可用于优化任意ADC参数。自动斜率收敛，无需手动设置迭代次数。

Gene - 基因定义

导入: from quantiamagica.optim import Gene

GeneticOptimizer - 遗传算法优化器

导入: from quantiamagica.optim import GeneticOptimizer

run() 方法参数:

OptimizationResult - 优化结果

SDCoeffOptimizer - SD ADC系数优化器

导入: from quantiamagica.optim import SDCoeffOptimizer

注意: SAR/Pipeline ADC使用通用GeneticOptimizer进行高度自定义优化。

完整示例

示例1：NS-SAR（噪声整形SAR）配合过采样

from quantiamagica import SARADC, SamplingEvent, OutputCodeEvent, EventPriority
import numpy as np

# 参数设置
BITS = 8
FS = 1e6          # 采样率 1MHz
OSR = 64          # 过采样率
SIGNAL_BW = FS / (2 * OSR)  # 信号带宽 ≈ 7.8kHz

# 创建NS-SAR插件类
class NoiseShapingSAR:
    def __init__(self, feedback_coeff=1.0):
        self.feedback_coeff = feedback_coeff
        self.prev_residue = 0.0
        self.sampled_voltage = 0.0
    
    def attach(self, adc):
        @adc.on(SamplingEvent, priority=EventPriority.HIGH)
        def apply_feedback(event):
            # 加入上次的量化残差
            event.voltage += self.feedback_coeff * self.prev_residue
            self.sampled_voltage = event.voltage
        
        @adc.on(OutputCodeEvent, priority=EventPriority.HIGH)
        def capture_residue(event):
            # 残差 = 采样电压 - DAC输出
            reconstructed = adc.code_to_voltage(event.code)
            self.prev_residue = self.sampled_voltage - reconstructed

# 使用
adc = SARADC(bits=BITS, vref=1.0)
ns_plugin = NoiseShapingSAR(feedback_coeff=1.0)
ns_plugin.attach(adc)

adc.sim(n_samples=16384, fs=FS, fin=1e3)
print(f"NS-SAR 带内ENOB大幅提升!")
# 运行 examples/03_ns_sar.py 查看完整对比

示例2：Pipeline ADC带级间增益误差

from quantiamagica import Pipeline, SARADC, InterstageGainEvent

# 创建3个8-bit SAR ADC串联成24-bit Pipeline
stages = [SARADC(bits=8) for _ in range(3)]
pipeline = Pipeline(stages=stages, interstage_gains=[256, 256])

@pipeline.on(InterstageGainEvent)
def gain_error(event):
    # 模拟1000倍运放有限增益带来的误差
    opamp_gain = 1000
    event.actual_gain = event.ideal_gain * (1 - 1/opamp_gain)
    event.offset = 0.5e-3  # 0.5mV失调

pipeline.sim(n_samples=65536)
pipeline.spectrum()
print(f"ENOB: {pipeline.enob():.2f}")  # 理想~23.99, 带误差~17.9

示例3：统一报告API（推荐）

from quantiamagica import SARADC

adc = SARADC(bits=12)

# 仿真一次
adc.sim()

# 然后可以多次调用report()查看不同报告 (不会重复仿真)
adc.report()                          # 完整报告
adc.report('spectrum')               # 仅频谱
adc.report('metrics')                # 仅打印指标
adc.report(save='fig.pdf')           # 保存PDF

# 可选参数：
# what: 'all'|'spectrum'|'time'|'static'|'metrics'
# columns: 1(单栏3.5") 或 2(双栏7.16")

示例4：自动优化测试参数 (sim_auto)

pip install torch --index-url https://download.pytorch.org/whl/cu121

$env:PYTHONPATH = "D:\Python\Lib\site-packages"  # PowerShell
set PYTHONPATH=D:\Python\Lib\site-packages           # CMD

from quantiamagica import SARADC

adc = SARADC(bits=12)

# 一行代码 - 自动优化！
result = adc.sim_auto(fs=1e6)  # 只需指定fs

# 返回值包含最优参数
print(f"最佳fin: {result['best_fin']:.2f} Hz")
print(f"最佳幅度: {result['best_amplitude']:.4f} V")
print(f"最佳ENOB: {result['best_enob']:.4f} bits")
print(f"收敛代数: {result['generations']}")
print(f"收敛原因: {result['reason']}")

# 结果已保存，可直接画图
adc.report()

# 适用于所有ADC类型
from quantiamagica import PipelineADC, SigmaDeltaADC
PipelineADC(12).sim_auto(fs=1e6)
SigmaDeltaADC(order=2, bits=1, osr=64).sim_auto(fs=1e6)

示例5：Sigma-Delta ADC（自定义复杂拓扑）

# =============================================================
# Sigma-Delta ADC: 通过QuantizerEvent实现任意复杂拓扑
# 演示：自定义2阶CIFB差分方程
# =============================================================

from quantiamagica import SigmaDeltaADC, QuantizerEvent
import numpy as np

# 参数
OSR, FS, N = 64, 1e6, 64 * 2048
FIN = 13 * FS / N
t = np.arange(N) / FS
signal = 0.5 + 0.4 * np.sin(2 * np.pi * FIN * t)  # 80%幅度

# =============== 自定义2阶CIFB拓扑 ===============
# 差分方程:
#   u1[n] = u1[n-1] + x[n] - y[n-1]
#   u2[n] = u2[n-1] + u1[n] - 2*y[n-1]
#   v[n] = u2[n]  (量化器输入)
# NTF = (1-z^-1)^2

state = [0.0, 0.0]  # [u1, u2] 积分器状态

sd = SigmaDeltaADC(order=1, bits=1, osr=OSR)

@sd.on(QuantizerEvent)
def custom_2nd_order_cifb(event):
    x = event.input_signal   # 当前输入
    y = event.prev_output    # 前一输出 (反馈)
    
    # 实现2阶CIFB差分方程
    state[0] = state[0] + x - y           # 第一级积分器
    state[1] = state[1] + state[0] - 2*y  # 第二级积分器
    
    # 覆盖量化器输入 (关键!)
    event.quantizer_input = state[1]

sd.sim(signal, fs=FS)
sd._result.metadata['fin'] = FIN
print(f"自定义2阶ENOB: {sd.enob():.2f} bits")  # ~11.67 bits

# =============== 1-bit 3阶Sigma-Delta ===============
# 1-bit 3阶需要: 缩放积分器(c=0.3) + 小输入幅度
u3 = [0.0, 0.0, 0.0]
c = 0.3  # 积分器缩放系数

sd3 = SigmaDeltaADC(order=1, bits=1, osr=OSR)

@sd3.on(QuantizerEvent)
def third_order_1bit(event):
    x, y = event.input_signal, event.prev_output
    u3[0] = u3[0] + c * (x - y)
    u3[1] = u3[1] + c * (u3[0] - 2*y)
    u3[2] = u3[2] + c * (u3[1] - y)
    event.quantizer_input = u3[2]

signal_3rd = 0.5 + 0.2 * np.sin(2 * np.pi * FIN * t)
sd3.sim(signal_3rd, fs=FS)
sd3._result.metadata['fin'] = FIN
print(f"3阶1-bit ENOB: {sd3.enob():.2f} bits")  # ~12.7 bits

示例4：遗传算法优化Sigma-Delta系数

import numpy as np
from quantiamagica import SigmaDeltaADC, QuantizerEvent
from quantiamagica.optim import GeneticOptimizer, Gene

# ===================== Step 1: 定义仿真参数 =====================
OSR = 64                        # 过采样率
FS = 1e6                        # 采样频率 1MHz
N_SAMPLES = OSR * 128           # 采样点数
FIN = 13 * FS / N_SAMPLES       # 相干采样频率

# ===================== Step 2: 定义要优化的基因 =====================
# 每个Gene定义一个参数的搜索范围
genes = [
    Gene('c1', 0.1, 0.8, 'float'),       # 第1级积分器增益
    Gene('c2', 0.1, 0.8, 'float'),       # 第2级积分器增益
    Gene('a1', 0.5, 2.5, 'float'),       # 第1级反馈系数
    Gene('a2', 0.5, 3.5, 'float'),       # 第2级反馈系数
    Gene('amplitude', 0.15, 0.4, 'float'),  # 输入正弦波幅度
]

# ===================== Step 3: 定义评估函数 =====================
# 这个函数接收一组参数，返回ENOB
def evaluate_sd_adc(params):
    """创建2阶CIFB Sigma-Delta并评估ENOB"""
    c1, c2 = params['c1'], params['c2']
    a1, a2 = params['a1'], params['a2']
    amplitude = params['amplitude']
    
    # 创建基础1阶SD ADC（我们通过事件扩展为2阶）
    sd = SigmaDeltaADC(order=1, bits=1, osr=OSR)
    state = [0.0, 0.0]  # 两个积分器的状态
    
    # 定义2阶CIFB拓扑
    @sd.on(QuantizerEvent)
    def second_order_cifb(event):
        x = event.input_signal      # 输入信号
        y = event.prev_output       # 量化器输出反馈 (+1/-1)
        # CIFB结构: 两级积分器 + 反馈
        state[0] = state[0] + c1 * (x - a1 * y)  # 第1级
        state[1] = state[1] + c2 * (state[0] - a2 * y)  # 第2级
        event.quantizer_input = state[1]  # 输出到量化器
    
    # 生成输入信号
    t = np.arange(N_SAMPLES) / FS
    signal = 0.5 + amplitude * np.sin(2 * np.pi * FIN * t)
    
    # 仿真并计算ENOB
    sd.sim(signal, fs=FS)
    sd._result.metadata['fin'] = FIN
    return sd.enob()

# ===================== Step 4: 定义适应度函数 =====================
# 遗传算法最大化此函数
def fitness(params):
    try:
        enob = evaluate_sd_adc(params)
        if enob <= 0 or np.isnan(enob) or enob > 30:
            return -1000  # 振荡或异常，给予惩罚
        # 目标：最大化ENOB，同时奖励较大的输入幅度
        return enob * 10 + params['amplitude'] * 5
    except:
        return -1000

# ===================== Step 5: 运行优化 =====================
optimizer = GeneticOptimizer(genes, fitness, maximize=True)
result = optimizer.run(population_size=40)  # 自动收敛，无需设置代数

# ===================== Step 6: 获取优化后的系数 =====================
print("优化后的系数:")
print(f"  c1 = {result.best_params['c1']:.4f}")  # 积分器1增益
print(f"  c2 = {result.best_params['c2']:.4f}")  # 积分器2增益
print(f"  a1 = {result.best_params['a1']:.4f}")  # 反馈系数1
print(f"  a2 = {result.best_params['a2']:.4f}")  # 反馈系数2
print(f"  amplitude = {result.best_params['amplitude']:.4f}")

# 验证优化结果
optimized_enob = evaluate_sd_adc(result.best_params)
print(f"\n优化后ENOB: {optimized_enob:.2f} bits")

# ===================== 对比：默认系数 vs 优化系数 =====================
default_params = {'c1': 0.5, 'c2': 0.5, 'a1': 1.0, 'a2': 2.0, 'amplitude': 0.3}
default_enob = evaluate_sd_adc(default_params)
print(f"默认系数ENOB: {default_enob:.2f} bits")
print(f"提升: +{optimized_enob - default_enob:.2f} bits")

快捷方式：SDCoeffOptimizer

如果只需优化标准SD ADC系数，可以使用封装好的优化器：

from quantiamagica.optim import SDCoeffOptimizer

# 一行创建 + 一行优化
sd_opt = SDCoeffOptimizer(order=2, bits=1, osr=64, fs=1e6)
result = sd_opt.optimize()

# 打印优化报告
print(result.summary())

# 获取优化后的系数
print(result.best_params)       # 所有参数
print(result.best_params['c1']) # 单个参数
print(result.best_enob)         # 优化后的ENOB
print(result.baseline_enob)     # 优化前的ENOB
print(result.improvement)       # 提升了多少bits

示例5：五阶Sigma-Delta极致优化

from quantiamagica import SigmaDeltaADC, QuantizerEvent
from quantiamagica.optim import GeneticOptimizer, Gene
import numpy as np

OSR, FS = 64, 1e6
N_SAMPLES = OSR * 256
FIN = 13 * FS / N_SAMPLES

# 定义5阶SD ADC的11个基因
genes = [
    # 积分器增益 (越往后越小以保持稳定)
    Gene('c1', 0.1, 0.5, 'float'),
    Gene('c2', 0.08, 0.4, 'float'),
    Gene('c3', 0.05, 0.3, 'float'),
    Gene('c4', 0.03, 0.2, 'float'),
    Gene('c5', 0.02, 0.15, 'float'),
    # 反馈系数
    Gene('a1', 0.8, 3.0, 'float'),
    Gene('a2', 0.5, 2.5, 'float'),
    Gene('a3', 0.3, 2.0, 'float'),
    Gene('a4', 0.2, 1.5, 'float'),
    Gene('a5', 0.1, 1.0, 'float'),
    Gene('amplitude', 0.08, 0.25, 'float'),
]

def evaluate_5th_order(params):
    c = [params[f'c{i+1}'] for i in range(5)]
    a = [params[f'a{i+1}'] for i in range(5)]
    
    sd = SigmaDeltaADC(order=1, bits=1, osr=OSR)
    state = [0.0] * 5
    
    @sd.on(QuantizerEvent)
    def fifth_order(event):
        x, y = event.input_signal, event.prev_output
        state[0] = state[0] + c[0] * (x - a[0] * y)
        for i in range(1, 5):
            state[i] = state[i] + c[i] * (state[i-1] - a[i] * y)
        event.quantizer_input = state[4]
    
    t = np.arange(N_SAMPLES) / FS
    signal = 0.5 + params['amplitude'] * np.sin(2*np.pi*FIN*t)
    sd.sim(signal, fs=FS)
    sd._result.metadata['fin'] = FIN
    return sd.enob()

def fitness(params):
    enob = evaluate_5th_order(params)
    return enob if enob > 0 else -1000

optimizer = GeneticOptimizer(genes, fitness, maximize=True)
result = optimizer.run(population_size=80)

print(f"优化后ENOB: {result.best_fitness:.2f} bits")
print(f"系数: {result.best_params}")

常见问题

Q: 为什么导入报错 ModuleNotFoundError?

确保你已经安装了QuantiaMagica。在项目目录下运行 pip install -e .

Q: 画图时中文显示为方块怎么办?

这是matplotlib字体问题。可以设置中文字体：

import matplotlib.pyplot as plt
plt.rcParams['font.sans-serif'] = ['SimHei']  # 黑体

Q: 如何保存仿真数据?

result = adc.sim()
result.save("data.npz")       # NumPy格式
result.save("data.csv", format="csv")  # CSV格式

Q: 如何从CSV文件导入自定义信号?

from quantiamagica import Signal

# CSV文件格式：每行一个电压值
sig = Signal.from_file("my_signal.csv", fs=1e6)
adc.sim(sig)

练习题

通过以下练习题逐步掌握QuantiaMagica的使用。点击"查看答案"可以看到参考解答。

from quantiamagica import SARADC

# 创建8位SAR ADC
adc = SARADC(bits=8)

# 运行仿真
adc.sim()

# 打印ENOB
print(f"ENOB: {adc.enob():.2f} bits")

from quantiamagica import SARADC

adc = SARADC(bits=12)
adc.sim(n_samples=4096)

print(f"SNR:  {adc.snr():.1f} dB")
print(f"SFDR: {adc.sfdr():.1f} dB")
print(f"THD:  {adc.thd():.1f} dB")

from quantiamagica import SARADC

adc = SARADC(bits=10)
adc.sim(fin=50e3, fs=1e6, n_samples=4096)
adc.spectrum()

from quantiamagica import (
    SARADC,
    SamplingEvent,
    CapacitorSwitchEvent,
    ComparatorEvent,
)
import numpy as np

# ========== 理想ADC ==========
ideal_adc = SARADC(bits=10, vref=1.0, name="Ideal")
ideal_adc.sim(n_samples=1024, fs=1e6, fin=10e3)

# ========== 非理想ADC ==========
real_adc = SARADC(bits=10, vref=1.0, name="Realistic")

# 事件1: 采样时添加kT/C热噪声
@real_adc.on(SamplingEvent)
def add_thermal_noise(event):
    kT = 1.38e-23 * 300  # Boltzmann * Temperature
    C = 1000e-15          # 1000fF = 1pF
    noise_sigma = np.sqrt(kT / C)
    event.voltage += np.random.normal(0, noise_sigma)

# 事件2: 电容切换时添加失配
@real_adc.on(CapacitorSwitchEvent)
def add_cap_mismatch(event):
    mismatch = np.random.normal(0, 0.005)  # 0.5% mismatch
    event.capacitance_actual = event.capacitance * (1 + mismatch)

# 事件3: 比较器非理想效应
@real_adc.on(ComparatorEvent)
def add_comparator_effects(event):
    event.offset = 0.5e-3       # 0.5mV失调
    event.noise_sigma = 0.1e-3  # 0.1mV噪声

real_adc.sim(n_samples=1024, fs=1e6, fin=10e3)

# ========== 对比结果 ==========
print(f"理想ADC:   ENOB={ideal_adc.enob():.2f}, SNR={ideal_adc.snr():.1f}dB")
print(f"非理想ADC: ENOB={real_adc.enob():.2f}, SNR={real_adc.snr():.1f}dB")

from quantiamagica import (
    SARADC,
    SamplingEvent,
    ComparatorEvent,
    OutputCodeEvent,
    EventPriority,
)
import numpy as np

adc = SARADC(bits=10, vref=1.0, name="Priority-Demo")

# HIGH优先级：最先执行
@adc.on(SamplingEvent, priority=EventPriority.HIGH)
def add_noise_first(event):
    """采样噪声，优先执行"""
    kT = 1.38e-23 * 300
    C = event.sampling_capacitance * 1e-15
    noise_sigma = np.sqrt(kT / C)
    event.voltage += np.random.normal(0, noise_sigma)

# NORMAL优先级：默认顺序
@adc.on(ComparatorEvent)
def comparator_effects(event):
    """比较器效应"""
    event.offset = 0.5e-3
    event.noise_sigma = 0.1e-3

# MONITOR优先级：只读监控，最后执行
@adc.on(OutputCodeEvent, priority=EventPriority.MONITOR)
def log_output(event):
    """记录转换结果（只读）"""
    if event.source._sample_index < 5:
        print(f"Sample {event.source._sample_index}: "
              f"V={event.input_voltage:.4f}V -> Code={event.code}")

print("前5个采样的转换记录：")
adc.sim(n_samples=1024, fs=1e6, fin=10e3)
print(f"\nENOB: {adc.enob():.2f} bits")

输入V → [Stage1: 8-bit SAR] → 残差×256 → [Stage2: 8-bit SAR] → 残差×256 → [Stage3: 8-bit SAR] → 输出
                ↓                              ↓                              ↓
             code1 (MSB 8位)               code2 (中间8位)                code3 (LSB 8位)
                                    ↓
                        最终24位码 = code1<<16 | code2<<8 | code3

from quantiamagica import Pipeline, SARADC, InterstageGainEvent

# ========== 创建3个8-bit SAR ADC ==========
stage1 = SARADC(bits=8, vref=1.0, name="SAR-Stage1")
stage2 = SARADC(bits=8, vref=1.0, name="SAR-Stage2")
stage3 = SARADC(bits=8, vref=1.0, name="SAR-Stage3")

# ========== 理想Pipeline (24-bit) ==========
ideal_pipe = Pipeline(
    stages=[stage1, stage2, stage3],
    gains=[256.0, 256.0],  # 级间增益=2^8
    name="24-bit-Ideal"
)
ideal_pipe.sim(n_samples=65536, fs=1e6, fin=10e3)

# ========== 带增益误差的Pipeline ==========
s1_err = SARADC(bits=8, vref=1.0, name="SAR-Stage1")
s2_err = SARADC(bits=8, vref=1.0, name="SAR-Stage2")
s3_err = SARADC(bits=8, vref=1.0, name="SAR-Stage3")

real_pipe = Pipeline(
    stages=[s1_err, s2_err, s3_err],
    gains=[256.0, 256.0],
    name="24-bit-GainError"
)

@real_pipe.on(InterstageGainEvent)
def add_gain_error(event):
    """模拟有限运放增益导致的非理想效应"""
    opamp_gain = 1000  # 运放增益
    gain_error = 1 - 1/opamp_gain  # ~0.1%误差
    event.actual_gain = event.ideal_gain * gain_error
    event.offset = 0.5e-3       # 0.5mV失调
    event.noise_sigma = 0.1e-3  # 0.1mV噪声

real_pipe.sim(n_samples=65536, fs=1e6, fin=10e3)

# ========== 对比结果 ==========
print("3×8-bit SAR → 24-bit Pipeline 分析")
print("=" * 50)
print(f"理想Pipeline:   ENOB={ideal_pipe.enob():.2f} bits, SNR={ideal_pipe.snr():.1f}dB")
print(f"带增益误差:     ENOB={real_pipe.enob():.2f} bits, SNR={real_pipe.snr():.1f}dB")
print(f"ENOB损失:       {ideal_pipe.enob() - real_pipe.enob():.2f} bits")

from quantiamagica import (
    SARADC,
    SamplingEvent,
    CapacitorSwitchEvent,
    ComparatorEvent,
    EventPriority,
)
import numpy as np

class RealisticSARPlugin:
    """可复用的SAR ADC非理想效应插件"""
    
    def __init__(self,
                 cap_mismatch_sigma=0.005,    # 0.5%电容失配
                 comparator_offset=0.5e-3,   # 0.5mV失调
                 comparator_noise=0.2e-3,    # 0.2mV噪声
                 sampling_cap_fF=500.0):     # 500fF采样电容
        self.cap_mismatch_sigma = cap_mismatch_sigma
        self.comparator_offset = comparator_offset
        self.comparator_noise = comparator_noise
        self.sampling_cap_fF = sampling_cap_fF
        self.cap_mismatches = None
        
    def attach(self, adc):
        """将所有非理想效应附加到ADC"""
        # 预生成固定的电容失配值
        self.cap_mismatches = 1 + np.random.normal(
            0, self.cap_mismatch_sigma, adc.bits
        )
        
        # 计算热噪声电压
        kT = 1.38e-23 * 300
        C = self.sampling_cap_fF * 1e-15
        self.thermal_noise_v = np.sqrt(kT / C)
        
        # 注册事件处理器
        @adc.on(SamplingEvent, priority=EventPriority.HIGH)
        def add_sampling_noise(event):
            event.voltage += np.random.normal(0, self.thermal_noise_v)
        
        @adc.on(CapacitorSwitchEvent)
        def add_cap_mismatch(event):
            event.capacitance_actual = (
                event.capacitance * self.cap_mismatches[event.bit_index]
            )
        
        @adc.on(ComparatorEvent)
        def add_comparator_effects(event):
            event.offset = self.comparator_offset
            event.noise_sigma = self.comparator_noise

# ========== 使用插件 ==========
print("1. 理想ADC")
ideal = SARADC(bits=12, vref=1.0)
ideal.sim(n_samples=2048, fs=1e6, fin=10e3)
print(f"   ENOB: {ideal.enob():.2f} bits")

print("\n2. 使用插件的非理想ADC")
real = SARADC(bits=12, vref=1.0)
plugin = RealisticSARPlugin()
plugin.attach(real)
real.sim(n_samples=2048, fs=1e6, fin=10e3)
print(f"   ENOB: {real.enob():.2f} bits")
print(f"   热噪声: {plugin.thermal_noise_v*1e6:.2f} uV rms")

from quantiamagica import SigmaDeltaADC
import numpy as np

sd = SigmaDeltaADC(order=2, bits=1, osr=64)

# 生成输入信号
fs = 1e6
fin = 1e3
n_samples = 8192
t = np.arange(n_samples) / fs
signal = 0.5 + 0.4 * np.sin(2 * np.pi * fin * t)

sd.sim(signal, fs=fs)
print(f"Sigma-Delta ENOB: {sd.enob():.2f} bits")

from quantiamagica.optim import SDCoeffOptimizer

# 创建优化器
optimizer = SDCoeffOptimizer(
    order=2,
    bits=1,
    osr=64,
    fs=1e6
)

# 运行优化
result = optimizer.optimize()

# 打印结果
print(result.summary())
print(f"\n优化前ENOB: {result.baseline_enob:.2f} bits")
print(f"优化后ENOB: {result.best_enob:.2f} bits")
print(f"提升: +{result.improvement:.2f} bits")

输入x → [积分器1] → [积分器2] → [积分器3] → [积分器4] → [积分器5] → [量化器] → 输出y
           ↑ c1        ↑ c2        ↑ c3        ↑ c4        ↑ c5
           └─a1·y──────┴─a2·y──────┴─a3·y──────┴─a4·y──────┴─a5·y (分布式反馈)

状态更新方程：
  state[0] = state[0] + c1 * (x - a1 * y)           // 第1级
  state[i] = state[i] + c[i] * (state[i-1] - a[i] * y)  // 第2-5级
  quantizer_input = state[4]                        // 输出到量化器

from quantiamagica import SigmaDeltaADC, QuantizerEvent
from quantiamagica.optim import GeneticOptimizer, Gene
import numpy as np

# ===================== 仿真参数 =====================
OSR = 64
BITS = 1
FS = 1e6
N_SAMPLES = OSR * 512
FIN = 13 * FS / N_SAMPLES  # 相干采样

# ===================== 定义11个基因 =====================
genes = [
    # 积分器增益（递减范围）
    Gene('c1', 0.05, 0.6, 'float'),
    Gene('c2', 0.04, 0.5, 'float'),
    Gene('c3', 0.03, 0.4, 'float'),
    Gene('c4', 0.02, 0.3, 'float'),
    Gene('c5', 0.01, 0.2, 'float'),
    # 反馈系数
    Gene('a1', 0.5, 4.0, 'float'),
    Gene('a2', 0.3, 3.5, 'float'),
    Gene('a3', 0.2, 3.0, 'float'),
    Gene('a4', 0.1, 2.5, 'float'),
    Gene('a5', 0.05, 2.0, 'float'),
    # 输入幅度
    Gene('amplitude', 0.03, 0.2, 'float'),
]

# ===================== 评估函数 =====================
def evaluate_5th_order_sd(params):
    """创建并评估5阶SD ADC"""
    c = [params[f'c{i+1}'] for i in range(5)]
    a = [params[f'a{i+1}'] for i in range(5)]
    amplitude = params['amplitude']
    
    sd = SigmaDeltaADC(order=1, bits=BITS, osr=OSR)
    state = [0.0] * 5  # 5个积分器状态
    
    @sd.on(QuantizerEvent)
    def fifth_order_cifb(event):
        """5阶CIFB结构"""
        x = event.input_signal
        y = event.prev_output
        
        # 5阶级联积分器 + 分布式反馈
        state[0] = state[0] + c[0] * (x - a[0] * y)
        for i in range(1, 5):
            state[i] = state[i] + c[i] * (state[i-1] - a[i] * y)
        
        event.quantizer_input = state[4]  # 输出到量化器
    
    # 生成输入信号
    t = np.arange(N_SAMPLES) / FS
    signal = 0.5 + amplitude * np.sin(2 * np.pi * FIN * t)
    
    sd.sim(signal, fs=FS)
    sd._result.metadata['fin'] = FIN
    return sd.enob()

# ===================== 适应度函数 =====================
def fitness(params):
    try:
        enob = evaluate_5th_order_sd(params)
        if enob <= 0 or np.isnan(enob) or enob > 35:
            return -1000  # 振荡或异常，给惩罚
        return enob
    except:
        return -1000

# ===================== 基准测试 =====================
baseline_params = {
    'c1': 0.25, 'c2': 0.18, 'c3': 0.12, 'c4': 0.08, 'c5': 0.05,
    'a1': 2.0, 'a2': 1.5, 'a3': 1.0, 'a4': 0.6, 'a5': 0.3,
    'amplitude': 0.1
}
baseline_enob = evaluate_5th_order_sd(baseline_params)
print(f"默认系数 ENOB: {baseline_enob:.2f} bits")

# ===================== 运行优化 =====================
print("开始优化11维参数空间...")
optimizer = GeneticOptimizer(genes, fitness, maximize=True)
result = optimizer.run(
    population_size=300,      # 大种群探索高维空间
    max_generations=500,
    mutation_rate=0.18,
    elite_ratio=0.10,
    seed=2024
)

# ===================== 输出结果 =====================
best_enob = evaluate_5th_order_sd(result.best_params)
print(f"\n优化后 ENOB: {best_enob:.2f} bits")
print(f"提升: +{best_enob - baseline_enob:.2f} bits")

print(f"\n优化后系数:")
print(f"  积分器: c1={result.best_params['c1']:.4f}, c2={result.best_params['c2']:.4f}, "
      f"c3={result.best_params['c3']:.4f}, c4={result.best_params['c4']:.4f}, c5={result.best_params['c5']:.4f}")
print(f"  反馈:   a1={result.best_params['a1']:.4f}, a2={result.best_params['a2']:.4f}, "
      f"a3={result.best_params['a3']:.4f}, a4={result.best_params['a4']:.4f}, a5={result.best_params['a5']:.4f}")
print(f"  幅度:   amplitude={result.best_params['amplitude']:.4f}")