BEDFLOW-ATLAS-TCC-2

pipeline automatizado para simulacao cfd de leitos empacotados usando dsl, blender e openfoam.

https://github.com/bengo501/CFD-PIPELINE-TCC-1/issues

https://github.com/bengo501/CFD-PIPELINE-TCC-1/milestones

tcc2: escopo local, docker e template

• execução local é o caminho principal do trabalho; stack em docker/docker-compose.yml (postgres, redis, minio, backend, frontend). na pasta docker: docker compose up --build.
• imagem backend: construída a partir da raiz do repo (docker build -f docker/Dockerfile ..). variável de build WITH_BLENDER=0 gera imagem sem blender (perfil python modeling); com 1 inclui blender.
• perfis de modelagem: MODELING_PROFILE=blender (default) ou MODELING_PROFILE=python — ver docs/tcc2/PERFIS_MODELAGEM.md. documentação para a monografia em docs/tcc2/.
• github template: checklist em docs/tcc2/USO_COMO_TEMPLATE.md.
• painel «banco de dados» na interface web (contagens sql + registo de pedidos): docs/DATABASE_PAGE.md.
• relatórios (texto + anexos a simulações/templates/resultados): docs/REPORTS_PAGE.md.
• perfil (singleton user_profiles, preferência de idioma): docs/PROFILE_PAGE.md.
• configurações (app_settings, options_json, modo simples/dev, openfoam/modelagem, swagger, shutdown dev): docs/SETTINGS_PAGE.md.
• modelo de dados (mapeamento frontend/backend, entidades sql, fixture json de teste): docs/MODELO_DE_DADOS.md.

sobre o projeto

este projeto implementa um pipeline completo e reproduzivel para simulacao cfd (computational fluid dynamics) de leitos empacotados. a solucao aborda os principais problemas de reproducibilidade em simulacoes cientificas atraves de:

1. dsl (domain specific language) - linguagem .bed para descrever parametros de leitos
2. geracao automatica de geometria 3d - usando blender com fisica rigid body
3. simulacao cfd automatizada - usando openfoam (blockmesh, snappyhexmesh, simplefoam)
4. containerizacao - docker compose na pasta docker/ para reproducibilidade local
5. interface web - dashboard para visualizacao e analise (planejado)

1. dsl - domain specific language

linguagem declarativa .bed para descrever leitos empacotados:

bed {
    diameter = 5cm
    height = 10cm
    wall_thickness = 2mm
    shape = "cylinder"
}

particles {
    count = 100
    kind = "sphere"
    diameter = 5mm
    mass = 0.1kg
}

packing {
    method = "rigid_body"
    gravity = (0, 0, -9.81) m/s2
}

cfd {
    regime = "laminar"
    inlet_velocity = 0.1 m/s
    fluid_density = 1000 kg/m3
}

2. compilador antlr

compila .bed para .bed.json normalizado (valores em si):

python dsl/compiler/bed_compiler_antlr_standalone.py leito.bed
# saida: leito.bed.json

3. geracao 3d com blender

cria modelo 3d com fisica rigid body:

python dsl/bed_wizard.py
# escolher modo blender
# modelo salvo em generated/3d/output/

features:

• cilindros ou cubos
• tampas planas ou hemisfericas
• particulas esfericas com fisica
• simulacao de empacotamento por gravidade

4. simulacao cfd com openfoam

configura e executa simulacao automaticamente:

python scripts/openfoam_scripts/setup_openfoam_case.py \
  dsl/leito.bed.json \
  generated/3d/output/leito.blend \
  --output-dir generated/cfd \
  --run

etapas automatizadas:

1. exportar stl do blender
2. criar caso openfoam (0/, constant/, system/)
3. gerar malha com blockmesh
4. refinar malha com snappyhexmesh
5. verificar qualidade com checkmesh
6. resolver com simplefoam
7. gerar arquivo para paraview

5. tutoriais openfoam versionados (tutorial/)

casos minimos no repositorio para validar openfoam e estudar fluxos classicos sem o pipeline do leito:

pasta	conteudo
tutorial/cavity-icoFoam/	cavidade com tampa arrastada — icoFoam (benchmark da literatura; ex.: ghia et al. 1982)
tutorial/channel-simpleFoam/	canal 2d laminar estacionario — simpleFoam
tutorial/sphere-snappyHexMesh/	blockMesh + snappyHexMesh com searchableSphere (sem stl)

instrucoes completas: tutorial/README.md (wsl/linux, source do openfoam, ./Allrun / ./Allmesh).

6. wizard terminal cli e interface web

• terminal: na raiz do repo, python bed_wizard.py (ou python dsl/bed_wizard.py). recomendado: pip install -r dsl/requirements-terminal.txt.
• browser: no wizard web, modo wizard terminal cli pede ao backend para tentar abrir uma janela de terminal ou mostra os comandos para copiar (GET /api/wizard/cli-instructions, POST /api/wizard/launch-cli-terminal).

tecnologias utilizadas

componente	tecnologia	versao	uso
dsl	antlr	4.13.1	parser e compilador
geometria	blender	4.0+	geracao 3d e fisica
cfd	openfoam	11	simulacao fluidos
visualizacao	paraview	5.11+	pos-processamento
linguagem	python	3.8+	automacao e scripts
ambiente	wsl2 + ubuntu	22.04	execucao openfoam no windows

documentacao

guias principais

• docs/tcc2/ - escopo tcc2, perfis blender/python, template, registo de alterações
• scripts/automation/README.md - instalacao e configuracao
• docs/UML_COMPLETO.md - arquitetura e diagramas
• docs/OPENFOAM_WINDOWS_GUIA.md - guia openfoam
• docs/GUIA_EXECUCAO_RAPIDO.md - guia de execucao rapida frontend + backend
• dsl/documentacao.html - documentacao web interativa
• docs/CFD_RESULTS_PIPELINE.md - fluxo de resultados cfd (openfoam → banco → dashboard)

guias especificos

• dsl/README_BLENDER_MODE.md - modo blender do wizard
• dsl/README_SISTEMA_AJUDA.md - sistema de ajuda
• tutorial/README.md - casos cavity, simplefoam e snappyhexmesh versionados
• scripts/openfoam_scripts/GUIA_SIMULACAO_MANUAL.md - simulacao manual
• scripts/openfoam_scripts/README.md - scripts openfoam

uso basico

1. criar um leito com wizard interativo

recomendado instalar a interface rica do terminal (tabelas, cores, barra tipo navegador):

pip install -r dsl/requirements-terminal.txt

# na raiz do projeto (recomendado)
python bed_wizard.py

# ou, equivalente:
python dsl/bed_wizard.py

# ou a partir da pasta dsl:
cd dsl
python bed_wizard.py

opcoes:

1. modo interativo - responder questoes
2. modo edicao - editar arquivo .bed
3. modo blender - gerar apenas 3d
4. modo blender interativo - gerar e abrir blender
5. documentacao - abrir docs html

2. gerar modelo 3d

o wizard ja gera automaticamente no modo blender. ou manualmente:

cd scripts/standalone_scripts
python executar_leito_headless.py

3. executar simulacao cfd

# configurar caso
python scripts/openfoam_scripts/setup_openfoam_case.py \
  dsl/leito_interativo.bed.json \
  generated/3d/output/leito_interativo.blend \
  --output-dir generated/cfd

# executar no wsl
wsl
cd /mnt/c/Users/[SEU_USUARIO]/Downloads/CFD-PIPELINE-TCC-1/generated/cfd/leito_interativo
source /opt/openfoam11/etc/bashrc
./Allrun

# visualizar
paraview caso.foam

estrutura do projeto

CFD-PIPELINE-TCC-1/
├── .config/                         # arquivos de configuracao (config.ini, env.example)
├── bed_wizard.py                    # atalho na raiz -> dsl/bed_wizard.py (wizard terminal)
├── tutorial/                        # casos openfoam minimos versionados (cavity, simplefoam, snappy)
├── docker/                          # docker-compose e dockerfiles
├── dsl/                              # domain specific language
│   ├── grammar/
│   │   └── Bed.g4                   # gramatica antlr
│   ├── compiler/
│   │   └── bed_compiler_antlr_standalone.py
│   ├── generated/                   # parser gerado pelo antlr
│   ├── bed_wizard.py                # interface principal
│   └── documentacao.html            # docs web
│
├── scripts/
│   ├── automation/                  # scripts de instalacao e setup
│   │   ├── setup_complete.py        # setup completo
│   │   ├── install_openfoam.py      # instalador openfoam
│   │   ├── install_antlr.py         # instalador antlr
│   │   └── README.md                # guia instalacao
│   ├── blender_scripts/
│   │   └── leito_extracao.py        # geracao 3d
│   ├── openfoam_scripts/
│   │   └── setup_openfoam_case.py   # configuracao cfd
│   ├── standalone_scripts/
│   │   └── executar_leito_headless.py
│   └── tests/                       # testes automatizados
│       ├── e2e/                     # testes end-to-end do pipeline
│       └── smoke/                   # smoke tests basicos (bed + pipeline reduzido)
│
├── generated/                       # artefatos gerados pelo pipeline
│   ├── 3d/
│   │   ├── blender/                 # arquivos .blend fonte
│   │   ├── exports/                 # glb/gltf/obj/stl exportados
│   │   └── output/                  # modelos 3d finais por execucao
│   ├── cfd/                         # casos openfoam (malha, 0/, system/, constant/)
│   ├── configs/                     # arquivos .bed e .bed.json normalizados
│   └── batch/                       # resultados de execucoes em lote
│
├── docs/                             # documentacao
│   └── GUIA_EXECUCAO_RAPIDO.md      # guia de execucao rapida
│
└── README.md                         # este arquivo

categorias de pastas

• codigo-fonte principal

  • backend/ - api fastapi, servicos, modelos, integracoes (openfoam, blender, dsl)
  • frontend/ - aplicacao web (react/vite)
  • dsl/ - gramatica, compilador e wizard (Bed.g4, bed_wizard.py, compiler/)
  • scripts/ - scripts de automacao, openfoam, blender e testes (automation/, openfoam_scripts/, blender_scripts/, standalone_scripts/, tests/)
  • docs/, .github/, .config/ - documentacao, templates e configuracoes

• codigo gerado mas versionado

  • dsl/generated/ - arquivos python gerados pelo antlr a partir de Bed.g4 (lexer/parser/listener)

• dados gerados em runtime (artefatos do pipeline)

  • generated/3d/ - arquivos .blend, exports (.glb, .gltf, .obj, .stl) e modelos finais por execucao
  • generated/cfd/ - casos openfoam (malha, 0/, system/, constant/, resultados)
  • generated/configs/ - arquivos .bed e .bed.json normalizados
  • generated/batch/ - execucoes em lote
  • diretorios de saida de testes em scripts/tests/e2e/** (outputs/, results/, logs/)

• artefatos temporarios / caches

  • **/__pycache__/, **/*.pyc
  • .pytest_cache/, coverage/, htmlcov/
  • frontend/node_modules/ e caches do vite (frontend/node_modules/.vite/)

estes artefatos podem ser regenerados (ou sao apenas cache) e nao precisam ser versionados.

limpeza segura do workspace

para evitar quebrar o pipeline, use as regras abaixo ao limpar o projeto:

• nao remover automaticamente

  • backend/**, frontend/**, dsl/**, scripts/**, docs/**, .github/**, .config/**
  • arquivos de configuracao locais (config/config.ini, backend/.env, etc.) - sempre fazer backup antes de qualquer limpeza agressiva

• seguro remover sempre (regeravel)

  • caches python: **/__pycache__/, **/*.pyc, .pytest_cache/
  • relatorios de cobertura: coverage/, htmlcov/
  • dependencias do frontend: frontend/node_modules/ (reinstalar com npm install)
  • caches vite: frontend/node_modules/.vite/
  • saidas e logs de testes e2e em scripts/tests/e2e/**/outputs, logs, results

• remover apenas se voce quiser refazer simulacoes / modelos

  • qualquer coisa em generated/**:
    • apagar generated/3d/** remove modelos 3d ja gerados
    • apagar generated/cfd/** remove casos e resultados openfoam
    • apagar generated/configs/** remove .bed.json normalizados (podem ser recriados a partir dos .bed)

antes de automatizar qualquer limpeza (por exemplo com scripts), sempre valide se o caminho alvo entra em uma destas categorias e nunca inclua pastas de codigo-fonte por engano.

scripts de automacao

instalacao completa

# instala tudo (python, java, antlr, blender, openfoam)
python scripts/automation/setup_complete.py

instalacao por componente

# apenas antlr + java
python scripts/automation/install_antlr.py

# apenas blender
python scripts/automation/install_blender.py

# apenas openfoam (windows)
python scripts/automation/install_openfoam.py

mais detalhes: scripts/automation/README.md

ferramentas auxiliares (dev tools)

• visualizacao de cilindro de teste em opengl

  • scripts: tools/vis_cilindro/modelo_cilindro.py e tools/vis_cilindro/visualizador.py
  • wrapper no windows: executar_modelo_e_visualizar.bat
  • saidas em: generated/3d/cilindro_teste/

• limpeza de workspace

  • script: tools/clean_workspace.py
  • comportamento:
    • remove caches (__pycache__, .pytest_cache, coverage, htmlcov, frontend/node_modules, logs, saidas de testes e2e)
    • opcionalmente, pode apagar toda a pasta generated/ (somente apos confirmacao explicita no terminal)

exemplos

exemplo 1: leito cilindrico com 100 particulas

python dsl/bed_wizard.py
# escolher modo blender
# diametro: 0.05m
# altura: 0.1m
# particulas: 100
# diametro particula: 0.005m

resultado: generated/3d/output/leito_blender.blend

exemplo 2: simulacao cfd completa

# 1. criar leito
python dsl/bed_wizard.py  # modo interativo

# 2. gerar modelo
# (ja gerado automaticamente)

# 3. configurar cfd
python scripts/openfoam_scripts/setup_openfoam_case.py \
  dsl/leito_interativo.bed.json \
  generated/3d/output/leito_interativo.blend \
  --output-dir generated/cfd \
  --run

# 4. visualizar
# (automatico ao final da simulacao)

testes

testar compilador dsl

cd dsl
python compiler/bed_compiler_antlr_standalone.py examples/leito.bed

testar geracao 3d

python scripts/standalone_scripts/executar_leito_headless.py

testar setup openfoam

python scripts/openfoam_scripts/setup_openfoam_case.py --help

autor

bengo501

• github: @bengo501