Turin And Torino

entendendo o que você realmente precisa antes de instalar

se você está aqui procurando turin e torino, provavelmente já se deparou com a necessidade de calcular números de Turán em grafos densos ou mapear toros em estruturas discretas. a confusão entre os dois nomes não é mera coincidência — ambos vêm da combinatorics aplicada e aparecem frequentemente no mesmo fluxo de trabalho quando você está otimizando something like clique-maximization ou edge-coloring. a biblioteca em si não vem com instalação automática. você vai clonar o repositório, ajustar o pyproject.toml para sua versão do python (3.10+, senão perde as tipagens que sustentam os caches internos), e rodar pip install . do diretório raiz. leve uns 4 minutos em máquina comum. se seu ambiente for macOS com M-series, compila os extensiones C++ manualmente ou aceita o fallback puramente em Cython, que é cerca de 30% mais lento mas funciona sem dor de cabeça.

por que as pessoas confundem turin e torino no dia a dia

eu já vi relatórios de engenharia onde o erro de digitação gerou um branch inteiro no GitHub porque alguém chamou torino.compute() num código que na verdade precisava de turin.clique_number(). o resultado sai diferente, mas a API é idêntica, então o bug só aparece quando você compara com uma solução de referência ou com dados reais. a diferença é que Turán calcula limites superiores para o número de arestas em grafos sem subgrafos completos, enquanto Torino (sim, nome próprio do pacote) é focado em decomposição de toros e caminhos hamiltonianos em grafos esparsos. não são intercambiáveis, mas compartilham a mesma interface de loader. um detalhe que ninguém cuenta: se você chamar turin com um grafo não-dirigido que tenha arestas paralelas, a função ignora duplicatas silenciosamente. eu perdi meio dia caçando um falso negativo assim em 2023. a workaround foi rodar um graph.remove_multiedges() antes de qualquer chamada, senão o limite de Turán fica subestimado e suas decisões de slicing dependem de um número errado.

como usar na prática, sem gambiarra

carregar o grafo é o passo mais trivial. use o formato mtx ou leia direto de NetworkX se estiver migrando algo existente. o parser aceita ambos, mas o formato nativo do pacote (.tnr) economiza cerca de 40% de tempo de warm-up porque pré-calcula adjacency hashes.

import turin
import torino

g = turin.load("meu_grafo.tnr")
limite = turin.turan_number(g, r=3)  K-free, por exemplo
print(limite)

já o lado Torino exige que o grafo seja conexo e sem vértices isolados. se não for, a função lança ValueError. eu costumo fazer um pré-processamento rápido:

from scipy.sparse import csgraph
components = csgraph.connected_components(g.adj, directed=False)
if components[0] > 1:
    g = g.subgraph(max(components, key=len))

depois disso, rodar torino.decompose(g) retorna uma lista de ciclos cobrindo todas as arestas — útil se você está montando roteiros de delivery ou scheduling de recursos em topologias fixas. o algoritmo é heurístico, não exato, então espere variações de até 12% no tamanho da cobertura entre execuções no mesmo grafo. isso é normal, não é bug.

pegadinhas que custam tempo e como evitar

a primeira: memória. para grafos com mais de 50k vértices, o módulo de Turán carrega uma matriz de adjacência densa na memória se você não especificar sparse=True. sem esse flag, um grafo de 100k nós pode facilmente estourar 8 GB. eu uso sempre turan_number(g, r=4, sparse=True) em pipelines de produção e o consumo cai para menos de 1,2 GB, com aumento de 200 ms no tempo de execução — trade-off que vale a pena. segunda: versões. o pacote não segue semantic versioning rigoroso entre releases pequenos. atualizei de 0.9.3 para 0.10.1 numa sexta à tarde e o wrapper de Torino quebrou porque a assinatura de decompose() mudou de positional para keyword-only. verifique o changelog antes de qualquer deploy automatizado. não confiável nessa parte.

terceira, e mais chata: a documentação não menciona que o seed do gerador aleatório usado pelo decompositor do Torino é fixo por processo, mas variável entre versões do Python. se você precisa reproducibilidade cross-platform, chame random.seed() explicitamente antes de importar torino, senão os resultados variam entre Linux e Windows mesmo com o mesmo grafo.

quando não usar

se o seu grafo é pequeno (menos de 5k arestas) e você precisa de resposta exata, Turán via force-compute em vez de aproximado pode demorar mais do que rodar uma enumeration simples com NetworkX + igraph. o pacote brilha mesmo acima de 50k arestas, onde algoritmos exatos viram inviáveis. abaixo disso, o overhead de inicialização consome boa parte da economia. para decomposição toroidal em grafos com pesos nas arestas, a implementação atual não suporta. você terá que usar uma fallback em conjunto com Z3 ou OR-Tools, o que aumenta a complexidade do setup consideravelmente. não recomendo tentar embeddar o Torino nesse cenário — a integração é frágil e não há testes de integração oficiais.

download e instalação

o repositório oficial fica em github.com/sapiens-ai/turin-torino. o pacote também está no PyPI com o nome turin-torino, então pip install turin-torino resolve a maioria dos casos. versões mais recentes podem levar alguns dias para chegar ao PyPI após o release no GitHub, então se você precisa de alguma feature específica, prefira clonar e instalar localmente. não tem wheel pré-compilado para ARM64 ainda. se seu ambiente é Apple Silicon ou Raspberry Pi 5, prepare-se para compilar os extensiones. o build leva cerca de 6 minutos e requer cmake 3.22+ e um compilador C++ que suporte C++17. se faltar algum desses, o pip vai falhar silenciosamente e instalar a versão puramente Python, que é funcional mas lenta para grafos grandes.

se aparecer algum erro de linking durante a instalação, o mais comum é falta da biblioteca BLAS no sistema. no Ubuntu, apt install libblas-dev liblapack-dev resolve. no macOS, o OpenBLAS já vem embutido, mas às vezes o Homebrew cria symlinks quebrados após atualizações — reiniciar o terminal e rodar brew reinstall openblas costuma resolver. em resumo, o pacote funciona bem dentro do escopo para o qual foi feito. fora disso, você vai passar tempo debugando limites e versões incompatíveis. planeje o uso antes de integrar, testem em staging com seus grafos reais e não subestimem o custo de manutenção quando a API mudar sem aviso prévio.