Thermodynamic calculations and interpretation

Documentation checked: 2026-10-01 against primer3-py 2.3.1 documentation. Use the version recorded by the actual run to describe tested behavior.

Record the physical assumptions

Nearest-neighbor predictions use sequence context and specified solution conditions. They do not make an oligo's Tm an invariant property. The unified DNA parameter framework is described by SantaLucia (1998); mixed monovalent and magnesium effects require appropriate correction, as studied by Owczarzy et al. (2008).

These parameter units are documented in the primer3-py quickstart. For proprietary mixes with undisclosed composition, label chosen values as assumptions and compare plausible conditions if necessary. Never back-fill exact chemistry from the name of a kit.

PRIMER_DNA_CONC is an effective concentration of annealing oligos during PCR; the Primer3 manual distinguishes it from initial reaction primer concentration. Record both and explain the model choice. The supplied checker uses the entered dna_conc for core Tm and structures, so comparisons share that assumption. The native calc_tm API supports DMSO/formamide, but the bundled adapter does not expose them; its results assume zero additive correction. Primer3 concentration convention.

Native Primer3 can return a finite -273.15°C Tm at zero effective salt. The checker rejects Tm at/below absolute zero as invalid, alongside NaN/infinite output; it does not convert these to valid low-temperature candidates. This guard is not a complete test that a buffer lies within the model's calibrated range.

Calculate several distinct quantities

Use the snake_case APIs: calc_tm, calc_hairpin, calc_homodimer, calc_heterodimer, and calc_end_stability. The end-stability calculation is directional; examine both oligo orders when either primer's 3′ end matters. Do not reverse-complement an oligo before passing synthesized sequences to the structure routines. API definitions.

For each oligo record its annealing-core Tm, GC fraction, and length, then review hairpin and self-dimer results for the full ordered sequence. For each interacting pair record heterodimer and both directional 3′-end assessments. Preserve predicted structure alignments when available so the location of terminal complementarity can be inspected.

ThermoResult.dg and .dh use cal/mol; .ds uses cal/(mol·K); .tm uses °C. Divide energy by 1000 before displaying kcal/mol. Store structure_found: missing structures and zero-valued fields are not interchangeable evidence. ThermoResult documentation.

Keep screening thresholds in context

• A low difference between primer Tm values supports compatible conditions but says nothing about reference specificity or amplification efficiency.
• A predicted favorable dimer ΔG does not by itself show that the polymerase can extend that alignment. Inspect 3′ placement as well as thermodynamic stability.
• Compare energies only at matched temperatures, concentrations, and model settings. Comparing one program's default ΔG with another's numeric cutoff is unreliable.
• A candidate close to a chosen limit deserves sensitivity analysis, not unwarranted numerical precision. Report useful decimals while retaining raw output.

Thresholds are selection criteria chosen for a particular assay. They are not universal scientific pass/fail constants. Retain the assumptions, threshold definition, observed value, and reason for any override.

Predicted Tm is not an automatic annealing temperature. Follow the selected polymerase's current instructions and validate an appropriate condition range. Even manufacturer protocols differ; for example, NEB's Q5 annealing-temperature study and Phusion Flash guidance use product-specific recommendations. A temperature tested on one enzyme, formulation, or target collection does not establish performance for another.

Model and implementation boundaries

The documented calc_tm nearest-neighbor path applies up to its configured length limit, normally 60 bases; longer sequences switch to an approximation. Structure routines also have length limits. The bundled checker constrains ordinary oligos instead of silently using unsupported long-tail calculations. Check runtime errors and emitted limits rather than inferring successful analysis from a partial table. primer3-py API.

Do not substitute ambiguity symbols, RNA, inosine, or modified bases into an ACGT DNA model and call the result validated. Modified chemistries require appropriate parameters; for example, LNA substitutions affect both stability and sequence-dependent mismatch discrimination. LNA thermodynamics study.

For tailed primers, model the core's initial template interaction separately from full-oligo structures. For degenerate mixtures, a single “consensus Tm” hides the different species and effective concentrations. For multiplex panels, include cross-pair interactions and disclose any capped enumeration.

Reproducibility and implementation checks

Record Python, primer3-py, and underlying libprimer3 versions, full sequence inputs, all chemistry/model settings, warnings, and raw results. Test that:

1. Tm changes appropriately when chemistry inputs change; values were not replaced by a fixed rule based only on GC count.
2. Displayed energy units match raw values and conversions.
3. Swapping oligos preserves symmetric dimer comparisons while directional end results retain their correct orientation.
4. An invalid or unsupported sequence is reported as unassessed, never silently shortened, stripped of modifications, or replaced with an arbitrary base.
5. Tails are included in full-oligo interaction analysis and excluded from the initial binding-core Tm and ordinary reference search.