From 2502d6425ff9fb3b374bd486abce412e2057a1b7 Mon Sep 17 00:00:00 2001
From: Michiel Cottaar <MichielCottaar@protonmail.com>
Date: Wed, 15 May 2024 15:40:59 +0100
Subject: [PATCH] Add basic sequence optimisation docs
---
docs/make.jl | 3 ++
docs/src/api.md | 56 ++++++++++++++++++++++++++-----
docs/src/implemented_sequences.md | 19 +++++++----
docs/src/scanners.md | 20 +++++++++++
docs/src/sequence_optimisation.md | 22 ++++++++++++
5 files changed, 106 insertions(+), 14 deletions(-)
create mode 100644 docs/src/scanners.md
create mode 100644 docs/src/sequence_optimisation.md
diff --git a/docs/make.jl b/docs/make.jl
index 5a98df3..a205e8c 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -11,13 +11,16 @@ makedocs(;
format=Documenter.HTML(;
prettyurls=get(ENV, "CI", "false") == "true",
edit_link="main",
+ size_threshold_ignore=["api.md"],
description="Documentation for MRIBuilder.jl: an MRI sequence builder in Julia",
footer=nothing,
canonical="https://open.win.ox.ac.uk/pages/ndcn0236/mribuilder.jl/stable/",
),
pages=[
"Home" => "index.md",
+ "Optimisation" => "sequence_optimisation.md",
"Implemented sequences" => "implemented_sequences.md",
+ "Scanners" => "scanners.md",
"API" => "api.md",
],
warnonly=Documenter.except(:example_block),
diff --git a/docs/src/api.md b/docs/src/api.md
index e121060..60bbf56 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -3,12 +3,18 @@ CollapsedDocStrings = true
```
# MRIBuilder.jl API
+## Scanners
+
+## Optimisation helper functions
```@autodocs
Modules = [
- MRIBuilder,
- MRIBuilder.Scanners,
MRIBuilder.BuildSequences,
- MRIBuilder.Variables,
+]
+```
+
+## Sequence components
+```@autodocs
+Modules = [
MRIBuilder.Components,
MRIBuilder.Components.AbstractTypes,
MRIBuilder.Components.GradientWaveforms,
@@ -24,21 +30,55 @@ Modules = [
MRIBuilder.Components.Readouts,
MRIBuilder.Components.Readouts.ADCs,
MRIBuilder.Components.Readouts.SingleReadouts,
+]
+```
+## Containers for sequence components
+```@autodocs
+Modules = [
MRIBuilder.Containers,
MRIBuilder.Containers.Abstract,
MRIBuilder.Containers.BuildingBlocks,
MRIBuilder.Containers.BaseSequences,
MRIBuilder.Containers.Alternatives,
+]
+```
+
+## Pathways
+```@autodocs
+Modules = [
MRIBuilder.Pathways,
+]
+```
+
+## Pre-defined sequence components
+```@autodocs
+Modules = [
MRIBuilder.Parts,
+ MRIBuilder.Parts.Trapezoids,
+ MRIBuilder.Parts.SpoiltSliceSelects,
+ MRIBuilder.Parts.SliceSelectRephases,
+ MRIBuilder.Parts.EPIReadouts,
+ MRIBuilder.Parts.HelperFunctions,
+]
+```
+## Post-hoc adjustments
+```@autodocs
+Modules = [
MRIBuilder.PostHoc,
- MRIBuilder.Sequences,
- MRIBuilder.Sequences.GradientEchoes,
- MRIBuilder.Sequences.SpinEchoes,
- MRIBuilder.Sequences.DiffusionSpinEchoes,
- MRIBuilder.Printing,
+]
+```
+
+## Sequence I/O
+```@autodocs
+Modules = [
MRIBuilder.SequenceIO,
MRIBuilder.SequenceIO.Pulseq,
+]
+```
+
+## Plot
+```@autodocs
+Modules = [
MRIBuilder.Plot,
]
```
\ No newline at end of file
diff --git a/docs/src/implemented_sequences.md b/docs/src/implemented_sequences.md
index 273eb7f..1861a3a 100644
--- a/docs/src/implemented_sequences.md
+++ b/docs/src/implemented_sequences.md
@@ -1,4 +1,4 @@
-# Using implemented sequences (@id implemented_sequences)
+# [Using implemented sequences](@id implemented_sequences)
## Usage
@@ -8,10 +8,17 @@ To get help on a specific sequence, either follow the link in the sequence list
When reading the help, you will notice that there are two type of expected inputs:
- `Parameters`: these define the type of components that will be includes, e.g., the shape of the excitation pulse or the readout strategy. These parameters have to be set to certain fixed values. If unset, they will be determined by their default value as defined in the documentation.
-- `Variables`: These are a special type of parameters. In addition to being set to a fixed value, they can also be set to `:min` or `:max` to minimise or maximise the variable. If they are unset, they will be determined based on the other variables.
-Internally whenever you call a sequence function it will run a non-linear optimisation given any constraints and/or objectives you have given to the `Variables`. It will give a single sequence that matches all of the constraints. If no solution exists, an error will be raised instead. If multiple solutions exist, a single (somewhat random) one is returned.
+- `Variables`: These are a special type of parameters. In addition to being set to a fixed value, they can also be set to `:min` or `:max` to minimise or maximise the variable. If they are unset, they will be determined based on the other variables. For more details, see the section on [sequence optimisation](@ref sequence_optimisation).
## Available sequences
-- [`GradientEcho`](@ref)
-- [`SpinEcho`](@ref)
-- [`DWI`](@ref)/[`DW_SE`](@ref)/[`DiffusionSpinEcho`](@ref)
\ No newline at end of file
+```@meta
+CollapsedDocStrings = true
+```
+```@autodocs
+Modules = [
+ MRIBuilder.Sequences,
+ MRIBuilder.Sequences.GradientEchoes,
+ MRIBuilder.Sequences.SpinEchoes,
+ MRIBuilder.Sequences.DiffusionSpinEchoes,
+]
+```
diff --git a/docs/src/scanners.md b/docs/src/scanners.md
new file mode 100644
index 0000000..3adaa3f
--- /dev/null
+++ b/docs/src/scanners.md
@@ -0,0 +1,20 @@
+# [Scanners](@id scanners)
+The MRI scanner that is used during acquisition puts various constraints on the MR sequences that can be used.
+These constraints include safety considerations, such as tissue heating, and hardware constraints, such as maximum gradient strength and slew rate.
+Currently, MRIBuilder only considers the latter.
+
+To define a sequence appropriate for a specific scanner, a user would define a new [`Scanner`](@ref) with the appropriate [`B0`](@ref), maximum [`gradient_strength`](@ref), and maximum [`slew_rate`](@ref).
+This scanner would then be passed on to the [sequence optimisation](@ref sequence_optimisation).
+
+For ease of use, the `gradient_strength` and `slew_rate` of many scanners have already been pre-defined.
+These are listed below.
+
+## Scanners API
+```@meta
+CollapsedDocStrings = true
+```
+```@autodocs
+Modules = [
+ MRIBuilder.Scanners,
+]
+```
\ No newline at end of file
diff --git a/docs/src/sequence_optimisation.md b/docs/src/sequence_optimisation.md
new file mode 100644
index 0000000..406647e
--- /dev/null
+++ b/docs/src/sequence_optimisation.md
@@ -0,0 +1,22 @@
+# [Sequence optimisation](@id sequence_optimisation)
+In MRIBuilder an MR [`Sequence`](@ref) is defined as a sequence of [`BuildingBlock`](@ref) objects.
+Most `BuildingBlock` objects will contain free parameters determining, for example, the duration of the block or the strength/orientation of the MR gradient.
+In most MR sequence building software, the user will have to set all of these free parameters by computing the appropriate values given a desired echo time, b-value, etc.
+
+In MRIBuilder the internal free parameters are not set directly.
+Instead, they are inferred using a non-linear, constrained optimisation.
+For each sequence type, the developer defines how to compute various summary variables from the `BuildingBlock` free parameters, such as [`echo_time`](@ref), [`repetition_time`](@ref), [`resolution`](@ref), [`gradient_strength`](@ref), [`diffusion_time`](@ref), etc.
+A user can then create a specific instantiation of the sequence by fixing any of these summary variables to their desired values (or setting them to `:min`/`:max` to minimise/maximise them).
+In addition to the user-defined constraints, this optimisation will also take into account any [scanner-defined constraints](@ref scanners).
+Internally, MRIBuilder will then optimise the `BuildingBlock` free parameters to match any user-defined constraints and/or objectives.
+This optimisation uses the [Ipopt](https://github.com/coin-or/Ipopt) optimiser accessed through the [JuMP.jl](https://jump.dev/JuMP.jl/stable/) library.
+
+## [Summary variables](@id variables)
+```@meta
+CollapsedDocStrings = true
+```
+```@autodocs
+Modules = [
+ MRIBuilder.Variables,
+]
+```
\ No newline at end of file
--
GitLab