docs(flomni): document tomo_scan_resume, scan queueing, and related tomo_parameters() additions

- Add tomo_scan_resume() as the primary recommended way to continue an
  interrupted scan, in both the user guide and the setup reference
  (manual subtomo_start/start_angle/projection_number kept as fallback)
- Add a new "Queueing multiple scans" section (short walkthrough in the
  user guide, full command reference + status semantics in the setup
  reference, cross-linked via a new anchor)
- Document the live progress report's ETA, automatic gap detection, and
  the total-time-lost-to-gaps summary
- Document the zero_deg_reference_at_each_subtomo tomo_parameters() option
- Fix stale SPEC_ptycho_align.m references -> BEC_ptycho_align.m

docs/user/ptychography/flomni.md

@@ -48,12 +48,13 @@ Manually move the gripper to a transfer position
 #### Coarse alignment
 
 After the sample transfer the sample stage moved to the measurement position with your new sample. The Xray eye will automatically move in and the shutter will open. You may already see the sample in the omny xeye interface running on the windows computer.
-If you see your sample already at the approximately correct height, you can skip steps 1 to 3. Otherwise adjust the height:
++Height is now centered automatically as part of step 3 below, so manual height adjustment is only needed if the sample is far off screen to begin with:
 
-1. `flomni.feedback_disable()` disable the closed loop operation to allow movement of coarse stages
-1. `umvr(dev.fsamy, 0.01)`, attention: unit <mm>, move the sample stage relative up (positive) or down (negative) until the sample is approximately vertically centered in xray eye screen
+
++1. If the sample is far off screen, `flomni.feedback_disable()` then `flomni.umvr_fsamy_tracked(0.01)`, attention: unit <mm>, move the sample stage relative up (positive) or down (negative) until the sample is visible in the xray eye screen, then `flomni.feedback_enable_with_reset()`
 1. `flomni.xrayeye_update_frame()` will update the current image on the xray eye screen
-1. `flomni.xrayeye_alignment_start()` start the coarse alignment of the sample by measuring (clicking in the X-ray eye software) the sample position at 0, 45, 90, 135, 180 degrees. The GUI will present a fit of this data, which is automatically loaded to BEC for aligning the sample.
++1. `flomni.xrayeye_alignment_start()` start the coarse alignment: mark the sample once to auto-center its height, then measure (clicking in the X-ray eye software) the sample position at 0, 45, 90, 135, 180 degrees. The GUI will present a fit of this data, which is automatically loaded to BEC for aligning the sample.
+
 
 #### Fine alignment
 
@@ -68,19 +69,31 @@ _To bypass the fine alignment: `flomni.feye_out`_
 ### Tomographic Measurement
 
 Now that the sample is aligned, the tomographic measurement can be performed.
-1. `flomni.tomo_parameters()` adjust the scan parameters for the tomographic scan. This includes the parameters for ptychographic scans of projections plus the strategy for angular sampling. The vertical shift adjusts the field of view, up (positive) or down (negative). After adjusting the numbers, type again `flomni.tomo_parameters()` and verify that they are correct.
-1. `flomni.tomo_scan_projection(angle)` perform a ptychographic scan at the rotation angle <angle>. Launch the tomographic measurement by `flomni.tomo_scan()`. 
+1. `flomni.tomo_parameters()` adjust the scan parameters for the tomographic scan. This includes the parameters for ptychographic scans of projections plus the strategy for angular sampling. The vertical shift adjusts the field of view, up (positive) or down (negative). After adjusting the numbers, type again `flomni.tomo_parameters()` and verify that they are correct. For the "8 sub-tomograms" mode, an optional 0-deg reference shot can be enabled at the start of every odd sub-tomogram and once more at the end, useful for tracking radiation damage over the course of a long measurement.
+1. `flomni.tomo_scan_projection(angle)` perform a ptychographic scan at the rotation angle <angle>. Launch the tomographic measurement by `flomni.tomo_scan()`. During the scan a live progress report is printed, including an estimated time of completion. Unusually long gaps (e.g. a beamline interruption) are detected automatically and excluded from the estimate, and the total time lost to such gaps is reported once the scan finishes.
 1. Before changing sample, verify that all subtomograms were completely acquired using the tomo_reconstruction matlab script.
 
+#### Queueing multiple scans
+
+Several parameter sets can be queued and run one after another automatically, e.g. a fast overview scan followed by a higher resolution scan on the same sample, without having to wait around to start the next one by hand.
+1. `flomni.tomo_parameters()` set up the first parameter set, then `flomni.tomo_queue_add("label")` to add it to the queue.
+1. Repeat for further parameter sets.
+1. `flomni.tomo_queue_show()` review the queue before starting.
+1. `flomni.tomo_queue_execute()` run all queued scans in sequence.
+
+If a queued scan is interrupted, the next call to `flomni.tomo_queue_execute()` resumes it automatically rather than starting over, then continues with the remaining entries. See [Tomography](user.ptychography.flomni.tomography) below for the full command reference.
+
 #### If something went wrong…
 
 A __single projection__ is to be repeated use
 `flomni.tomo_scan_projection(<angle>)`. The target angle of scans can be found in the second column of the file in 
 `~/data/raw/logs/tomography_scannumbers.txt`
 
-To continue an __interrupted tomography scan__:
+To continue an __interrupted tomography scan__, run  
+`flomni.tomo_scan_resume()`  
+It picks up automatically from wherever the scan was interrupted, no need to look up the exact subtomogram/angle by hand.
 
-Depending on the tomo mode following parameters can be given to the `flomni.tomo_scan()` command:
+Alternatively, the same kind of parameters used internally by `tomo_scan_resume()` can be given to `flomni.tomo_scan()` directly, e.g. to resume from a different point than where it actually stopped:
 | tomo type | parameters and their defaults |
 | --- | --- |
 | 8 sub-tomograms | subtomo_start=1, start_angle=None |
@@ -245,7 +258,7 @@ To start the xray eye alignment (and clear any previous alignment)
 This command can also be called to keep the shutter open and live view active. Warning: The dose to the sample will be significantly higher.
 `flomni.xrayeye_update_frame(keep_shutter_open=True)`
 
-To load the fit parameters from directory _dir_path_ computed by _SPEC_ptycho_align.m_ in Matlab run  
+To load the fit parameters from directory _dir_path_ computed by _BEC_ptycho_align.m_ in Matlab run  
 `flomni.read_alignment_offset(dir_path='')`  
 The loading routine uses default values for the vertical alignment. This behavior can be changed (e.g. for getting new default values) by the parameter `use_vertical_default_values=False`.
 
@@ -263,7 +276,7 @@ The alginment obtained by the X-ray eye can be refinde by recording ptychography
 Next, run the alignment scan by
 `flomni.tomo_alignment_scan()`
 
-Reconstruct the scan and use SPEC_ptycho_align.m to obtain improved fit parameters. The new parameters can be loaded by  
+Reconstruct the scan and use BEC_ptycho_align.m to obtain improved fit parameters. The new parameters can be loaded by  
 `flomni.read_alignment_offset()`
 
 For a __very__ tight vertical field of view, a fine vertical alignment based on outputs generated from early tomography reconstructions can be used. A corresponding file can be generated by the tomography reconstruction script and can be loaded by the following two methods:  
@@ -288,6 +301,7 @@ Define the scan parameters by `flomni.tomo_parameters()`
 
 Run a scan at _angle_ (in degrees) by `flomni.tomo_scan_projection(angle)`
 
+(user.ptychography.flomni.tomography)=
 ### Tomography
 
 The tomo parameters have to be set by  
@@ -296,6 +310,8 @@ The tomo parameters have to be set by
 Once satisfied with the alignment, the tomography scan can be started by  
 `flomni.tomo_scan()`
 
+During the scan, a live progress report is printed (subtomogram/projection counters and an estimated time of completion). Gaps significantly longer than a normal acquisition cycle (e.g. a beamline-down interruption, or a crash followed by a restart) are detected automatically from the time between consecutive projections and excluded from the time estimate; the total time lost to such gaps is printed once the scan finishes.
+
 Three modes for angular sampling are implemented and they have different optional parameters for the tomo_scan method:
 | tomography mode | parameters and defaults |
 | --- | --- |
@@ -303,9 +319,38 @@ Three modes for angular sampling are implemented and they have different optiona
 | Golden ratio tomography (sorted in bunches) | projection_number=None |
 | Equally spaced with golden starting angle | projection_number=None |
 
-The parameters can be used to __restart an interrupted acquisition__. 
+For the "8 sub-tomograms" mode, `flomni.tomo_parameters()` also offers a `zero_deg_reference_at_each_subtomo` option: when enabled, an additional reference projection at exactly 0 degrees is acquired at the start of every odd (forward) sub-tomogram and once more after the final sub-tomogram, useful for tracking radiation damage across the full measurement.
+
+The parameters above can be used to __restart an interrupted acquisition__ manually, or - more conveniently - by running  
+`flomni.tomo_scan_resume()`  
+which reads the last recorded progress and resumes automatically at the exact point (subtomogram/angle, or projection for the golden ratio modes) the scan was interrupted at, without needing to look up the values by hand.
+
 In case of eight equally spaced sub-tomograms, an individual sub tomogram can be scanned by flomni.sub_tomo_scan(subtomo_number, start_angle). If the start angle is not specified, it will be computed depending on the subtomo_number, which is ranging from 1 to 8.
 
+#### Queueing multiple scans
+
+Several tomo parameter sets can be queued and run sequentially on the same sample, without having to start each one by hand.
+
+| command | explanation |
+| --- | --- |
+| `flomni.tomo_queue_add(label=None)` | Snapshot the currently set tomo parameters and add them as a new job to the queue. Returns the job's index. |
+| `flomni.tomo_queue_show()` | Print and return the current queue, with status per job. |
+| `flomni.tomo_queue_delete(*indices)` | Delete one or more jobs by index. |
+| `flomni.tomo_queue_clear()` | Empty the queue. |
+| `flomni.tomo_queue_execute(start_index=0)` | Run all pending jobs in sequence, on the current sample. |
+
+The queue is persisted (it survives a BEC client restart). Each job's status is one of `pending`, `running`, `incomplete`, or `done`. A job that did not run to completion (an exception was caught, or the BEC client itself crashed mid-scan) is automatically resumed - rather than restarted - the next time `flomni.tomo_queue_execute()` is called.
+
+Example:
+```
+flomni.tomo_parameters()                  # set up parameter set #1
+flomni.tomo_queue_add("fast overview")
+flomni.tomo_parameters()                  # set up parameter set #2
+flomni.tomo_queue_add("hires scan")
+flomni.tomo_queue_show()
+flomni.tomo_queue_execute()               # runs both, in order, on this sample
+```
+
 ### Sample storage and transfer
 
 [See short version](user.ptychography.flomni.transfer)