arara_oarmp/README.md

# 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 |

---

## Histórico dos modelos

### v1 — Protótipo inicial (`software/oamrp_v1.py`)

Primeiro protótipo do modelo MIP em PuLP. Estrutura simples de atribuição aeronave-missão sem rede espaço-tempo, sem inspeções e sem ferry. Serviu para validar a configuração do ambiente e a integração com o solver CBC.

- **Formulação:** atribuição direta, variáveis binárias por (aeronave, missão)
- **Restrições:** cobertura básica e continuidade de base
- **Sem:** janelas de tempo, inspeções, ferry, prioridades
- **Status:** protótipo histórico, não usar em produção

---

### v2 — Dados reais de 2025 (`software/oamrp_v2.py`)

Primeira rodada com dados reais do registro de voo de janeiro/2025, pré-processados a partir da planilha original. Introduziu janelas de tempo (decolagem e chegada do CSV), TAT entre missões e prioridade uniforme.

- **Dados de entrada:** `db/processed/registro_voo_2025_consolidado.csv` (1 267 trechos, 1 420 linhas originais)
- **Resultado:** 50 de 61 missões cumpridas em janeiro/2025 (`db/processed/resultado_oamrp_jan_2025.csv`)
- **Limitação identificada:** os dados reais de jan/2025 eram predominantemente voos locais SBMN→SBMN, não exercitando roteamento cross-base nem inspeções

```powershell
python software/oamrp_v2.py
```

---

### v3 — Rede espaço-tempo completa (`software/oamrp_v3.py`) ← **modelo ativo**

Reescrita completa baseada em Al-Thani, Ben Ahmed & Haouari (2016). Introduziu a formulação por rede espaço-tempo com nós No e arcos Arco, inspeções com relógio de horas acumuladas e reset, arcos de ferry entre bases e missões sintéticas cross-base para validação de roteamento.

**Fases implementadas:**

| Fase | Restrições | Descrição |
|---|---|---|
| 1 | C1–C6 | Rede espaço-tempo, cobertura (Set Partitioning), conservação de fluxo, TAT |
| 2 | C7–C11 | Nós de inspeção, relógio H[k,i,n] com reset, downtime, slot único |
| 3 | Ferry | Arcos de ferry entre quaisquer bases (haversine ÷ 430 km/h), consome horas de célula |

**Nomenclatura alinhada com Al-Thani (2016):**

- `F_max` — batente fixo (intervalo máximo legal entre manutenções, ex: 300 h)
- `f0` — horas acumuladas no início do horizonte (estado inicial da aeronave)
- `LRT = F_max − f0` — tempo legal restante (decresce com o voo)
- `H[k, seq, nid]` — acumulado em tempo real, rastreado na rede (equivale a u_j do artigo)

**Missões sintéticas:** como os dados reais de 2025 não exercitavam roteamento, o modelo usa um gerador sintético cross-base (`--sintetico`) com distâncias reais (haversine) e velocidade de cruzeiro do C-105 (430 km/h).

**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 (1 420 trechos)
db/processed/registro_voo_2025_consolidado.csv            — consolidado para roteamento
```