added multi-processing for final dimer solve

Author: jonas-fuchs

docs/how_varvamp_works.md

@@ -56,6 +56,21 @@ To search for the best amplicon, varVAMP uses a graph based approach.
 7. Test amplicons for their [minimal free energy](https://en.wikipedia.org/wiki/Gibbs_free_energy) at their lowest primer temperature with [`seqfold`](https://github.com/Lattice-Automation/seqfold) and filter to avoid secondary structures. Amplicons with large potential deletions (>QAMPLICON_DEL_CUTOFF) will be ignored. Smaller deletions will be accepted.
 8. Take the best qPCR schemes of overlapping schemes.
 
+
+#### Multi-processing
+varVAMP can use multiple cores at some steps in the workflow. If you have performance issues
+at the following steps it might be worth increasing the number of cores.
+
+1. All workflows:
+- BLAST search: Each amplicon is searched for off-targets in the BLAST database.
+- Primer dimer search against a user-provided list of primers.
+
+2. Tiled workflow:
+- Final primer dimer solve.
+
+3. qPCR workflow:
+- Amplicon deltaG calculation: Each amplicon is checked for potential secondary structures.
+
 #### Penalty calculation
 
 ```python

varvamp/command.py

@@ -304,7 +304,7 @@ def shared_workflow(args, log_file):
         progress_text=f"{len(left_primer_candidates)} fw and {len(right_primer_candidates)} rv potential primers"
     )
 
-    # filter primers against non-dimer sequences if provided, can use multi-processing
+    # filter primers against user-provided list of compatible primers, can use multi-processing
     if compatible_primers is not None:
         left_primer_candidates = primers.filter_non_dimer_candidates(
             left_primer_candidates, compatible_primers, args.threads
@@ -433,7 +433,9 @@ def tiled_workflow(args, amplicons, left_primer_candidates, right_primer_candida
         amplicon_scheme,
         left_primer_candidates,
         right_primer_candidates,
-        all_primers)
+        all_primers,
+        args.threads
+    )
 
     # report dimers solve
     if n_initial_dimers > 0 and not dimers_not_solved:

varvamp/scripts/default_config.py

@@ -33,7 +33,7 @@
 # primer dimer constraints
 PRIMER_MAX_DIMER_TMP = 35  # max melting temp for dimers, lower temperature means more stringent filtering
 PRIMER_MAX_DIMER_DELTAG = -9000  # max allowed gibbs free energy for dimer formation, higher values mean more stringent filtering
-END_OVERLAP = 5  # maximum allowed nt overlap between primer ends
+END_OVERLAP = 5  # maximum allowed nt overlap between ends of primers to be considered a dimer
 
 # QPCR parameters
 # basic probe parameters

varvamp/scripts/logging.py

@@ -291,6 +291,7 @@ def confirm_config(args, log_file):
             "PRIMER_MAX_DINUC_REPEATS",
             "PRIMER_GC_END",
             "PRIMER_MAX_DIMER_TMP",
+            "PRIMER_MAX_DIMER_DELTAG",
             "PRIMER_MIN_3_WITHOUT_AMB",
             "PCR_MV_CONC",
             "PCR_DV_CONC",
@@ -446,15 +447,20 @@ def confirm_config(args, log_file):
         )
     if config.PRIMER_HAIRPIN < 0:
         raise_error(
-            "decreasing hairpin melting temp to negative values "
-            "will influence successful primer search!",
+            "decreasing hairpin melting temp to negative values will influence successful primer search!",
             log_file
         )
-    if config.PRIMER_MAX_DIMER_TMP < 0:
+    if config.PRIMER_MAX_DIMER_TMP < 21:
         raise_error(
-            "there is no need to set max dimer melting temp below 0.",
+            "there is no need to set max dimer melting temp below room temperature.",
             log_file
         )
+    if config.PRIMER_MAX_DIMER_DELTAG > -6000:
+        raise_error(
+            "primer interactions with deltaG values higher than -6000 are generally considered unproblematic.",
+            log_file
+        )
+
     if config.PRIMER_MAX_BASE_PENALTY < 8:
         raise_error(
             "decreasing the base penalty will filter out more primers.",
@@ -595,7 +601,6 @@ def goodbye_message():
     messages = [
         "Thank you. Come again.",
         ">Placeholder for your advertisement<",
-        "Make primers great again!",
         "Ciao cacao!",
         "And now lets pray to the PCR gods.",
         "**bibobibobop** task finished",
@@ -611,6 +616,19 @@ def goodbye_message():
         "Task failed successfully.",
         "Never gonna give you up, never gonna let you down.",
         "Have you tried turning it off and on again?",
+        "Just try it. PCR is magic!",
+        "One goat was sacrificed for this primer design to work.",
+        "You seem trustworthy. Here's a cookie!",
+        "Owwww yeah, primers done!",
+        "These primers were designed without AI assistance.",
+        "Research is fun (if you ignore the pipetting).",
+        "Balance your primers, balance your life.",
+        "Keep calm and PCR on.",
+        "In silico we trust.",
+        "May the primers be with you.",
+        "Designing primers like a boss!",
+        "Primer design completed. Time for a break!",
+        "Eureka! Your primers are ready.",
         "Look, I am your primer scheme.",
         "Quod erat demonstrandum.",
         "Miau?",

varvamp/scripts/scheme.py

@@ -5,6 +5,7 @@
 # BUILT-INS
 import heapq
 import math
+from multiprocessing import Pool
 
 # varVAMP
 from varvamp.scripts import config, primers
@@ -375,31 +376,45 @@ def test_overlaps_for_dimers(overlapping_primers, non_dimers):
                 return [first_overlap, second_overlap]
 
 
-def check_and_solve_heterodimers(amplicon_scheme, left_primer_candidates, right_primer_candidates, all_primers):
+def _solve_single_dimer(args):
+    """
+    Helper function for multiprocessing: solve a single dimer independently.
+    Returns (amp_index, primer_name, new_primer) tuples or empty list if no solution.
+    """
+    dimer, amplicon_scheme, left_primer_candidates, right_primer_candidates, non_dimers_all_pools = args
+    pool = amplicon_scheme[dimer[0][0]]["pool"]
+    non_dimers = non_dimers_all_pools[pool]
+
+    overlapping_primers = get_overlapping_primers(dimer, left_primer_candidates, right_primer_candidates)
+    new_primers = test_overlaps_for_dimers(overlapping_primers, non_dimers)
+
+    return new_primers if new_primers else []
+
+
+def check_and_solve_heterodimers(amplicon_scheme, left_primer_candidates, right_primer_candidates, all_primers, num_processes):
     """
     check scheme for heterodimers, try to find
     new primers that overlap and replace the existing ones.
-    this can lead to new primer dimers. therefore the scheme
-    is checked a second time. if there are still primer dimers
-    present the non-solvable dimers are returned
+    Uses multiprocessing to solve dimers in parallel.
     """
-
     primer_dimers, non_dimers_all_pools = test_scheme_for_dimers(amplicon_scheme)
     n_initial_dimers = len(primer_dimers)
 
     if not primer_dimers:
         return [], []
 
-    for dimer in primer_dimers:
-        # determine the pool this dimer belongs to (both primers are in the same pool)
-        pool = amplicon_scheme[dimer[0][0]]["pool"]
-        non_dimers = non_dimers_all_pools[pool]
+    # Prepare arguments for each dimer
+    args_list = [
+        (dimer, amplicon_scheme, left_primer_candidates, right_primer_candidates, non_dimers_all_pools)
+        for dimer in primer_dimers
+    ]
+
+    # Solve dimers in parallel
+    with Pool(processes=num_processes) as pool:
+        results = pool.map(_solve_single_dimer, args_list)
 
-        # get overlapping primers that have not been considered
-        overlapping_primers = get_overlapping_primers(dimer, left_primer_candidates, right_primer_candidates)
-        # test all possible primers against each other for dimers
-        new_primers = test_overlaps_for_dimers(overlapping_primers, non_dimers)
-        # now change these primers in the scheme
+    # Apply all solutions to the scheme
+    for new_primers in results:
         if new_primers:
             for amp_index, primer_name, primer in new_primers:
                 # overwrite in final scheme