Crate primer3 

primer3

Safe, idiomatic Rust bindings to the primer3 C library for PCR primer design and oligonucleotide thermodynamic calculations.

Quick Start

Melting Temperature

use primer3::calc_tm;

let tm = calc_tm("GTAAAACGACGGCCAGT").unwrap();
println!("Tm = {tm:.1}°C");

Thermodynamic Analysis

use primer3::{calc_hairpin, calc_homodimer, calc_heterodimer};

let hairpin = calc_hairpin("CCCCCATCCGATCAGGGGG").unwrap();
println!("Hairpin Tm = {:.1}°C, dG = {:.0} cal/mol", hairpin.tm(), hairpin.dg());

let dimer = calc_heterodimer("AAAAAAAAAA", "TTTTTTTTTT").unwrap();
println!("Heterodimer Tm = {:.1}°C", dimer.tm());

Primer Design

use primer3::{design_primers, SequenceArgs, PrimerSettings};

let seq_args = SequenceArgs::builder()
    .sequence("ATCGATCG...")
    .target(100, 200)  // start=100, length=200
    .build()
    .unwrap();

let settings = PrimerSettings::builder()
    .primer_opt_tm(60.0)
    .primer_min_tm(57.0)
    .primer_max_tm(63.0)
    .product_size_range(75, 150)
    .build()
    .unwrap();

let result = design_primers(&seq_args, &settings, None, None).unwrap();
for pair in result.pairs() {
    println!("{}", pair.left().sequence());
}

Thread Safety

The underlying C library uses global state for thermodynamic parameters, which are compiled in from thal_default_params.h (no file I/O needed). Thermodynamic calculation functions (calc_tm, calc_hairpin, etc.) are safe to call concurrently. Both design_primers() and align() are mutex-guarded because the underlying C routines use mutable global state (primer3’s internal bookkeeping and dpal’s ~40 MB scoring/traceback matrices, respectively).

Defaults

This crate uses primer3 C library v2 defaults (p3_create_global_settings()). Some defaults differ from primer3-py – consult the primer3 manual for details.

Modules

boulder

Boulder I/O format support for primer3 interoperability.

Structs

AlignmentArgs

Parameters for dynamic programming alignment.

AlignmentResult

Result of a dynamic programming alignment.

DesignResult

Complete result of a primer design run.

Interval

A genomic interval as (start, length), both 0-based.

OkRegionPair

A pair of OK regions for left and right primers.

OligoSettings

Settings for an individual primer or internal oligo.

OligoWeights

Weights for scoring individual primers or oligos.

PairWeights

Weights for scoring primer pairs.

PrimerPair

A primer pair (left + right + optional internal oligo).

PrimerRecord

An individual primer or oligo record.

PrimerSettings

Global settings for primer design.

PrimerSettingsBuilder

Builder for PrimerSettings.

SequenceArgs

Per-sequence arguments for primer design.

SequenceArgsBuilder

Builder for SequenceArgs.

SequenceLibrary

A library of sequences for mispriming or mishybridization checks.

SolutionConditions

Salt and buffer concentrations for thermodynamic calculations.

ThermoArgs

Parameters for thermodynamic calculations (hairpin, dimer, end stability).

ThermoResult

Result of a thermodynamic calculation (hairpin, dimer, or end stability).

TmParams

Parameters for Tm calculation.

Enums

AlignmentMode

Alignment mode specifying how sequences are aligned.

AlignmentOutput

Output mode for alignment computation.

OligoType

Type of oligo (left primer, right primer, or internal probe).

Primer3Error

Errors that can occur when using the primer3 library.

PrimerTask

The task that primer3 should perform.

SaltCorrectionMethod

Method for salt concentration correction.

TmMethod

Method for calculating melting temperature.

Constants

MAX_ALIGN_LENGTH

Maximum sequence length for alignment (1600 bp).

Functions

align

Performs dynamic programming alignment of two DNA sequences.

calc_end_oligodg

Calculates the delta G (Gibbs free energy) of the last len bases of a DNA oligonucleotide using the nearest-neighbor model.

calc_end_oligodg_with

Calculates the delta G of the last len bases with a specific Tm method.

calc_end_stability

Calculates 3’ end stability of seq1 hybridized against seq2.

calc_end_stability_with

Calculates 3’ end stability with custom parameters.

calc_hairpin

Calculates hairpin formation thermodynamics for a DNA sequence.

calc_hairpin_with

Calculates hairpin formation thermodynamics with custom parameters.

calc_heterodimer

Calculates heterodimer formation thermodynamics between two DNA sequences.

calc_heterodimer_with

Calculates heterodimer formation thermodynamics with custom parameters.

calc_homodimer

Calculates homodimer formation thermodynamics for a DNA sequence.

calc_homodimer_with

Calculates homodimer formation thermodynamics with custom parameters.

calc_oligodg

Calculates the delta G (Gibbs free energy) of disruption of a DNA oligonucleotide using the nearest-neighbor model.

calc_oligodg_with

Calculates the delta G of disruption with a specific Tm method.

calc_tm

Calculates the melting temperature of a DNA sequence using default parameters.

calc_tm_with

Calculates the melting temperature of a DNA sequence with custom parameters.

design_primers

Designs primers for the given sequence using the specified settings.

divalent_to_monovalent

Converts divalent cation concentration to an equivalent monovalent concentration using the primer3 formula.

is_symmetric

Returns true if the DNA sequence is self-complementary (palindromic).

reverse_complement

Returns the reverse complement of a DNA sequence.

Type Aliases

Result

A Result type alias using Primer3Error.