Ensemble.m - Revision history

Kuprov: sync with Spinach main 3975f139: per-worker case blocks and ens_block.m

2026-09-18T09:59:31Z

sync with Spinach main 3975f139: per-worker case blocks and ens_block.m

Kuprov: sync with Spinach main f053e432: parallel pool case distribution note added; duplicate Parameters section merged

2026-08-30T05:42:08Z

sync with Spinach main f053e432: parallel pool case distribution note added; duplicate Parameters section merged

Kuprov: Update function See also links and function index membership

2026-06-06T18:36:22Z

Update function See also links and function index membership

Kuprov: Rename Arguments section heading to Parameters

2026-06-05T17:48:41Z

Rename Arguments section heading to Parameters

Kuprov: Normalise preformatted blank lines in function documentation blocks

2026-06-05T16:40:54Z

Normalise preformatted blank lines in function documentation blocks

Kuprov: Add missing leading spaces to function header blocks

2026-06-05T15:47:42Z

Add missing leading spaces to function header blocks

Kuprov: Update function page arguments and outputs from current Spinach source

2026-06-05T14:22:26Z

Update function page arguments and outputs from current Spinach source

Kuprov: Correct function page syntax from current Spinach source

2026-06-05T14:12:24Z

Correct function page syntax from current Spinach source

Kuprov: Normalise sequential blank lines

2026-04-25T11:25:15Z

Normalise sequential blank lines

Kuprov: Restore pre-bulk-edit wiki content

2026-04-05T14:48:32Z

Restore pre-bulk-edit wiki content

@@ Line 33: / Line 33: @@
 This is a low level function that is not designed to be called directly. Use [[grape_xy.m]] and [[grape_phase.m]] instead.
-The ensemble cases enumerated in spin_system.control.catalog are distributed over the parallel pool workers. Each case fetches the frozen problem data from the pool constant published by [[optimcon.m]] and grafts the live client-side control structure on top of it, so only the waveform and the live control fields travel at each objective evaluation.
+The ensemble cases enumerated in spin_system.control.catalog are processed in the contiguous per-worker blocks assigned by [[optimcon.m]] in spin_system.control.worker_cases. Each worker holds the common frozen problem and the drift generators of its own block, published by [[optimcon.m]] as pool constants; the per-case physics runs in [[ens_block.m]] on each worker, so only the waveform and the live control fields travel at each objective evaluation, and the gradient, the Hessian, and averaged trajectories are summed on the workers. This function must be called from the client, on the pool that was open when [[optimcon.m]] ran: a worker holds only its own block.
 ==See also==
-[[grape_xy.m]], [[grape_phase.m]], [[alpha_conds.m]], [[aux_mat.m]], [[bfgs.m]], [[cubic_interp.m]], [[dirdiff.m]], [[drifts.m]], [[hess_reorder.m]], [[objeval.m]], [[optimcon.m]], [[trapdiff.m]], [[Optimal control module]]
+[[grape_xy.m]], [[grape_phase.m]], [[alpha_conds.m]], [[aux_mat.m]], [[bfgs.m]], [[cubic_interp.m]], [[dirdiff.m]], [[drifts.m]], [[ens_block.m]], [[hess_reorder.m]], [[objeval.m]], [[optimcon.m]], [[trapdiff.m]], [[Optimal control module]]
 ''Version 2.0, authors: [[Ilya Kuprov]], [[David Goodwin]]''

@@ Line 7: / Line 7: @@
       [traj_data,fidelity,gradient,hessian]=ensemble(waveform,spin_system)
 ==Parameters==
@@ Line 36: / Line 32: @@
 ==Notes==
 This is a low level function that is not designed to be called directly. Use [[grape_xy.m]] and [[grape_phase.m]] instead.
 ==See also==

@@ Line 38: / Line 38: @@
 ==See also==
-[[Optimal control module]]
+[[grape_xy.m]], [[grape_phase.m]], [[alpha_conds.m]], [[aux_mat.m]], [[bfgs.m]], [[cubic_interp.m]], [[dirdiff.m]], [[drifts.m]], [[hess_reorder.m]], [[objeval.m]], [[optimcon.m]], [[trapdiff.m]], [[Optimal control module]]
 ''Version 2.0, authors: [[Ilya Kuprov]], [[David Goodwin]]''

← Older revision		Revision as of 17:48, 5 June 2026
Line 8:		Line 8:


−	==~~Arguments~~==	+	==Parameters==

	waveform - control coefficients for each control operator, rad/s		waveform - control coefficients for each control operator, rad/s

@@ Line 20: / Line 20: @@
   traj_data - trajectory data for subsequent diagnostic plotting
-−
   fidelity  - figure of merit for the overlap of the current state of the
              system and the desired state(s). When penalty methods are
              specified, fidelity is returned as an array separating the
              penalties from the simulation fidelity
-−
   gradient  - gradient of the fidelity with respect to the control sequence.
              When penalty methods are specified, gradient is returned as an
              array separating penalty gradients from the fidelity gradient
-−
   hessian   - Hessian of the fidelity with respect to the control sequence.
              When penalty methods are specified, hessian is returned as an

@@ Line 4: / Line 4: @@
 ==Syntax==
       [fidelity,gradient,hessian]=ensemble(waveform,spin_system)
 ==Parameters==

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:ensemble.m}} __NOTOC__
 A parallel wrapper around GRAPE that enables ensemble optimal control optimisations. This function handles systems with multiple control power levels, multiple resonance offsets, multistate transfers, and ensembles of drift Liouvillians.
 ==Syntax==
-[traj_data,fidelity,gradient,hessian]=ensemble(waveform,spin_system)
+     [fidelity,gradient,hessian]=ensemble(waveform,spin_system)
-==Outputs==
+==Parameters==
-traj_data    - trajectory data for subsequent diagnostic plotting
+    waveform  - control coefficients for each control operator, rad/s
-   fidelity     - figure of merit for the overlap of the current state
+==Outputs==
-    gradient     - gradient of the fidelity with respect to the control
+   fidelity      - figure of merit for the overlap of the current state
-                  sequence. When penalty methods are specified, gradi-
+                   of the system and the desired state(s). When penalty
-                  ent is returned as an array separating penalty gra-
+                   methods are specified, fidelity is returned as an ar-
-                  dients from the fidelity gradient.
+                   ray separating the penalties from the simulation
+                   fidelity.
-    hessian      - Hessian of the fidelity with respect to the control
-                  sequence. When penalty methods are specified, gradi-
+    gradient      - gradient of the fidelity with respect to the control
-                  ent is returned as an array separating penalty Hes-
+                   sequence. When penalty methods are specified, gradi-
-                  sians from the fidelity Hessian.
+                   ent is returned as an array separating penalty gra-
+                   dients from the fidelity gradient.
- david.goodwin@inano.au.dk
- ilya.kuprov@weizmann.ac.il
+    hessian       - Hessian of the fidelity with respect to the control
- m.keitel@soton.ac.uk
+                   sequence. When penalty methods are specified, gradi-
 ==Notes==
 This is a low level function that is not designed to be called directly. Use [[grape_xy.m]] and [[grape_phase.m]] instead.
 ==See also==
 [[Optimal control module]]
 ''Version 2.0, authors: [[Ilya Kuprov]], [[David Goodwin]]''