Add basic sequence optimisation docs

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),

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

docs/src/implemented_sequences.md

-# 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)
+```@meta
+CollapsedDocStrings = true
+```
\ No newline at end of file
+```@autodocs
+Modules = [
+    MRIBuilder.Sequences,
+    MRIBuilder.Sequences.GradientEchoes,
+    MRIBuilder.Sequences.SpinEchoes,
+    MRIBuilder.Sequences.DiffusionSpinEchoes,
+]
+```

docs/src/scanners.md

+# [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

docs/src/sequence_optimisation.md

+# [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