========================================================================
This folder contains the solver (semismoothsolverK_preconditioner.m) 
for the Semismooth Newton Method for BAP for Spectrahedra. 
========================================================================

QUICK START
-----------
Solves matrix projection problems of the form:
    minimize    1/2 * ||x - v||^2
    subject to  A*x = b,
                sMat(x) is positive semidefinite.
Here, `x` and `v` are represented in svec coordinates, and `sMat(x)`
maps the vector representation to a symmetric matrix. The problem is the
Euclidean projection of `v` onto the intersection of an affine space and
the positive semidefinite cone.

The solver uses the optimality conditions
    F(y) = A * (v + A' * y)_+ - b = 0,
where `(.)_+` denotes projection onto the positive semidefinite cone.

USAGE
-----
Call the solver as follows:

  output = semismoothsolverK_preconditioner(A, b, v, options)

INPUTS
------
    A       - Constraint matrix of size m-by-n_svec. Its rows are assumed to be linearly independent (full row rank).
    b       - Right-hand-side vector of length m.
    v       - Initial/reference point in svec coordinates, of length n*(n+1)/2.
    options - Optional structure controlling the solver. Supported fields:
        maxiter       Maximum number of iterations (default: 100).
        tol           Stopping tolerance for the relative primal residual (default: 1e-7).
        modprint      Print progress every modprint iterations (default: 10).
        verbose       Enable textual output (default: true).
        verbosePlot   Generate convergence and Jacobian-condition plots (default: true).
        yk            Initial dual multiplier; supplying it provides a warm start (default: zeros(m,1)).
        saveeigs      Save Jacobian eigenvalues during the iterations when true.
        svindn        Indices of the strictly upper-triangular entries used in the svec representation (default: standard upper-triangular indices).
        sMindn        Index mapping used to convert between svec and matrix representations (default: constructed internally).
              
OUTPUTS
-------
The function returns an `output` structure. Main fields include:
    xfinal      Final primal vector in svec coordinates.
    Xfinal      Final primal matrix.
    zfinal      Final cone/slack vector in svec coordinates.
    Zfinal      Final cone/slack matrix.
    yfinal      Final dual multiplier.
    relresid    Relative equality-constraint residual.
    lbnd        Dual lower bound for the projection objective.
    iter        Iteration count.
    mineig      Smallest eigenvalue of the final primal matrix.
    noSlater    Flag set when the solver's ill-conditioning test indicates possible failure of strict feasibility.
    condJac     Condition number of the Jacobian at termination.


REQUIRED HELPERS
----------------
Ensure `projK.m`, `ssMat.m`, and `degenChecker.m` are on your MATLAB path.