ens_catalog.m

Ensemble case catalog for optimal control problems. Enumerates the Cartesian product of the state-target pairs, the drift generators, the control power levels, the resonance offsets, the phase cycle lines, and the distortion functions; then applies the ensemble correlation filters and the ensemble budget. Each row of the catalog is one ensemble case to be simulated at each evaluation of the control sequence fidelity. The six grid dimensions are taken from the number of elements of control.rho_init, from control.ndrifts, from the number of elements of control.pwr_levels, from the product of the numbers of elements of the cells of control.offsets (one if that cell array is empty), from the number of rows of control.phase_cycle, and from the number of rows of control.distortion. The product is built by repeated Kronecker expansion, so the state-target pair index runs fastest and the distortion index runs slowest.

The entries of control.ens_corrs are then applied as filters. With 'rho_ens', the state-target pair column is dropped, the remaining five columns are reduced with unique(...,'rows','stable'), and the surviving rows are numbered consecutively in that order to give the new state-target pair column; the pairing of user-supplied state-target pairs to ensemble members therefore follows the order in which the distinct five-column combinations first appear in the catalog. With 'rho_drift', only the rows in which the state-target pair index equals the drift index are kept. With 'power_drift', only the rows in which the power level index equals the drift index are kept.

The ensemble budget in control.budget is applied last. A finite budget that is not greater than one is a fraction of the case count: the number of cases retained is round(n_cases*control.budget), floored at one. Any larger budget is an absolute case count. When the resulting number is smaller than the number of catalog rows, a random subset of the rows is drawn; the random number generator is set to the Mersenne twister with seed 5318008 for the draw and its previous state is restored afterwards, so the subset is the same on every run.

Syntax

    [catalog,ens_sizes]=ens_catalog(control)

Parameters

    control    - control data structure produced by optimcon.m

Outputs

    catalog    - [n_cases x 6] array of ensemble indices; the col-
                 umns index the state-target pair, the drift gene-
                 rator, the power level, the offset combination,
                 the phase cycle line, and the distortion function

    ens_sizes  - [1 x 6] array of the ensemble dimension sizes the
                 catalog was built from, in the same column order

Notes

ens_sizes reports the dimensions of the full Cartesian grid, before the correlation filters and the budget are applied; the number of rows of catalog is in general smaller than the product of those dimensions.

The function requires control to be a structure carrying the rho_init, ndrifts, pwr_levels, offsets, phase_cycle, distortion, ens_corrs, and budget fields.

See also

optimcon.m, ensemble.m, drifts.m, Optimal control module

Version 2.13, authors: Ilya Kuprov