> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Primer3
> [primer3-py](https://github.com/libnano/primer3-py) is a Cython binding to the [Primer3](https://primer3.org/) C library for oligonucleotide thermodynamics. This tool wraps its nearest-neighbor calculators to score a DNA oligo (and an optional partner) for melting temperature, hairpin and dimer stability, GC content, and 3' GC-clamp — the core filters used to judge whether a primer is fit for [qPCR](https://en.wikipedia.org/wiki/Real-time_polymerase_chain_reaction) and general PCR.
**License:** Primer3 has a GPL-2.0 license. Please refer to [the license](https://github.com/libnano/primer3-py/blob/master/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.
```bibtex theme={null}
@article{untergasser2012primer3,
title={Primer3--new capabilities and interfaces},
author={Untergasser, Andreas and Cutcutache, Ioana and Koressaar, Triinu and Ye, Jian and Faircloth, Brant C. and Remm, Maido and Rozen, Steven G.},
journal={Nucleic Acids Research},
volume={40},
number={15},
pages={e115},
year={2012},
publisher={Oxford University Press},
doi={10.1093/nar/gks596}
}
```
| Function | Description | |
| ------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_primer3_thermodynamics()` | Score DNA oligos for Tm, hairpin/homodimer/heterodimer ΔG, GC content, and GC-clamp | Docs Source |
## Background
Primer3 ([Untergasser et al., 2012](https://doi.org/10.1093/nar/gks596)) is the de-facto standard engine for primer design and evaluation. Its thermodynamic calculations use the [nearest-neighbor model](https://en.wikipedia.org/wiki/Nucleic_acid_thermodynamics), 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](https://en.wikipedia.org/wiki/Nucleic_acid_thermodynamics#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 of `0.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](https://libnano.github.io/primer3-py/) (libnano) - API reference for the `calc_tm`, `calc_hairpin`, `calc_homodimer`, and `calc_heterodimer` functions wrapped here, including every thermodynamic parameter.
* [Primer3 manual](https://primer3.org/manual.html) (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](https://www.thermofisher.com/us/en/home/references/ambion-tech-support/rtpcr-analysis/general-articles/top-ten-pitfalls-in-quantitative-real-time-pcr-primer.html) (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
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.
DNA oligo (A/C/G/T only). Scored for Tm, hairpin, homodimer, GC content, and 3' GC-clamp.
Optional second oligo. When set, heterodimer ΔG is computed between `sequence` and `partner` (e.g. a forward primer with its reverse partner). None ⇒ heterodimer\_dg is null.
Source
Monovalent cation concentration in mM. Default 50.0.
Divalent cation (Mg2+) concentration in mM. Default 1.5.
dNTP concentration in mM. Default 0.6.
Oligo (DNA) concentration in nM. Default 50.0.
Temperature in °C for hairpin/dimer ΔG. Default 37.0.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
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.
Source
Per-oligo scores, in input order.
Positional label of the input oligo (`oligo_0` ...).
Oligo length in nucleotides.
Melting temperature in °C.
Hairpin ΔG in kcal/mol (more negative = more stable).
Self-dimer ΔG in kcal/mol.
Cross-dimer ΔG with the partner, or None when no partner was supplied.
Fraction of G/C bases, 0-1.
True if either of the last two 3' bases is G or C.
Whether a hairpin structure was found.
Whether a homodimer structure was found.
Whether a heterodimer was found, or None when no partner was supplied.
#### 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 its `partner` 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_c` to 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`, and `dna_conc=50` reproduce Primer3 directly. Typical qPCR conditions are closer to `dv_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 install` provides 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 `partner` with an oligo to compute its heterodimer ΔG.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/55339880a8d5da4f1c7677518bcf90974a6365b7/proto_tools/tools/sequence_scoring/primer3/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/sequence\_scoring/primer3
nndahiro
libnano
