{"id":6216,"library":"qdldl","title":"QDLDL Factorization","description":"QDLDL is a Python wrapper for the QDLDL C library, providing a high-performance LDL factorization routine primarily for sparse matrices. It's designed for use in optimization and numerical methods, particularly for solving symmetric indefinite systems like those arising in KKT matrices. The current version is 0.1.9.post1, with updates released periodically to support newer Python versions, architectures, and upstream C library improvements.","status":"active","version":"0.1.9.post1","language":"en","source_language":"en","source_url":"https://github.com/oxfordcontrol/qdldl-python/","tags":["linear algebra","sparse matrices","factorization","numerical optimization","LDL factorization","KKT systems"],"install":[{"cmd":"pip install qdldl","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Used for sparse matrix creation (csc_matrix) in common workflows and examples.","package":"scipy","optional":false}],"imports":[{"note":"The library is typically imported directly as 'qdldl'.","symbol":"qdldl","correct":"import qdldl"}],"quickstart":{"code":"import qdldl\nimport numpy as np\nfrom scipy.sparse import csc_matrix\n\n# Construct a sparse symmetric indefinite matrix, typically a KKT matrix.\n# K = [ P  A.T ]\n#     [ A   0  ]\n\n# Example components:\nP_data = np.array([2.0, 1.0, 1.0, 3.0])\nP_row_ind = np.array([0, 0, 1, 1])\nP_col_ind = np.array([0, 1, 0, 1])\nP = csc_matrix((P_data, (P_row_ind, P_col_ind)), shape=(2, 2))\n\nA_constr_data = np.array([1.0, 1.0, 1.0])\nA_constr_row_ind = np.array([0, 1, 1])\nA_constr_col_ind = np.array([0, 0, 1])\nA_constr = csc_matrix((A_constr_data, (A_constr_row_ind, A_constr_col_ind)), shape=(2, 2))\n\nn_P = P.shape[0]\nn_A = A_constr.shape[0]\nn = n_P + n_A\n\n# Build the full KKT matrix\nKKT = csc_matrix(\n    (n, n),\n    dtype=P.dtype\n)\nKKT[:n_P, :n_P] = P\nKKT[:n_P, n_P:] = A_constr.T\nKKT[n_P:, :n_P] = A_constr\n\n# The 'd' argument for qdldl.qdldl is a user-defined initial diagonal for pivoting.\n# A common choice is a vector of ones.\nd = np.ones(n)\n\n# Perform LDL factorization\n# L_factor is a csc_matrix (lower triangular factor),\n# D_diag is a numpy array (diagonal of D),\n# P_vec is a numpy array (permutation vector).\nL_factor, D_diag, P_vec = qdldl.qdldl(KKT, d)\n\n# Solve a system KKT @ x = b\nb = np.array([10.0, 20.0, 5.0, 8.0]) # Example right-hand side\n\n# Use the qdldl.solve function to get the solution x\nx = qdldl.solve(L_factor, D_diag, P_vec, b)\n\nprint(\"Input KKT matrix (dense representation for display):\\n\", KKT.toarray())\nprint(\"Right-hand side b:\\n\", b)\nprint(\"Solution x:\\n\", x)\n\n# Verify the solution\nprint(\"KKT @ x:\\n\", KKT @ x)\nprint(\"Error (KKT @ x - b):\\n\", KKT @ x - b)\nassert np.allclose(KKT @ x, b, atol=1e-9)\nprint(\"Solution verified.\")","lang":"python","description":"This quickstart demonstrates how to factorize a sparse symmetric indefinite matrix (e.g., a KKT matrix) using `qdldl.qdldl` and then solve a linear system with the obtained factors using `qdldl.solve`. It uses `scipy.sparse.csc_matrix` for efficient sparse matrix representation."},"warnings":[{"fix":"Upgrade `qdldl` to `0.1.7.post4` or newer: `pip install --upgrade qdldl`.","message":"Older versions of `qdldl` (pre-0.1.7.post4) may not be compatible with NumPy 2.0 due to breaking changes in NumPy's API, potentially leading to build failures or runtime errors.","severity":"gotcha","affected_versions":"<0.1.7.post4"},{"fix":"Ensure input matrices are in CSC format. If starting from another sparse format (e.g., CSR), convert using `matrix.tocsc()`.","message":"QDLDL is specifically optimized for sparse matrices and expects input matrices to be in the Compressed Sparse Column (CSC) format for optimal performance and correctness.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the `qdldl` release notes on GitHub for specific Python version compatibility. Ensure your Python environment is supported by the installed `qdldl` version, or upgrade `qdldl`.","message":"Compatibility with newer Python versions is added incrementally. For example, version `0.1.9` added support for Python 3.14. Using an older `qdldl` with a very new Python interpreter, or vice-versa, might lead to installation issues or unexpected behavior.","severity":"gotcha","affected_versions":"Specific older `qdldl` versions with very new Python interpreters, or vice-versa."},{"fix":"Consider the numerical stability of your problem and input data. For ill-conditioned systems, preconditioning or alternative solvers may be necessary.","message":"The underlying C library of QDLDL uses `double` precision floating-point numbers. Users should be aware of potential floating-point inaccuracies inherent in numerical computations, especially when dealing with ill-conditioned matrices.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}