toimyud1/agentic-cfd

Fluxo de Trabalho Agentic CFD

Você transforma um enunciado de problema em um relatório de simulação confiável. O leitor é um engenheiro que lerá principalmente o resumo e deve ser capaz de verificar cada afirmação. Quatro regras:

1. O código computa cada número. Você escreve o código; nunca digita um resultado, valor de referência ou saída de fórmula manualmente no relatório. A teoria é resolvida simbolicamente (SymPy) e auto-verificada.
2. Cada escolha é documentada. Cada configuração do OpenFOAM pertence a uma decisão com porquê / efeito / alternativas. Um verificador se recusa a renderizar o relatório caso contrário.
3. Nada de memória. Dados de referência, correlações e constantes vêm dos arquivos reference/ do problema ou de uma fonte citada. Se você precisar usar um valor aproximado, diga isso no relatório.
4. Insights ao vivo, como um caderno de laboratório. Parte do seu trabalho é melhorar este fluxo de trabalho para os agentes depois de você. No momento em que algo falha, surpreende você, precisa de uma segunda tentativa ou não está claro nestas diretrizes, abra um insight (antes de começar a corrigi-lo): insights.log(case, stage, problem); preencha o diagnóstico, correção, lição e diretriz com insights.resolve(...) depois de resolvido. Não os guarde para o final: memórias de uma longa sessão se perdem e distorcem. Espere registrar de 5 a 15 entradas; uma execução com nenhuma não foi examinada de perto.

Estrutura de Pastas

cfdlib/                       ferramentas compartilhadas (NÃO modifique; registre mudanças necessárias como insights, stage "tooling")
  foam.py        render_case, run (timeout, arquivo PID), stop, running; ler campos e arquivos .dat de postProcessing
  monitor.py     parse_log, assess (verificações de saúde), preflight (execução de teste curta + projeção de tempo de execução)
  verification.py normas de erro, ordem observada, extrapolação de Richardson, GCI, level_sequence
                 (convergência de qualquer sequência de níveis, incluindo a própria referência)
  signals.py     sinais periódicos: ciclos, picos refinados, verificação de periodicidade, FFT de frequência
  plots.py       estilo e tamanhos de figuras (figure, wide, sketch); to_svg verifica texto sobreposto
  report.py      m(), tex_num(), tex_fix() (decimais fixos para colunas de tabela), tex_pct(), LETTERS, load_yaml,
                 environment_info(), render()
  perf.py        números de desempenho por execução (summarize, machine) para o apêndice de desempenho
  contract.py    o verificador de contrato do relatório (também modo --decisions)
  insights.py    o registro de insights ao vivo (verifica a formatação quando você registra; recusa sobrescrever uma entrada preenchida)
  foamdict.py    analisador de dicionário OpenFOAM (usado pelo verificador)
cases/<nome>/                 uma pasta por problema
  problem.yaml   FORNECIDO pelo usuário: descrição (visão geral curta), setup (lista de fatos: geometria,
                 condições de contorno, definições), dados fornecidos, saídas solicitadas [+ reference/].
                 Não altere a física. Passe a descrição e o setup para o relatório inalterados.
  reference/     dados de referência fornecidos pelo usuário com citações
  numerics.yaml  seu plano numérico (malhas, durações de execução, tolerâncias)
  decisions.yaml cada escolha, escrita ENQUANTO você configura o caso
  insights.yaml  o registro ao vivo (cfdlib.insights)
  template/      o caso OpenFOAM (0/, constant/, system/) com {{ placeholders }}
  theory.py / analytical.py, sketch.py, run.py, analyze.py
results/<nome>/  dados brutos, results.json, report.html

Exemplos trabalhados (leia todos os seus arquivos antes de começar; copie a estrutura, não as configurações numéricas):

• cases/plane_poiseuille/: linear, estacionário, solução exata (verificação). Relatório: results/plane_poiseuille/report.html.
• cases/lid_driven_cavity_re100/: não linear, estacionário, sem solução exata, benchmark publicado (comparação de benchmark, extrapolação de Richardson, SIMPLEC parado por resíduo, comandos separados de pré-viabilidade e produção). Relatório: results/lid_driven_cavity_re100/report.html. Seu insights.yaml contém 15 lições do agente que o construiu.
• cases/stokes_first_problem/: linear, TRANSIENTE, solução exata (estudos combinados e separados de malha e passo de tempo, balanço de momento por passo, execuções concorrentes). Relatório: results/stokes_first_problem/report.html.
• cases/dfg_cylinder_re100/: não linear, TRANSIENTE e periódico (emissão de vórtices), benchmark com vários níveis de referência, malha O-grid de corpo curvo gerada em Python, execuções MPI e um apêndice de desempenho. Relatório: results/dfg_cylinder_re100/report.html. Seu insights.yaml contém 16 lições (a mais importante: PISO era de primeira ordem no tempo).

Estágios

0. Recepção

• Leia problem.yaml e quaisquer arquivos reference/. Liste as saídas solicitadas (elas recebem letras a, b, c...).
• Calcule os números adimensionais de governo (Re, Ma, ...) em código. Decida qual física se aplica.
• Se dados estiverem faltando ou forem contraditórios, escolha uma suposição documentada e sinalize-a no relatório limitações. Nunca invente entradas silenciosamente.
• Se uma referência não fornecer incerteza, estime uma (sua malha, seus dígitos impressos, uma segunda fonte) e registre como; você precisará dela no estágio 5.

1. Teoria: o que pode ser conhecido sem a simulação

• Solução exata disponível: deduza-a com SymPy, auto-verifique-a (satisfaz equações e condições de contorno), avalie as quantidades solicitadas. Veja cases/plane_poiseuille/analytical.py.
• Sem solução exata (caso usual): diga isso em theory.intro, e forneça o que a teoria PODE dizer: casos limites, escalonamento, leis de conservação, simetria, sinal de quantidades, estrutura de escoamento esperada. Veja cases/lid_driven_cavity_re100/theory.py.
• Cada quantidade derivada recebe: por que é importante, o significado e o valor de cada símbolo neste problema, e a fórmula com os números substituídos (verificação manual).

2. Configuração e decisões

• Encontre o tutorial OpenFOAM mais próximo ($FOAM_TUTORIALS) e comece a partir dele; faça mudanças mínimas.
• Leia references/openfoam-primer.md para saber o que cada arquivo controla e as armadilhas conhecidas.
• Os modelos podem conter loops Jinja: gerar um blockMeshDict inteiro a partir de Python é aceitável e é a maneira de malhar corpos curvos (exemplo: mesh_spec() em cases/dfg_cylinder_re100/run.py).
• Edite arquivos que contenham apenas LaTeX com as ferramentas Edit/Write, nunca através de heredocs Bash ou Python inline: a ferramenta Bash come barras invertidas (\times se torna um TAB). Os Casos 3 e 4 ambos perderam tempo com isso.
• Escreva decisions.yaml enquanto avança: uma entrada por escolha com kind (physics / accuracy / solver / output) e padrões settings cobrindo cada configuração nos arquivos do caso. Verifique a cobertura assim que um caso for renderizado: python -m cfdlib.contract --decisions cases/<nome>/decisions.yaml <dir do caso>.
• Planeje um estudo de malha: pelo menos 3 malhas, razão de refino 2 (necessária para ordem observada e GCI). Problemas transientes também precisam de um estudo de passo de tempo (ou um argumento, com números, de que o erro de tempo é desprezível).
• Defina uma verificação física de convergência/estabilidade para seu problema (um balanço, uma quantidade conservada, um valor monitorado que deve parar de mudar) e sua tolerância ANTES de ver os resultados. Resíduos normalizados sozinhos não são suficientes. Problemas transientes: um balanço por passo (mudança de uma quantidade conservada = fluxos de contorno) é uma verificação forte; ele deve usar o próprio esquema temporal do solver.
• As tolerâncias de aprovado/reprovado devem discriminar: dimensione-as a partir do erro grosseiro da pré-viabilidade e da ordem esperada (o que a malha mais fina deve alcançar), não a partir de números redondos. Uma tolerância 100x mais frouxa do que o alcançado não prova nada (caso 3). Torne a ordem de precisão observada uma regra por si só.

3. Teste de pré-viabilidade (obrigatório, antes de qualquer execução longa)

• cfdlib.monitor.preflight() nas malhas MAIS GROSSEIRA E MAIS FINA com uma execução curta (alguns % da duração total). Ele funciona em uma cópia separada <case>_preflight; renderize os casos de pré-viabilidade e produção em diretórios separados também, para que reexecutar um nunca delete o outro.
• Ele relata falhas, NaN, número de Courant, tendências de resíduo/Courant/continuidade e projeta o tempo de execução. Execuções transientes: a projeção é confiável. Execuções estacionárias: passe residual_targets; o resultado é um limite inferior (SIMPLE desacelera mais tarde e em malhas mais finas).
• Imprima o cabeçalho e as primeiras linhas de cada arquivo postProcessing que a pré-viabilidade escreveu e verifique se cada um é não trivial (caso 4: uma integral de pressão escreveu 0 a cada passo, silenciosamente).
• Problemas transientes não lineares: um estudo curto de passo de tempo (3 passos de tempo, razão 2, em uma malha grosseira) pertence à pré-viabilidade, antes do estudo de malha. Ele mostra a ordem observada no tempo: PISO (1 corretor externo) acabou sendo de primeira ordem no caso 4 e custou uma reexecução completa.
• Uma pré-viabilidade que começa do repouso subestima o custo de um escoamento não estacionário desenvolvido (caso 4: duas vezes). Comece-a a partir de um campo desenvolvido (mapFields de uma execução grosseira) ou orce o dobro da projeção.
• Se falhar ou emitir um aviso, corrija a configuração e registre um insight. Nenhuma execução de produção em uma pré-viabilidade com falha. Se o tempo projetado for excessivo (> ~15 min por execução aqui), engrosse o plano e diga isso.

4. Execuções de produção

• Execute malhas da grosseira para a fina. Para execuções estacionárias, extrapole a contagem de iterações da malha mais fina a partir das mais grosseiras (ela frequentemente cresce 3-4x por refino) antes de lançá-la.
• A parada deve ser física: torne a verificação física do estágio 2 a regra de parada (por exemplo, um objeto de função runTimeControl em valores sondados, veja o primer), ou verifique por malha se os alvos de resíduo realmente a satisfazem, primeiro nas malhas mais grosseiras.
• Execuções independentes (malhas diferentes) podem ser executadas ao mesmo tempo, até 6 de uma vez (8 núcleos). Diga isso nas notas de reprodutibilidade, pois infla os tempos de parede por execução.
• Execuções longas vão para segundo plano; python -m cfdlib.foam ps lista processos do solver, e python -m cfdlib.foam stop <dir do caso> mata um (parar o wrapper Python sozinho deixa um solver órfão). Registre por execução: saúde (monitor.assess), a verificação física, tempo de parede.
• Execute uma sequência de execuções longas como UM script de segundo plano que escreve um marcador de conclusão e um registro por execução. Após qualquer interrupção (uma pausa da API também), leia esses arquivos antes de reexecutar qualquer coisa.
• Enquanto todos os threads de hardware executam um solver, seu próprio trabalho o desacelera: deixe 1-2 threads livres ou orce 1,5 vezes a projeção.

5. Análise

• Todas as comparações em código. Com uma solução exata: erros e ordem observada por malha. Sem: ordem observada e extrapolação de Richardson a partir de 3 malhas, GCI na malha mais fina (verification.py), então compare o valor extrapolado com a referência.
• Um benchmark também é uma simulação: julgue a concordância contra (sua banda GCI + a incerteza da própria referência), não contra zero. Se a diferença não diminuir com o refino, não é seu erro de discretização; teste robustez (outro esquema, iteração mais apertada) antes de culpar qualquer lado, e recomende uma segunda referência independente.
• Quando a referência fornece vários níveis de malha, ela ainda está convergindo: calcule SUA ordem observada e valor de Richardson (verification.level_sequence) e compare seu resultado tanto com seu nível mais fino quanto com seu valor extrapolado. Decida a regra de aprovação antes de olhar (o caso 4 manteve a regra do nível mais fino e relatou a extrapolação como contexto).
• Saídas periódicas (emissão, oscilações): use cfdlib.signals (ciclos entre cruzamentos ascendentes, picos refinados por parábola, verificação de periodicidade, verificação cruzada FFT) em vez de escrever as suas.
• Uma correspondência de malha grosseira pode ser sorte (cancelamento de erro). Relate diferenças honestamente, onde e por que.
• Uma explicação é uma afirmação: verifique-a contra os dados (sinal, tamanho, escalonamento) antes de escrevê-la. No caso 3, a primeira explicação de um erro tinha o sinal errado e um terço do tamanho.

6. Relatório

• Construa results.json em analyze.py e chame report.render(results, svgs, out, case_dir=<caso mais fino>). O contrato está em references/report-contract.md; render recusa escrever um relatório que o quebre.
• Matemática: cada fórmula, símbolo e número científico no texto como LaTeX dentro de \( \) (m(), tex_num()): escreva \(0.009\,U\), nunca 0.009 U, 6.3e-06 ou u*H/nu. O verificador rejeita notação-e e matemática ASCII, e avisa sobre número-vezes-símbolo em texto simples.
• Legendas e descobertas também são resultados: gere-as a partir dos dados (uma legenda que diz "diminui" deve ser computada). Refira-se a figuras como {fig:<chave>}; render() insere o número.
• Figuras (cfdlib.plots): plots.figure() para um painel, plots.wide(n) para 2-3 painéis, plots.sketch() para o esboço do problema (obrigatório). to_svg() recusa figuras cujo texto se sobrepõe a texto, linhas, setas ou formas, ou cuja legenda cobre dados, ou que são mais largas que a coluna. Corrija o layout (rótulos longe de linhas, annotate com uma linha de chamada, legenda fora); allow= apenas para sobreposições que são verdadeiramente intencionais, e registre um insight se precisar.
• Verdicto: APROVADO somente se cada verificação que você definiu passar; AVISO se os resultados forem utilizáveis ​​com ressalvas; REPROVADO caso contrário. Nunca suavize uma verificação reprovada.

7. Revisão visual (obrigatória)

O contrato verifica a estrutura; apenas olhar captura o que um leitor verá. Abra o relatório no navegador embutido através do servidor local (file:// não funciona): http://localhost:8765/<nome>/report.html (se não carregar, inicie o servidor reports a partir de .claude/launch.json com a ferramenta de visualização). Adicione ?v=<n> após re-renderizar para evitar uma cópia em cache.

• Capture a tela de cada seção, de cima para baixo. Verifique: figuras legíveis (texto não minúsculo, nada sobreposto, linhas de chamada não cruzando curvas), tabelas não cortadas, matemática renderizada (sem \( bruta), colunas de tabela alinhadas, o resumo responde a cada solicitação.
• Execute na página (aguarda MathJax, abre todos os painéis ⓘ, então lista todo elemento cujo conteúdo está cortado; deve estar vazio; executar logo após o carregamento, antes que o MathJax termine, relata TeX não tipografado como estouro): await MathJax.startup.promise; document.querySelectorAll('details').forEach(d => d.open = true); [...document.querySelectorAll('section *')].filter(x => !x.tagName.startsWith('MJX') && x.scrollWidth > x.clientWidth && getComputedStyle(x).overflow !== 'visible').map(x => x.tagName + '#' + x.id + ' ' + x.textContent.slice(0, 80))