libnanoLicense: Primer3 has a GPL-2.0 license. Please refer to the license for full terms.
Proto is not affiliated with libnano. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.
libnano/primer3-py
Primer3—new capabilities and interfaces
evo-design/proto-tools/proto_tools/tools/sequence_scoring/primer3Open Notebook
Open notebook
Toolkit contributors
nndahiro
nndahiroBackground
Primer3 (Untergasser et al., 2012) is the de-facto standard engine for primer design and evaluation. Its thermodynamic calculations use the nearest-neighbor model, which predicts duplex stability from the stacking energies of adjacent base pairs rather than a naive base count, and applies salt and concentration corrections so that the predicted melting temperature reflects the actual reaction buffer. The free energy (ΔG) of a self-folded hairpin, a self-dimer (homodimer), or a cross-dimer between two oligos (heterodimer) is reported in kcal/mol: a more negative ΔG means a more stable — and therefore more problematic — secondary structure that competes with productive priming. For a primer to amplify cleanly, its melting temperature must sit in a workable band, its two ends should not fold back on themselves or pair with a partner, and its 3’ end should anchor stably to the template. These constraints are what the metrics below quantify. A ΔG of0.0 with the corresponding structure flag False is the favorable case: no significant structure was found. Thermodynamic conditions (monovalent and divalent cation, dNTP, and oligo concentrations) shift every prediction, so they are exposed as configuration and default to Primer3’s own defaults for reproducibility against the upstream tool.
Learning Resources
- primer3-py documentation (libnano) - API reference for the
calc_tm,calc_hairpin,calc_homodimer, andcalc_heterodimerfunctions wrapped here, including every thermodynamic parameter. - Primer3 manual (Untergasser, Rozen, et al.) - the authoritative description of Primer3’s parameters, salt-correction formulas, and design logic.
- Top ten pitfalls in quantitative real-time PCR primer/probe design (Thermo Fisher) - practical target ranges and failure modes for qPCR assay design.
Tools
Primer3 Thermodynamics (primer3-thermodynamics)
Scores each input DNA oligo for melting temperature, hairpin/homodimer ΔG, GC content, and 3’ GC-clamp, plus heterodimer ΔG against an optional partner oligo.API Reference
Source
Input: Primer3ThermodynamicsInput
Input: Primer3ThermodynamicsInput
List[Primer3Oligo]
required
Oligos to score. A bare DNA string, a
{"sequence": ..., "partner": ...} dict, or a single oligo are all accepted and coerced to a one-element list. Results are returned in input order. Source
Config: Primer3ThermodynamicsConfig
Config: Primer3ThermodynamicsConfig
number
default:"50.0"
Monovalent cation concentration in mM. Default 50.0.
number
default:"1.5"
Divalent cation (Mg2+) concentration in mM. Default 1.5.
number
default:"0.6"
dNTP concentration in mM. Default 0.6.
number
default:"50.0"
Oligo (DNA) concentration in nM. Default 50.0.
number
default:"37.0"
Temperature in °C for hairpin/dimer ΔG. Default 37.0.
integer
default:"0"
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr).
True is coerced to 1 and False to 0.string
default:"cpu"
Device to run the tool on.
integer
default:"3600"
Maximum execution time in seconds.
None waits indefinitely.integer
Random seed. When set, tools run reproducibly up to small GPU float noise (see
BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.Applications
Use this to screen candidate PCR and qPCR primers before ordering them, or as the scoring step inside a primer-selection pipeline. Pair a forward primer with its reverse as itspartner to check the primer pair for cross-dimerization, the most common cause of a failed or noisy amplification.Usage Tips
- For qPCR, aim for Tm 58–62 °C, GC 40–60%, and a GC clamp. Keep the two primers of a pair within ~1 °C of each other.
gc_clamp=True(a G or C in the last two 3’ bases) helps 3’ anchoring, but avoid more than three G/C in the last five bases to prevent mispriming. - Treat ΔG thresholds as guidelines: hairpin > −2 kcal/mol, homodimer and heterodimer > −6 kcal/mol. More negative values indicate stable competing structures. Because ΔG depends on temperature, set
temp_cto your annealing temperature (default 37 °C) for the most relevant hairpin/dimer numbers. - Defaults match primer3-py, not a qPCR preset.
dv_conc=1.5,dntp_conc=0.6, anddna_conc=50reproduce Primer3 directly. Typical qPCR conditions are closer todv_conc≈3,dntp_conc≈0.8,dna_conc≈200–250; set them explicitly to match your master mix, since they shift Tm and every ΔG.
Toolkit Notes
These apply to the Primer3 tool in this toolkit (primer3-thermodynamics).
- Runs on CPU, no model weights. primer3-py compiles the Primer3 C library into its wheel, so a single
pip installprovides everything; there is no GPU path and nothing to download at first use. - Inputs are strictly A/C/G/T. Sequences are uppercased and validated; degenerate bases (
N, IUPAC ambiguity codes) are rejected because the nearest-neighbor model needs concrete bases. - Scoring is per-oligo and batchable. Pass a list of oligos to score them in one call; results are returned in input order. Bundle a
partnerwith an oligo to compute its heterodimer ΔG.
Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.Tool Persistence
Keep a tool’s model warm across calls instead of reloading it every invocation.
Device Management
How GPUs are allocated to tools and how to target specific devices.
Parallel Execution
Fan a batch of inputs out across multiple GPUs.