Port the Stiefel manifold solvers to Fortran 77

[saudzahirr]

Moves the pystmopt algorithm into this template and reimplements every numerical step in Fortran 77, reached through f2py.

What is in Fortran

The Fortran side owns the whole computation, not just the kernels — the manifold geometry, the proximal operators, the Barzilai-Borwein step sizes and the solver loops themselves. Python only marshals arguments, calls back into the user objective, and prints progress.

The dense linear algebra is hand written alongside it (matrix products, Cholesky, a Jacobi eigensolver for the polar factor, modified Gram-Schmidt), so the extension links against nothing but the Fortran runtime.

File	Contents
src/smblas.f	dense kernels
src/smman.f	Stiefel geometry: C, JA, JC, the A map, the polar retraction
src/smprox.f	proximal operators and the l21 multiplier
src/smslpg.f	the SLPG drivers and the Arrow-Hurwicz inner iteration
src/smpencf.f	the PenCF driver
src/_smopt.pyf	f2py signatures
src/smopt/	the Python layer

All fixed-form, within 72 columns, no allocatable storage — f2py allocates the workspaces via intent(cache,hide) so they never appear in the Python signature.

Interface

The solver set and the output dictionary are unchanged, but the names now follow PEP 8 rather than the original PascalCase, so the package no longer ships names its own linter rejects (N802/N803 hold everywhere and the naming exemptions are gone from pyproject.toml):

was	now
SLPG_smooth	slpg_smooth
SLPG	slpg
SLPG_l21	slpg_l21
PenCF	pencf
Stiefel.Phi/A/C/JA/JC/JC_transpose	phi/a/c/ja/jc/jc_transpose
Feas_eval/Init_point/Post_process	feas_eval/init_point/post_process
Xinit=	xinit=

Stiefel keeps its capital, being a class. The short method names are the symbols the theory documentation already uses for those maps. The original's top-level Solver / manifold / utility packages become smopt.solver / smopt.manifold / smopt.utility, since shipping those names at top level would collide with anything else installed.

Defects fixed in the original

• Init_point compared an array against None with ==, which raises rather than testing for a missing argument.
• Post_process divided by a vanishing singular value, returning a point off the manifold whenever the l21 penalty had zeroed enough rows to make the iterate singular. The rank deficient directions now get an orthonormal completion.

Build and CI fixes

Several of these affect any project generated from f2py-tpl, not just this one.

• f2py splits its own command line on whitespace, so the absolute --build-dir broke on any path containing a space — the normal case on Windows. bin/run_f2py.py stages the signature file into the build directory and runs f2py on a bare file name.
• Meson linked this mixed C/Fortran target with gcc, which rejects the -static-* flags. The link language is pinned to Fortran, and the flags are probed rather than assumed, since -static-libquadmath only exists from GCC 13 on.
• The Windows extension did not import at all — DLL load failed while importing _smopt. It still depended on libwinpthread-1.dll: libgfortran.a refers to it and the gfortran driver appends its own -lwinpthread after everything Meson passes, by which point the linker is back in dynamic mode. --whole-archive defines those symbols independently of link order. The built extension now imports KERNEL32, the UCRT stubs and python3xx only. This affected the published Windows wheel too, not just CI: the build job passed because cibuildwheel builds without importing.
• An SPDX license cannot be combined with a License :: classifier; meson-python refuses outright.
• The test matrix was not testing what it claimed. Its python-version axis was referenced only in the artifact name and never passed to setup-uv, so every job resolved to whichever interpreter uv picked — the job labelled 3.10 actually built and tested cp313. Now passed through, so the five versions are really covered.
• test_pencf_reaches_the_known_minimum asserted rel=1e-5 against the known optimum, which PenCF does not deliver. Holding the problem fixed and varying only the starting point over 60 draws, the relative error has median 7.6e-07 and worst case 1.2e-04; a 150-seed sweep tops out at 1.0e-04, and the NumPy reference is worse still at 1.7e-04. That is the penalty method, not the port — the SLPG solvers reach 3.7e-16 on the same instance and keep their tight tolerance.

The Codecov 404s seen on the first run were left alone deliberately: every earlier run had that step skipped because pytest failed first, so it was the first run to reach the endpoint and no repository record existed yet. Uploads later in the very same run succeeded, so the race is over and weakening fail_ci_if_error would have papered over a resolved transient.

Docs assets

Artwork in the eggzec block style, built from the same rounded blocks on the same grey ground as the other project marks, with lettering from the real eggzec-block.js. Colours are the Space berries palette. The mark is the orthonormality condition itself: a bracketed matrix whose diagonal is solid and whose off-diagonal entries have collapsed to points, which is what X'X = I looks like.

mkdocs.yml already pointed at four asset paths that did not exist (smopt.ico, smopt.png, extra.css, katex.js); all are now resolved, with a single smopt-icon.svg serving as both logo and favicon.

Verification

tests/reference.py keeps a NumPy transcription of the original algorithm as a test oracle, and the suite compares whole trajectories against it, not just the final answer. 151 tests plus 6 doctests pass; ruff check and ruff format --check are clean.

The two implementations are not bit-identical — NumPy sums through BLAS, the Fortran kernels sum in their own order — so the trajectory tests compare a 10-iteration horizon, where the worst deviation across every case is 6.5e-10. Convergence over long runs is asserted separately against the known optimum.

All 23 checks pass across ubuntu, macOS and Windows on Python 3.10 through 3.14.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️