Historical v2 release notes, retained for legacy users. These describe the interface and behavior of this version. See the current release overview for v3 availability and migration guidance.

Release v2.5.0

Release Date: August 31, 2026

Additions

  • TI_normal for mTI — multipolar simulations now write the normal-component envelope ({montage}_mTI_normal.msh) by default, computed by evaluating the multi-carrier envelope along the cortical surface normal; the analyzer’s normal_* ROI statistics populate for mTI exactly as for standard TI.
  • fsaverage projection for mTI — map_to_fsavg no longer skips multipolar runs: the modulation depth is read from the mTI central surface and hf_peak/hf_sar are derived from all N channel volume meshes.
  • Multipolar exhaustive search (mex-search) — a multipolar counterpart to ex-search (tit/opt/mex), with a TI/mTI toggle, symmetric (bilateral) buckets, atlas-region and MNI-space ROI targeting, and a shared searchable ROI picker across ex-search and mTI.
  • Threshold-free focality goal for flex-search — a new opt-in focality objective plus an opt-in current-ratio search, replacing threshold-dependent focality scoring.
  • Selectable output fields — the simulator now writes only the fields you choose (TI_max by default) instead of a fixed set, with field definitions documented in the help popup.
  • Custom subject masks as ROI targets — label volumes placed under m2m_<id>/masks/ are auto-discovered and offered as subcortical ROI targets in flex/ex/mex-search and the analyzer.
  • Unified TI/mTI field metrics — carrier grouping, hf_peak sign handling, and the TI/mTI metric surface were corrected and unified across calc, sim and the analyzer, closing several description/code mismatches; a literature-grounded field-metrics note documents the math.
  • DWI preflight validation — gradient tables and sidecars are validated and QSIPrep node crashfiles are logged before/at container failure, catching bad DWI conversions early.
  • Interactive atlas browser and multipolar TI documentation pages on the docs site, including subject-space atlas assets and a redesigned full-width docs theme with per-page subnav and KaTeX equation rendering.
  • Claude Code / AI-assistant plugin (agent-plugin/) — an MCP server and marketplace listing so AI coding assistants understand the TI-Toolbox codebase, plus a maintainer-verified Troubleshooting Archive.
  • Faster ex/mex-search — unit-current channel fields are now computed once per montage and reused across current splits, the TI/mTI envelope is evaluated on ROI∪GM only (not the whole head), and candidates run on a forked worker pool (n_jobs). Ex-search: 0.39 s → 0.05 s per evaluation (~8×; a 4,375-evaluation bucket search dropped from 28 min to 3 min). Mex-search: 58 s → ~1.4–2 s per candidate (~30–40×) via a fused numba kernel for the K≥2 mTI direction search.
  • Ex/mex-search electrode-map visuals — every ex/mex-search run now writes an electrode participation heatmap and montage strength/focality maps, ported from work by Larissa Albantakis on her ex-search-multipolar branch.
  • Zenodo DOIs added for the archived software release.

Changes

  • Breaking: tit.calc consolidated to exactly three envelope functions — get_TI_vectors(fields, psi=None) (K ≥ 1 carriers; the K = 1 exact closed form is applied internally), get_TI_avg(fields, psi=None), and get_TI_dir(fields, directions, psi=None). Scripts calling get_TI_vectors(E1, E2) positionally must switch to get_TI_vectors([E1, E2]); get_mTI_vectors is now get_TI_vectors, get_mTI_dir is get_TI_dir, and the deprecated get_nTI_vectors shim and the unused get_magnitude_am were removed, as was the legacy channels= carrier-regrouping parameter.
  • Carrier wiring removed — mTI is always positional (each two consecutive electrodes compose a channel, each two consecutive channels compose a carrier): the mex-search “Carrier Wiring” combo, MTI_CHANNEL_ARCHITECTURES, and the channels JSON config keys are gone (old configs with the key are ignored).
  • Documentation vocabulary unified across the simulator, analyzer and ex-search pages: electrodes → channels (2 electrodes each) → carriers (shared by 2 channels); TI = 4 electrodes / 2 channels / 1 carrier, mTI = 8 electrodes / 4 channels / 2 carriers.

Fixes

  • Analyzer sim-list bug fix, plus analyzer/ex-search layout cleanups (paired Tissue/Space and Field/Type controls, either/or ROI selection, dead vertical space removed).
  • Ex-search now rejects empty ROI configs, tolerates header rows in MNI ROI CSVs, and fails cleanly on zero candidates instead of silently returning nothing.
  • Flex-search summary.txt no longer prints a raw Python function repr on the Goal line.
  • QSIPrep/QSIRecon fixes — the root BIDS dataset description is always created, a missing T1w is reported up front, QSIRecon’s log directory is no longer mistaken for existing output, and a converted DWI arriving without its gradient table now warns instead of failing silently.
  • DICOM import — a converted DWI missing its gradient table is now caught and reported.
  • Atlas resampling in the analyzer — atlases and tissue masks are now matched to the field on shape and affine and resampled nearest-neighbour, replacing a shape-only check and an interpolating mri_convert call that also required FreeSurfer binaries absent from the simulation container. See the note below.
  • Docs — corrected stale ROI, tissue, atlas, CLI and testing-pipeline claims across the wiki, scripting, ex-search and analyzer pages; fixed release download links and a blank atlas viewer for cached scripts.
  • Dev loader — loader_dev.sh rewritten as a working Python-free bash loader after regressions.

Note: atlas resampling in the analyzer

The analyzer’s grid check compared shape only, so an atlas with matching dimensions but a different affine could pass through untouched and produce statistics for the wrong tissue, silently. Resampling also used mri_convert --reslice_like, whose default trilinear interpolation blends discrete region ids into ids that belong to no region. The check now compares the affine too, resampling is nearest-neighbour, and neither step needs FreeSurfer binaries that the simulation container does not ship.

Old versus new atlas resampling in v2.5.0

This is a robustness fix, not a result-changing one. Interpolation order only matters when the atlas and field lattices do not coincide, which for the 1 mm FreeSurfer parcellations, the thalamic nuclei and every MNI atlas they do — old and new are bit-identical there. The one exception is the 0.333 mm hippocampal and amygdala subfields, shown above: even in that worst case the reported field changes by ~0.5% (mean −0.6%, max −1.2%) while the ROI volume changes by −42%, because trilinear erodes the region’s boundary. Field statistics from earlier versions stand; ROI voxel counts and volumes from a hippocampal or amygdala subfield ROI are worth regenerating. Details on the Brain Atlases page.

Desktop App (v2.5.0): macOS Intel · macOS Apple Silicon · Windows · Linux AppImage · Linux deb

Other:

For installation instructions, see the Installation Guide.

Getting Help

If you encounter issues with this release:

  1. Check the Installation Guide for setup instructions
  2. Review the Troubleshooting section
  3. Search existing issues
  4. Ask in GitHub Discussions