User guide

User guide#

Installing the package, the platforms it is supported on, and how the project is used. The references to cite are on the homepage. Sequence physics and design concepts are covered in Explanations; executable workflows are in Examples.

Documentation sections#

Section

Purpose

This page

Installation, supported platforms, running a shipped sequence, issue reporting and security.

Developer guide

Development setup and contribution workflow.

Explanations

Pulseq representation, sequence design and constraint models.

Examples

A course in sequence design, and a page per shipped sequence.

Sequence catalogue

Catalogue of the shipped sequences, one reference page each.

API reference

Exact interfaces, units and defaults.

Miscellaneous

Licensing, related projects and contributors.

Source

Repository, issues and discussions.

PDF manual

Single-file documentation from the latest release.

Prerequisites and supported platforms#

pypulseqpp supports Python 3.10 through 3.13. CI tests the lower and upper bounds on Linux, macOS and Windows.

Published wheels cover:

Platform

Architectures

Linux

x86-64, glibc (manylinux)

macOS

Apple silicon and x86-64

Windows

AMD64

The native core is compiled into each wheel. Source builds may work on other C++17 platforms, but those configurations are not release-tested. A source build requires a C++17 compiler, CMake, Python development headers and the checked-out Git submodules.

Installation#

Install the core package from PyPI:

pip install pypulseqpp

Optional facilities are installed as extras:

Extra

Command

Purpose

SeqEyes viewer

pip install 'pypulseqpp[plot]'

Interactive sequence viewing through the separately distributed GPL viewer.

Intel MKL

pip install 'pypulseqpp[mkl]'

Optional FFT backend for mechanical-resonance analysis on x86-64.

FSE design

pip install 'pypulseqpp[design]'

torchsim, used by optimized fast-spin-echo refocusing schedules.

Developer installation is documented in Developer guide.

Running a shipped sequence#

Each shipped sequence is a module of pypulseqpp.sequences. Calling the module designs the sequence at the prescription given as keyword arguments and returns it; the prescription each accepts is on its page in the catalogue.

>>> from pypulseqpp import sequences
>>> seq = sequences.gre2D_sequence(n_x=64, n_y=64, n_slices=1)
>>> signature = seq.write("gre_2d.seq")

Every module is also a command-line entry point, whose options are derived from the same prescription:

python -m pypulseqpp.sequences.sequence.gre2D_sequence --help

Reporting issues#

Use the GitHub issue tracker for a reproducible defect, a documentation error, or a narrowly scoped feature request. A useful report includes the package and Python versions, operating system, relevant PyPulseq version, the affected subsystem and the smallest reproducer.

Questions and broad design proposals belong in Discussions, and vulnerabilities follow the private process stated under Security.

Discussions#

GitHub Discussions is the public forum for usage questions and broad design ideas. Search existing topics before opening a new Q&A or idea. Reproducible defects belong in the issue tracker.

Security#

The canonical policy is SECURITY.md. Vulnerabilities must be reported through GitHub private vulnerability reporting, not through a public issue.