mri-hardware · diff
v0.8.0 to v0.11.0
53 added, 101 removed. Audit A to A.
---
name: mri-hardware
description: >-
- MRI hardware and safety expert — magnets, gradients, RF coils, consoles /
- spectrometers, low-field and open-source systems, and MR safety. Use for
- hardware design or selection, low-field MRI, open-source consoles (MaRCoS,
- OCRA), RF/gradient coil design and EM simulation, shimming, and MR safety
- (SAR, PNS, implants, quench, contrast agents). Triggers: MRI hardware, gradient
- coil, RF coil, low-field MRI, MaRCoS, OCRA, spectrometer/console, shimming,
- SAR, PNS, quench, MR safety, B0/B1. Orientation only — not clinical advice.
- For waveform/sequence programming hand off to pulse-sequence-design, and for
- turning acquired k-space into images to mri-reconstruction.
+ Read before any calculation, design or advice about MR hardware or safety: B0
+ field maps and shimming (spherical harmonics, current limits, oblique
+ geometry), gradient and RF coils (Biot-Savart, efficiency, linearity, B1), RF
+ exposure (B1+rms, SAR, IEC 60601-2-33 modes), dB/dt and nerve stimulation,
+ receiver noise, coil combination and SNR scaling, low-field and open-source
+ consoles, quench and implants. Prevents silent errors in units, frames, field
+ components, harmonic normalization, bounded optimization and limit definitions.
+ Ships tested SI helpers checked against analytic cases. Not clinical advice;
+ waveform programming belongs to pulse-sequence-design.
metadata:
author: Ke Wang
- version: "0.8.0"
+ version: "0.11.0"
---
- # MRFoundry: MRI Hardware & Safety
-
- You are a hardware-oriented MR engineer/physicist. Hardware work is physical and
- safety-critical — point to the primary projects and their communities, and put
- safety first.
-
-
- ## Papers and textbooks
-
- See the [annotated reading list](references/reading-list.md) for primary papers,
- textbooks, publication details, direct source links and what each source supports.
- Use the [repo-wide reference index](https://github.com/KeWang0622/MRFoundry/blob/main/REFERENCES.md) to navigate across skills.
- When using a method, cite its specific source; distinguish paper evidence from
- software instructions and current venue/safety requirements.
-
-
- ## Project research memory
-
- If only the legacy `.mri-research/` notebook exists, migrate it with the project
- memory initializer before creating new notes; preserve existing evidence.
- For project experiments, read `.mrfoundry/INDEX.md` when present and retrieve
- only relevant preferences, environment notes and evidence-linked lessons. After
- meaningful runs or corrections, record outcomes, failures, limitations and next
- steps; revise scoped lessons without erasing history. Keep user preferences
- separate from scientific findings. Use the [project memory workflow](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/project-memory.md)
- to initialize the folder or connect project `CLAUDE.md` / `AGENTS.md`. If the hub
- is absent, retrieve the reference from the official skill repository.
-
- ## Tool setup before execution
-
- For any application this skill uses, check for a compatible installation and
- follow the official upstream's setup instructions. Within the authorized task,
- install missing dependencies yourself in an isolated environment, run a small
- upstream example, then execute the user's workflow. Do not leave routine setup
- to the user or replace a missing tool with a homemade numerical implementation.
- Use established simulators/solvers; write only necessary configuration and glue.
- If blocked, report the actual obstacle and an established alternative.
- Read the [tool setup guide](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/tool-setup.md) when installing,
- repairing, or choosing an execution environment. If the hub is not installed,
- retrieve that reference from the official `KeWang0622/MRFoundry` repository.
-
- ## The hardware chain
+ # MRFoundry: MRI Hardware and Safety
- - **Main magnet (B0)** — static field (0.05 T portable → 1.5/3/7 T+). Strength
- drives SNR and many tradeoffs; **low-field (<0.1 T)** is a fast-growing area.
- - **Gradients** — coils + amplifiers for spatial encoding. Specs: amplitude
- (mT/m), slew rate (T/m/s), duty cycle; bounded by hardware and **PNS**.
- - **RF** — transmit coil(s) + receive arrays, RF power amp, T/R switch, preamps.
- Multi-channel receive arrays enable parallel imaging.
- - **Console / spectrometer** — generates precise RF/gradient waveforms and
- digitizes signal (ADC/DAC); where open-source efforts focus.
- - **Shim system** — corrects B0 inhomogeneity (passive/active/dynamic).
+ Hardware numbers are useful only with their units, conventions and a check. Use the tested helpers in
+ `scripts/mrfoundry_hwlib.py` (numpy/scipy, SI units) and import them rather than re-deriving them:
+ `python .agents/skills/mri-hardware/scripts/mrfoundry_hwlib.py --api` lists signatures (do not cat the source); `scripts/test_hwlib.py` shows
+ each helper on an analytic case.
- ## Low-field & open-source hardware
+ ## Route
- - **OSI²** — https://www.opensourceimaging.org — hub for open MRI hardware. Design
- files/code live on GitLab (https://gitlab.com/osii), incl. the full **OSI² ONE**
- low-field scanner.
- - **MaRCoS** — open control system for (mostly low-field) MRI: `marcos_client` /
- `marcos_server` / streaming `marga` (https://github.com/vnegnev).
- - **OCRA** — low-cost (~$500) real-time console on STEMLab/Red Pitaya; Pulseq via
- **ocra-pulseq** (https://github.com/LincolnCB/ocra-pulseq).
- - **GPA-FHDO** — open gradient power amplifier
- (https://github.com/menkueclab/GPA-FHDO). **MRI4ALL** — community open scanner +
- magnet/gradient/shim design repos (https://github.com/mri4all).
+ | Task | Use (`mrfoundry_hwlib.py`) |
+ |---|---|
+ | Field map from multi-echo phase (nonzero phase0, uneven echo times) | `fieldmap_multiecho(phase, te, magnitude, max_abs_hz)` (temporal unwrapping; also spatially unwrap if fields can exceed 1/(2 ΔTE_min)) |
+ | Shim basis at voxel positions | `voxel_world_coords(affine, shape)` (full affine, mm to m), then evaluate the vendor's polynomials there; `solid_harmonics`, `fit_harmonics` for analysis |
+ | Optimal shim currents within limits | `shim_currents(field, roi, channel_maps, lower, upper, current_during_acquisition=I_acq)`: absolute currents, `frequency_adjust` (= -offset) and a KKT optimality report |
+ | Any bounded least-squares fit you wrote yourself | `bounded_lsq_kkt(A, b, x, lower, upper)` must return ok |
+ | Coil fields, gradient efficiency and linearity | `biot_savart`, `circle_path`, `loop_bz_on_axis`, `gradient_metrics` |
+ | RF exposure | `rf_energy`, `b1_rms` (window includes dead time), `b1_rms_of_train`, `b1_for_flip`, `sar_scale`, `iec_sar_limits`, `time_averaged_sar` |
+ | Gradient safety | `slew_rate`, `dbdt_at_radius`, `effective_stimulus_duration`, `pns_threshold_dbdt`, `iec_dbdt_limit` |
+ | Receiver noise and SNR | `noise_covariance`, `prewhitening_matrix`, `roemer_combine` (SNR units), `rss_combine`, `snr_scale` |
- ## Coil, gradient & shim design
+ Derivations, standard values and references: [computations](references/computations.md).
- - **Gradient / shim coils:** **CoilGen** (BEM stream-function designer,
- https://github.com/Philipp-MR/CoilGen) and its Python port **pyCoilGen**
- (https://github.com/kev-m/pyCoilGen).
- - **RF coil EM / SAR:** **openEMS** (https://github.com/thliebig/openEMS),
- **MARIE** / **mariepy** (https://github.com/thanospol/MARIE), **CoSimPy**
- (https://github.com/umbertozanovello/CoSimPy); **scikit-rf** for impedance
- matching. Commercial: HFSS, CST, Sim4Life.
- - **B0 shimming:** **Shimming Toolbox** (static/dynamic/real-time, Python) —
- https://github.com/shimming-toolbox/shimming-toolbox.
+ ## Checks that prevent silent errors
- ## MR safety (research orientation — NOT clinical guidance)
+ 1. **Write the convention down before computing**: units (T, mT, µT; Hz, ppm; mT/m vs G/cm; per ampere),
+ frame and axis (z = bore axis; world RAS+ from the NIfTI affine), field component (Bz vs |B|), region of
+ interest, and which limit (6-min vs 10-s SAR, peak vs RMS, normal vs first-level mode).
+ 2. **Field-model bookkeeping for shimming**: the measured map already contains the field of the currents that
+ were on during the acquisition. Solve for ABSOLUTE new currents with `current_during_acquisition`, bound
+ those, and map the free offset to the centre-frequency convention you report.
+ 3. **Prove optimality, do not assume it**: run `bounded_lsq_kkt` on any constrained solution (column scaling
+ left unscaled, bounds applied to scaled variables and sign flips all pass a "residual went down" check).
+ Report which channels sit at their limits.
+ 4. **Validate the tool on an analytic case first** (loop on axis, solenoid, synthetic harmonic field, a
+ rectangular RF train) and check discretization convergence before the real geometry.
+ 5. **Use established solvers for geometry-dependent physics** (Biot-Savart for coils; full-wave EM with a
+ body model for local SAR; published PNS models). Never present a uniform-body estimate as local SAR.
+ 6. **Report margins and limits**: standard and edition, mode, averaging window, assumptions and what was not
+ modelled. Say when a qualified MR safety expert is required.
- Not a substitute for your site's MR safety program, screening, or a qualified MR
- safety officer / medical physicist. For any real magnet or subjects, follow
- local policy, IRB/ethics approval, and vendor specs. Hazard classes: static
- field (ferromagnetic projectiles, implants), gradients (PNS, acoustic noise),
- RF (SAR heating), cryogens/quench, implants/devices, and contrast agents
- (gadolinium — a clinical decision). References:
- - ACR Manual on MR Safety — https://www.acr.org/Clinical-Resources/Clinical-Tools-and-Reference/radiology-safety/mr-safety
- - MRIsafety.com (Shellock) — https://www.mrisafety.com/
- - ISMRM — https://www.ismrm.org/
+ ## Before you finish
- ## Hand-offs
+ python .agents/skills/mri-research-workflow/scripts/finish_check.py --require <every deliverable name> \
+ --rerun "python <entrypoint> <documented arguments with {inputs} and {out}>" --inputs <input folder>
- - **Programming the waveforms** a console plays (Pulseq/PyPulseq, gradient and RF
- design, trajectory design, PNS-constrained gradient optimization):
- `pulse-sequence-design`.
- - **Reconstructing data** off an open or low-field scanner: `mri-reconstruction`
- (BART/SigPy, classical) or `deep-learning-recon` (trained).
- - **Landscape, citations, and the wider MRI map:** the `mri-research` hub.
+ ## More (open only when needed)
- Deeper reference:
- https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/hardware.md
+ - Hardware chain, low-field and open-source consoles, coil and shim design tools, MR safety references:
+ [hardware landscape](references/landscape.md) and the hub's [hardware guide](../mri-research/references/hardware.md).
+ - Citations: [reading list](references/reading-list.md). Setup problems:
+ [tool setup guide](../mri-research/references/tool-setup.md). Project notes (only with `.mrfoundry/INDEX.md`):
+ [project memory](../mri-research/references/project-memory.md).
+ - Waveforms: `pulse-sequence-design`. Reconstruction: `mri-reconstruction`.