Version Compatibility

Reference examples tested with: primer3-py 2.3+.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show primer3-py then help(primer3.calc_heterodimer) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Primer Validation -- Thermodynamic Self-Structure of the Chosen Oligos

"Are these primers free of dimers and hairpins?" -> Predict the most stable intramolecular and inter-primer structures and judge them at the reaction conditions -- because a structure's harm is set by its dG at the annealing temperature and by whether it ties up the 3' end, not by a single global score.

• Python: primer3.calchairpin(seq), calchomodimer(seq), calcheterodimer(seq1, seq2), calcendstability(seq1, seq2) return a ThermoResult with .tm, .dg, .structurefound.

Scope: thermodynamic validation of the OLIGOS themselves (hairpin, homodimer, heterodimer, 3'-end stability, pair Tm match) under stated conditions. Genome-wide off-target / mispriming / in-silico PCR -> primer-specificity. Designing primers -> primer-basics. qPCR primer+probe co-design -> qpcr-primers.

The Single Most Important Modern Insight -- A "Dimer-Free" Verdict Is a Prediction at the Conditions Supplied, and the 3' End Is What Kills the Reaction

1. These are predictions, not facts. calchairpin/calchomodimer/calcheterodimer compute a dG/Tm under a specific monovalent/divalent/dNTP/oligo concentration and an evaluation temperature (tempc). The same primer can read "fine" at default 37 C / default salt and "dimer-prone" at the real annealing temperature and Mg2+. Validate at the conditions and temp_c of the actual reaction, or the verdict is decorative.
2. The 3' end is the lethal locus. A dimer or hairpin that pairs the primer's 3' end is polymerase-EXTENDABLE: it gets turned into primer-dimer that amplifies exponentially, consumes reagents, and (in SYBR qPCR) generates competing signal. A structure with a more negative GLOBAL dG but a free 3' end is far less harmful. So do NOT rank by global dG or global Tm -- inspect 3'-end involvement (calcendstability and the ASCII structure) and judge at the annealing temperature.
3. Read the units and the gate. ThermoResult.dg, .dh are in cal/mol (and .ds in cal/(K.mol)) -- a value of -6000 is -6 kcal/mol, so divide by 1000 before comparing to kcal/mol heuristics. Always check .structure_found first: if no structure formed, the .tm/.dg are not a real duplex.

The Three Structures, and Why They Differ

• Hairpin (intramolecular): the primer folds on itself; harmful mainly when it sequesters the 3' end or raises effective Tm enough to block template annealing.
• Homodimer (self-dimer): two copies of one primer pair; common with self-complementary or palindromic primers.
• Heterodimer (cross-dimer): the forward and reverse primers pair with each other. A primer can be individually clean and still cross-dimer with its partner, so the pair must be checked explicitly -- this is the dimer most often missed.

Tool Taxonomy

Decision Tree by Scenario

Default when uncertain: run the four-call panel at the real salt/Mg/dNTP/oligo concentrations with temp_c set to the annealing temperature, flag any structure whose dG is strongly negative at Ta, and weight 3'-end involvement most.

Validate a Primer Pair at Reaction Conditions

Goal: Decide whether a chosen forward/reverse pair will misbehave through hairpins or dimers in the actual reaction, with the 3' end weighted appropriately.

Approach: Run hairpin and homodimer on each primer and heterodimer on the pair, all at the reaction's salt/Mg/dNTP/oligo concentrations and with tempc set to the annealing temperature; gate every result on .structurefound; additionally compute calcendstability on the heterodimer to expose 3'-anchored (extendable) dimers; compare the two primer Tms for a match.

import primer3

fwd, rev = 'GTCTCCTCTGACTTCAACAGCG', 'ACCACCCTGTTGCTGTAGCCAA'
COND = dict(mv_conc=50.0, dv_conc=3.0, dntp_conc=0.8, dna_conc=250.0, temp_c=60.0)  # match the qPCR/PCR reaction + Ta

def flag(label, res):
    if res.structure_found:
        print(f'{label}: Tm={res.tm:.1f}C dG={res.dg/1000:.2f} kcal/mol')   # dg is cal/mol -> /1000
    else:
        print(f'{label}: no structure')

for name, seq in [('fwd', fwd), ('rev', rev)]:
    flag(f'{name} hairpin', primer3.calc_hairpin(seq, **COND))
    flag(f'{name} homodimer', primer3.calc_homodimer(seq, **COND))

flag('heterodimer', primer3.calc_heterodimer(fwd, rev, **COND))
end = primer3.calc_end_stability(fwd, rev, **COND)            # 3'-end-anchored stability = the extendable-dimer risk
print(f"3'-end stability dG={end.dg/1000:.2f} kcal/mol")

dtm = abs(primer3.calc_tm(fwd, **{k: COND[k] for k in ('mv_conc','dv_conc','dntp_conc','dna_conc')})
          - primer3.calc_tm(rev, **{k: COND[k] for k in ('mv_conc','dv_conc','dntp_conc','dna_conc')}))
print(f'pair Tm difference={dtm:.1f}C')

Reading the Result: dG, the 3' End, and the Structure

ThermoResult.dg is in cal/mol (divide by 1000 for kcal/mol). More negative = more stable = more concerning. But two structures with similar Tm can have very different dG at the annealing temperature, and the structure's own Tm is just where its dG crosses zero -- so judge by dG at tempc = Ta, not by Tm. Print res.asciistructure (or res.asciistructurelines) to SEE where the duplex sits: a dimer that pairs the recessed 3' ends is extendable and disqualifying even at modest dG, while a stronger structure with free 5'/internal pairing only transiently lowers free primer. calcendstability(fwd, rev) isolates exactly the 3'-end-of-fwd-against-rev stability, which is the right number for "will this dimer extend." It scores the 3' end of the FIRST argument, so check both directions (also calcendstability(rev, fwd)) -- either primer's 3' end can anchor the extendable dimer.

Per-Method Failure Modes

Ranking dimers by global dG or Tm

Trigger: Accepting/rejecting a structure on its overall dG or Tm. Mechanism: a weak dimer that locks the 3' ends is extended into artifact, while a strong dimer with free 3' ends is benign. Symptom: a "passing" pair still produces primer-dimer; a "failing" pair amplifies fine. Fix: inspect 3'-end involvement (calcendstability, ASCII structure) and weight it above whole-molecule dG.

Validating at the wrong temperature/conditions

Trigger: Using default tempc=37 and default salt instead of the reaction's Ta and Mg2+. Mechanism: structure stability is strongly condition-dependent; a structure that melts below Ta is harmless. Symptom: false alarms (or false passes) that do not match the bench. Fix: set tempc to the annealing temperature and pass the real mv/dv/dntp/dna concentrations.

Trusting dG without a structure

Trigger: Reading .dg/.tm without checking .structurefound. Mechanism: when no structure forms the fields are not a real duplex. Symptom: nonsense or contradictory numbers. Fix: gate every result on .structurefound before reporting.

Unit confusion (cal vs kcal)

Trigger: Comparing .dg directly to a kcal/mol threshold. Mechanism: primer3-py reports dG in cal/mol, so -6000 is -6 kcal/mol. Symptom: thresholds off by 1000x; everything looks catastrophic or fine. Fix: divide .dg by 1000 before comparing.

Validating only the binding core of a tailed primer

Trigger: Checking the template-binding portion of a primer that carries a 5' tail. Mechanism: the full oligo (tail included) is what physically exists; palindromic restriction sites and complementary Gibson arms dimerize. Symptom: clean validation, dimers on the bench. Fix: run the calls on the FULL tailed oligo.

Quantitative Thresholds

These are FLAGGING heuristics for inspection, not hard cutoffs; they are condition-dependent (salt, Mg2+, primer concentration, Ta). Read the structure and judge at Ta before accepting or rejecting.

Common Errors

References

• Untergasser A, Cutcutache I, Koressaar T, et al. 2012. Primer3 - new capabilities and interfaces. Nucleic Acids Res 40:e115.
• SantaLucia J Jr, Hicks D. 2004. The thermodynamics of DNA structural motifs. Annu Rev Biophys Biomol Struct 33:415-440.
• SantaLucia J Jr. 1998. A unified view of polymer, dumbbell, and oligonucleotide DNA nearest-neighbor thermodynamics. PNAS 95:1460-1465.
• Koressaar T, Remm M. 2007. Enhancements and modifications of primer design program Primer3. Bioinformatics 23:1289-1291.
• Kwok S, Kellogg DE, McKinney N, et al. 1990. Effects of primer-template mismatches on the polymerase chain reaction: human immunodeficiency virus type 1 model studies. Nucleic Acids Res 18:999-1005.

Related Skills

• primer-basics - Design Tm-matched primer pairs (redesign if validation fails)
• primer-specificity - Genome-wide off-target / in-silico PCR (a different question)
• qpcr-primers - Co-design qPCR primers and probes, including probe self-structure
• sequence-manipulation/seq-objects - Reverse-complement and assemble tailed oligos to validate