mri-hardware
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
Install
npx skills add https://github.com/KeWang0622/mri-research-skill/tree/main/skills/mri-hardware
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kewang0622-mri-research-skill@llmmart
git clone https://github.com/KeWang0622/mri-research-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kewang0622/mri-research-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
MRFoundry: MRI Hardware and Safety
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.
Route
| 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 |
| Safety numbers of an exported Pulseq file (B1+rms, B1 peak, gradient rms, ramp PNS, crusher moments) | pulse-sequence-design/scripts/check_exported_seq.py seq --safety --pns-rheobase .. --pns-chronaxie .. (limits: --b1rms-max, --pns-max, ...) |
| Off-resonance correction of a long readout with a field map | fieldmap_multiecho here, then mri-reconstruction offres_least_squares and smooth_field |
| Receiver noise and SNR | noise_covariance, prewhitening_matrix, roemer_combine (SNR units), rss_combine, snr_scale |
Derivations, standard values and references: computations.
Checks that prevent silent errors
- 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).
- 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. - Prove optimality, do not assume it: run
bounded_lsq_kkton 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. - 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.
- 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.
- Design inside limits with a margin (2-5 %): size flips, pulse durations, echo counts and TR from the limit
before building (
b1_rms_of_train), because rounding to rasters and ramp shapes move realized values; recompute every reported safety number from the exported file. Simulated signals of an exported sequence come from KomaMRI with the replay check ofpulse-sequence-design. - 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.
Before you finish
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>
More (open only when needed)
- Hardware chain, low-field and open-source consoles, coil and shim design tools, MR safety references: hardware landscape and the hub's hardware guide.
- Citations: reading list. Setup problems:
tool setup guide. Project notes (only with
.mrfoundry/INDEX.md): project memory. - Waveforms:
pulse-sequence-design. Reconstruction:mri-reconstruction.
Files (mri-research-skill)
-
references
-
computations.md 5.2 KB
Loading… -
landscape.md 2.1 KB
Loading… -
reading-list.md 2.1 KB
Loading…
-
-
scripts
-
mrfoundry_hwlib.py 23.8 KB
Loading… -
test_hwlib.py 8.3 KB
Loading…
-
-
SKILL.md 5.4 KB
--- name: mri-hardware description: >- Read before any MR hardware or safety calculation: B0 field maps and shimming with current limits, gradient and RF coil fields, B1+rms and SAR (IEC 60601-2-33), dB/dt and nerve stimulation, receiver noise and SNR, low- field and open-source consoles. 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. metadata: author: Ke Wang version: "0.14.0" --- # MRFoundry: MRI Hardware and Safety 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. ## Route | 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` | | Safety numbers of an exported Pulseq file (B1+rms, B1 peak, gradient rms, ramp PNS, crusher moments) | `pulse-sequence-design/scripts/check_exported_seq.py seq --safety --pns-rheobase .. --pns-chronaxie ..` (limits: `--b1rms-max`, `--pns-max`, ...) | | Off-resonance correction of a long readout with a field map | `fieldmap_multiecho` here, then `mri-reconstruction` `offres_least_squares` and `smooth_field` | | Receiver noise and SNR | `noise_covariance`, `prewhitening_matrix`, `roemer_combine` (SNR units), `rss_combine`, `snr_scale` | Derivations, standard values and references: [computations](references/computations.md). ## Checks that prevent silent errors 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. **Design inside limits with a margin** (2-5 %): size flips, pulse durations, echo counts and TR from the limit before building (`b1_rms_of_train`), because rounding to rasters and ramp shapes move realized values; recompute every reported safety number from the exported file. Simulated signals of an exported sequence come from KomaMRI with the replay check of `pulse-sequence-design`. 7. **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. ## Before you finish 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> ## More (open only when needed) - 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`.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.