237 lines
8.6 KiB
Markdown
237 lines
8.6 KiB
Markdown
# Arara OAMRP
|
||
|
||
Este repositório organiza os arquivos, processamentos e protótipos do projeto Arara OAMRP do Esquadrão Arara, em Manaus.
|
||
|
||
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.
|
||
|
||
## O que é um repositório
|
||
|
||
Um repositório é uma pasta controlada pelo Git. Ele guarda os arquivos do projeto e também o histórico de alterações.
|
||
|
||
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.
|
||
|
||
Na prática:
|
||
|
||
- 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.
|
||
|
||
## Estrutura do projeto
|
||
|
||
```text
|
||
arara_oarmp/
|
||
db/
|
||
raw/
|
||
pre_process/
|
||
processed/
|
||
software/
|
||
docs/
|
||
CONTEXTO.md
|
||
LOG.md
|
||
README.md
|
||
```
|
||
|
||
- `db/raw/`: documentos originais. Não editar esses arquivos diretamente.
|
||
- `db/pre_process/`: scripts e arquivos intermediários gerados a partir dos documentos originais.
|
||
- `db/processed/`: arquivos finais, limpos e prontos para análise ou uso.
|
||
- `software/`: modelos e protótipos executáveis, incluindo o modelo MIP inicial de roteamento.
|
||
- `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.
|
||
|
||
## Colaboradores
|
||
|
||
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 `db/raw/` para consultar documentos originais.
|
||
4. Use `db/pre_process/` para consultar arquivos intermediários.
|
||
5. Use `db/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
|
||
```
|
||
|
||
Se o comando não funcionar, o Git ainda não está instalado.
|
||
|
||
Depois, clone o repositório:
|
||
|
||
```powershell
|
||
git clone https://git.ppgao.ita.br/vitorcesavc/arara_oarmp.git
|
||
cd arara_oarmp
|
||
```
|
||
|
||
Antes de começar a trabalhar, atualize sua cópia:
|
||
|
||
```powershell
|
||
git pull
|
||
```
|
||
|
||
Depois de alterar arquivos, veja o que mudou:
|
||
|
||
```powershell
|
||
git status
|
||
```
|
||
|
||
Adicione os arquivos modificados:
|
||
|
||
```powershell
|
||
git add .
|
||
```
|
||
|
||
Crie um commit com uma mensagem curta:
|
||
|
||
```powershell
|
||
git commit -m "Descreva a alteração feita"
|
||
```
|
||
|
||
Envie para o Gitea:
|
||
|
||
```powershell
|
||
git push
|
||
```
|
||
|
||
## Fluxo recomendado de trabalho
|
||
|
||
1. Rode `git pull` antes de começar.
|
||
2. Coloque documentos novos em `db/raw/`.
|
||
3. Gere arquivos intermediários em `db/pre_process/`.
|
||
4. Coloque resultados finais em `db/processed/`.
|
||
5. Atualize o `LOG.md`.
|
||
6. Faça commit.
|
||
7. Rode `git push`.
|
||
|
||
## Cuidados importantes
|
||
|
||
- Não editar arquivos originais dentro de `db/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.
|
||
|
||
## Estado atual (v0.10)
|
||
|
||
O modelo ativo é `software/oamrp_v3.py`, que implementa o OAMRP sobre uma rede espaço-tempo com arcos de ferry, múltiplos tipos de inspeção e Set Partitioning para cobertura de missões.
|
||
|
||
**Última rodada validada (2026-06-16, commit `a34ed6b`):**
|
||
- 20/20 missões sintéticas cobertas, solver CBC Optimal em < 15 s
|
||
- Cenário com INSP 2A (4 dias em solo) visível no Gantt da matrícula 2803
|
||
- Set Partitioning: toda missão coberta por exatamente 1 aeronave
|
||
|
||
### Formulação de cobertura
|
||
|
||
O modelo usa **Set Partitioning** (`z[m] = 1` para toda missão `m`): cada missão deve ser atribuída a exatamente uma aeronave. Versões anteriores usavam Set Covering (`z[m] ≤ 1`), que permitia missões descobertas. A transição foi documentada em `docs/changelog.md` (v0.10).
|
||
|
||
> **Atenção para contribuidores:** Set Partitioning foi validado apenas para o cenário sintético padrão (20 missões, seed 42, 4 aeronaves, somente 2803 com LRT apertado). Com mais missões ou múltiplas aeronaves com LRT < 5 h simultâneas, o MIP pode ser infeasível ou ultrapassar o time limit. Consulte as limitações detalhadas em `docs/changelog.md`.
|
||
|
||
### Arquivos principais
|
||
|
||
```text
|
||
software/oamrp_v3.py — modelo MIP principal (Fases 1–3 + Set Partitioning)
|
||
software/gerar_ofrag.py — gerador da tabela OFRAG
|
||
software/visualizar_resultado.py — Gantt + mapa + tabela interativa
|
||
db/processed/ofrag.csv — ordens de missão com prioridades 1–5
|
||
db/processed/f0_cenario_insp_grande.json — f0 calibrado para forçar INSP 2A em 2803
|
||
db/processed/resultado_oamrp_v3.csv — resultado da última rodada
|
||
db/processed/planejamento_insp_grande.html — Gantt com inspeção de 4 dias visível
|
||
```
|
||
|
||
### Como rodar
|
||
|
||
Cenário padrão (inspeção grande visível no Gantt):
|
||
|
||
```powershell
|
||
python software/oamrp_v3.py --sintetico --seed 42 --f0 db/processed/f0_cenario_insp_grande.json --time-limit 60
|
||
python software/visualizar_resultado.py --resultado db/processed/resultado_oamrp_v3.csv --saida db/processed/planejamento_insp_grande.html
|
||
```
|
||
|
||
Parâmetros relevantes do modelo:
|
||
|
||
| Parâmetro | Padrão | Descrição |
|
||
|---|---|---|
|
||
| `--sintetico` | — | Usa missões sintéticas cross-base em vez do CSV real |
|
||
| `--n-missoes` | 20 | Número de missões sintéticas |
|
||
| `--seed` | 42 | Semente aleatória (reprodutibilidade) |
|
||
| `--f0` | — | JSON com horas acumuladas iniciais por aeronave/inspeção |
|
||
| `--time-limit` | 300 | Limite de tempo do solver CBC (segundos) |
|
||
| `--aleatorio` | — | Sorteia f0 aleatório entre 10%–90% de F_max |
|
||
|
||
Pré-processamentos disponíveis:
|
||
|
||
```text
|
||
db/raw/relatorio_ciclo_inspecoes_c105_2805_2026-06-15.pdf — ciclo de inspeções C-105/2805
|
||
db/processed/registro_voo_2025.csv — registro de voo 2025 limpo (1420 trechos)
|
||
db/processed/registro_voo_2025_consolidado.csv — consolidado para roteamento
|
||
```
|
||
## Atualizacao - registro de voo 2025
|
||
|
||
A `Planilha 2025.xlsx` foi pre-processada a partir de `db/raw/` sem alterar o arquivo original.
|
||
|
||
Arquivos gerados:
|
||
|
||
```text
|
||
db/pre_process/registro_voo_2025/preprocess_planilha_2025.py
|
||
db/pre_process/registro_voo_2025/registro_voo_2025_limpo.csv
|
||
db/pre_process/registro_voo_2025/registro_voo_2025_limpo.xlsx
|
||
db/pre_process/registro_voo_2025/registro_voo_2025_consolidado.csv
|
||
db/pre_process/registro_voo_2025/missoes_oamrp_2025.csv
|
||
db/pre_process/registro_voo_2025/missoes_oamrp_2025_consolidado.csv
|
||
db/pre_process/registro_voo_2025/resumo_registro_voo_2025.json
|
||
db/pre_process/registro_voo_2025/validacao_registro_voo_2025.md
|
||
db/processed/registro_voo_2025.csv
|
||
db/processed/registro_voo_2025_consolidado.csv
|
||
```
|
||
|
||
O consolidado trata `ROTA` como marcador de transicao, nao como localidade operacional, e remove a linha original 793 da aeronave 2806 dos artefatos processados.
|
||
|
||
## Modelo OAMRP v2
|
||
|
||
O arquivo `software/oamrp_v2.py` executa a primeira rodada do modelo com dados reais consolidados de 2025. Por padrao, ele usa janeiro/2025, as aeronaves `2800`, `2803`, `2809` e `2811`, e grava:
|
||
|
||
```text
|
||
db/processed/resultado_oamrp_jan_2025.csv
|
||
```
|
||
|
||
Para executar:
|
||
|
||
```powershell
|
||
python software/oamrp_v2.py
|
||
```
|
||
|
||
A rodada inicial de janeiro/2025 foi resolvida como otima pelo CBC, com 50 de 61 missoes cumpridas.
|