Add koma CLI app (#769)

* Add KomaMRI CLI app

* Bump KomaMRI patch version

* Fix CLI app compatibility

* Add koma CLI preferences

* Cover koma CLI behavior

* Use pkg app commands in docs

* Use app dev in CLI docs

* Cover koma CLI batch paths

* Update docs preview metadata

Author: cncastillo

.github/workflows/docs-preview.yml

@@ -120,7 +120,9 @@ jobs:
             const prNumber = Number('${{ steps.pr.outputs.number }}');
             const previewUrl = `https://juliahealth.github.io/KomaMRI.jl/previews/PR${prNumber}/`;
             const marker = '<!-- komamri-docs-preview-link -->';
-            const body = `${marker}\nPreview available: ${previewUrl}`;
+            const previewSha = context.payload.workflow_run.head_sha.slice(0, 7);
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const body = `${marker}\nPreview available: ${previewUrl}\n\nLast preview build: ${previewSha}, [Docs Preview run ${context.runId}](${runUrl})`;
 
             const { data: comments } = await github.rest.issues.listComments({
               owner: context.repo.owner,

Project.toml

@@ -1,11 +1,14 @@
 name = "KomaMRI"
 uuid = "6a340f8b-2cdf-4c04-99be-4953d9b66d0a"
-version = "0.10.1"
+version = "0.10.2"
 authors = ["Carlos Castillo Passi <cncastillo@uc.cl>"]
 
 [workspace]
 projects = ["test", "docs", "benchmarks", "KomaMRIBase", "KomaMRICore", "KomaMRIFiles", "KomaMRIPlots"]
 
+[apps]
+koma = { submodule = "CLI", julia_flags = ["--threads=auto"] }
+
 [deps]
 AssetRegistry = "bf4720bc-e11a-5d0c-854e-bdca1663c893"
 Blink = "ad839575-38b3-5650-b840-f874b8c74a25"
@@ -16,6 +19,8 @@ KomaMRIFiles = "fcf631a6-1c7e-4e88-9e64-b8888386d9dc"
 KomaMRIPlots = "76db0263-63f3-4d26-bb9a-5dba378db904"
 MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
 MRIReco = "bdf86e05-2d2b-5731-a332-f3fe1f9e047f"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 
 [compat]
@@ -28,5 +33,7 @@ KomaMRIFiles = "0.10"
 KomaMRIPlots = "0.11"
 MAT = "0.10, 0.11, 0.12"
 MRIReco = "0.6, 0.7, 0.8, 0.9"
+PrecompileTools = "1"
+Preferences = "1"
 Reexport = "1"
 julia = "1.9"

README.md

@@ -103,9 +103,12 @@ To install, just **type** `] add KomaMRI` in the Julia REPL or copy-paste the fo
 ```julia
 pkg> add KomaMRI
 pkg> add CUDA     # Optional: Install desired GPU backend (CUDA, AMDGPU, Metal, or oneAPI (experimental))
+pkg> app add KomaMRI # Optional: Install the koma app (Julia 1.12+)
 
 ```
+
 For more information about installation instructions, refer to the section [Getting Started](https://JuliaHealth.github.io/KomaMRI.jl/dev/how-to/1-getting-started) of the documentation.
+
 ## First run
 KomaMRI.jl features a convenient GUI with predefined simulation inputs (i.e. `Sequence`, `Phantom`, and `Scanner`). To launch the GUI, use the following command:
 

docs/src/how-to/1-1-use-koma-ui.md

@@ -22,6 +22,10 @@ julia> using KomaMRI
 
 julia> KomaUI()
 ```
+After installing the [`koma` app](1-4-use-koma-cli.md#Installing-the-App) (Julia 1.12+), the same interface can be opened from the terminal:
+```bash
+koma
+```
 ```@raw html
 <p align="center"><img width="90%" src="../assets/gui-dashboard.png"/></p>
 ```
@@ -151,4 +155,3 @@ The variables that update the interface are:
 * `img_ui[]` for the **Image**
 
 Don't forget to add the brackets `[]` to these variables, otherwise it won't work.
-

docs/src/how-to/1-4-use-koma-cli.md

@@ -0,0 +1,110 @@
+# Use Koma from the Command Line
+
+KomaMRI provides the `koma` Julia app for opening the UI or running simulations from a terminal.
+
+## Installing the App
+
+Install KomaMRI with `pkg> add KomaMRI`, then install the `koma` app (Julia 1.12+):
+```julia-repl
+pkg> app add KomaMRI # Julia 1.12+
+pkg> # app dev /path/to/KomaMRI.jl # Local checkout, Julia 1.12+
+```
+
+The executable is installed in `~/.julia/bin`. If `koma` is not found, add that directory to your `PATH`.
+The app command is named `koma`; Julia app names are executable names, not registered package names.
+
+## Basic Workflow & Input Defaults
+
+With no arguments, `koma` opens the graphical interface with default inputs:
+```bash
+koma
+```
+
+Add input files without output paths to preload the UI before it opens:
+```bash
+koma -i epi.seq brain.phantom
+```
+
+Input files can be passed in any order. KomaMRI identifies them by extension: `.seq`, `.phantom` or `.h5`.
+A scanner `.sys` file is also accepted, but it does nothing for now.
+
+## Running Simulation
+
+Add a simulation output path with `-o` or `--outputs` to run without opening the UI:
+```bash
+koma -i epi.seq brain.phantom -o raw.mrd
+```
+
+Simulation output can be `.mrd` or `.mat`, selected from the output filename extension.
+
+## Reconstructing Image using MRIReco
+
+Pass a second output path to reconstruct after simulation. Reconstruction output is currently `.mat`:
+```bash
+koma -i epi.seq brain.phantom -o raw.mrd image.mat
+```
+
+Use `_` to skip saving the simulation output:
+```bash
+koma -i epi.seq brain.phantom -o _ image.mat
+```
+
+## Simulation and Reconstruction Parameters
+
+Simulation and reconstruction parameters can be passed as repeated `KEY=VALUE` pairs:
+```bash
+koma -i epi.seq brain.phantom -s sim_method=BlochMagnus4 -r reco=direct -o raw.mrd
+```
+
+The long forms are `--sim-param` and `--recon-param`.
+
+## Backend and Threading
+
+Simulations run on multi-threaded CPU by default. GPU backends can be loaded by name:
+```bash
+koma -b Metal -i epi.seq brain.phantom -o raw.mrd
+```
+
+The selected backend package must be installed in your default Julia environment.
+
+The app starts with CPU threading enabled automatically. To choose a thread count, pass Julia flags before `--` and KomaMRI arguments after it:
+```bash
+koma --threads=8 -- -i epi.seq brain.phantom -o raw.mrd
+```
+
+## Default App Configuration
+
+`koma` can read CLI defaults from Julia's `LocalPreferences.toml` in the app environment. Put the file in the path that matches how the app was installed:
+
+- Installed with `pkg> app add KomaMRI` (Julia 1.12+): `~/.julia/environments/apps/KomaMRI/LocalPreferences.toml`
+- Installed with `pkg> app dev /path/to/KomaMRI.jl` (Julia 1.12+): `/path/to/KomaMRI.jl/LocalPreferences.toml`
+
+```toml
+[KomaMRI.koma]
+backend = "CPU" # CPU, CUDA, Metal, AMDGPU, or oneAPI
+
+[KomaMRI.koma.inputs]
+sequence = "mysequence.seq"
+phantom = "myphantom.phantom"
+
+[KomaMRI.koma.outputs]
+# rawdata = "raw.mrd"
+# image = "image.mat"
+
+[KomaMRI.koma.sim_params]
+# Numerical accuracy
+sim_method = "BlochMagnus4"
+precision = "f32"
+"Δt" = 1e-3
+"Δt_rf" = 5e-5
+# Memory
+max_block_length = 512
+max_rf_block_length = inf
+# CPU multi-threaded
+Nthreads = 8
+# GPU kernel launch config
+gpu_groupsize_precession = 256
+gpu_groupsize_excitation = 256
+```
+
+CLI arguments override these defaults.

docs/src/introduction/1-getting-started.md

@@ -16,11 +16,12 @@ This process should take about 5 minutes in a fresh Julia installation. Here is
 ```julia-repl
 julia> ]
 
-(@v1.9) pkg> add KomaMRI
+(@v1.12) pkg> add KomaMRI
+
+pkg> app add KomaMRI # Optional: add koma CLI app (Julia 1.12+)
 ```
 Then press `Ctrl+C` or `backspace` to return to the `julia>` prompt.
 
-
 ---
 ## My First MRI Simulation
 
@@ -35,6 +36,8 @@ The first time you use this command it may take more time than usual, but a wind
 
 ![](../assets/ui-mainpage.png)
 
+The same UI can also be opened from the terminal with the [`koma` app](../how-to/1-4-use-koma-cli.md).
+
 The user interface has some basic definitions for the scanner, phantom, and sequence already preloaded. So you can immediately interact with the simulation and reconstruction processes, and then visualize the results.
 
 As a simple demonstration, press the `Simulate!` button and wait until the simulation is ready. Now you have acquired the `Raw Signal` and you should see the following:

src/KomaApp.jl

@@ -0,0 +1,17 @@
+module CLI
+
+import ..KomaMRI: CLI_HELP, run_cli
+
+function print_help()
+    print(CLI_HELP)
+    return nothing
+end
+
+function (@main)(ARGS)
+    if length(ARGS) == 1 && ARGS[1] in ("-h", "--help")
+        return print_help()
+    end
+    return run_cli(ARGS)
+end
+
+end