# Sequence functions

A sequence function is a function `sequence(system, **protocol)` that returns a
{class}`~pypulseqpp.Sequence`, or a list of them with the prescans first and the
main sequence last. The objects below read its protocol, label its blocks,
write what it returns, time it, and build the excitation a volumetric
prescription chooses. The sequences themselves are listed in
{doc}`../sequences`; the structure of a sequence function, its protocol and its
prescan chain are described in
{doc}`../explanations/sequence-design`.

```{eval-rst}
.. currentmodule:: pypulseqpp.sequences
```

## Sequence functions

The protocol of a sequence function is its keyword parameters after `system`.
`parameters` reads each one's type and default from the signature, and its unit,
choices and description from the NumPy-style Parameters section.
{func}`pypulseqpp.cli.run` derives the command-line options from the same
signature.

| Object | Input | Returns | Purpose |
| --- | --- | --- | --- |
| {obj}`~pypulseqpp.sequences.parameters` | Sequence function | `dict` of `ProtocolParameter`, in signature order | Protocol of a sequence function. |
| {obj}`~pypulseqpp.sequences.ProtocolParameter` | Returned by `parameters` | Frozen record | One protocol parameter: its type, default, unit, choices and description. |
| {obj}`~pypulseqpp.sequences.Labels` | The new value of each label, by Pulseq name | Label events to add to the block | Writer of the label events a block changes. |
| {obj}`~pypulseqpp.sequences.write` | Path, a sequence or a list of sequences | Written paths, in play order | Write a sequence, or a chain of linked sequences, as Pulseq files. |
| {obj}`~pypulseqpp.sequences.duration` | A sequence or a list of sequences | Duration (s) | Return the time a sequence, or a chain, plays. |

## Excitation choice

A volumetric sequence function offers its excitation as one protocol parameter,
whose choices are `EXCITATIONS`, and builds the module with `make_excitation`
from one slab prescription.

| Object | Input | Returns | Purpose |
| --- | --- | --- | --- |
| {obj}`~pypulseqpp.sequences.EXCITATIONS` | — | `("nonselective", "slab", "spsp")` | The excitation kinds `make_excitation` builds. |
| {obj}`~pypulseqpp.sequences.make_excitation` | System, kind, flip angle (deg), slab thickness (m) | Excitation module | Non-selective, slab-selective or water-selective spectral-spatial excitation of one slab. |