run

Contents

run#

pypulseqpp.cli.run()[source]#

Run a sequence function, or a sequence script’s main, from the command line.

Every keyword parameter of main annotated with a scalar becomes an option, described by what main’s own docstring says about it. Five names are answered here instead: plot, test_report, write_seq and seq_filename, which are the calling convention rather than the prescription, and system, which is built from the limit options.

Parameters:
  • main (callable) – A sequence function main(system, **protocol), or the script’s entry point. Returns the sequence, or for a sequence function a list of sequences.

  • argv (list of str, default=None) – The arguments, without the program name. sys.argv[1:] when omitted.

  • description (str, default=None) – What --help says the script does. The first line of main’s docstring when omitted.

  • default_output (str, default='sequence.seq') – Where to write when --output is not given.

Returns:

The exit status: zero when the sequence was written.

Return type:

int

Notes

A sequence function takes system as its first parameter. It is called with the limit options built into a Opts, the default limits when none is given, and its result is written to --output with pypulseqpp.sequences.write(), in binary form under --binary: one file for a sequence, linked files for a list of them. --report prints each sequence’s test report.

The sequence a script’s main returns is written to --output with pypulseqpp.io.write(), in binary form under --binary.

Examples

>>> import pypulseqpp as pp
>>> from pypulseqpp.cli import run
>>> def main(write_seq: bool = False, seq_filename: str = "x.seq",
...          *, n_x: int = 128, tr: float | None = None) -> pp.Sequence:
...     '''One line.
...
...     Parameters
...     ----------
...     n_x : int, optional
...         Readout samples.
...     tr : float or None, optional
...         Repetition time, in seconds.
...     '''
...     return pp.Sequence()

The options are the function’s parameters, described by its docstring:

>>> import contextlib, io
>>> text = io.StringIO()
>>> with contextlib.redirect_stdout(text), contextlib.suppress(SystemExit):
...     run(main, ["--help"])
>>> "--n-x" in text.getvalue(), "Readout samples." in text.getvalue()
(True, True)

A sequence function takes the system first, and the options are its keyword parameters:

>>> import pathlib, tempfile
>>> def gre(system, *, n_x: int = 128) -> pp.Sequence:
...     '''One line.
...
...     Parameters
...     ----------
...     n_x : int, default=128
...         Readout samples.
...     '''
...     seq = pp.Sequence(system)
...     seq.add_block(pp.make_delay(n_x * 1e-6))
...     return seq
>>> path = pathlib.Path(tempfile.mkdtemp()) / "gre.seq"
>>> with contextlib.redirect_stdout(text):
...     status = run(gre, ["-o", str(path), "--n-x", "64"])
>>> status, pp.io.read(path).num_blocks
(0, 1)