Guia de reprodução. Para navegar o repositório, veja instructions.md; para traduzir
um comando antigo no novo, veja MIGRATION.md.
Aviso de verificação. Este documento foi escrito a partir do estado do disco e dos relatórios da refatoração. Os comandos de grade e de célula única seguem o protocolo que foi testado durante a refatoração (
--dry-rune--print_config), mas os comandos deste arquivo não foram re-executados um a um. Rode sempre--dry-runantes da primeira vez. O que é inferência está marcado como tal.
A pergunta que atravessa o repositório é se inicializar o encoder com FLIM bate as inicializações clássicas. Estes são os pares prontos para lançar, reconstruídos do que já foi treinado (2.587 runs no cache do W&B mais os checkpoints em disco):
| Grupo | COM FLIM | SEM FLIM | runs |
|---|---|---|---|
| LeJEPA SSL | lejepa/init_flim.yaml |
lejepa/init_no_flim.yaml |
545 × 1.252 |
| Destilação | distillation/all_init_flim.yaml |
distillation/all_init_no_flim.yaml |
1.299 × 794 |
| Crescimento SPiFiL | autoencoder/growth_*.yaml (9 famílias) |
— ¹ | 893 |
| Classhead | classification/classhead_flim.yaml |
— ² | 204 |
O braço sem FLIM do LeJEPA agrega os quatro: he (397), xavier (338), random (338),
trunc_normal (179). Na destilação, o único não-FLIM que rodou é trunc_normal.
¹ O crescimento não tem contrafactual de init — o autoencoder só aceita flim. O
controle dele é outro: growth_g5_random.yaml, que usa random_layer (troca só os
valores dos pesos no fim, preservando a norma filtro a filtro).
² Idem: o módulo levanta ValueError sem pesos FLIM.
python -m experiments.ray.launch experiments/lejepa/init_flim.yaml --dry-run
python -m experiments.ray.launch experiments/lejepa/init_no_flim.yaml --dry-run
skip: stateem todos: relançar pula o que já tem checkpoint em disco, então dá para rodar por cima do que já existe sem repetir trabalho.
python train.py fit \
--config configs/default.yaml \
--config configs/dataset/<dataset>/split_<N>.yaml \
--config configs/model/<metodo>/<init>/<dataset>/split_<N>.yaml \
--data.init_args.percentage=<pct>
São três --config e o LightningCLI empilha nessa ordem: o último vence. O global
traz trainer e callbacks; o de dataset traz o parasita e o split; o de método traz a
classe, os pesos FLIM e os hiperparâmetros.
percentage não está no config de dataset, e isso é de propósito. Ele é eixo da
grade, não propriedade do dataset — por isso vem por fora. Um config de dataset sozinho
não instancia: falha alto dizendo que falta percentage, em vez de cair num default
silencioso.
Trocar --print_config por fit imprime a configuração resolvida sem treinar. Use isso
para conferir antes de queimar GPU.
python -m experiments.ray.launch experiments/<metodo>/<nome>.yaml --dry-run
python -m experiments.ray.launch experiments/<metodo>/<nome>.yaml
--dry-run imprime cada comando montado e sai sem executar nada. O pré-voo roda
antes do ray.init() e nenhum job é submetido se ele falhar — ele nomeia o arquivo
culpado e lista os caminhos que faltam, um por linha.
Flags do launcher (as únicas quatro que sobreviveram no repositório inteiro):
| flag | para quê |
|---|---|
--dry-run |
imprime e sai |
--fail-fast |
para no primeiro erro |
--gpu-ids 0 1 |
sobrepõe resources.gpu_ids |
--set chave=valor |
sobrepõe qualquer chave do YAML (--set grid.percentages=[5,50]) |
skip: wandb consulta a rede. Se você não quer isso, rode com --set skip=state,
que decide pelo estado em disco.
Autoridade do schema: experiments/ray/schema.py. Chave desconhecida em runner_args
é erro, não aviso.
Pergunta: a inicialização FLIM do encoder bate as inicializações clássicas no pré-treino auto-supervisionado?
Configs: 45 células — configs/model/lejepa/<init>/<dataset>/split_N.yaml, com
init ∈ {flim, he, xavier, random, trunc_normal}. A grade está completa: as 24
células que faltavam (os inits não-flim de eggs e larvae) foram geradas a partir dos
genéricos que o launcher antigo usava, preservando os hiperparâmetros de cada init.
Atenção:
trunc_normalusalr: 5.0e-4eweight_decay: 1.0e-5; os outros três não-flim usam3.0e-3e5.0e-2. Não é engano — é o experimento como sempre foi.
Grade inteira:
python -m experiments.ray.launch experiments/lejepa/init_ablation.yaml --dry-run
270 pontos (5 inits × 3 datasets × 3 splits × 6 percentuais).
Uma célula:
python train.py fit \
--config configs/default.yaml \
--config configs/dataset/helminth-eggs/split_1.yaml \
--config configs/model/lejepa/flim/helminth-eggs/split_1.yaml \
--data.init_args.percentage=50
Saída: artifacts/lejepa/init_ablation/. Nome do run:
lejepa_line_<dataset>_split_<N>_pct_<P>_model_<init>.
Variantes fora da grade (configs/model/lejepa/_variants/): real_sigreg.yaml e
simple_sigreg.yaml trocam o eixo sigreg_type; resnet50.yaml troca o encoder.
custom_cnn.yaml está em QUARENTENA — aponta para uma classe que nunca existiu, e
o cabeçalho do arquivo explica com as evidências. Não use.
Avaliar: seção 5.
Pergunta: crescer o encoder FLIM camada a camada, guiado por superpixels, melhora a representação em relação a parar no encoder base?
Configs: 9 células — configs/model/autoencoder/flim/<dataset>/split_N.yaml.
Só existe o init flim, e isso é correto: o módulo levanta ValueError sem pesos
FLIM, então as outras 36 células seriam experimentos que abortam antes da primeira época.
Grade:
python -m experiments.ray.launch experiments/autoencoder/growth_grid4.yaml --dry-run
18 pontos, 144 comandos de estágio — o runner encadeia treina → cresce → treina, e
cada estágio recebe o best_kappa.ckpt do anterior via init_ckpt.
Uma célula (só o estágio 1, sem crescer):
python train.py fit \
--config configs/default.yaml \
--config configs/dataset/helminth-eggs/split_1.yaml \
--config configs/model/autoencoder/flim/helminth-eggs/split_1.yaml \
--data.init_args.percentage=50
Saída: artifacts/spifil_growth/<name>/<parasita>_split<N>_pct<P>/<estagio>/.
Nome do run: spifil_growth_<name>_<parasita>_split<N>_pct<P>_<estagio>.
O
namedo YAML vira o diretório dos pesos. Trocá-lo quebra o link com os checkpoints já gravados. Ele deve ser o basename dowork_dir(grid4, nãospifil_growth_grid4— há uma guarda contra o prefixo duplicado, mas não conte com ela).
Cada família de artifacts/spifil_growth/ tem agora o seu YAML em
experiments/autoencoder/. Os knobs foram reconstruídos das flags nos logs de cada
corrida (logs/<familia>.log), não do run_metadata.json — este grava só os hparams
do estágio de treino, e os knobs de grow não aparecem nele.
| Família | Datasets | pcts | Knobs que a definem | YAML |
|---|---|---|---|---|
grid3 |
eggs, larvae, protozoan | 5, 50 | baseline, sem controle | growth_grid3.yaml |
grid4 |
eggs, larvae, protozoan | 5, 50 | baseline | growth_grid4.yaml |
g5_in_image |
eggs, larvae, protozoan | 5, 50 | spifil_in_image, impurities, one_per_class |
growth_g5_in_image.yaml |
g5_in_feature |
eggs, larvae, protozoan | 5, 50 | spifil_in_feature, impurities, one_per_class |
growth_g5_in_feature.yaml |
g5_head |
eggs, larvae, protozoan | 5, 50 | head_finetune + spifil_in_image + impurities + one_per_class |
growth_g5_head.yaml |
g5_random |
eggs, larvae, protozoan | 5, 50 | random_layer + head_finetune + one_per_class |
growth_g5_random.yaml |
g5_head_larvae |
larvae | 5, 50 | mesma do g5_head, restrita |
growth_g5_head_larvae.yaml |
g5_head_repro |
larvae | 5, 50 | replicação do anterior | growth_g5_head_repro.yaml |
g5_head_nsp450 |
larvae | 5, 50 | impurities, one_per_class, n_superpixels: 450 ⚠ |
growth_g5_head_nsp450.yaml |
_debug |
— | — | descartável | — |
⚠ O 450 do g5_head_nsp450 vem do NOME, não do log — o --n-superpixels não
aparece nas flags registradas. Confirme antes de rodar.
O par g5_in_image × g5_in_feature é a comparação central: a mesma coisa com a
segmentação por superpixel feita na imagem ou na grade de features.
python -m experiments.ray.launch experiments/autoencoder/growth_g5_in_feature.yaml --dry-run
Os 20 knobs aceitos estão em RUNNER_ARGS["growth"] (experiments/ray/schema.py):
max_rounds, kappa_tolerance, rounds_patience, embed_mode, kernel_size,
out_channels, pool_stride, n_superpixels, n_images, image_size, seed,
spifil_in_feature, spifil_in_image, impurities, one_per_class, random_layer,
random_layer_classic, head_finetune, unfrozen_after_stage_two, layerwise.
Os YAMLs reconstruídos herdaram
resourcesdogrowth_grid4.yaml(GPUs 1-3, 3 slots cada). Ajuste ao que estiver livre na máquina antes de lançar.
Os dois controles aleatórios são perguntas diferentes.
random_layeré o controle pareado: roda o pipeline inteiro e troca só os valores dos pesos no fim, preservando a norma filtro a filtro.random_layer_classicé o controle clássico:kaiming_normal_, sem checkpoint, sem dado, sem superpixel, sem orçamento. Não são intercambiáveis.
Orçamento de covariância. O crescimento recusa com código de saída 3 quando
N <= D(D = in_channels × kernel²). Isso vale também pararandom_layer, que é o mesmo caminho; sórandom_layer_classicescapa, porque não ajusta nada.
Avaliar o crescimento: python -m eval.growth_stages (aceita pct=).
O encoder começa sem nenhuma camada. O SPiFiL cria uma camada, só ela treina por reconstrução contra um decoder novo e, em seguida, ela é congelada e vem a próxima. O SVM oficial avalia o encoder congelado depois de cada camada (L1, L2, …).
| treino | avaliação (SVM) | CSV | |
|---|---|---|---|
| 3 camadas | growth_layerwise3.yaml |
eval_svm_layerwise3.yaml |
results/svm_layerwise3.csv |
| 5 camadas | growth_layerwise5.yaml |
eval_svm_layerwise5.yaml |
results/svm_layerwise5.csv |
Os 4 YAMLs ficam em experiments/autoencoder/. Primeiro o treino e, quando ele terminar,
a avaliação:
python -m experiments.ray.launch experiments/autoencoder/growth_layerwise3.yaml
python -m experiments.ray.launch experiments/autoencoder/eval_svm_layerwise3.yaml
(para 5 camadas, troque 3 por 5; as duas grades usam GPUs diferentes e podem rodar juntas).
- Larguras:
LAYERWISE_SPECS(experiments/ray/runners/growth.py). L1–L3 = 16/32/48 filtros com pooling (configpaperdo SPiFiL); L4–L5 = 48 sem pooling. evaluate.SVM: falseno treino: o SVM só roda no YAML de eval.- Se o peso de uma camada antiga mudar, o braço morre (
_assert_frozen). layer_kernels: [5,5,5,1,1]dá o kernel de cada camada (sem ela,kernel_sizeem todas).layerwise_from_flim: 3pula o grow de L1–L3: o 1º estágioL3treina o FLIM de partida.method: ijepa_grow: nada congela; cadaLkpassaold_layers=k-1(camadas antigas com lr baixo) e não há_assert_frozen.- Antes de lançar:
export RAY_ACCEL_ENV_VAR_OVERRIDE_ON_ZERO=0eexport LD_LIBRARY_PATH=<env scalable_FLIM>/lib.
Pergunta: um aluno pequeno consegue herdar a representação do professor I-JEPA, e qual cabeça de projeção preserva melhor a informação?
Configs: 18 células — configs/model/distillation/<init>/<dataset>/split_N.yaml,
com init ∈ {flim, trunc_normal}.
O class_path é quem escolhe o aluno. As quatro variantes vivem em
methods/distillation/ e são selecionadas por overrides no experiment YAML, não por
flag:
| Módulo | Cabeça |
|---|---|
DistillationModule |
linear (base) |
DistillationConvModule |
convolucional |
DistillationOneLayerModule |
uma camada (1×1 ou 3×3, por proj_kernel) |
DistillationTwoLayerModule |
duas camadas 1×1 + BatchNorm2d |
As antigas flags --distill_1..4 não existem mais: o class_path já é a escolha, e
proj_kernel: 1|3 desambigua as duas que dividem o mesmo módulo.
Reconstruídas do argv real gravado em artifacts/distillation/**/wandb-metadata.json.
Não é inferência de nome: é a linha de comando que rodou.
Grupo A — família distill4_* (DistillationConvModule, ex---distill_4 --init_flim),
todas com eggs+larvae+protozoan, splits 1–3, pcts 1/5/25/50/75/100:
| YAML | loss | professor | runs |
|---|---|---|---|
distill4_cos_frozen.yaml |
cosseno | congelado | 48 |
distill4_cos_unfrozen.yaml |
cosseno | descongelado | 134 |
distill4_mse_frozen.yaml |
MSE | congelado | 2 |
distill4_mse_unfrozen.yaml |
MSE | descongelado | 14 |
distill4_kd_frozen.yaml |
KD híbrido (fine_tune=True) |
congelado | 22 |
distill4_kd_unfrozen.yaml |
KD híbrido | descongelado | 135 |
Grupo B — as famílias por --distillation-type:
| YAML | init | cabeça | pcts | runs |
|---|---|---|---|---|
direct_trunc_normal.yaml |
trunc_normal | — (os 4 módulos) | todos | 619 |
direct_flim.yaml |
flim | one_layer + two_layer | todos | 450 |
direct_flim_1x1.yaml |
flim | 1×1 | todos | 236 |
direct_flim_1x1_frozen.yaml |
flim | 1×1, encoder congelado | todos | 222 |
direct_trunc_normal_1x1.yaml |
trunc_normal | 1×1 | todos | 139 |
cosine_flim_bn2d.yaml |
flim | 1×1 BN2d 1280 | 1, 75 | 36 |
cosine_trunc_normal_bn2d.yaml |
trunc_normal | 1×1 BN2d 1280 | 1, 75 | 36 |
direct_trunc_normal é a maior família (619 runs) e foi rodada nos quatro módulos —
troque model.class_path no overrides para reproduzir cada um.
python -m experiments.ray.launch experiments/distillation/distill4_cos_frozen.yaml --dry-run
Uma célula:
python train.py fit \
--config configs/default.yaml \
--config configs/dataset/helminth-eggs/split_1.yaml \
--config configs/model/distillation/flim/helminth-eggs/split_1.yaml \
--data.init_args.percentage=100 \
--model.class_path=methods.distillation.DistillationOneLayerModule
A leitura dos resultados está em reports/distill_details.md, que documenta seis
grupos pelo sufixo do run (2l_1x1_init_flim_256_1280_no_imagenet_norm,
1x1_BN2d_1280_one_layer_flim_init_no_imagenet_norm, 3x3_BN2d_1280_one_layer_init_flim,
2l_1x1_init_flim_256_1280, next_layers_direct, pct75_modeldirect) com módulo, cabeça
e contagem de parâmetros. Esses sufixos são recortes dos YAMLs acima, não famílias à parte.
Saída: artifacts/distillation/<name>/.
Os YAMLs reconstruídos usam
gpu_ids: [0,1,2,3],max_per_gpu: 2. Ajuste ao que estiver livre. Ealpha: 0.5/temperature: 4.0vieram do argv — confira se é o que você quer antes de relançar.
Cada YAML carrega o
num_classesdo seu próprio dataset — eggs 9, larvae 2, protozoan 7. Isso importa: o conserto desse bug vivia no antigo_run_one, não no módulo. Um valor único para todos faz o bug do--dataset allvoltar pela porta do YAML.
Contagem de parâmetros tem armadilhas conhecidas: há um MLP vestigial e o encoder aparece duplicado no
state_dict. São propriedades do checkpoint gravado, não sujeira a limpar.reports/distill_details.mdtem a seção sobre isso.
Pergunta: ReLU ou sigmoid na cabeça de classificação sobre o encoder FLIM?
Configs: 9 células — configs/model/classification/flim/<dataset>/split_N.yaml.
Uma célula:
python train.py fit \
--config configs/default.yaml \
--config configs/dataset/helminth-eggs/split_1.yaml \
--config configs/model/classification/flim/helminth-eggs/split_1.yaml \
--data.init_args.percentage=100
Saída: artifacts/classification_flim/. Nome do run:
classhead_<parasita>_split<N>_pct<P>_<variante>.
O fine-tune supervisionado é outra classe, methods.classification.ClassificationFinetuneModule,
com config em configs/model/classifier.yaml. A chave dele mudou de nome:
freeze_encoder virou freeze, porque o nome antigo sombreava a função importada e a
classe levantava TypeError na construção — ela nunca instanciou. Está consertada.
Todas em eval/. Elas não treinam: rodam sobre checkpoints já gravados.
python -m experiments.ray.launch experiments/lejepa/eval_mlp_freeze.yaml --dry-run
54 jobs. Os configs de entrada são gerados, ficam em
configs/generated/mlp/{freeze,unfreeze}/<dataset>/<run_id>.yaml e estão no
.gitignore — regere com python -m experiments.gen_configs.
python -m eval.svm
As 10 variantes por experimento vivem em eval/svm_variants/: svm_distillation,
svm_distillation_conv, svm_ijepa, svm_distill_with_projection,
svm_classification_flim, eval_svm_flim_flatten, eval_autoencoder,
svm_real_flim, eval_avg_pooling_48d, svm_flim_residual. Cada uma roda com
python -m eval.svm_variants.<nome>.
svm_classification_flimgravaaccmicro E balanceada, ef1weighted E macro, de propósito — é para comparabilidade comdata/reports_felipe/svm/. Três outras gravamaccbalanceada eacc_rawmicro no mesmo CSV. Não unifique nenhuma delas.
| Sonda | Comando |
|---|---|
| Classificadores clássicos (QDA, RF, LGBM, GP, kNN) | python -m eval.classical_classifiers |
| Avaliação unificada | python -m eval.unified_eval |
| Estágios de crescimento | python -m eval.growth_stages |
| t-SNE | python -m eval.tsne |
Uso normal: python -m <modulo>, que roda com os defaults.
| Grupo | Módulos |
|---|---|
analysis.stats |
wilcoxon_acc, wilcoxon_f1, wilcoxon_kappa, wilcoxon_equivalence, wilcoxon_flim_init, compute_cost |
analysis.activations |
heatmap_stages, relu_vs_sigmoid, saturation, unit_activations |
analysis.distill |
embedding_analysis, ruler_mismatch, distill_destroys_flim |
analysis.plots |
plot_comparacao_flim_protocolo, plot_continuity_spifil_hybrid, plot_partial_train_spifil_hybrid, plot_sigmoid_saturation, plot_svm_results |
analysis.checks |
check_ssl, check_ckpt_slim, keep_only_best_ckpt, check_refactor_equivalence, check_probe_matches_evaluator, check_spifil_growth, … |
Exemplos:
python -m analysis.stats.wilcoxon_kappa
python -m analysis.activations.relu_vs_sigmoid
python -m analysis.plots.plot_continuity_spifil_hybrid
Para sobrepor um parâmetro:
python -c "from analysis.stats.wilcoxon_acc import wilcoxon_acc; wilcoxon_acc(alpha=0.01)"
heatmap_stages (14 parâmetros) e plot_continuity_spifil_hybrid (16) aceitam um YAML:
passe config='meu.yaml'.
analysis/distill/roda contra outro checkout. Os três módulos resolvemsrc.*de/dados/home/moliveira/scalable_FLIM_self_supervised(último commit de junho de 2026) e escrevem os.jsonlá, não aqui. É deliberado: religá-los mudaria números já publicados.
analysis.checks.keep_only_best_ckptAPAGA checkpoint. A regra é "sempre o best, nunca o last"; onde só existelast, olastfica. Ele tem--skip-recent-minpara não tocar em run vivo.
percentagefora do config de dataset — é eixo da grade. Config de dataset sozinho não instancia, e falha alto de propósito.skip: wandbvai à rede. Use--set skip=statepara decidir por disco.configs/model/lejepa/_variants/custom_cnn.yamlestá em quarentena — aponta para uma classe que nunca existiu. Nasceu quebrado no commit inicial e nunca rodou.- O
namedo growth vira o diretório dos pesos. Trocar quebra o link com os checkpoints gravados. num_classespor dataset nos YAMLs de destilação (9 / 2 / 7).- Protozoan usa bases FLIM diferentes para arquitetura e para pesos: arch em
ch24_30_48, pesos emch24_32_48. Não unifique. - Um arquivo que calcula a raiz do repo com
parents[N]quebra em silêncio ao mudar de profundidade — roda e escreve no lugar errado, sem erro. save_hyperparameters()só funciona se o__init__mencionarsuper. Trocar porpl.LightningModule.__init__(self)esvazia ohparamse o módulo não treina.
src/, scripts/ e tools/ ainda existem como legado e ainda não foram apagados.
O inventário de deleção está em MIGRATION.md, seção final. O ponto de retorno de toda
a refatoração é o commit f43435d.
O grafo do graphify está desatualizado — foi construído contra o layout antigo e
não conhece core/, flim/, methods/, eval/. Rode graphify update . antes de
consultá-lo.