obitools4/blackboard/Prospective/large_sequence_parsing.md

Optimisation du parsing des grandes séquences

Contexte

OBITools4 doit pouvoir traiter des séquences de taille chromosomique (plusieurs Gbp), notamment issues de fichiers GenBank/EMBL (assemblages de génomes) ou de fichiers FASTA convertis depuis ces formats.

Architecture actuelle

Pipeline de lecture (pkg/obiformats/)

ReadFileChunk (goroutine)
    → ChannelFileChunk
    → N × _ParseGenbankFile / _ParseFastaFile (goroutines)
    → IBioSequence

ReadFileChunk (file_chunk_read.go) lit le fichier par morceaux via une chaîne de PieceOfChunk (rope). Chaque nœud fait fileChunkSize bytes :

• GenBank/EMBL : 128 MB (1024*1024*128)
• FASTA/FASTQ : 1 MB (1024*1024)

La chaîne est accumulée jusqu'à trouver la fin du dernier enregistrement complet (splitter), puis Pack() est appelé pour fusionner tous les nœuds en un seul buffer contigu. Ce buffer est transmis au parseur via FileChunk.Raw *bytes.Buffer.

Parseur GenBank (genbank_read.go)

GenbankChunkParser reçoit un io.Reader sur le buffer packé, lit ligne par ligne via bufio.NewReader (buffer 4096 bytes), et pour chaque ligne de la section ORIGIN :

line = string(bline)                        // allocation par ligne
cleanline := strings.TrimSpace(line)        // allocation
parts := strings.SplitN(cleanline, " ", 7) // allocation []string + substrings
for i := 1; i < lparts; i++ {
    seqBytes.WriteString(parts[i])
}

Point positif : seqBytes est pré-alloué grâce à lseq extrait de la ligne LOCUS.

Parseur FASTA (fastaseq_read.go)

FastaChunkParser lit octet par octet via scanner.ReadByte(). Pour 3 Gbp : 3 milliards d'appels. seqBytes est un bytes.Buffer{} sans pré-allocation.

Problème principal

Pour une séquence de plusieurs Gbp, Pack() fusionne une chaîne de ~N nœuds de 128 MB en un seul buffer contigu. C'est une allocation de N × 128 MB suivie d'une copie de toutes les données. Bien que l'implémentation de Pack() soit efficace (libère les nœuds au fur et à mesure via slices.Grow), la copie est inévitable avec l'architecture actuelle.

De plus, le parseur GenBank produit des dizaines de millions d'allocations temporaires pour parser la section ORIGIN (une par ligne).

Invariant clé découvert

Si la rope a plus d'un nœud, le premier nœud seul ne se termine pas sur une frontière d'enregistrement (pas de //\n en fin de piece1).

Preuve par construction dans ReadFileChunk :

• splitter est appelé dès le premier nœud (ligne 157)
• Si end >= 0 → frontière trouvée dans 128 MB → boucle interne sautée → rope à 1 nœud
• Si end < 0 → boucle interne ajoute des nœuds → rope à ≥ 2 nœuds

Corollaire : si rope à 1 nœud, Pack() ne fait rien (aucun nœud suivant).

Attention : rope à ≥ 2 nœuds ne signifie pas qu'il n'y a qu'une seule séquence dans la rope. La rope packée peut contenir plusieurs enregistrements complets. Exemple : records de 80 MB → nextpieces (48 MB de reste) + nouveau nœud (128 MB) = rope à 2 nœuds contenant 2 records complets + début d'un troisième.

L'invariant dit seulement que piece1 seul est incomplet — pas que la rope entière ne contient qu'un seul record.

Invariant : le dernier FileChunk envoyé finit sur une frontière d'enregistrement.

Deux chemins dans ReadFileChunk :

1. Chemin normal (end >= 0 via splitter) : le buffer est explicitement tronqué à end (ligne 200 : pieces.data = pieces.data[:end]). Frontière garantie par construction pour tous les formats. ✓

2. Chemin EOF (end < 0, end = pieces.Len()) : tout le reste du fichier est envoyé.

   • GenBank/EMBL : présuppose fichier bien formé (se termine par //\n). Le parseur lève un log.Fatalf sur tout état inattendu — filet de sécurité suffisant. ✓
   • FASTQ : présupposé, vérifié par le parseur. ✓
   • FASTA : garanti par le format lui-même (fin d'enregistrement = EOF ou >). ✓

Hypothèse de travail adoptée : les fichiers d'entrée sont bien formés. Dans le pire cas, le parseur lèvera une erreur explicite. Il n'y a pas de risque de corruption silencieuse.

Piste d'optimisation : se dispenser de Pack()

Idée centrale

Au lieu de fusionner la rope avant de la passer au parseur, parser directement la rope nœud par nœud, et écrire la séquence compactée in-place dans le premier nœud.

Pourquoi c'est sûr :

• Le header (LOCUS, DEFINITION, SOURCE, FEATURES) est petit et traité en premier
• La séquence (ORIGIN) est à la fin du record
• Au moment d'écrire la séquence depuis l'offset 0 de piece1, le pointeur de lecture est profond dans la rope (offset >> 0) → jamais de collision
• La séquence compactée est toujours plus courte que les données brutes

Pré-allocation

Pour GenBank/EMBL : lseq est connu dès la ligne LOCUS/ID (première ligne, dans piece1). On peut faire slices.Grow(piece1.data, lseq) dès ce moment.

Pour FASTA : pas de taille garantie dans le header, mais rope.Len() donne un majorant. On peut utiliser rope.Len() / 2 comme estimation initiale.

Gestion des jonctions entre nœuds

Une ligne peut chevaucher deux nœuds (rare avec 128 MB, mais possible). Solution : carry buffer de ~128 bytes pour les quelques bytes en fin de nœud.

Cas FASTA/FASTQ multi-séquences

Un FileChunk peut contenir N séquences (notamment FASTA/FASTQ courts). Dans ce cas l'écriture in-place dans piece1 n'est pas applicable directement — on écrase des données nécessaires aux séquences suivantes.

Stratégie par cas :

• Rope à 1 nœud (record ≤ 128 MB) : Pack() est trivial (no-op), parseur actuel OK
• Rope à ≥ 2 nœuds : par l'invariant, piece1 ne contient pas de record complet → une seule grande séquence → in-place applicable

Format d'une ligne séquence GenBank (Après ORIGIN)

/^ *[0-9]+( [nuc]{10}){0,5} [nuc]{1,10}/

Format d'une ligne séquence GenBank (Après SQ)

La ligne SQ contient aussi la taille de la séquence

/^ *( [nuc]{10}){0,5} [nuc]{1,10} *[0-9]+/

Compactage in-place sur bline ([]byte brut, sans conversion string) :

w := 0
i := 0
for i < len(bline) && bline[i] == ' '  { i++ }   // skip indentation
for i < len(bline) && bline[i] <= '9'  { i++ }   // skip position number
for ; i < len(bline); i++ {
    if bline[i] != ' ' {
        bline[w] = bline[i]
        w++
    }
}
// écrire bline[:w] directement dans piece1.data[seqOffset:]

Changements nécessaires

1. FileChunk : exposer la rope *PieceOfChunk non-packée en plus (ou à la place) de Raw *bytes.Buffer
2. GenbankChunkParser / EmblChunkParser : accepter *PieceOfChunk, parser la rope séquentiellement avec carry buffer pour les jonctions
3. FastaChunkParser : idem, avec in-place conditionnel selon taille de la rope
4. ReadFileChunk : ne pas appeler Pack() avant envoi sur le channel (ou version alternative ReadFileChunkRope)

Fichiers concernés

• pkg/obiformats/file_chunk_read.go — structure rope, ReadFileChunk
• pkg/obiformats/genbank_read.go — GenbankChunkParser, _ParseGenbankFile
• pkg/obiformats/embl_read.go — EmblChunkParser, ReadEMBL
• pkg/obiformats/fastaseq_read.go — FastaChunkParser, _ParseFastaFile
• pkg/obiformats/fastqseq_read.go — parseur FASTQ (même structure)

Plan d'implémentation : parseur GenBank sur rope

Contexte

Baseline mesurée : obiconvert gbpln640.seq.gz → 49s real, 42s user, 29s sys, 57 GB RSS. Le sys élevé indique des allocations massives. Deux causes :

1. Pack() : fusionne toute la rope (N × 128 MB) en un buffer contigu avant de parser
2. Parser ORIGIN : string(bline) + TrimSpace + SplitN × millions de lignes

1. gbRopeScanner

Struct de lecture ligne par ligne sur la rope, sans allocation heap :

type gbRopeScanner struct {
    current *PieceOfChunk
    pos     int
    carry   [256]byte  // stack-allocated, max GenBank line = 80 chars
    carryN  int
}

ReadLine() :

• Cherche \n dans current.data[pos:] via bytes.IndexByte
• Si trouvé sans carry : retourne slice direct du node (zéro alloc)
• Si trouvé avec carry : copie dans carry buffer, retourne carry[:n]
• Si non trouvé : copie le reste dans carry, avance au node suivant, recommence
• EOF : retourne carry[:carryN] puis nil

extractSequence(dest []byte, UtoT bool) int :

• Scan direct des bytes pour section ORIGIN, sans passer par ReadLine
• Machine d'états : lineStart → skip espaces/digits → copier nucléotides dans dest
• Stop sur // en début de ligne
• Zéro allocation, UtoT inline

2. GenbankChunkParserRope

func GenbankChunkParserRope(source string, rope *PieceOfChunk,
    withFeatureTable, UtoT bool) (obiseq.BioSequenceSlice, error)

• Même machine d'états que GenbankChunkParser, sur []byte (bytes.HasPrefix)
• LOCUS : extrait id et lseq par scan direct (remplace _seqlenght_rx)
• FEATURES / default inFeature : taxid extrait par scan de /db_xref="taxon: dans la source feature ; featBytes rempli seulement si withFeatureTable=true
• DEFINITION : toujours conservée
• ORIGIN : dest = make([]byte, 0, lseq+20) puis s.extractSequence(dest, UtoT)

3. Modifications _ParseGenbankFile et ReadGenbank

_ParseGenbankFile utilise chunk.Rope :

sequences, err := GenbankChunkParserRope(chunk.Source, chunk.Rope, ...)

ReadGenbank passe pack=false :

entry_channel := ReadFileChunk(..., false)

4. Ce qui NE change pas

• GenbankChunkParser reste (référence, tests)
• ReadFileChunk, Pack(), autres parseurs (EMBL, FASTA, FASTQ) : inchangés

5. Gains attendus

• RSS : pic ≈ 128 MB × workers (au lieu de N × 128 MB)
• Temps sys : élimination des mmap/munmap pour les gros buffers
• Temps user : ~50M allocations éliminées

6. Vérification

/usr/local/go/bin/go build ./...
diff <(obiconvert gbpln640.seq.gz) gbpln640.reference.fasta
cd bugs/genbank && ./benchmark.sh gbpln640.seq.gz

Cible : RSS < 1 GB, temps comparable ou meilleur.