Compute a set of leading singular triplets of a black-box operator.

**NOTE:** triplets are not guaranteed to convergence in any
particular order. If you need a predetermined number of the dominating triplets
of the operator, please compute a few extra triplets and discard any unwanted
triplets.

`h=bbsvdf(bb,f,...)` | |

`h=bbsvdf(bb,opt,f,...)` |

This is a medium-level routine for computing some leading singular triplets of a black-box matrix. For a high-level alternative see bbsvds.

As a result of design decisions meant to minimize memory consumption, the function
`bbsvdf`

may seem complicated to use. It is best used as a subroutine for
functions at a higher level. You should evaluate the package using
bbsvds to determine whether `bbsvdf`

is
worthwhile.

`bb` |
Black-box operator or matrix |

`f` |
to callback function. |

`opt`
| Struct with options |

The call-back function, `f`

, is called with the following syntax:

`done = f(u,v,sig,...)` |

The trailing arguments are the same as those given to `bbsvdf`

.
The return-value `done`

should be `true`

if `bbsvdf`

should stop further processing and `false`

otherwise.

The idea of returning triplets to a user-defined function may be unfamiliar. However, many applications can use the triplets one at a time and then dispose of them (e.g. solving equations). This scheme allows one to use more triplets than will fit in memory.

`opt`

, if given, is a structure that allows one to tune the computation.
This should not normally be necessary unless memory consumption is an issue.
See bbsvdopt for a description of the most useful
options (the full list is given in the
reference documentation).

The SVD resulting from the computation is returned using the call-back function
`f`

. This is the main result of the computation.

`h`

is a structure with internal data used by `bbsvdf`

.
It is highly unlikely that a normal user would ever use the result, which contains data such
as unconverged subspaces. The exact format of this result is subject to change and should
not be relied upon.

In short, only highly adventurous people who thinks they know what they are doing, and people trying to debug the package should use this output.

In exact arithmetics the algorithm would be equivalent to Lanczos
Bidiagonalization [15] with
implicit restarting [17]. To battle rounding errors it also uses
reorthogonalization, using a scheme that falls somewhere in between
*full reorthogonalization* and *selective reorthogonalization*, depending
on the deflation strategy.

[15] Christopher Conway Paige and Michael A. Saunders.
__LSQR: An Algorithm for Sparse Linear Equations and Sparse Least Squares__.
*ACM Transactions on Mathematical Software (TOMS)*, 8(1):43-71, 1982.
ACM Press.
ISSN: 0098-3500.
(Paper)

[17] Danny C. Sorensen.
__Implicitly restarted Arnoldi/Lanczos methods for large scale eigenvalue calculations__.
Published in 1996.
Reference number: TR-96-40.
(Technical report: )