Skip to content
Skills Library
Programming · Learning & explanation

ti-codebase

/ti-codebase

TI-Toolbox codebase patterns, module graph, conventions and architecture (v3 — Electron desktop app, FastAPI tit.server, shared tit science core). Use when reading or modifying source under tit/ or desktop/ (developers).

Repository
ti-toolbox ↗
Licence
GPL-3.0
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

TI-Toolbox codebase patterns, module graph, conventions and architecture (v3 — Electron desktop app, FastAPI tit.server, shared tit science core). Use when reading or modifying source under tit/ or desktop/ (developers).

Original author description

TI-Toolbox codebase patterns, module graph, conventions and architecture (v3 — Electron desktop app, FastAPI tit.server, shared tit science core). Use when reading or modifying source under tit/ or desktop/ (developers).

How it works

  1. The three pieces
  2. Module dependency graph
  3. The job engine (tit/jobs/)
  4. Other v3 subsystems worth knowing before you touch them
  5. Config → JSON → subprocess pattern
  6. PathManager singleton
  7. Testing strategy
  8. The gate
  9. The science-integrity rule
  10. Conventions
Original SKILL.md headings · 278 lines, 2,042 words
SKILL.md preview
---
name: ti-codebase
description: TI-Toolbox codebase patterns, module graph, conventions and architecture (v3 — Electron desktop app, FastAPI tit.server, shared tit science core). Use when reading or modifying source under tit/ or desktop/ (developers).
user-invocable: false
---

# TI-Toolbox Codebase Guide (v3)

[AGENTS.md](../../../AGENTS.md) owns documentation routing. `docs/dev/` contains
ARCHITECTURE, DECISIONS, TESTING, RELEASING, BENCHMARKS, ROADMAP, CHANGELOG and AUTOMATION.
Read these through `read_dev_doc`; setup is in root CONTRIBUTING.md. Only CHANGELOG is published
from that directory. This skill is an orientation guide; current project documents take precedence.

## The three pieces

| Piece | Where | Owns |
|-------|-------|------|
| Electron desktop app | `desktop/` (main/preload + React + TS strict + Vite) | Host lifecycle only. It starts the container and `loadURL`s the UI from it. |
| FastAPI job server | `tit/server/` inside `idossha/ti-toolbox` | The job model — queue, dependencies, locks, budget, live events, cancellation. Serves the React bundle at `/`. |
| Science core | `tit/` | Every scientific decision. Imports no Qt, no FastAPI-only types. |

Wire contract: `contracts/openapi.yaml`. **The PyQt5 package `tit/gui/` was
deleted in v3.0.0** — do not cite it, do not restore patterns from it.

Frozen interface paths (a change requires the contract edit **and** the
`DECISIONS.md` entry in the same commit): `contracts/` and
`desktop/src/shared/tit-bridge.d.ts`.

## Module dependency graph

```
tit/__init__.py       setup_logging, add_file_handler, add_stream_handler,
                      get_path_manager, paths, constants   (__version__ here)
  +-- tit.paths       PathManager singleton (depends on tit.constants)
  +-- tit.constants   pure constants, no internal deps (is_valid_pair_count here)
  +-- tit.logger      no internal deps

science core
  tit.calc            the three envelope functions + the mTI direction search
  tit.fields          hf_peak / hf_sar exposure metrics (positional wiring)
  tit._mti_kernel     numba-accelerated sweep kernel

tit.sim
  +-- tit.sim.config           SimulationConfig, Montage, SimulationMode, MontageMode
  +-- tit.sim.base             BaseSimulation
  +-- tit.sim.TI / mTI         the two field pathways (note the capitalisation)
  +-- tit.sim.montage_sources  named / flex-mapped / free-hand montage resolution
  +-- tit.sim.utils            run_simulation, load_montages

tit.opt
  +-- tit.opt.config      FlexConfig, ExConfig, MExConfig, ROIs, electrode pools
  +-- tit.opt.flex.*      run_flex_search (differential evolution)
  +-- tit.opt.ex.*        run_ex_search   (exhaustive over a leadfield)
  +-- tit.opt.mex.*       run_m_ex_search (multipolar)
  +-- tit.opt.leadfield*  leadfield build + the leadfield_runner job module

tit.analyzer   Analyzer, AnalysisResult, GroupResult, run_group_analysis,
               select_field_file;  tit.atlas re-exported
tit.stats      run_group_comparison, run_correlation, engine (permutation), nifti,
               surface, nifti_average
tit.pre        run_pipeline, DICOM->NIfTI, FastSurfer, CHARM, QSIPrep, DIPY DTI fit (qsi/dti_extractor + qsi/tensor_math), optional QSIRecon
tit.source     forward model + project_fields_to_fsaverage
tit.reporting  html/ (the one report layer) + generators/ (dti_qc, simulation, flex_search, ex_search)
tit.plotting, tit.blender, tit.tools, tit.project_init, tit.telemetry, tit.examples

tit.config_io  (de)serialisation with `_type` discriminators; used by tit.server
               job submission and every module's __main__ runner

v3 application layer
  tit.server     FastAPI app; routes/ auto-discovered; kernels.py, notebooks.py,
                 static.py, ws.py, auth.py, settings.py
  tit.jobs       the job engine (see below)
  tit.scene      scene payloads from a subject's real files + the packaged guide
  tit.viewspec   build_view(kind, ...) -> ViewSpec (a pure function)
  tit.catalog    subject/simulation discovery for the UI
  tit.launch     `tit launch` — the run spec reader
  tit.cli        the `tit` CLI (one subcommand: launch)
```

## The job engine (`tit/jobs/`)

`kinds.py` maps a kind to a module; every job is
`simnibs_python -m <module> <spec_path>`.

Kinds: `pre sim flex flex_adaptive flex_pareto ex mex leadfield analyzer stats
source blender nifti_average nilearn tools project_init`.
States: `queued running succeeded failed cancelled skipped lost`.

- **`scheduler.py` is pure.** `evaluate()` takes a snapshot (the candidate job, all
  known jobs, held locks, running cost totals) and returns one `Decision`. It
  touches no filesystem and no clock. `JobManager` calls it once per queued job per
  tick and acts. A dependency naming an unknown id is a **skip**, never a wait.
- **`registry.py` is the on-disk store**:
  `<project>/code/ti-toolbox/jobs/<id>/{spec.json,status.json,events.jsonl,stdout.log}`,
  written atomically (temp file + `os.replace`). Retention 200 jobs / 30 days.
  Python-only fields (`locks`, `cost`, `pid`, `create_time`, `budget_wait`) are
  stripped by `to_api()` before a response leaves the server.
- **One job per product.** `scheduler.PRODUCT_OF` (pre / sim / optimizer kinds /
  analyzer): a job waits while another job of its product runs. There is no
  concurrency setting; a stale `parallel_subjects` or `group_cap` is ignored. The count
  is read off live statuses, so it survives a server restart. The server forces
  each generated config's `subject_id` to its own subject: subject isolation is a
  server guarantee, not a client convention. A `Promise.all` or an awaited POST
  loop is *not* an implementation of parallel or sequential execution.
- **`eta.py`**: `minutes = (fixed + per_unit * units) * mesh_scale * system.factor
  / parallel`. `mesh_scale` uses the `.msh` *file size* as a cheap proxy for
  element count (a `stat()`, not a parse). `EMULATION_FACTOR = 3.0` (amd64 under
  Rosetta). Every number is an estimate and the UI must label it as one.
- **Failure taxonomy** — six `error.type` values, the `JobError(type=...)` literals in
  `tit/jobs/manager.py`, labelled in `desktop/src/renderer/app/jobs-rail/format.ts`:
  `runner_failed` (a non-zero exit or a signal; signal 9 says "likely out-of-memory"),
  `skipped` (a dependency failed), **`lost` → "Lost (server restarted mid-run)"**,
  `forced` (`POST /api/jobs/{id}/force`: the job lands in state `lost`, or `cancelled` if
  it was still queued), `kind_error` and `spawn_error` (the runner could not start).
- **A server restart never re-adopts running jobs** (by design, Sep 2026):
  startup reconciliation (`JobManager._reconcile_all`) terminates a still-live
  runner tree and records the job `failed` with `error.type` `lost`; a queued job
  fails "interrupted before start"; a job whose `events.jsonl` shows a real exit
  keeps its true outcome. Nothing is re-submitted automatically.

## Other v3 subsystems worth knowing before you touch them

- **`tit/server/kernels.py`** — Jupyter kernels driven **in-process** with
  `jupyter_client`, inside the container; the pipe is `WS /ws/kernels/{id}`.
  `MAX_KERNELS = 2`, 30-minute idle timeout, both reported by `GET /api/kernels`
  so no client hard-codes them. A restart must stop and join the pump threads
  before touching a ZMQ socket (libzmq aborts the process, and the process is
  `tit.server`). A keystroke never starts a kernel. **There is no sandbox** — a
  kernel runs arbitrary user code as the container's user; nothing in the product
  may call it one.
- **`tit/server/notebooks.py`** — the `.ipynb` on disk *is* the document; a save is
  validated before it lands and unknown keys survive untouched, so open+save must
  produce an empty git diff.
- **`tit/scene/`** — builds skin (`crop_mesh(tags=[1005])`), grey matter
  (`tags=[1002]`), electrodes (`eeg_positions/<net>.csv`) and region labels
  (`segmentation/*.annot` + `surfaces/*.central.gii`) from the subject's real
  files, plus a packaged subject-free guide served with an ETag of the file's
  SHA-256. A guide coordinate is never written into a configuration.
- **Native TetraVox** — desktop main installs a pinned official release for the host user;
  server scene exports map project paths for its native application. The image has no viewer bundle.

- **`tit/viewspec.py`** — `build_view` is a pure function returning a JSON-able
  `ViewSpec`. The server resolves what to show; the client renders it. **The viewer
  never assembles paths.**
- **`tit/catalog.py`** — built only on `PathManager` plus per-domain helpers, so
  BIDS layout rules are never re-implemented outside `tit`. A run directory without
  its completion manifest (`flex_meta.json`, `run_config.json`, `analysis.json` +
  `results.csv`) is ignored, so a cancelled run never appears as a result.

## Config → JSON → subprocess pattern

1. Build the config dataclass (`SimulationConfig`, `FlexConfig`, `ExConfig`, …).
2. Serialize via `tit.config_io`: `serialize_config` (Enums via `.value`, nested
   dataclasses recursively, union types via a `_type` discriminator);
   `write_config_json(config, prefix="flex")` returns a path.
3. Launch `simnibs_python -m tit.<module> config.json`.

`_type` discriminators: ROIs (`SphericalROI`, `AtlasROI`, `SubcorticalROI`),
electrodes (`PoolElectrodes`, `BucketElectrodes`), montages.

## PathManager singleton

```python
from tit.paths import get_path_manager
pm = get_path_manager("/path/to/project")   # sets project_dir on first call
pm = get_path_manager()                     # returns the existing instance
```
Auto-detection falls back to `PROJECT_DIR`, then `PROJECT_DIR_NAME` + the Docker
mount prefix. Zero-arg: `derivatives() simnibs() config_dir() reports()
jobs_dir()`. One-arg: `m2m(sid) simulations(sid) logs(sid)`. Two-arg:
`simulation(sid, sim) ti_mesh(sid, sim)`. Listing: `list_subjects()` (m2m only)
vs `list_all_subjects()` (all locations). `pm.ensure(path)` creates and returns.
**All paths go through the PathManager — never hand-built.**
Tests: `reset_path_manager()`; the `_reset_path_manager` fixture is `autouse`.

## Testing strategy

- **Host suite** — `.venv/bin/python -m pytest tests/ -q --ignore=tests/numerical` from
  the repo root. `conftest.py` installs mocks into `sys.modules` before any `tit` import: `simnibs` (+
  `simulation.sim_struct`, `mesh_tools.mesh_io`, `utils.transformations`), `bpy`,
  `scipy`, `nibabel`, `h5py`, `matplotlib`, `pandas`, `joblib`, `nilearn`.
  **numpy is real** — `tit/calc.py` tests do actual vector math.
- **Numerical suite** — `tests/numerical/`, whose conftest restores real libraries, is a
  separate container leg: `docker exec -w /ti-toolbox <c> simnibs_python -m pytest
  tests/numerical -q`. This is where a scientific claim is proved.
- **Frontend** — `cd desktop && npm run typecheck && npm run lint && npx vitest run`.
- **E2E** — Playwright, offscreen by default (`TIT_E2E_OFFSCREEN=1`), **one run at
  a time** under `/tmp/tit-e2e.lock`. Some scene specs need `VITE_SCENE_HOOKS=1`
  and/or `VITE_INCLUDE_GALLERY=1` at build time.
- **Guards** — `python3 dev/route_import_guard.py && python3 dev/contracts_check.py`.
- **Real-container smoke** — `dev/smoke.sh --list | dev/smoke.sh | dev/smoke.sh <row>`.
- pytest markers: `unit integration requires_data host_numerical smoke` (`smoke` is
  deselected by default; `dev/smoke.sh` runs it. `host_numerical` marks a `tests/numerical`
  module that needs only real numpy, scipy and nibabel, so CI also runs it on the host with
  `pytest tests/numerical -m host_numerical`).

## The gate

Run all of it and **report the numbers, not "green"**:

```bash
cd desktop && npm run typecheck && npm run lint && npx vitest run
.venv/bin/python -m pytest tests/ -q --ignore=tests/numerical
docker exec -w /ti-toolbox <container> simnibs_python -m pytest tests/numerical -q
python3 dev/route_import_guard.py && python3 dev/contracts_check.py
cd desktop && TIT_E2E_OFFSCREEN=1 npm run e2e:quiet
actionlint                 # if you touched .github/workflows
npm run verify:package     # if you touched packaging
cd desktop && npm run build   # LAST, always
```

After changing `tit/server/**`, `tit/jobs/**` or `tit/catalog.py`, restart only
once `GET /api/jobs` shows nothing running or queued. **A 200 from `/api/health` is
not evidence the new code loaded** — the pre-reload process can still answer.

## The science-integrity rule

Any change to `tit/stats`, `tit/analyzer`, `tit/calc`, `tit/fields` or `tit/sim`
needs **both**:

1. a test in `tests/numerical/` running against the **real** libraries that asserts
   the claim **independently** — an independent reader or a closed form, never a
   retyping of the implementation; and
2. if any published result moves, an entry in the applicable `docs/releases/` page
   saying what was wrong, which versions, which outputs move and by how much, how a
   user spots an affected result, and whether to **re-run or rescale**.

A number that changes and is not written down there is indistinguishable, to a
user, from a result they can no longer trust.

## Conventions

- `black tit/` before committing. Exception types live beside the code that raises them (`tit/launch.py`, `tit/pre/utils.py`, `tit/jobs/kinds.py`); there is no central errors module.
  `logging.getLogger(__name__)` per module; `setup_logging()` only at entry points.
- Commit titles state the defect or the new truth, e.g.
  `fix(analyzer): voxel focality volumes in cm^3, geometry from the affine`.
  **No AI co-author trailers.**
- `setup_logging()` adds **no handlers** — file-only by design.
  `add_file_handler(log_file, ...)` attaches one and returns it;
  `add_stream_handler()` writes bare `%(message)s` to stdout so the job runner can
  capture a subprocess. Each job writes a log file; the desktop app streams it over
  the server's HTTP API. There is no in-process UI logging handler in `tit/`.
- Shared-worktree rules: stage only your own files; **never `git stash`**; never
  revert another lane's working-tree changes; one Playwright run at a time; plain
  `npm run build` last; never recreate the maintainer's dev container (a plain
  `docker restart` keeps the token; a recreate mints a new one and kills jobs).
- Version lockstep: `dev/update/update_version.py --version X.Y.Z [--dry-run]` owns
  every version site — `tit/__init__.py`, `version.py`, `desktop/package.json`, the
  compose image tag, `CITATION.cff`, the release pages. CI re-checks the
  load-bearing ones and hard-fails on disagreement.

## How to add a new component

**A report generator**: `tit/reporting/generators/my_report.py` with `collect` (read the
run's outputs), `build_html` (compose `tit.reporting.html.components`) and a `main` for
`python -m tit.reporting.generators.my_report`; write it with `common.write_report`.

**A new UI page or panel**: the interface lives in `desktop/`, not `tit/`. Add the
Python side as a config dataclass plus a `__main__.py` runner plus a job kind in
`tit/jobs/kinds.py`, then the page under `desktop/src/renderer/pages/`. The rail
order is `NAV_ORDER` in `desktop/src/renderer/app/registry.ts` (its index is the
⌘-number, ⌘0–⌘9): nine rows are taken, so an eleventh workflow row would have no
digit.

**A new server route**: drop a module in `tit/server/routes/`; it is
auto-discovered (`iter_route_modules()`), so no `app.py` edit. Expose `router`
(behind auth) and/or `ws_router`. Routers carry **no prefix** — declare full paths
per endpoint. Only `health` is unauthenticated.

## Gotchas

- The container is Python 3.11 and **case-sensitive**: verify path and filesystem
  behaviour there, never on macOS. Note `tit/sim/TI.py` and `tit/sim/mTI.py`.
- nibabel's gzip save fails on bind mounts — write a plain `.nii` and gzip it with
  the standard library.
- **Never run two FEM simulations in parallel** under emulation; the smoke harness
  enforces it.
- `cpus` does **not** accelerate flex-search: `workers=` is never passed to
  `differential_evolution` and could not be — `goal_fun` holds an unpicklable
  pre-factored `OnlineFEM`. The realistic win is parallelising the multi-start
  restarts.
- `--project=real`, not `--project real`.

Versions

The database has no other skills named ti-codebase.

Database snapshot: 13.11.2026 · package version eca4c56a8761 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ti-scripting
    Python scripting API of TI-Toolbox (`tit` package) — SimulationConfig, FlexConfig, ExConfig, Analyzer, run_group_comparison, run_pipeline, the tit.calc envelope functions, JSON config runners. Use when writing or debugging scripts or notebooks that drive TI-Toolbox, or…
  • 90desktop-electron
    Use when the user asks about Electron app development, Chromium-based desktop apps, main/renderer process architecture, IPC communication, or packaging Electron apps. Do NOT use for: Tauri (desktop-tauri), or web app frontend (non-desktop skills).
  • 100ti-toolbox
    Orientation for the Temporal Interference Toolbox (TI-Toolbox, Python package `tit`). Use whenever the user mentions TI-Toolbox, TI stimulation simulation/optimization, SimNIBS-based TI workflows, flex-search, ex-search, mTI, the v3 desktop app, or a BIDS project with…
  • 100electron-desktop
    Desktop application development with Electron for Windows, macOS, and Linux. Use when building cross-platform desktop apps, implementing native OS features, or packaging web apps for desktop.
  • 100electron
    Provides comprehensive guidance for Electron framework including main process, renderer process, IPC communication, window management, and desktop app development. Use when the user asks about Electron, needs to create desktop applications, implement Electron features, or build…
  • 100electron-expert
    Expert in Electron framework, desktop app development, IPC, and cross-platform packaging. Use when the user mentions desktop, Node.js, cross platform, Windows, macOS, or Linux, or when the task involves Electron Architecture, Process Types, IPC Communication, or App Lifecycle.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.