Encontro 4 — Reprodutibilidade e o DisSModel¶
Modelagem Dinâmica Espacial · LambdaGeo/UFMA
Sem Python instalado? O selo acima abre este notebook no Google Colab, no navegador. Lá, use Arquivo → Salvar uma cópia no Drive antes de mudar qualquer coisa: sem a cópia, o que você escrever se perde ao fechar a página.
Neste notebook você não precisa escrever código: rode as células na ordem (Shift+Enter), leia as saídas e responda às perguntas marcadas com ✏️. Em alguns lugares você vai trocar um número e rodar de novo.
Ao final, você deve saber responder:
- O que significa dizer que um resultado é reprodutível?
- Quais informações de uma execução precisam ser guardadas para outra pessoa repeti-la?
- Por que dois arquivos com o mesmo conteúdo podem ter "impressões digitais" diferentes?
- Como o DisSModel registra essas informações sem que você precise lembrar delas?
- Por que os critérios de aceitação se escrevem antes de rodar?
As notas de aula deste encontro reúnem o método de conferência usado em toda a disciplina.
0. Preparação¶
No Colab, a célula abaixo instala o DisSModel e o pacote de autômatos celulares (cerca de 1 minuto). No laboratório o ambiente já está instalado e ela não instala nada.
import sys
if "google.colab" in sys.modules:
%pip install -q "dissmodel==0.6.6" "dissmodel-ca @ git+https://github.com/DisSModel/dissmodel-ca.git@v0.2.0"
import hashlib, json, sqlite3, glob, os
import geopandas as gpd
import warnings
import dissmodel, dissmodel_ca
# esconde um aviso do pyogrio que não afeta o resultado
warnings.filterwarnings("ignore", message=".*non conformant file extension")
os.environ["PYTHONWARNINGS"] = "ignore::RuntimeWarning"
print("dissmodel", dissmodel.__version__)
dissmodel 0.6.6
1. Impressão digital de um arquivo (hash)¶
Um hash (aqui, SHA-256) é um código calculado a partir de todos os bytes de um arquivo. Arquivos iguais têm o mesmo hash; se um único byte muda, o hash muda por completo.
Vamos criar uma "floresta" de 30 × 30 células e calcular o hash do arquivo.
from dissmodel.geo import vector_grid
from dissmodel.io import load_dataset, save_dataset
floresta = vector_grid(dimension=(30, 30), resolution=100, attrs={"state": 0}, crs="EPSG:31983")
save_dataset(floresta, "floresta.gpkg")
_, hash_antes = load_dataset("floresta.gpkg")
print("hash da floresta:", hash_antes[:16], "...")
hash da floresta: 75b9ff73a82cf24a ...
Agora mudamos uma única célula de uma cópia e comparamos.
copia = floresta.copy()
copia.loc[0, "state"] = 1 # uma célula entre 900
save_dataset(copia, "floresta_copia.gpkg")
_, hash_copia = load_dataset("floresta_copia.gpkg")
print("original:", hash_antes[:16], "...")
print("cópia :", hash_copia[:16], "...")
print("mesmo arquivo?", hash_antes == hash_copia)
original: 75b9ff73a82cf24a ... cópia : b01ccf99fff9ae91 ... mesmo arquivo? False
✏️ Pergunta 1. Se um colega diz "usei o mesmo arquivo floresta.gpkg que você", o que você pediria para ter certeza?
2. Um modelo de incêndio, escrito como executor¶
No DisSModel, um modelo que vai gerar resultado para um trabalho é escrito como um executor: uma classe com três passos separados.
| Passo | O que faz | O que registra |
|---|---|---|
load |
lê os dados de entrada | o hash da entrada |
run |
roda a simulação (sem ler nem gravar arquivos) | as métricas |
save |
grava o resultado | o hash da saída |
O modelo é o FireModel do pacote dissmodel-ca (o mesmo Fire do TerraME): cada célula é floresta ou vazia, o fogo começa em algumas células e se espalha para a floresta vizinha. A célula abaixo só grava o executor num arquivo fogo.py; não precisa entender cada linha.
%%writefile fogo.py
from dissmodel.executor import ModelExecutor
from dissmodel.io import load_dataset, save_dataset
class FogoExecutor(ModelExecutor):
name = "fogo"
def load(self, record):
gdf, checksum = load_dataset(record.source.uri)
record.source.checksum = checksum # hash da entrada
return gdf
def run(self, data, record):
from dissmodel.core import Environment
from dissmodel_ca.models import FireModel, FireState
p = record.parameters # vêm do model.toml
env = Environment(start_time=0, end_time=p["end_time"])
modelo = FireModel(gdf=data,
initial_fire_density=p["initial_fire_density"],
seed=p["seed"])
modelo.initialize()
env.run()
record.metrics["celulas_queimadas"] = int((data["state"] == FireState.BURNED).sum())
return data
def save(self, result, record):
record.output_sha256 = save_dataset(result, record.output_path) # hash da saída
record.status = "completed"
return record
if __name__ == "__main__":
from dissmodel.executor.cli import run_cli
run_cli(FogoExecutor)
Writing fogo.py
Os parâmetros não ficam no código. Ficam num arquivo de configuração, model.toml, que você pode abrir e editar como texto.
%%writefile model.toml
[model]
name = "fogo"
[model.parameters]
initial_fire_density = 0.005 # fração de células que começam queimando
end_time = 8 # número de passos
seed = 7 # semente do sorteio inicial
Writing model.toml
Antes de rodar, os critérios. Escrevemos agora, antes de ver qualquer resultado, o que uma rodada precisa cumprir para ser aceita. No projeto, este arquivo entra no git antes da rodada final, e o commit prova quando foi escrito (as notas de aula, seção 4, explicam por quê).
%%writefile aceitacao.toml
# Critérios escritos ANTES de rodar o modelo.
[entrada]
mesma_entrada = true # todas as rodadas leram o mesmo arquivo (mesmo hash)
[repeticao]
mesma_semente_mesmos_valores = true # mesma semente -> mesmo hash dos valores
[resultado]
min_celulas_queimadas = 100 # o fogo precisa passar das células onde começou
Writing aceitacao.toml
3. Rodar duas vezes¶
Rodamos o mesmo modelo, com a mesma entrada e os mesmos parâmetros, duas vezes. A linha começa com ! porque é um comando do terminal, o mesmo que você usaria fora do notebook.
!python fogo.py run --input floresta.gpkg --output saida/fogo.gpkg
▶ Validating... ▶ Loading... ▶ Running... ▶ Saving...
Running from 0 to 8 (duration: 8)
✅ Completed
output: saida/fogo_f566917e.gpkg
record: saida/fogo_f566917e.record.json
artifacts:
- output: d645e26b30af99ab...
- profiling: 6a47be274a1b60d8...
status: completed
⏱️ Times: val=0.00s | load=0.50s | run=2.96s | save=0.05s | TOTAL=3.51s
Saved profiling artifact → saida/profiling_f566917e.md
!python fogo.py run --input floresta.gpkg --output saida/fogo.gpkg
▶ Validating... ▶ Loading... ▶ Running... ▶ Saving...
Running from 0 to 8 (duration: 8)
✅ Completed
output: saida/fogo_044f4428.gpkg
record: saida/fogo_044f4428.record.json
artifacts:
- output: 486e0b61a54d0bb6...
- profiling: c1bafc052a644336...
status: completed
⏱️ Times: val=0.00s | load=0.33s | run=2.76s | save=0.04s | TOTAL=3.13s
Saved profiling artifact → saida/profiling_044f4428.md
Cada execução ganhou um identificador (as 8 letras no nome do arquivo) e deixou, ao lado da saída, um registro .record.json. Vamos comparar os hashes das duas saídas.
def registros(pasta):
out = []
for f in sorted(glob.glob(f"{pasta}/*.record.json"), key=os.path.getmtime):
r = json.load(open(f))
out.append(r)
print(r["experiment_id"][:8], " seed =", r["parameters"]["seed"],
" hash da saída:", r["artifacts"]["output"][:16], "...")
return out
rodadas = registros("saida")
f566917e seed = 7 hash da saída: d645e26b30af99ab ... 044f4428 seed = 7 hash da saída: 486e0b61a54d0bb6 ...
✏️ Pergunta 2. Os dois hashes são iguais? O modelo é aleatório (o fogo começa em células sorteadas). A diferença vem do sorteio?
Antes de responder, vamos olhar o conteúdo das duas saídas, e não só o arquivo.
4. Investigando: o arquivo mudou, os valores não¶
Calculamos agora o hash dos valores da coluna state (o estado de cada célula), lidos de dentro de cada arquivo.
def hash_dos_valores(caminho):
g = gpd.read_file(caminho)
return hashlib.sha256(g["state"].to_numpy().tobytes()).hexdigest()
for r in rodadas:
print(r["experiment_id"][:8], " valores:", hash_dos_valores(r["output_path"])[:16], "...")
f566917e valores: 3a944c45605079c3 ... 044f4428 valores: 3a944c45605079c3 ...
Os valores são idênticos. Então o que mudou no arquivo? O GeoPackage guarda, dentro dele, a data e a hora em que foi gravado:
for r in rodadas:
con = sqlite3.connect(r["output_path"])
print(r["experiment_id"][:8], con.execute("select last_change from gpkg_contents").fetchone()[0])
con.close()
f566917e 2026-11-02T15:53:57.150Z 044f4428 2026-11-02T15:54:01.384Z
Esse é um caso real, e comum: o hash do arquivo responde "é este arquivo?", não "é o mesmo resultado?". Há duas saídas:
- comparar o hash dos valores (o que fizemos acima);
- fixar o que varia sem motivo. O GDAL, que grava o arquivo, aceita uma data fixa pela variável
OGR_CURRENT_DATE.
Vamos rodar duas vezes de novo, com a data fixada.
os.environ["OGR_CURRENT_DATE"] = "2026-01-01T00:00:00Z" # vale para os comandos abaixo
!python fogo.py run --input floresta.gpkg --output saida_fixa/fogo.gpkg
!python fogo.py run --input floresta.gpkg --output saida_fixa/fogo.gpkg
▶ Validating... ▶ Loading... ▶ Running... ▶ Saving...
Running from 0 to 8 (duration: 8)
✅ Completed
output: saida_fixa/fogo_6266a672.gpkg
record: saida_fixa/fogo_6266a672.record.json
artifacts:
- output: b11afdd025a07858...
- profiling: 201dba61ff3e4df8...
status: completed
⏱️ Times: val=0.00s | load=0.30s | run=2.19s | save=0.04s | TOTAL=2.53s
Saved profiling artifact → saida_fixa/profiling_6266a672.md
▶ Validating... ▶ Loading... ▶ Running... ▶ Saving...
Running from 0 to 8 (duration: 8)
✅ Completed
output: saida_fixa/fogo_e9c48cab.gpkg
record: saida_fixa/fogo_e9c48cab.record.json
artifacts:
- output: b11afdd025a07858...
- profiling: 48c9dfc768f7877e...
status: completed
⏱️ Times: val=0.00s | load=0.29s | run=2.28s | save=0.03s | TOTAL=2.60s
Saved profiling artifact → saida_fixa/profiling_e9c48cab.md
fixas = registros("saida_fixa")
6266a672 seed = 7 hash da saída: b11afdd025a07858 ... e9c48cab seed = 7 hash da saída: b11afdd025a07858 ...
5. A semente: aleatoriedade sob controle¶
Agora mudamos de propósito a semente. Troque o 8 por outro número, se quiser. O --param sobrescreve o valor do model.toml só nesta execução, e o registro guarda o valor usado.
!python fogo.py run --input floresta.gpkg --output saida_fixa/fogo.gpkg --param seed=8
▶ Validating... ▶ Loading... ▶ Running... ▶ Saving...
Running from 0 to 8 (duration: 8)
✅ Completed
output: saida_fixa/fogo_4862cfec.gpkg
record: saida_fixa/fogo_4862cfec.record.json
artifacts:
- output: f162092b481cf705...
- profiling: ee3a9b5e8fcbf19f...
status: completed
⏱️ Times: val=0.00s | load=0.32s | run=2.70s | save=0.02s | TOTAL=3.05s
Saved profiling artifact → saida_fixa/profiling_4862cfec.md
fixas = registros("saida_fixa")
print()
for r in fixas:
print(r["experiment_id"][:8], " seed =", r["parameters"]["seed"],
" queimadas:", r["metrics"]["celulas_queimadas"])
6266a672 seed = 7 hash da saída: b11afdd025a07858 ... e9c48cab seed = 7 hash da saída: b11afdd025a07858 ... 4862cfec seed = 8 hash da saída: f162092b481cf705 ... 6266a672 seed = 7 queimadas: 575 e9c48cab seed = 7 queimadas: 575 4862cfec seed = 8 queimadas: 443
Vamos ver as três saídas lado a lado.
import matplotlib.pyplot as plt
from matplotlib.colors import ListedColormap
cores = ListedColormap(["#2e7d32", "#e65100", "#424242", "#e0e0e0"]) # floresta, queimando, queimada, vazia
fig, eixos = plt.subplots(1, len(fixas), figsize=(4 * len(fixas), 4))
for ax, r in zip(eixos, fixas):
gpd.read_file(r["output_path"]).plot(column="state", cmap=cores, vmin=0, vmax=3, ax=ax)
ax.set_title(f'seed={r["parameters"]["seed"]} ({r["experiment_id"][:8]})')
ax.set_axis_off()
plt.tight_layout()
✏️ Pergunta 3. Um modelo com sorteio é reprodutível? Em que condição?
Um modelo estocástico é reprodutível se a semente for registrada. Para tirar conclusões dele, porém, uma rodada não basta: é preciso várias sementes e olhar a distribuição dos resultados (voltamos a isso no encontro 12).
6. O que o registro guarda¶
Abra o registro de uma execução. Você não escreveu nada disso: o DisSModel preencheu sozinho.
r = fixas[-1]
campos = ["experiment_id", "created_at", "model_name", "model_commit", "code_version",
"source", "parameters", "output_path", "artifacts", "metrics", "status"]
print(json.dumps({k: r[k] for k in campos}, indent=2, ensure_ascii=False))
{
"experiment_id": "4862cfec23b2469087a95160e4a1a43a",
"created_at": "2026-11-02T15:54:09.837610Z",
"model_name": "fogo",
"model_commit": "local-cli",
"code_version": "0.6.6",
"source": {
"type": "local",
"uri": "floresta.gpkg",
"collection": "",
"version": "",
"checksum": "75b9ff73a82cf24a5c965167afd47710edadb88f250410a7f7b31377ddb2b533"
},
"parameters": {
"initial_fire_density": 0.005,
"end_time": 8,
"seed": 8
},
"output_path": "saida_fixa/fogo_4862cfec.gpkg",
"artifacts": {
"output": "f162092b481cf70546280591c32a3776e766cd576ba896ad4993b67be3f04507",
"profiling": "ee3a9b5e8fcbf19f7916c76ff44c1b75ae610cd717a535926751ab63c34f58bd"
},
"metrics": {
"celulas_queimadas": 443,
"time_validate_sec": 0.0,
"time_load_sec": 0.322,
"time_run_sec": 2.704,
"time_save_sec": 0.019,
"time_total_sec": 3.046
},
"status": "completed"
}
| Campo | Pergunta que responde |
|---|---|
experiment_id, created_at |
Qual execução é esta, e quando rodou? |
model_name, model_commit, code_version |
Qual modelo e qual versão do código? |
source (com checksum) |
Qual arquivo de entrada, comprovado pelo hash? |
parameters |
Com quais parâmetros, incluindo a semente? |
artifacts |
Qual o hash de cada arquivo gerado? |
metrics |
O que foi medido, e quanto tempo levou cada passo? |
✏️ Pergunta 4. O campo model_commit diz local-cli. Por quê? O que mudaria se o executor viesse de um pacote instalado com versão (por exemplo, disslucc==0.5.0)?
7. Quando "igual" não é a pergunta certa¶
Às vezes os valores não são idênticos, e mesmo assim o resultado está certo. O computador arredonda cada conta, e a ordem das contas muda o último dígito:
a = (0.1 + 0.2) + 0.3
b = 0.1 + (0.2 + 0.3)
print(a, b, "iguais?", a == b, " diferença:", abs(a - b))
0.6000000000000001 0.6 iguais? False diferença: 1.1102230246251565e-16
Por isso há dois tipos de verificação, e o trabalho deve dizer qual usou:
| Pergunta | Verificação |
|---|---|
| É o arquivo arquivado? | hash do arquivo |
| São os mesmos dados, em outra máquina? | hash dos valores |
| É o mesmo resultado, calculado de novo? | tolerância (maior diferença ≤ ε, com ε justificado) |
O próprio TerraME, rodado oito vezes na mesma máquina, gravou o primeiro lab do LuccME com hashes diferentes, todos a menos de 10⁻¹² um do outro.
8. Registrar o ambiente¶
O mesmo código pode dar outro resultado com outras versões das bibliotecas. A forma mais simples de registrar o ambiente é a lista de tudo que está instalado:
!pip freeze > requirements.lock
!grep -i -E "^(dissmodel|geopandas|numpy|pyogrio)" requirements.lock
import platform, sys
print("Python", sys.version.split()[0], "|", platform.platform())
dissmodel==0.6.6 dissmodel-abm @ git+https://github.com/DisSModel/dissmodel-abm.git@653580d5f735bcb412bde989991868d2ff80f7ec dissmodel-ca @ git+https://github.com/DisSModel/dissmodel-ca.git@23684708ab51e6af53f39e797fc54041de7aaf93 dissmodel-sysdyn @ git+https://github.com/DisSModel/dissmodel-sysdyn.git@cd79c7451fb9f3f595870afe4bb702a294911fdf geopandas==1.2.0 numpy==2.5.3 pyogrio==0.13.0
Python 3.13.18 | Linux-6.18.44-fc-v185-x86_64-with-glibc2.39
9. Conferir os critérios sem rodar o modelo¶
Os registros das rodadas guardam tudo o que os critérios pedem. A função abaixo lê o aceitacao.toml e os registros, e diz se cada critério passou. Ela não roda o modelo: leva menos de um segundo. É o que se chama de nível 0 de conferência, auditar o registro.
import tomllib
from collections import defaultdict
def conferir(registros, arquivo="aceitacao.toml"):
crit = tomllib.load(open(arquivo, "rb"))
resultado = {}
if crit["entrada"]["mesma_entrada"]:
resultado["mesma entrada"] = len({r["source"]["checksum"] for r in registros}) == 1
if crit["repeticao"]["mesma_semente_mesmos_valores"]:
por_semente = defaultdict(set)
for r in registros:
por_semente[r["parameters"]["seed"]].add(hash_dos_valores(r["output_path"]))
resultado["mesma semente, mesmos valores"] = all(len(v) == 1 for v in por_semente.values())
minimo = crit["resultado"]["min_celulas_queimadas"]
resultado[f"queimadas >= {minimo}"] = all(r["metrics"]["celulas_queimadas"] >= minimo for r in registros)
for nome, ok in resultado.items():
print(f"{'OK ' if ok else 'FALHOU '} {nome}")
return all(resultado.values())
conferir(fixas)
OK mesma entrada OK mesma semente, mesmos valores OK queimadas >= 100
True
✏️ Pergunta 5. A rodada com semente 8 queimou 443 células, e a de semente 7, 575. Se, depois de ver esses números, você mudasse o mínimo para 500, o que aconteceria com a rodada de semente 8? Por que isso não vale como critério?
Repetir um experimento inteiro pode levar horas. Por isso um projeto bem montado oferece caminhos mais curtos para quem confere, cada um mostrando uma parte da evidência:
| Nível | O que faz | O que mostra |
|---|---|---|
| 0. Auditar o registro | confere os critérios a partir dos registros (o que fizemos acima) | que o resultado relatado cumpre o que foi declarado |
| 1. Teste rápido | roda o modelo num caso pequeno, duas vezes | que o código roda e repete o resultado |
| 2. Dados reais | roda o caso de verdade em outra máquina | que outra pessoa chega ao mesmo resultado |
| 3. Rodada completa | tudo, com todos os critérios | o experimento inteiro |
O repositório open-lucc-workflow faz isso para um modelo do Brasil inteiro: o nível 0 leva segundos, o nível 1 cerca de 15 s e a rodada completa 6 horas e meia. Lá também está o caso do Mac em que os valores foram iguais e os hashes dos arquivos não (seção 3 das notas).
10. Para levar ao projeto¶
Checklist de reprodutibilidade do projeto da disciplina:
- Parâmetros num arquivo de configuração, não no código.
- Semente registrada (e várias sementes, se o modelo for estocástico).
- Hash dos dados de entrada.
- Registro de cada execução que vai para o relatório, e da plataforma (
requirements.lock, versão do Python, sistema). - Critérios no
aceitacao.toml, no git antes da rodada final; os que falharem são relatados, não removidos. - Níveis 0 e 1 de conferência, com um comando cada no README.
- Verificação declarada: hash do arquivo, hash dos valores ou tolerância.
Exercícios (entregar até o próximo encontro)¶
- Rode o modelo com
initial_fire_densityigual a 0.002, 0.005 e 0.01, com a mesma semente. Faça uma tabela com o identificador, a densidade e as células queimadas, tirada dos registros. - Peça a um colega o
floresta.gpkge omodel.tomldele e rode na sua máquina. Os valores batem? E os hashes dos arquivos? - Em duas ou três frases: que informação da sua dissertação você hoje não conseguiria recuperar daqui a um ano?
- Leia as notas de aula e escreva um
aceitacao.tomlcom dois ou três critérios para o seu projeto, mesmo que provisórios.