Struct MafftEngine 

pub struct MafftEngine {

    pub mode: AlignmentMode,
    pub scoring_model: ScoringModel,
    pub retree: usize,
    pub gap_open: Option<f64>,
    pub gap_offset: Option<f64>,
    pub gap_extend: Option<f64>,
    pub pair_lop: Option<f64>,
    pub pair_lep: Option<f64>,
    pub pair_lexp: Option<f64>,
    pub pair_gop: Option<f64>,
    pub pair_gep: Option<f64>,
    pub pair_gexp: Option<f64>,
    pub shift_penalty_factor: Option<f64>,
    pub minimum_weight: Option<f64>,
    pub nwildcard: bool,
    pub skipiterate: Option<f64>,
    pub bestfirst: bool,
    pub nthread: usize,
    pub oneiteration: bool,
    pub pileup: bool,
    pub cluster_method: ClusterMethod,
    pub nofft: bool,
    pub allowshift: bool,
    pub unalign_level: f64,
    pub kimura_r: Option<i32>,
    pub parttree: bool,
    pub dpparttree: bool,
    pub groupsize: Option<usize>,
    pub reorder_output: bool,
    pub treein_path: Option<PathBuf>,
    pub memsavetree: bool,
    pub youngestlinkage: bool,
    pub legacy_gap_cost: bool,
    pub seed_homology: Option<LocalHomologyTable>,
    pub memsave_dp: bool,
    pub c_compat: bool,
}

The main MAFFT alignment engine.

Fields

mode: AlignmentMode

scoring_model: ScoringModel

retree: usize

Number of guide tree rebuilds. C’s FFT-NS-2 default is 2.

gap_open: Option<f64>

Gap opening penalty override (positive float, e.g. 1.53 → internal -1530). None = use default for the scoring model.

gap_offset: Option<f64>

Offset/extension penalty override (positive float, e.g. 0.123 → internal -123). None = use default.

gap_extend: Option<f64>

Gap extension penalty override (--exp). User passes a positive float (e.g. --exp 0.1); C negates internally (gexp = -1.0 * arg) and then constants() scales by (int)(scale * gexp + 0.5) (scale = 600/1000 for protein, 3*600/1000 for DNA). When Some, overrides scoring.gap.extend in the same pattern as gap_offset overrides scoring.gap.offset. Default None keeps the model default (0 for protein/DNA).

pair_lop: Option<f64>

Per-class pairwise gap params for L-INS-i (--lop / --lep / --lexp). Override the hardcoded lgop=-2.00 / laof=0.100 / lexp=-0.100 C defaults applied in the local pairwise alignment stage. Each None = use the C default.

pair_lep: Option<f64>

pair_lexp: Option<f64>

pair_gop: Option<f64>

Per-class pairwise gap params for E-INS-i generalized affine (--gop / --gep / --gexp). Override the C defaults pggop=-1.53 / pgaof=0.10 / pgexp=-0.00. Each None = use the C default.

pair_gep: Option<f64>

pair_gexp: Option<f64>

shift_penalty_factor: Option<f64>

--shiftpenalty factor for --allowshift. C’s spfactor multiplies the gap-open penalty to derive the per-cell shift cost: penalty_shift = (int)(spfactor * penalty). Default 2.0 (the C --allowshift baseline). None keeps the default.

minimum_weight: Option<f64>

--minimumweight floor applied to per-sequence weights in the intergroup-score accumulation. Threaded into RefinementParams.minimum_weight. None keeps the C default (0.00001).

nwildcard: bool

--nwildcard: fill the DNA scoring matrix’s 'n' row with round(0.25 * self_score) per residue, matching C’s constants.c::nscore. When false (default and --nzero), the N row stays at the build-time defaults (effectively zero for the unscored entries). DNA-only — protein inputs silently bypass.

skipiterate: Option<f64>

--skipiterate F threshold — mirrors C’s dvtditr -E $fixthreshold → autosubalignment = F. When F exceeds the max distance-from-tip in the guide tree, refinement is skipped entirely (matches C’s generatesubalignmentstable returning 1, which prints the “WARNING: Iterative refinement was not done” diagnostic and exits). For small F values, the port (R-3, closed 2026-06-03) generates sub-alignment clusters via mafft_tree::generate_subalignments_table and sets per-(step, side) skip flags in RefinementParams::skip_branches, mirroring C’s dvtditr.c:997-1006 includemember && !samemember gate.

bestfirst: bool

--bestfirst refinement strategy. Default false (BAATARI2, matches C MAFFT’s default). When true, refinement evaluates every branch against the same baseline alignment per iteration, picks the one with the largest gain, applies, repeats — mirroring C’s parallelizationstrategy = BESTFIRST.

nthread: usize

--thread N. C selects a different refinement implementation on nthread > 0 (tditeration.c:1433): athread walks the tree in a fixed order and converges/stops by different rules than the single-threaded loop — see RefinementParams::per_cycle_convergence. 0 (the default, and what C’s script passes for both no --thread and --thread 0) selects the single-threaded rules.

oneiteration: bool

--oneiteration “one-vs-others” refinement (C’s disttbfast -r → dooneiteration in mafft-upstream/core/disttbfast.c:2217). Runs once after the progressive merge and before regular refinement. ONLY triggered in the disttbfast-path modes (FFT-NS-2, FFT-NS-i); L/G/E-INS-i bypass it because scripts/mafft:2673 only passes -r to disttbfast, never to tbfast or dvtditr.

pileup: bool

--pileup: build a comb-tree guide via mafft_tree::Topology::pileup_chain instead of UPGMA, then run progressive merge once with no refinement (C strategy name “Pileup-NS-1”, scripts/mafft:2169). Skips distance computation entirely. Forces retree = 1 and disables --maxiterate refinement.

cluster_method: ClusterMethod

Tree-linkage method for UPGMA cluster joining. Mirrors C’s tbfast -X $sueff (scripts/mafft:264,419,422,427). Default = Mix { sueff: 0.1 } (C default). --averagelinkage → Mix { sueff: 1.0 } ≡ Average; --minimumlinkage → Mix { sueff: 0.0 } ≡ Minimum; --mixedlinkage F → Mix { sueff: F }. C’s --youngestlinkage is a separate algorithm (memory-saving k-mer tree builder with on-demand cluster distance recompute); rust wires it via self.memsavetree, which uses the same algorithm family; the dedicated --youngestlinkage port (mafft_tree::youngestlinkage_tree) is byte-identical to C (see TODO.md R-8).

nofft: bool

Disable FFT: force pure DP for all alignment steps.

allowshift: bool

Enable long-range gap shift penalty (–allowshift). In MAFFT 7.526 the warp DP itself is dead code (defs.c:54 trywarp = 0 and never set); the actual --allowshift effect is to set unalign_level = 0.8 which triggers per-step makedynamicmtx (disttbfast.c:2304). Kept as a boolean for CLI symmetry; only unalign_level > 0 has runtime effect.

unalign_level: f64

Per-step substitution-score offset = (distfromtip - unalign_level) * 600 (clamped at 0). Mirrors C specificityconsideration + dist2offset

• makedynamicmtx. 0 = disabled, 0.8 = --allowshift default.

kimura_r: Option<i32>

Kimura R parameter for DNA distance model (–kimura).

parttree: bool

Use PartTree for guide tree construction (–parttree).

dpparttree: bool

Use DP-based PartTree (–dpparttree).

groupsize: Option<usize>

Group size for PartTree partitioning (–groupsize).

reorder_output: bool

Reorder output sequences in guide-tree DFS order (–reorder). Default is input order (–inputorder), matching C MAFFT 7.526.

treein_path: Option<PathBuf>

Use a user-supplied guide tree (--treein FILE). Format matches C MAFFT’s _guidetree: nseq-1 lines of im jm len0 len1 (1-indexed, im < jm), as produced by newick2mafft.rb. When Some, distance computation and tree building are skipped — the loaded tree is used for every progressive pass (mirrors C tbfast.c:2072-2078).

memsavetree: bool

Use the memory-saving guide-tree algorithm (--memsavetree). Mirrors C MAFFT compacttree_memsaveselectable with howcompact=2 (mltaln9.c:5491) — k-mer-based distances computed on the fly with no full distance matrix. Enabled by --auto for the 100k+ bracket.

youngestlinkage: bool

--youngestlinkage — same family as memsavetree but with per-step recomputation of cluster distances after each join. C MAFFT mltaln9.c::compacttree_memsaveselectable(howcompact=2, memsave=1).

legacy_gap_cost: bool

--leavegappyregion / --legacygappenalty — disable the gap-aware DP reweighting (legacygapcost = 1, Salignmm.c:1604-1610). Restores pre-7.110 behaviour where gappy columns are scored as if fully nongap.

seed_homology: Option<LocalHomologyTable>

Seed local-homology table (--seed FILE constraints). Mirrors C MAFFT’s hat3.seed produced by multi2hat3s — pairwise korh = 'k' regions between seed sequences with opt pre-multiplied by tsuyosa = user_nseq² * 100. The table is sized to the full (seeds + user input) nseq. When Some, the engine folds these entries into its pairwise homology table (or uses them directly for non-INS-i modes) and forces iterate ≥ 2 so the refinement step picks them up (scripts/mafft:1911-1923).

memsave_dp: bool

--memsave Hirschberg DP routing. When true and the non-FFT progressive merge would call profile_align, route through mafft_align::msalignmm instead (linear-space DP — mirrors C MAFFT’s MSalignmm in tbfast.c:1159-1161 under alg='M'). For inputs that fit in memory the alignment is the same as profile_align; only memory usage differs.

c_compat: bool

--c-compat opt-in: replicate C MAFFT’s Salignmm.c::A__align static-TLS memoization (reuseprofiles / cpmx_calc_add) so tied-DP-cell choices match C bit-for-bit at the cost of carrying per-thread cross-call state. Default false (stateless, pure progressive engine). Enable to reproduce C’s output on inputs where the §B.2 / BALIBASE-corpus residual divergences matter for downstream byte-equality requirements. See the BB20027 deep-dive in balibase_parity_run.md for the diagnosis (historical: every BALIBASE fixture is now byte-identical without it).

Implementations

impl MafftEngine

pub fn new(mode: AlignmentMode) -> Self

pub fn with_c_compat(self, c_compat: bool) -> Self

Enable --c-compat: replicate C MAFFT’s static-TLS cpmx memoization so tied-DP-cell choices match C bit-for-bit.

pub fn with_retree(self, retree: usize) -> Self

Set the number of guide tree rebuilds.

pub fn with_gap_open(self, op: f64) -> Self

Set gap opening penalty (positive float, e.g. 1.53).

pub fn with_gap_offset(self, ep: f64) -> Self

Set offset/extension penalty (positive float, e.g. 0.123).

pub fn with_parttree(self, parttree: bool) -> Self

Use PartTree for guide tree (–parttree).

pub fn with_dpparttree(self, dpparttree: bool) -> Self

Use DP-based PartTree (–dpparttree).

pub fn with_groupsize(self, groupsize: usize) -> Self

Set group size for PartTree (–groupsize).

pub fn with_kimura(self, kimura_r: i32) -> Self

Set Kimura R parameter for DNA distance model (default 2).

pub fn with_allowshift(self, allowshift: bool) -> Self

Enable long-range gap shift penalty (CLI symmetry only — see field docstring; only unalign_level > 0 has runtime effect).

pub fn with_unalign_level(self, level: f64) -> Self

Set per-step dynamic-matrix offset (specificityconsideration). Disabled at 0.0; --allowshift defaults to 0.8.

pub fn with_nofft(self, nofft: bool) -> Self

Disable FFT: force pure DP for all alignment steps.

pub fn with_reorder(self, reorder: bool) -> Self

Emit output sequences in guide-tree DFS order (--reorder). When false (default), output stays in input order (--inputorder).

pub fn with_scoring_model(self, model: ScoringModel) -> Self

Set scoring model (e.g. BLOSUM with specific number).

pub fn align(&self, input: &SequenceSet) -> MultipleAlignment

Align a set of sequences.

pub fn add_to_alignment( &self, existing_input: &SequenceSet, new_input: &SequenceSet, keeplength: bool, ) -> MultipleAlignment

Add new sequences to an existing alignment.

existing_input is the already-aligned MSA (FASTA with gaps). new_input contains the new unaligned sequences to add. keeplength if true, preserves the existing alignment’s column structure.

pub fn add_to_alignment_with_map( &self, existing_input: &SequenceSet, new_input: &SequenceSet, ) -> (MultipleAlignment, Vec<Vec<(usize, usize)>>)

Same as [add_to_alignment] with keeplength = true, but also returns the per-added-sequence list of dropped insertion runs. Used by --mapout / --compactmapout to emit the .map file. Each entry is (start_pos_in_addbk_0based, run_length).

pub fn align_file(&self, path: &Path) -> Result<MultipleAlignment, IoError>

Convenience: read FASTA file and align.

Trait Implementations

impl Clone for MafftEngine

fn clone(&self) -> MafftEngine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MafftEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MafftEngine

fn default() -> Self

Returns the “default value” for a type.