Convergence Tuning Guide (Python + YAML)¶

Este guia foca no runtime suportado: Python + YAML (pulsim-v1).

Sintomas comuns¶

Falha no ponto de operação DC (dc_operating_point).
Muitos timestep_rejections no transiente.
Queda para fallback linear com frequência alta.
Passos muito pequenos e simulação lenta.

Checklist rápido¶

Garanta caminho DC para o terra (evite nós flutuantes).
Use simulation.solver.order e fallback_order explícitos.
Em circuitos stiff, prefira integrator: trbdf2 ou rosenbrockw.
Ative precondicionador ILUT para malhas grandes.
Use adaptive_timestep: false quando quiser baseline determinístico.

Verificar backends compilados¶

No Python:

import pulsim as ps
print(ps.backend_capabilities())
# Exemplo: {'c_block': True} (chaves podem variar conforme build)

Observação: no caminho suportado de transiente, use o core nativo com simulation.step_mode (fixed|variable), sem seleção de backend legado.

Exemplo de configuração robusta¶

schema: pulsim-v1
version: 1
simulation:
  tstart: 0.0
  tstop: 2e-3
  dt: 1e-6
  step_mode: variable
  dt_min: 1e-10
  dt_max: 5e-5
  adaptive_timestep: true  # override avançado
  integrator: trbdf2

  solver:
    order: [klu, gmres]
    fallback_order: [sparselu]
    allow_fallback: true
    auto_select: true
    size_threshold: 400
    nnz_threshold: 2500
    diag_min_threshold: 1e-12
    iterative:
      max_iterations: 300
      tolerance: 1e-8
      restart: 40
      preconditioner: ilut
      ilut_drop_tolerance: 1e-3
      ilut_fill_factor: 10
      enable_scaling: true
      scaling_floor: 1e-12

  newton:
    max_iterations: 60
    enable_limiting: true
    max_voltage_step: 2.0
    max_current_step: 5.0

Ajustes por cenário¶

Buck/boost com chaveamento rápido¶

integrator: trbdf2
dt inicial pequeno (ordem de 1/50 a 1/200 do período de comutação)
enable_events: true

Malha grande com muitos passivos¶

order: [gmres, klu] ou [klu, gmres] (teste as duas)
ILUT ligado
aumente iterative.max_iterations

Problema quase singular¶

aumente diag_min_threshold
reduza max_voltage_step
aumente gmin_fallback e max_step_retries

Observabilidade para diagnóstico¶

No resultado transiente, acompanhe:

result.newton_iterations_total
result.timestep_rejections
result.linear_solver_telemetry.total_fallbacks
result.fallback_trace

Esses campos são essenciais para comparar tuning entre cenários e evitar regressão.

Estratégia de validação¶

Ajuste em circuito pequeno de referência.
Replique no benchmark matrix.
Confirme em ngspice e depois LTspice.
Execute stress tiers A/B/C antes de promover configuração.