routine_inventory.py

"""Reviewed SciPy 1.18.0 float64 LAPACK inventory and LAPACK family ownership."""

from __future__ import annotations

from dataclasses import dataclass

SCIPY_VERSION = "1.18.0"
EXPECTED_LAPACK_SOURCE_FILES = 2062
EXPECTED_LAPACK_PROCEDURES = 2066
F2PY_SCALAR_WRITEBACK_ROUTINES = frozenset(
    {"dlarfg", "dlartg", "dgbcon", "dgecon", "dgtcon", "dpocon", "dppcon", "dsycon", "dtrcon"}
)

F2PY_FUNCTION_RESULTS = frozenset({"dlamch", "dlangb", "dlange", "dlantr"})
ROUTINE_GROUPS = {
    "auxiliary": (
        "dlamch",
        "dlangb",
        "dlange",
        "dlantr",
        "dlarf",
        "dlarfg",
        "dlartg",
        "dlaswp",
    ),
    "linear_general": (
        "dgecon",
        "dgeequ",
        "dgeequb",
        "dgesc2",
        "dgesv",
        "dgesvx",
        "dgetc2",
        "dgetrf",
        "dgetri",
        "dgetrs",
    ),
    "linear_symmetric_indefinite": (
        "dsycon",
        "dsyconv",
        "dsyequb",
        "dsysv",
        "dsysvx",
        "dsytf2",
        "dsytrf",
        "dsytri",
        "dsytrs",
    ),
    "linear_positive_definite": (
        "dlauum",
        "dpftrf",
        "dpftri",
        "dpftrs",
        "dpocon",
        "dposv",
        "dposvx",
        "dpotrf",
        "dpotri",
        "dpotrs",
        "dppcon",
        "dppsv",
        "dpptrf",
        "dpptri",
        "dpptrs",
        "dpstf2",
        "dpstrf",
        "dsfrk",
    ),
    "linear_banded_tridiagonal": (
        "dgbcon",
        "dgbsv",
        "dgbtrf",
        "dgbtrs",
        "dgtcon",
        "dgtsv",
        "dgtsvx",
        "dgttrf",
        "dgttrs",
        "dpbsv",
        "dpbtrf",
        "dpbtrs",
        "dptsv",
        "dptsvx",
        "dpttrf",
        "dpttrs",
        "dtbtrs",
    ),
    "linear_triangular": (
        "dtfsm",
        "dtfttp",
        "dtfttr",
        "dtpttf",
        "dtpttr",
        "dtrcon",
        "dtrtri",
        "dtrtrs",
        "dtrttf",
        "dtrttp",
    ),
    "least_squares": (
        "dgels",
        "dgelsd",
        "dgelss",
        "dgelsy",
        "dgglse",
    ),
    "orthogonal_factorizations": (
        "dgemqrt",
        "dgeqp3",
        "dgeqrf",
        "dgeqrfp",
        "dgeqrt",
        "dgerqf",
        "dorgqr",
        "dorgrq",
        "dormqr",
        "dormrz",
        "dtpmqrt",
        "dtpqrt",
        "dtzrzf",
    ),
    "eigen_nonsymmetric": (
        "dgebal",
        "dgees",
        "dgeev",
        "dgehrd",
        "dorghr",
        "dtrexc",
        "dtrsen",
        "dtrsyl",
    ),
    "eigen_symmetric": (
        "dpteqr",
        "dsbev",
        "dsbevd",
        "dsbevx",
        "dstebz",
        "dstein",
        "dstemr",
        "dsterf",
        "dstev",
        "dstevd",
        "dsyev",
        "dsyevd",
        "dsyevr",
        "dsyevx",
        "dsytrd",
    ),
    "eigen_generalized": (
        "dgges",
        "dggev",
        "dsygst",
        "dsygv",
        "dsygvd",
        "dsygvx",
        "dtgexc",
        "dtgsen",
        "dtgsyl",
    ),
    "svd": (
        "dgejsv",
        "dgesdd",
        "dgesvd",
        "dorcsd",
        "dlasd4",
    ),
}

ROUTINES = tuple(name for names in ROUTINE_GROUPS.values() for name in names)
ROUTINE_FAMILIES = {name: family for family, names in ROUTINE_GROUPS.items() for name in names}
EXPLICIT_TEST_NAMES = {
    "dlamch": "test_dlamch_reports_float64_machine_epsilon",
    "dlangb": "test_dlangb_computes_frobenius_norm_of_band_storage",
    "dlange": "test_dlange_computes_one_norm",
    "dlantr": "test_dlantr_ignores_unused_triangle_and_unit_diagonal",
    "dlarf": "test_dlarf_applies_householder_reflector_from_left",
    "dlarfg": "test_dlarfg_constructs_a_valid_householder_reflector",
    "dlartg": "test_dlartg_constructs_a_givens_rotation",
    "dlaswp": "test_dlaswp_applies_native_one_based_row_pivots",
    "dgecon": "test_dgecon_estimates_reciprocal_condition",
    "dgeequ": "test_dgeequ_computes_row_and_column_scaling",
    "dgeequb": "test_dgeequb_computes_radix_scaling",
    "dgesc2": "test_dgesc2_solves_complete_pivot_lu_system",
    "dgesv": "test_dgesv_solves_general_system",
    "dgesvx": "test_dgesvx_solves_and_reports_error_bounds",
    "dgetc2": "test_dgetc2_factorizes_with_complete_pivoting",
    "dgetrf": "test_dgetrf_reconstructs_pivoted_lu",
    "dgetri": "test_dgetri_inverts_lu_factorization",
    "dgetrs": "test_dgetrs_solves_from_native_lu",
    "dsycon": "test_dsycon_estimates_symmetric_reciprocal_condition",
    "dsyconv": "test_dsyconv_converts_bunch_kaufman_storage",
    "dsyequb": "test_dsyequb_scales_symmetric_matrix",
    "dsysv": "test_dsysv_solves_symmetric_indefinite_system",
    "dsysvx": "test_dsysvx_solves_and_bounds_symmetric_error",
    "dsytf2": "test_dsytf2_factorizes_symmetric_indefinite_matrix",
    "dsytrf": "test_dsytrf_factorizes_symmetric_indefinite_matrix",
    "dsytri": "test_dsytri_inverts_symmetric_indefinite_factor",
    "dsytrs": "test_dsytrs_solves_from_symmetric_indefinite_factor",
    "dlauum": "test_dlauum_forms_triangular_product",
    "dpftrf": "test_dpftrf_factorizes_rfp_spd_matrix",
    "dpftri": "test_dpftri_inverts_rfp_cholesky_factor",
    "dpftrs": "test_dpftrs_solves_from_rfp_cholesky_factor",
    "dpocon": "test_dpocon_estimates_spd_reciprocal_condition",
    "dposv": "test_dposv_solves_spd_system",
    "dposvx": "test_dposvx_solves_and_bounds_spd_error",
    "dpotrf": "test_dpotrf_reconstructs_spd_matrix",
    "dpotri": "test_dpotri_inverts_cholesky_factor",
    "dpotrs": "test_dpotrs_solves_from_cholesky_factor",
    "dppcon": "test_dppcon_estimates_packed_spd_condition",
    "dppsv": "test_dppsv_solves_packed_spd_system",
    "dpptrf": "test_dpptrf_factorizes_packed_spd_matrix",
    "dpptri": "test_dpptri_inverts_packed_cholesky_factor",
    "dpptrs": "test_dpptrs_solves_from_packed_cholesky_factor",
    "dpstf2": "test_dpstf2_reconstructs_pivoted_cholesky",
    "dpstrf": "test_dpstrf_reconstructs_blocked_pivoted_cholesky",
    "dsfrk": "test_dsfrk_updates_spd_matrix_in_rfp_storage",
    "dgbcon": "test_dgbcon_estimates_general_band_condition",
    "dgbsv": "test_dgbsv_solves_general_band_system",
    "dgbtrf": "test_dgbtrf_factorizes_general_band_matrix",
    "dgbtrs": "test_dgbtrs_solves_from_general_band_lu",
    "dgtcon": "test_dgtcon_estimates_tridiagonal_condition",
    "dgtsv": "test_dgtsv_solves_general_tridiagonal_system",
    "dgtsvx": "test_dgtsvx_solves_and_bounds_tridiagonal_error",
    "dgttrf": "test_dgttrf_factorizes_general_tridiagonal_matrix",
    "dgttrs": "test_dgttrs_solves_from_tridiagonal_lu",
    "dpbsv": "test_dpbsv_solves_positive_definite_band_system",
    "dpbtrf": "test_dpbtrf_factorizes_positive_definite_band_matrix",
    "dpbtrs": "test_dpbtrs_solves_from_positive_definite_band_factor",
    "dptsv": "test_dptsv_solves_spd_tridiagonal_system",
    "dptsvx": "test_dptsvx_solves_and_bounds_spd_tridiagonal_error",
    "dpttrf": "test_dpttrf_factorizes_spd_tridiagonal_matrix",
    "dpttrs": "test_dpttrs_solves_from_spd_tridiagonal_factor",
    "dtbtrs": "test_dtbtrs_solves_triangular_band_system",
    "dtfsm": "test_dtfsm_solves_with_rfp_triangular_factor",
    "dtfttp": "test_dtfttp_converts_rfp_to_packed",
    "dtfttr": "test_dtfttr_converts_rfp_to_full_triangular",
    "dtpttf": "test_dtpttf_converts_packed_to_rfp",
    "dtpttr": "test_dtpttr_converts_packed_to_full_triangular",
    "dtrcon": "test_dtrcon_estimates_triangular_reciprocal_condition",
    "dtrtri": "test_dtrtri_inverts_triangular_matrix",
    "dtrtrs": "test_dtrtrs_solves_triangular_system",
    "dtrttf": "test_dtrttf_converts_full_triangular_to_rfp",
    "dtrttp": "test_dtrttp_converts_full_triangular_to_packed",
    "dgels": "test_dgels_solves_full_rank_least_squares",
    "dgelsd": "test_dgelsd_solves_rank_revealing_least_squares",
    "dgelss": "test_dgelss_solves_svd_least_squares",
    "dgelsy": "test_dgelsy_solves_pivoted_rank_revealing_least_squares",
    "dgglse": "test_dgglse_solves_equality_constrained_least_squares",
    "dgemqrt": "test_dgemqrt_applies_compact_wy_reflector",
    "dgeqp3": "test_dgeqp3_reconstructs_column_pivoted_qr",
    "dgeqrf": "test_dgeqrf_reconstructs_qr_factorization",
    "dgeqrfp": "test_dgeqrfp_reconstructs_qr_with_nonnegative_diagonal",
    "dgeqrt": "test_dgeqrt_reconstructs_compact_wy_qr",
    "dgerqf": "test_dgerqf_reconstructs_rq_factorization",
    "dorgqr": "test_dorgqr_forms_explicit_orthogonal_q",
    "dorgrq": "test_dorgrq_forms_explicit_row_orthogonal_q",
    "dormqr": "test_dormqr_applies_qr_reflectors",
    "dormrz": "test_dormrz_applies_rz_reflector",
    "dtpmqrt": "test_dtpmqrt_applies_triangular_pentagonal_reflector",
    "dtpqrt": "test_dtpqrt_reconstructs_triangular_pentagonal_qr",
    "dtzrzf": "test_dtzrzf_reconstructs_rz_factorization",
    "dgebal": "test_dgebal_preserves_eigenvalues_while_balancing",
    "dgees": "test_dgees_computes_real_schur_decomposition",
    "dgeev": "test_dgeev_returns_right_eigenvectors",
    "dgehrd": "test_dgehrd_reduces_matrix_to_upper_hessenberg",
    "dorghr": "test_dorghr_forms_hessenberg_similarity_transform",
    "dtrexc": "test_dtrexc_reorders_real_schur_blocks",
    "dtrsen": "test_dtrsen_reorders_selected_schur_eigenvalue",
    "dtrsyl": "test_dtrsyl_solves_sylvester_equation",
    "dpteqr": "test_dpteqr_diagonalizes_positive_definite_tridiagonal",
    "dsbev": "test_dsbev_diagonalizes_symmetric_band_matrix",
    "dsbevd": "test_dsbevd_diagonalizes_band_matrix_by_divide_and_conquer",
    "dsbevx": "test_dsbevx_selects_all_symmetric_band_eigenpairs",
    "dstebz": "test_dstebz_bisects_tridiagonal_eigenvalues",
    "dstein": "test_dstein_computes_tridiagonal_eigenvectors",
    "dstemr": "test_dstemr_computes_robust_tridiagonal_eigenpairs",
    "dsterf": "test_dsterf_computes_tridiagonal_eigenvalues",
    "dstev": "test_dstev_computes_tridiagonal_eigenpairs",
    "dstevd": "test_dstevd_computes_divide_and_conquer_tridiagonal_eigenpairs",
    "dsyev": "test_dsyev_returns_orthonormal_eigenvectors",
    "dsyevd": "test_dsyevd_computes_divide_and_conquer_symmetric_eigenpairs",
    "dsyevr": "test_dsyevr_selects_symmetric_eigenpairs_by_index",
    "dsyevx": "test_dsyevx_selects_symmetric_eigenpairs_by_value",
    "dsytrd": "test_dsytrd_reduces_symmetric_matrix_to_tridiagonal",
    "dgges": "test_dgges_computes_generalized_real_schur_form",
    "dggev": "test_dggev_computes_generalized_right_eigenvectors",
    "dsygst": "test_dsygst_reduces_symmetric_generalized_problem",
    "dsygv": "test_dsygv_solves_symmetric_generalized_eigenproblem",
    "dsygvd": "test_dsygvd_solves_divide_and_conquer_generalized_problem",
    "dsygvx": "test_dsygvx_selects_generalized_eigenpairs",
    "dtgexc": "test_dtgexc_reorders_generalized_schur_blocks",
    "dtgsen": "test_dtgsen_reorders_selected_generalized_eigenvalue",
    "dtgsyl": "test_dtgsyl_solves_generalized_sylvester_equations",
    "dgejsv": "test_dgejsv_reconstructs_matrix_with_jacobi_svd",
    "dgesdd": "test_dgesdd_reconstructs_matrix_with_divide_and_conquer_svd",
    "dgesvd": "test_dgesvd_reconstructs_matrix",
    "dorcsd": "test_dorcsd_decomposes_partitioned_orthogonal_matrix",
    "dlasd4": "test_dlasd4_solves_rank_one_secular_equation",
}

WORKSPACE_ROUTINES = frozenset(
    {
        "dgbcon",
        "dgecon",
        "dgemqrt",
        "dgees",
        "dgeev",
        "dgehrd",
        "dgejsv",
        "dgels",
        "dgelsd",
        "dgelss",
        "dgelsy",
        "dgeqp3",
        "dgeqrf",
        "dgeqrfp",
        "dgeqrt",
        "dgerqf",
        "dgesdd",
        "dgesvd",
        "dgesvx",
        "dgetri",
        "dgges",
        "dggev",
        "dgglse",
        "dgtcon",
        "dgtsvx",
        "dlangb",
        "dlange",
        "dlantr",
        "dlarf",
        "dlasd4",
        "dorcsd",
        "dorghr",
        "dorgqr",
        "dorgrq",
        "dormqr",
        "dormrz",
        "dpocon",
        "dposvx",
        "dppcon",
        "dpstf2",
        "dpstrf",
        "dpteqr",
        "dptsvx",
        "dsbev",
        "dsbevd",
        "dsbevx",
        "dstebz",
        "dstein",
        "dstemr",
        "dstev",
        "dstevd",
        "dsycon",
        "dsyequb",
        "dsyev",
        "dsyevd",
        "dsyevr",
        "dsyevx",
        "dsygvd",
        "dsygv",
        "dsygvx",
        "dsysv",
        "dsysvx",
        "dsytrd",
        "dsytrf",
        "dsytri",
        "dtgexc",
        "dtgsen",
        "dtgsyl",
        "dtpmqrt",
        "dtpqrt",
        "dtrcon",
        "dtrexc",
        "dtrsen",
        "dtzrzf",
    }
)

INDEX_ROUTINES = frozenset(
    {
        "dgbcon",
        "dgbsv",
        "dgbtrf",
        "dgbtrs",
        "dgebal",
        "dgeqp3",
        "dgesc2",
        "dgesv",
        "dgesvx",
        "dgetc2",
        "dgetrf",
        "dgetri",
        "dgetrs",
        "dgtcon",
        "dgtsvx",
        "dgttrf",
        "dgttrs",
        "dgelsy",
        "dlasd4",
        "dlaswp",
        "dpstf2",
        "dpstrf",
        "dsbevx",
        "dstebz",
        "dstein",
        "dstemr",
        "dsyevr",
        "dsyevx",
        "dsycon",
        "dsyconv",
        "dsysv",
        "dsysvx",
        "dsytf2",
        "dsytrf",
        "dsytri",
        "dsytrs",
        "dsygvx",
        "dtgexc",
        "dtgsen",
        "dtrexc",
    }
)

ORACLE_BY_FAMILY = {
    "auxiliary": "explicit machine, norm, reflector, rotation, or permutation identity",
    "linear_general": "solution residual, LU reconstruction, inverse identity, scaling, or condition estimate",
    "linear_symmetric_indefinite": "solution residual, Bunch-Kaufman factor behavior, inverse, scaling, or condition estimate",
    "linear_positive_definite": "Cholesky reconstruction, solution residual, inverse, rank, storage conversion, or condition estimate",
    "linear_banded_tridiagonal": "reconstructed logical matrix, factor agreement, solution residual, or condition estimate",
    "linear_triangular": "triangular residual, inverse identity, condition estimate, or packed/RFP round trip",
    "least_squares": "normal-equation residual, rank, singular values, or equality constraint",
    "orthogonal_factorizations": "reflector identity, orthogonality, and factorization/application reconstruction",
    "eigen_nonsymmetric": "eigen residual, similarity/Schur reconstruction, orthogonality, or Sylvester equation",
    "eigen_symmetric": "eigen residual, orthogonality, selected spectrum, or tridiagonal reduction",
    "eigen_generalized": "generalized eigen residual, Schur reconstruction, or generalized Sylvester equations",
    "svd": "SVD/CSD reconstruction, orthogonality, or secular equation",
}

F2PY_EXPORT_LIMITATIONS = {
    "dgees": "NumPy f2py 2.5.1 generates an incomplete select callback declaration from the unannotated source",
    "dgges": "NumPy f2py 2.5.1 generates an incomplete selctg callback declaration from the unannotated source",
}

PRIK_ABI_ADAPTERS = {
    "dtgsen": "GFortran default-LOGICAL selection storage is four bytes per element while PRIK accepts a NumPy bool buffer",
    "dtrsen": "GFortran default-LOGICAL selection storage is four bytes per element while PRIK accepts a NumPy bool buffer",
}


@dataclass(frozen=True)
class RoutineSpec:
    """Reviewed audit metadata for one selected native LAPACK routine."""

    native_name: str
    source_file: str
    scipy_name: str
    prik_export: str
    prik_adapter: str
    f2py_export: str
    f2py_behavior: str
    family: str
    mutation: str
    returns: str
    workspace: str
    index_convention: str
    oracle: str
    test_name: str


ROUTINE_SPECS = {
    name: RoutineSpec(
        native_name=name,
        source_file=f"{name}.f90" if name == "dlartg" else f"{name}.f",
        scipy_name=name,
        prik_export=name,
        prik_adapter=PRIK_ABI_ADAPTERS.get(name, "none"),
        f2py_export=name,
        f2py_behavior=F2PY_EXPORT_LIMITATIONS.get(
            name,
            (
                "build-local intent directives expose caller-owned scalar writeback storage"
                if name in F2PY_SCALAR_WRITEBACK_ROUTINES
                else "none"
            ),
        ),
        family=ROUTINE_FAMILIES[name],
        mutation="explicit in/out arrays and preserved inputs are asserted in the named test",
        returns="PRIK native scalar tuple, SciPy projected tuple, and f2py observable writeback",
        workspace=(
            "explicit workspace arrays and sizes are visible in the named test"
            if name in WORKSPACE_ROUTINES
            else "no caller-managed workspace"
        ),
        index_convention=(
            "native PRIK/f2py indexes are one-based; any SciPy conversion is visible in the named test"
            if name in INDEX_ROUTINES
            else "no pivot or index conversion"
        ),
        oracle=ORACLE_BY_FAMILY[ROUTINE_FAMILIES[name]],
        test_name=EXPLICIT_TEST_NAMES[name],
    )
    for name in ROUTINES
}