Skip to content

feat: scientific validation and constraint-aware control synthesis - #1

Merged
enthonyaraujo merged 7 commits into
mainfrom
test/academic-validation
Nov 19, 2026
Merged

enthonyaraujo merged 7 commits into
mainfrom
test/academic-validation

Conversation

@enthonyaraujo

Copy link
Copy Markdown
Owner

Contexto

Após a migração do motor matemático do ControLAB de Python para Rust nativo, foi conduzida uma validação científica, numérica, funcional, visual e de desempenho em 11 etapas tomando como base as listas acadêmicas da disciplina de Sistemas de Controle II da UFERSA (19 casos de Lugar Geométrico das Raízes e 9 questões de Projeto de Controladores), comparadas com derivações analíticas fechadas, execuções independentes no MATLAB R2022b (Control System Toolbox) e referências congeladas do motor Python legado (be79347).

Resumo das Alterações

1. Motor de Verificação e Síntese por Restrições (crates/control-engine)

  • Novo módulo genérico crates/control-engine/src/controller_synthesis.rs:
    • Verificação completa da malha fechada real (verify_controller) sobre o polinômio característico não reduzido (estabilidade externa e interna, rejeitando cancelamentos no SPD/$j\omega$).
    • Semântica explícita de restrições: DampingSpec::{Equal, AtLeast, DidacticEstimate}, NaturalFreqSpec::{Equal, AtLeast, OptionalEstimate}, SettlingSpec::{AtMost, Equal} com tolerância padrão uniforme (±2%, piso 0,02 s), max_overshoot_pct, erro atuante no somador vs rastreamento da saída em realimentação não unitária, identificação do polo/par de referência e razão exata de resíduos modais de Heaviside.
    • Síntese genérica por restrições (temporal_refined e auto_simplest percorrendo P -> PI -> PD -> Lead -> PID), com parametrização canônica [Kp, Ki, Kd] para PID (zeros reais ou complexos no SPE) e classificação explícita FeasibilityClass::{Feasible, ProvenInfeasible, NotFoundWithinSearchBounds} (incluindo provas algébricas diferenciadas para $k/s^2$ com $y(\infty)=1$ e $k/(s^2+c)$ com $y(\infty) = 1 - c/\omega_n^2$).
    • Preservação integral do modo didático clássico (lgr_classic) e da paridade legada (152/152).
  • Correções em crates/control-engine/src/controllers.rs: corrigidas regressões de formatação e paridade do commit c32b2d4, restaurando 152/152 casos em xtask parity.

2. Interface Nativa (native)

  • Adicionados seletores de Modo de Síntese, Restrição de ts e Restrição de ξ em native/modules.json.
  • Adicionado painel de conformidade em native/src/results.rs exibindo banner (CONFORME, CONFORME COM ALERTAS, NÃO CONFORME), motivos de não conformidade, Polo(s) de referência (ξ/ωn) com razão de resíduos, tabela Solicitado × Teórico × Medido × Diferença com marcações [OBRIGATÓRIA] vs [ESTIMATIVA OPCIONAL] e advertências técnicas.
  • Teste automatizado de regressão da UI em native/src/ui_tests.rs.

3. Suítes Permanentes de Regressão Acadêmica (100% Rust, sem Python/MATLAB em runtime)

  • crates/control-engine/tests/academic_lgr_validation.rs (19 casos LGR + Routh + resíduos de $D(s)+KN(s)=0$)
  • crates/control-engine/tests/academic_controllers_validation.rs (9 questões de controladores + perturbação Q8 + critério definitivo de $t_s$)
  • crates/control-engine/tests/academic_requirements_compliance.rs (não conformidade clássica, sistemas instáveis/SPD, referência independente Q8 -1 - 0,2/s com perturbações $\pm 10%$, síntese exata $\xi = 0{,}4$ na Q5 e $\xi = 0{,}5$ na Q2 PID, provas ProvenInfeasible e NotFoundWithinSearchBounds)
  • crates/blocklab-core/tests/academic_diagrams.rs (redução exata via Mason de todos os diagramas das duas listas + Q8 referência 1.44/(s+1.44))
  • crates/mscript/tests/academic_validation.rs (reprodução em scripts .m no Studio)

4. Documentação Científica, CI e Curadoria

  • Documentação pública estruturada em docs/validation/ (README.md, methodology.md, academic-validation.md, synthesis-comparison.md, benchmarks.md, final-acceptance.md, validation-matrix.csv com 42 configurações e 4 capturas selecionadas em docs/validation/assets/).
  • Atualizados README.md, CHANGELOG.md (Unreleased), .gitignore (preservando artefatos/logs locais em artifacts/ fora do controle de versão) e .github/workflows/build-all.yml (executando cargo run --locked --release -p xtask -- parity na CI Linux).

Resultados de Validação e Benchmarks

  • Testes permanentes (cargo test --workspace): 411 passed, 0 failed, 3 ignored (testes opt-in MATLAB).
  • Testes opt-in ao vivo contra MATLAB R2022b (cargo test --release -p mscript -- --ignored): 3/3 passed (erro relativo escalado máximo 7,883e-15).
  • Paridade congelada (cargo run --release -p xtask -- parity): 152/152 matched (complete_parity: true, 260 ativos visuais).
  • Auditoria de fontes (cargo run --release -p xtask -- check-sources): aprovado (0 dependências Python/JS/TS/HTML/CSS).
  • Benchmarks (Rust --release vs Python legado be79347, processo persistente JSON-lines, 3 warmups, 5–25 iterações, Linux Intel Core i5-13420H): aceleração mediana de 3,76× a 15,50× (9,01× em síntese de controladores, 12,89× em LGR, 15,50× na suíte completa de 19 LGRs) e redução de RSS de até 11,47× (detalhes e escopo em docs/validation/benchmarks.md).

Evidências Visuais

Q8 Clássico (NÃO CONFORME, $M_p=33{,}84%$) Q8 Refinado (CONFORME COM ALERTAS, $M_p=0%$)
Q8 Clássico Q8 Refinado
Q5 Etapa 11 ($\xi=0{,}4000$, $t_s=0{,}997\text{ s}$) Q2 PID Etapa 11 ($\xi=0{,}5000$ dom., $M_p=13{,}58%$, $t_s=4{,}000\text{ s}$)
Q5 Exato Q2 PID Exato

Limitações Conhecidas

  • A validação abrange sistemas SISO lineares contínuos nos módulos e casos testados (não declara equivalência universal com todo o ecossistema MATLAB/Simulink).
  • Q2 PD e Q9 PD sob igualdade exata $\xi = 0{,}5$ simultaneamente a $M_p \le 16{,}3%$/$16{,}0%$ são matematicamente inviáveis (provado em docs/validation/synthesis-comparison.md).
  • Cancelamentos aproximados de polos estáveis emitem advertências explícitas de robustez paramétrica.

Checklist de Qualidade

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace (411 passed, 0 failed)
  • cargo build --workspace --release
  • cargo run --release -p xtask -- parity (152/152 matched)
  • cargo run --release -p xtask -- check-sources
  • cargo test --release -p mscript -- --ignored (3/3 passed contra MATLAB R2022b)
  • git diff --check
  • Sem merge automático, sem tags e sem alteração de versão

@enthonyaraujo
enthonyaraujo merged commit 1fe483d into main Nov 19, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant