Skip to content

Add exact opt-in threading to mapcolpairfreq!#197

Open
diegozea wants to merge 2 commits intomasterfrom
feat/threaded-mapcolpairfreq
Open

Add exact opt-in threading to mapcolpairfreq!#197
diegozea wants to merge 2 commits intomasterfrom
feat/threaded-mapcolpairfreq

Conversation

@diegozea
Copy link
Copy Markdown
Owner

@diegozea diegozea commented Mar 29, 2026

Summary

  • Add threads::Bool = false to mapcolpairfreq!.
  • Keep the existing serial _mappairfreq! path as the default.
  • Add a threaded column-pair path that uses thread-local scratch tables and writes only to disjoint output slots.

Why the threaded path is exact

  • Each column pair is computed independently with the same _mapfreq_kernel! used by the serial implementation.
  • The threaded path does not change per-pair residue order or introduce cross-pair reductions, so each score matches the serial result exactly.
  • New tests compare the full output structure for threads=false and threads=true on both a synthetic case and Gaoetal2011.fasta.

Why it is thread-safe

  • The threaded path allocates one deep-copied frequency/probability table per Julia thread.
  • Threads.threadid() is used only to select thread-local scratch storage.
  • Workers write only to unique PairwiseListMatrix slots derived from ij2k(...), so there are no overlapping writes.

Tests added

  • Synthetic exact-equality test with usediagonal=true and additive smoothing.
  • Real-fixture exact-equality test on Gaoetal2011.fasta with normalized_mutual_information.
  • Existing CorrectedMutualInformation and gap-related tests were rerun.

Commands run

  • using Pkg; Pkg.instantiate()
  • MIToSTests.retest("Information")
  • MIToSTests.retest("Iterations") twice
  • MIToSTests.retest("CorrectedMutualInformation") twice
  • MIToSTests.retest("Gaps") twice
  • Local timing check for mapcolpairfreq!(normalized_mutual_information, ...) on Gaoetal2011.fasta

Timing note

  • On the small Gaoetal2011.fasta fixture, the threaded path was slower locally due to thread overhead. This PR prioritizes exactness and thread safety over small-input speedups.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 29, 2026

Benchmark Results (Julia v1)

Time benchmarks
master 9f51ab9... master / 9f51ab9...
Information/CorrectedMutualInformation/buslje09/msa 0.884 ± 0.0073 s 0.884 ± 0.0087 s 1 ± 0.013
Information/CorrectedMutualInformation/buslje09/msa_large 0.0365 ± 0.0013 s 0.0365 ± 0.0012 s 1 ± 0.049
Information/CorrectedMutualInformation/buslje09/msa_wide 0.795 ± 0.0098 s 0.789 ± 0.011 s 1.01 ± 0.018
Information/MIp/PF09645 9.73 ± 0.28 ms 9.5 ± 0.29 ms 1.02 ± 0.043
Information/frequencies!/1 0.3 ± 0.021 μs 0.301 ± 0.02 μs 0.997 ± 0.096
Information/frequencies!/2 1.45 ± 0.021 μs 1.44 ± 0.02 μs 1.01 ± 0.02
Information/highlevel/BLMI 0.0645 ± 0.0002 s 0.061 ± 0.00023 s 1.06 ± 0.0052
Information/highlevel/buslje09 11.5 ± 0.27 ms 11.4 ± 0.093 ms 1.01 ± 0.025
Information/shannon_entropy/PF09645 19.8 ± 0.73 μs 19.8 ± 0.67 μs 1 ± 0.05
MSA/Annotations/filtercolumns/boolean mask 9.92 ± 0.25 μs 9.97 ± 0.24 μs 0.995 ± 0.035
MSA/Annotations/filtercolumns/index array 3.54 ± 0.15 μs 3.53 ± 0.13 μs 1 ± 0.056
MSA/Base.vcat/annotated 4.45 ± 0.33 μs 4.47 ± 0.38 μs 0.996 ± 0.11
MSA/Base.vcat/unannotated 1.5 ± 0.13 μs 1.5 ± 0.14 μs 1 ± 0.13
MSA/Residue conversions/char2res 0.353 ± 0.026 ms 0.353 ± 0.036 ms 0.999 ± 0.12
MSA/Residue conversions/int2res 0.227 ± 0.048 ms 0.23 ± 0.8 ms 0.99 ± 3.5
MSA/Residue conversions/res2char 0.261 ± 0.012 ms 0.262 ± 0.012 ms 0.997 ± 0.066
MSA/Residue conversions/res2int 0.232 ± 0.071 ms 0.238 ± 0.78 ms 0.974 ± 3.2
MSA/hobohmI/pid20 0.491 ± 0.15 μs 0.48 ± 0.1 μs 1.02 ± 0.38
MSA/hobohmI/pid62 0.561 ± 0.14 μs 0.561 ± 0.1 μs 1 ± 0.31
MSA/hobohmI/pid80 0.561 ± 0.13 μs 0.551 ± 0.1 μs 1.02 ± 0.3
MSA/hobohmI/pid99 0.711 ± 0.14 μs 0.701 ± 0.1 μs 1.01 ± 0.25
MSA/identity/matrix_Float64 18.5 ± 0.54 μs 17.7 ± 0.59 μs 1.05 ± 0.046
MSA/identity/mean 0.0917 ± 0.022 ms 0.0908 ± 0.022 ms 1.01 ± 0.35
MSA/read/Clustal 29.4 ± 3.7 μs 29.9 ± 3.4 μs 0.983 ± 0.17
MSA/read/Clustal_num 29.6 ± 3.8 μs 30 ± 3.4 μs 0.987 ± 0.17
MSA/read/FASTA 0.0475 ± 0.0077 ms 0.0488 ± 0.0081 ms 0.974 ± 0.23
MSA/read/FASTA.gz 0.0444 ± 0.0063 ms 0.0445 ± 0.0049 ms 0.999 ± 0.18
MSA/read/FASTA.gz_annotated 0.0509 ± 0.0059 ms 0.0508 ± 0.0057 ms 1 ± 0.16
MSA/read/FASTA_deletefullgaps 6.17 ± 1.2 ms 6.26 ± 1 ms 0.986 ± 0.25
MSA/read/FASTA_deletefullgaps_mapping 0.097 ± 0.024 s 0.0954 ± 0.023 s 1.02 ± 0.35
MSA/read/Stockholm 0.0348 ± 0.0088 ms 0.0347 ± 0.0083 ms 1.01 ± 0.35
MSA/read/Stockholm.gz 0.0618 ± 0.0033 ms 0.0617 ± 0.0035 ms 1 ± 0.078
MSA/read/Stockholm_annotated 0.0466 ± 0.011 ms 0.0467 ± 0.012 ms 0.998 ± 0.34
MSA/read/Stockholm_mapping 0.205 ± 0.041 ms 0.198 ± 0.04 ms 1.03 ± 0.29
MSA/read/Stockholm_mapping_coords 0.125 ± 0.03 ms 0.124 ± 0.031 ms 1.01 ± 0.35
MSA/write/FASTA 0.25 ± 0.063 ms 0.235 ± 0.076 ms 1.06 ± 0.44
PDB/_generate_interaction_keys/defaults 0.0443 ± 0.017 ms 0.0455 ± 0.017 ms 0.974 ± 0.52
PDB/_get_matched_Cαs/hemoglobin 0.0386 ± 0.0078 ms 0.0385 ± 0.0077 ms 1 ± 0.28
PDB/_pdbresidues_to_mmcifdict/2vqc 0.648 ± 0.097 ms 0.66 ± 0.13 ms 0.982 ± 0.24
PDB/contact/1CBN_20_30_CB 0.2 ± 0.011 μs 0.2 ± 0.011 μs 1 ± 0.078
PDB/contact/1CBN_20_30_heavy 0.251 ± 0.011 μs 0.25 ± 0.01 μs 1 ± 0.06
PDB/count_alanine/1CBN 0.321 ± 0.001 μs 0.321 ± 0.001 μs 1 ± 0.0044
PDB/distance/1CBN_20_30 0.14 ± 0 μs 0.131 ± 0.01 μs 1.07 ± 0.082
PDB/read/MMCIFFile 2.93 ± 0.052 ms 2.98 ± 0.074 ms 0.986 ± 0.03
PDB/squared_distance/1CBN_20_30_CB 0.2 ± 0.001 μs 0.21 ± 0.01 μs 0.952 ± 0.046
PDB/squared_distance/1CBN_20_30_heavy 0.261 ± 0.001 μs 0.26 ± 0.01 μs 1 ± 0.039
Pfam/accession mapping/acc2seqnames 0.194 ± 0.013 ms 0.193 ± 0.012 ms 1 ± 0.091
SIFTS/ResidueDetails/_get_details 2.44 ± 0.62 μs 2.14 ± 0.83 μs 1.14 ± 0.53
SIFTS/ResidueDetails/_is_missing 2.1 ± 0.51 μs 2.13 ± 0.66 μs 0.986 ± 0.39
SIFTS/SIFTSResidue/18gs 0.11 ± 0.001 μs 0.11 ± 0.01 μs 1 ± 0.091
SIFTS/siftsmapping/2vqc 2.32 ± 0.078 ms 2.35 ± 0.046 ms 0.989 ± 0.038
Utils/get_n_words/ascii 0.13 ± 0.01 μs 0.13 ± 0.01 μs 1 ± 0.11
Utils/get_n_words/utf8 0.11 ± 0.01 μs 0.12 ± 0.01 μs 0.917 ± 0.11
Utils/hascoordinates/invalid 0.081 ± 0.01 μs 0.081 ± 0.01 μs 1 ± 0.17
Utils/hascoordinates/valid 0.131 ± 0.01 μs 0.13 ± 0.01 μs 1.01 ± 0.11
Utils/list2matrix/upper 0.244 ± 0.027 ms 0.236 ± 0.053 ms 1.03 ± 0.26
Utils/list2matrix/upper_diagonal 0.33 ± 0.072 ms 0.325 ± 0.069 ms 1.02 ± 0.31
Utils/matrix2list/upper 0.0732 ± 0.031 ms 0.0668 ± 0.026 ms 1.1 ± 0.62
Utils/matrix2list/upper_diagonal 0.0725 ± 0.029 ms 0.0662 ± 0.027 ms 1.1 ± 0.63
time_to_load 0.794 ± 0.002 s 0.803 ± 0.01 s 0.989 ± 0.013
Memory benchmarks
master 9f51ab9... master / 9f51ab9...
Information/CorrectedMutualInformation/buslje09/msa 0.766 M allocs: 0.032 GB 0.766 M allocs: 0.032 GB 1
Information/CorrectedMutualInformation/buslje09/msa_large 0.0901 M allocs: 5.03 MB 0.0901 M allocs: 5.03 MB 1
Information/CorrectedMutualInformation/buslje09/msa_wide 0.742 M allocs: 30.3 MB 0.742 M allocs: 30.3 MB 1
Information/MIp/PF09645 20.3 k allocs: 0.819 MB 20.3 k allocs: 0.819 MB 1
Information/frequencies!/1 0 allocs: 0 B 0 allocs: 0 B
Information/frequencies!/2 0 allocs: 0 B 0 allocs: 0 B
Information/highlevel/BLMI 19.9 k allocs: 1.19 MB 19.9 k allocs: 1.19 MB 1
Information/highlevel/buslje09 0.0377 M allocs: 2.3 MB 0.0377 M allocs: 2.3 MB 1
Information/shannon_entropy/PF09645 0.047 k allocs: 12.2 kB 0.047 k allocs: 12.2 kB 1
MSA/Annotations/filtercolumns/boolean mask 18 allocs: 5.22 kB 18 allocs: 5.22 kB 1
MSA/Annotations/filtercolumns/index array 16 allocs: 1.62 kB 16 allocs: 1.62 kB 1
MSA/Base.vcat/annotated 0.143 k allocs: 6.58 kB 0.143 k allocs: 6.58 kB 1
MSA/Base.vcat/unannotated 0.064 k allocs: 2.7 kB 0.064 k allocs: 2.7 kB 1
MSA/Residue conversions/char2res 3 allocs: 4.1 MB 3 allocs: 4.1 MB 1
MSA/Residue conversions/int2res 3 allocs: 4.1 MB 3 allocs: 4.1 MB 1
MSA/Residue conversions/res2char 3 allocs: 2.05 MB 3 allocs: 2.05 MB 1
MSA/Residue conversions/res2int 3 allocs: 4.1 MB 3 allocs: 4.1 MB 1
MSA/hobohmI/pid20 31 allocs: 1.77 kB 31 allocs: 1.77 kB 1
MSA/hobohmI/pid62 31 allocs: 1.77 kB 31 allocs: 1.77 kB 1
MSA/hobohmI/pid80 31 allocs: 1.77 kB 31 allocs: 1.77 kB 1
MSA/hobohmI/pid99 31 allocs: 1.77 kB 31 allocs: 1.77 kB 1
MSA/identity/matrix_Float64 0.249 k allocs: 11.8 kB 0.249 k allocs: 11.8 kB 1
MSA/identity/mean 1.23 k allocs: 0.0517 MB 1.23 k allocs: 0.0517 MB 1
MSA/read/Clustal 0.394 k allocs: 24.3 kB 0.394 k allocs: 24.3 kB 1
MSA/read/Clustal_num 0.394 k allocs: 24.3 kB 0.394 k allocs: 24.3 kB 1
MSA/read/FASTA 0.406 k allocs: 0.044 MB 0.406 k allocs: 0.044 MB 1
MSA/read/FASTA.gz 0.443 k allocs: 0.0752 MB 0.443 k allocs: 0.0752 MB 1
MSA/read/FASTA.gz_annotated 0.533 k allocs: 0.0793 MB 0.533 k allocs: 0.0794 MB 0.999
MSA/read/FASTA_deletefullgaps 13.6 k allocs: 17.4 MB 13.6 k allocs: 17.4 MB 1
MSA/read/FASTA_deletefullgaps_mapping 1.64 M allocs: 0.0795 GB 1.64 M allocs: 0.0795 GB 1
MSA/read/Stockholm 0.402 k allocs: 0.033 MB 0.402 k allocs: 0.033 MB 1
MSA/read/Stockholm.gz 0.479 k allocs: 0.0754 MB 0.479 k allocs: 0.0754 MB 1
MSA/read/Stockholm_annotated 0.562 k allocs: 0.0413 MB 0.562 k allocs: 0.0413 MB 1
MSA/read/Stockholm_mapping 2.08 k allocs: 0.104 MB 2.08 k allocs: 0.104 MB 1
MSA/read/Stockholm_mapping_coords 1.64 k allocs: 0.0812 MB 1.64 k allocs: 0.0812 MB 1
MSA/write/FASTA 0.303 k allocs: 14.1 kB 0.303 k allocs: 14.1 kB 1
PDB/_generate_interaction_keys/defaults 0.497 k allocs: 0.0581 MB 0.497 k allocs: 0.0581 MB 1
PDB/_get_matched_Cαs/hemoglobin 0.584 k allocs: 0.0438 MB 0.584 k allocs: 0.0438 MB 1
PDB/_pdbresidues_to_mmcifdict/2vqc 8.56 k allocs: 1.12 MB 8.56 k allocs: 1.12 MB 1
PDB/contact/1CBN_20_30_CB 4 allocs: 0.281 kB 4 allocs: 0.281 kB 1
PDB/contact/1CBN_20_30_heavy 4 allocs: 0.281 kB 4 allocs: 0.281 kB 1
PDB/count_alanine/1CBN 0 allocs: 0 B 0 allocs: 0 B
PDB/distance/1CBN_20_30 0 allocs: 0 B 0 allocs: 0 B
PDB/read/MMCIFFile 0.039 M allocs: 2.9 MB 0.039 M allocs: 2.9 MB 1
PDB/squared_distance/1CBN_20_30_CB 4 allocs: 0.281 kB 4 allocs: 0.281 kB 1
PDB/squared_distance/1CBN_20_30_heavy 4 allocs: 0.281 kB 4 allocs: 0.281 kB 1
Pfam/accession mapping/acc2seqnames 4.32 k allocs: 0.319 MB 4.32 k allocs: 0.319 MB 1
SIFTS/ResidueDetails/_get_details 25 allocs: 1.45 kB 25 allocs: 1.45 kB 1
SIFTS/ResidueDetails/_is_missing 25 allocs: 1.45 kB 25 allocs: 1.45 kB 1
SIFTS/SIFTSResidue/18gs 4 allocs: 0.125 kB 4 allocs: 0.125 kB 1
SIFTS/siftsmapping/2vqc 5.94 k allocs: 0.88 MB 5.94 k allocs: 0.88 MB 1
Utils/get_n_words/ascii 5 allocs: 0.203 kB 5 allocs: 0.203 kB 1
Utils/get_n_words/utf8 5 allocs: 0.219 kB 5 allocs: 0.219 kB 1
Utils/hascoordinates/invalid 0 allocs: 0 B 0 allocs: 0 B
Utils/hascoordinates/valid 0 allocs: 0 B 0 allocs: 0 B
Utils/list2matrix/upper 3 allocs: 1.91 MB 3 allocs: 1.91 MB 1
Utils/list2matrix/upper_diagonal 6 allocs: 2.86 MB 6 allocs: 2.86 MB 1
Utils/matrix2list/upper 3 allocs: 0.952 MB 3 allocs: 0.952 MB 1
Utils/matrix2list/upper_diagonal 3 allocs: 0.956 MB 3 allocs: 0.956 MB 1
time_to_load 0.149 k allocs: 11.1 kB 0.149 k allocs: 11.1 kB 1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@diegozea