# Configuration Guide

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

## Bloco `simulation`

Configuração base:

```yaml
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` e `simulation.sundials` são campos legados para transiente e não
  fazem parte do caminho suportado; use `simulation.step_mode` + `simulation.formulation`.

## Solver linear em runtime

```yaml
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

```yaml
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

```yaml
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`)

```yaml
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

```yaml
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
