generosoecgj/aircraftrouting_arara
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add OARMP routing engine, dashboard and documentation

Browse Source 
- Complete routing engine: ingest, optimizer (CG+B&B), maintenance
  monitor, metrics, pipeline, quality checks
- Streamlit dashboard with Input/Output tab structure, editable data
  editors, interactive Folium map with satellite layer and maintenance
  base highlights, FH stacked bar chart with TTM availability
- CSV data files: AERONAVES, CHECKS, AIRPORTS, ESCALA DE VOO
- README, CONTEXTO and CHANGELOG added
- Remove legacy pre_process scripts and raw binary files (PDFs/xlsx)
- Update .gitignore to exclude outputs/, data/, raw/*.pdf, raw/*.xlsx

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Eduardo Carlos
2026-06-17 11:52:34 -03:00
parent 32ad7c9f23
commit 3607965c88
43 changed files with 3419 additions and 1936 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
README.md
View File

@@ -1,158 +1,145 @@
# Arara OARMP
# OARMP — Aircraft Routing & Maintenance Planning
Este repositório organiza os arquivos e processamentos do projeto Arara OARMP do Esquadrão Arara, em Manaus.
Sistema de otimização de roteamento de aeronaves com planejamento integrado de manutenção, desenvolvido para o Curso de Especialização em Administração de Organizações (CEAO 809).
A ideia é construir, em conjunto, uma base confiável para encaixar missões, aeronaves e manutenções. O repositório serve como lugar único para guardar documentos originais, registrar decisões, transformar relatórios em dados utilizáveis e manter um histórico claro do que foi feito por cada colaborador.
## Visão geral
## O que é um repositório
O OARMP resolve o problema de atribuição de aeronaves a fragmentos de voo (OFRAGs) respeitando as restrições de **Time to Maintenance (TTM)** de cada aeronave, minimizando as horas perdidas de TTM ao longo do planejamento.
Um repositório é uma pasta controlada pelo Git. Ele guarda os arquivos do projeto e também o histórico de alterações.
### Formulação matemática
O Gitea do PPGAO/ITA é o site onde esse repositório fica hospedado de forma privada, para que os colaboradores possam acessar, baixar, atualizar e enviar contribuições.
**Set Partitioning com Column Generation + Branch & Bound**
Na prática:
```
Minimizar Σ_r c_r · x_r (perda total de TTM)
s.a. Σ_{r: j∈r} x_r = 1 ∀ j ∈ OFRAGs (cada OFRAG coberto exatamente uma vez)
Σ_{r: a(r)=a} x_r ≤ 1 ∀ a ∈ Aeronaves (uma rota por aeronave)
x_r ∈ {0, 1}
```
- o Git mostra o que mudou;
- o Gitea permite compartilhar o projeto;
- os commits são registros das alterações feitas;
- o `LOG.md` explica o motivo e o contexto das mudanças importantes.
O subproblema de precificação (pricing) é resolvido por **programação dinâmica (label-setting DP)** sobre o DAG de OFRAGs ordenados por horário de partida.
## Estrutura do projeto
```text
```
arara_oarmp/
raw/
pre_process/
processed/
docs/
CONTEXTO.md
LOG.md
README.md
├── app/
│ └── dashboard.py # Interface Streamlit (entrada de dados + resultados)
├── raw/ # Dados de entrada (CSV)
│ ├── AERONAVES.csv
│ ├── CHECKS.csv
│ ├── AIRPORTS.csv
│ └── ESCALA DE VOO MODELO 1.csv
├── src/
│ └── routing_engine/
│ ├── config.py # Parâmetros e caminhos
│ ├── ingest.py # Leitura e normalização dos dados
│ ├── inspect_files.py # Detecção automática de colunas (sinônimos)
│ ├── network_generator.py # Grafo de adjacência entre OFRAGs
│ ├── optimizer.py # CG + B&B (PuLP/CBC)
│ ├── maintenance_monitor.py # Validação TTM e eventos de manutenção
│ ├── metrics.py # Tabelas e sumários de saída
│ ├── pipeline.py # Orquestração end-to-end
│ └── quality.py # Verificações de qualidade dos dados
├── scripts/ # Scripts auxiliares de inspeção e execução
├── outputs/ # Resultados gerados pelo pipeline
│ ├── schedules/
│ └── exports/
├── requirements.txt
└── run_pipeline.bat
```
- `raw/`: documentos originais. Não editar esses arquivos diretamente.
- `pre_process/`: scripts e arquivos intermediários gerados a partir dos documentos originais.
- `processed/`: arquivos finais, limpos e prontos para análise ou uso.
- `docs/`: documentação técnica, autoria e histórico de versões.
- `CONTEXTO.md`: regras, combinados e orientações permanentes do projeto.
- `LOG.md`: histórico rastreável das ações feitas no projeto.
- `README.md`: este guia inicial.
## Instalação
## Colaboradores
```bash
# Criar ambiente virtual
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
Usamos tags curtas para identificar quem fez cada alteração relevante:
- `VTO`: Vitor Cesa.
- `GNR`: Generoso.
- `JOM`: João Marcos.
Sempre que alguém fizer uma mudança importante, deve registrar no `LOG.md` com data, hora, tag do autor, ação, arquivos e observações.
## Como usar pelo site do Gitea
Este caminho é bom para quem só quer ver arquivos, baixar documentos ou conferir o histórico.
1. Abra o repositório no Gitea do PPGAO/ITA.
2. Entre nas pastas para ver os arquivos.
3. Use `raw/` para consultar documentos originais.
4. Use `pre_process/` para consultar arquivos intermediários.
5. Use `processed/` para consultar dados finais quando existirem.
6. Abra o `LOG.md` para entender o que já foi feito.
7. Abra o `CONTEXTO.md` para ver os combinados do projeto.
Para baixar um arquivo pelo site:
1. Clique no arquivo.
2. Clique em `Download raw file` ou no botão de download.
3. Salve no computador.
## Documentação
- `docs/about.md`: descrição técnica, fluxo de dados, limitações e oportunidades de melhoria.
- `docs/authors.md`: autoria, colaboradores e regras de contribuição.
- `docs/changelog.md`: histórico resumido de versões significativas.
- `LOG.md`: diário operacional detalhado.
## Como usar no computador
Este caminho é para quem vai mexer nos arquivos e devolver alterações ao Gitea.
Primeiro, instale o Git:
```powershell
git --version
# Instalar dependências
pip install -r requirements.txt
```
Se o comando não funcionar, o Git ainda não está instalado.
### Dependências principais
Depois, clone o repositório:
| Pacote | Uso |
|--------|-----|
| `pulp` | Formulação e resolução do MIP (solver CBC) |
| `pandas` / `numpy` | Manipulação de dados |
| `streamlit` | Dashboard interativo |
| `plotly` | Gráficos (Gantt, barras) |
| `folium` + `streamlit-folium` | Mapa interativo de rotas |
| `airportsdata` | Coordenadas geográficas de aeroportos por ICAO |
| `networkx` | Grafo de adjacência entre OFRAGs |
```powershell
git clone https://git.ppgao.ita.br/vitorcesavc/arara_oarmp.git
cd arara_oarmp
## Execução
### Via dashboard (recomendado)
```bash
streamlit run app/dashboard.py
```
Antes de começar a trabalhar, atualize sua cópia:
### Via script de linha de comando
```powershell
git pull
```bash
python scripts/03_run_optimization_pipeline.py
# ou
run_pipeline.bat
```
Depois de alterar arquivos, veja o que mudou:
## Dados de entrada
```powershell
git status
```
Todos os arquivos ficam em `raw/` com separador `;`:
Adicione os arquivos modificados:
### AERONAVES.csv
| Campo | Descrição |
|-------|-----------|
| MATRICULA | Indicativo da aeronave |
| MODELO | Modelo (ex: C105) |
| FH TOTAIS | Horas de voo totais acumuladas |
```powershell
git add .
```
### CHECKS.csv
| Campo | Descrição |
|-------|-----------|
| CHECKS | Nome do check |
| FH | Threshold cumulativo de FH para o check |
| TEMPO DE EXECUCAO (DIAS) | Duração do check em dias |
| LOCAL DE EXECUCAO | Código ICAO da base de manutenção |
Crie um commit com uma mensagem curta:
### AIRPORTS.csv
| Campo | Descrição |
|-------|-----------|
| AIRPORT_CODE | Código ICAO |
| AIRPORT_NAME | Nome do aeroporto |
| IS_MAINTENANCE_BASE | 1 = base de manutenção |
```powershell
git commit -m "Descreva a alteração feita"
```
### ESCALA DE VOO MODELO 1.csv
Escala de missões com colunas: `DATA`, `ETAPA`, `DEP`, `ARR`, `HORA_DEP`, `HORA_ARR`, `TEMPO_VOO`, `SEGMTO`, `MISSAO`, `OFRAG`.
Formato de data aceito: `DD/MM/AAAA` ou `DD/mon` (ex: `15/jan`).
Envie para o Gitea:
## Dashboard — abas
```powershell
git push
```
### Entrada (📥 Input)
- **Escala de Voo**: tabela editável com adição/remoção de linhas
- **Aeronaves**: frota com FH totais e TAT mínimo
- **Checks**: thresholds e durações de manutenção
- **Bases de Manutenção**: aeroportos habilitados para check
## Fluxo recomendado de trabalho
### Saída (📤 Output)
- **Resumo**: métricas gerais + diagrama de Gantt
- **Escala com Atribuição**: escala original com aeronave atribuída por OFRAG
- **Manutenção e Aeronaves**: eventos de manutenção, gráfico de FH por aeronave (FH iniciais + planejadas antes/após manutenção + TTM disponível)
- **Frota**: utilização percentual do TTM por aeronave
- **Mapa**: rotas por aeronave em mapa interativo (satélite Esri / CartoDB)
1. Rode `git pull` antes de começar.
2. Coloque documentos novos em `raw/`.
3. Gere arquivos intermediários em `pre_process/`.
4. Coloque resultados finais em `processed/`.
5. Atualize o `LOG.md`.
6. Faça commit.
7. Rode `git push`.
## Conceitos-chave
## Cuidados importantes
**OFRAG** — Fragmento de voo: conjunto de etapas que sai e retorna à base de manutenção. Unidade de alocação do problema.
- Não editar arquivos originais dentro de `raw/`.
- Não apagar arquivos de outros colaboradores sem combinar.
- Não subir arquivos temporários do Office, como arquivos começando com `~$`.
- Não colocar senhas, tokens ou informações pessoais desnecessárias no repositório.
- Preferir nomes de arquivo descritivos, com tipo do documento, aeronave, matrícula e data quando possível.
- Registrar no `LOG.md` qualquer decisão que afete os dados.
**TTM (Time to Maintenance)** — Horas de voo disponíveis até o próximo check obrigatório. Cada ciclo de check tem seu próprio TTM.
## Estado atual
**TTM Loss** — Horas de TTM não utilizadas quando a manutenção é realizada antes de esgotar o ciclo (inevitável quando o próximo OFRAG excederia o limite).
Já existe um pré-processamento do relatório de ciclo de inspeções da aeronave C-105 matrícula 2805, com data de relatório `2026-06-15`.
Arquivos principais:
```text
raw/relatorio_ciclo_inspecoes_c105_2805_2026-06-15.pdf
pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/preprocess_pdf.py
pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_texto.txt
pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.json
pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.csv
```
Esse processamento extraiu 18 inspeções e separou campos como inspeção, referência, vencimento, TSO, letra, nível, duração, intervalo por horas de voo, meses contínuos e pousos.
**TAT (Turnaround Time)** — Tempo mínimo entre o pouso de um OFRAG e a decolagem do seguinte na mesma aeronave.