Configuration Guide¶

Este guia concentra as configurações que mais impactam convergência, tempo de simulação e fidelidade.

Bloco `simulation`¶

Configuração base:

simulation:
  tstart: 0.0
  tstop: 2e-3
  dt: 1e-6
  step_mode: variable   # fixed | variable
  formulation: projected_wrapper  # projected_wrapper | direct
  dt_min: 1e-10
  dt_max: 1e-4
  integrator: trbdf2

Campos práticos:

tstop, dt: resolução e duração.
step_mode: fixed para grade determinística; variable para adaptação automática.
formulation: projected_wrapper (padrão, mais robusto em mistas) ou direct (DAE direto).
adaptive_timestep: override avançado (evite no fluxo canônico; prefira step_mode).
integrator: trapezoidal, bdf1..bdf5, trbdf2, rosenbrockw, sdirk2.

Observação de migração:

simulation.backend, simulation.sundials e o bloco simulation.advanced foram removidos da superfície suportada; use simulation.step_mode + simulation.formulation e ajustes explícitos em simulation.solver, simulation.newton, simulation.timestep, etc.

Solver linear em runtime¶

simulation:
  solver:
    order: [klu, gmres]
    fallback_order: [sparselu]
    allow_fallback: true
    auto_select: true
    size_threshold: 400
    nnz_threshold: 2500
    diag_min_threshold: 1e-12

Quando usar:

KLU/SparseLU: redes pequenas/médias com robustez alta.
GMRES/BiCGSTAB: redes grandes e esparsas.
fallback_order: proteção para casos difíceis.

Iterativo e precondicionador¶

simulation:
  solver:
    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

Regras rápidas:

comece com ilut em conversores maiores;
aumente max_iterations se ficar próximo de convergir;
enable_scaling ajuda matrizes mal condicionadas.

Newton, fallback e robustez¶

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

Complementos úteis:

max_step_retries: quantas tentativas por passo.
gmin_fallback: reforço de robustez em regiões difíceis.
fallback_policy: rastreio e política de retry (fallback_trace).

Controle em malha fechada (`simulation.control`)¶

simulation:
  control:
    mode: auto         # auto | continuous | discrete
    sample_time: 1e-4  # obrigatório quando mode=discrete

Semântica:

auto: usa sample_time explícito; se ausente, infere Ts = 1/f_pwm_max (maior frequência PWM do circuito).
continuous: atualiza blocos de controle a cada passo aceito.
discrete: atualiza PI/PID apenas nos instantes de amostragem.

Dicas práticas:

Em buck/boost chaveado, comece com auto para sincronizar controle com PWM.
Se houver oscilação numérica por controle muito rápido, teste discrete com sample_time = 1/f_sw ou 1/(2*f_sw).
Use limites explícitos (output_min/output_max) e anti_windup em PI/PID.

Perdas e térmico¶

simulation:
  enable_losses: true
  thermal:
    enabled: true
    ambient: 25.0
    policy: loss_with_temperature_scaling
    default_rth: 1.5
    default_cth: 0.02

Saídas relevantes:

result.loss_summary
result.thermal_summary
result.component_electrothermal
result.events para inspeção de chaveamento/eventos.

Componentes com porta térmica suportada (component.thermal.enabled: true):

resistor, diode, mosfet, igbt, bjt_npn, bjt_pnp

Estratégias de configuração¶

Debug rápido¶

step_mode: fixed
integrator: trapezoidal
order: [sparselu]

Produção robusta¶

step_mode: variable
formulation: projected_wrapper
integrator: trbdf2 ou rosenbrockw
order: [klu, gmres]
fallback_order: [sparselu]

DAE direto (diagnóstico/perfil)¶

step_mode: fixed ou variable
formulation: direct
opcional: direct_formulation_fallback: false para comparar somente rota direta