pochep-procmat 0.0.1__tar.gz

pochep_procmat-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

pochep_procmat-0.0.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.0.1
+
+- First release. QR, SVD, Cholesky normal equations, NNLS and NMF solvers for `M t = p`.
+- `ProcessMemoryModel` with `fit`, `predict` and `FitResult`.
+- Synthetic generator `make_process_profiles` for tests and the demo.
+- Input validators raising `TypeError` or `ValueError`. 24 tests on Python 3.14.

pochep_procmat-0.0.1/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "pochep-procmat: matrix decompositions for the process memory model M t = p"
+type: software
+version: 0.0.1
+date-released: 2026-11-13
+license: MIT
+repository-code: "https://github.com/89605502155/pochep-procmat"
+url: "https://pypi.org/project/pochep-procmat/"
+authors:
+  - family-names: Ferubko
+    given-names: Andrey O.
+    affiliation: "Bryansk State University of Engineering and Technology"
+    email: ferubko1999@yandex.ru
+    orcid: "https://orcid.org/0009-0006-5625-137X"
+  - family-names: Kazakov
+    given-names: Oleg D.
+    affiliation: "Bryansk State University of Engineering and Technology"
+    email: kazakov@bgitu.ru
+    orcid: "https://orcid.org/0000-0001-9665-8138"
+keywords:
+  - matrix decomposition
+  - SVD
+  - QR
+  - NMF
+  - process memory

pochep_procmat-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg D. Kazakov, Andrey O. Ferubko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pochep_procmat-0.0.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: pochep-procmat
+Version: 0.0.1
+Summary: Matrix decompositions (QR, SVD, Cholesky, NNLS, NMF) for the process memory model M t = p
+Project-URL: Homepage, https://github.com/89605502155/pochep-procmat
+Project-URL: Repository, https://github.com/89605502155/pochep-procmat
+Project-URL: Demo, https://github.com/89605502155/pochep-procmat-demo
+Project-URL: Changelog, https://github.com/89605502155/pochep-procmat/blob/main/CHANGELOG.md
+Author-email: "Andrey O. Ferubko" <ferubko1999@yandex.ru>, "Oleg D. Kazakov" <kazakov@bgitu.ru>
+Maintainer-email: "Andrey O. Ferubko" <ferubko1999@yandex.ru>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: NMF,QR,SVD,linear model,matrix decomposition,memory,process
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0
+Description-Content-Type: text/markdown
+
+# pochep-procmat
+
+Matrix decompositions for the process memory model `M t = p`.
+
+Rows of `M` are timestamps and columns are processes. `p` is the total memory measured at each
+timestamp and `t` is the vector of per-process weights. The package solves this linear system
+with QR, SVD, Cholesky normal equations, non-negative least squares (NNLS), and fits NMF
+factors `M ~ W H`. It also provides a synthetic generator of process profiles for tests.
+
+Russian version: [README.ru.md](README.ru.md). Documentation: [docs/en](docs/en/theory.md), [docs/ru](docs/ru/theory.md).
+Demo notebook with strengths and weaknesses: https://github.com/89605502155/pochep-procmat-demo
+
+## Install
+
+```bash
+pip install pochep-procmat
+```
+
+Requires Python 3.11 to 3.14 and NumPy 2.0 or newer. Released on PyPI: https://pypi.org/project/pochep-procmat/
+
+## Example
+
+```python
+from pochep_procmat import ProcessMemoryModel, make_process_profiles
+
+M, t_true, p = make_process_profiles(n_times=120, n_processes=4, seed=1, noise=0.01)
+model = ProcessMemoryModel("svd")
+result = model.fit(M, p)
+print(result.weights, result.relative_residual, result.rank)
+```
+
+## Methods
+
+| Method | Function | Needs | Output |
+|---|---|---|---|
+| `qr` | `solve_qr` | full column rank | least-squares weights |
+| `svd` | `solve_svd` | none, truncation by `rcond` | minimum-norm weights |
+| `cholesky` | `solve_normal_cholesky` | positive definite `M^T M`, or `ridge > 0` | weights |
+| `nnls` | `solve_nnls` | none | non-negative weights |
+| `nmf` | `nmf`, then NNLS | non-negative `M` and `p` | non-negative weights from `W H` |
+
+## Licence
+
+MIT. Authors: Andrey O. Ferubko, Oleg D. Kazakov. How to cite: see `CITATION.cff`.

pochep_procmat-0.0.1/README.md

@@ -0,0 +1,44 @@
+# pochep-procmat
+
+Matrix decompositions for the process memory model `M t = p`.
+
+Rows of `M` are timestamps and columns are processes. `p` is the total memory measured at each
+timestamp and `t` is the vector of per-process weights. The package solves this linear system
+with QR, SVD, Cholesky normal equations, non-negative least squares (NNLS), and fits NMF
+factors `M ~ W H`. It also provides a synthetic generator of process profiles for tests.
+
+Russian version: [README.ru.md](README.ru.md). Documentation: [docs/en](docs/en/theory.md), [docs/ru](docs/ru/theory.md).
+Demo notebook with strengths and weaknesses: https://github.com/89605502155/pochep-procmat-demo
+
+## Install
+
+```bash
+pip install pochep-procmat
+```
+
+Requires Python 3.11 to 3.14 and NumPy 2.0 or newer. Released on PyPI: https://pypi.org/project/pochep-procmat/
+
+## Example
+
+```python
+from pochep_procmat import ProcessMemoryModel, make_process_profiles
+
+M, t_true, p = make_process_profiles(n_times=120, n_processes=4, seed=1, noise=0.01)
+model = ProcessMemoryModel("svd")
+result = model.fit(M, p)
+print(result.weights, result.relative_residual, result.rank)
+```
+
+## Methods
+
+| Method | Function | Needs | Output |
+|---|---|---|---|
+| `qr` | `solve_qr` | full column rank | least-squares weights |
+| `svd` | `solve_svd` | none, truncation by `rcond` | minimum-norm weights |
+| `cholesky` | `solve_normal_cholesky` | positive definite `M^T M`, or `ridge > 0` | weights |
+| `nnls` | `solve_nnls` | none | non-negative weights |
+| `nmf` | `nmf`, then NNLS | non-negative `M` and `p` | non-negative weights from `W H` |
+
+## Licence
+
+MIT. Authors: Andrey O. Ferubko, Oleg D. Kazakov. How to cite: see `CITATION.cff`.

pochep_procmat-0.0.1/README.ru.md

@@ -0,0 +1,34 @@
+# pochep-procmat
+
+Матричные разложения для модели потребления памяти процессов `M t = p`.
+
+Строки `M` соответствуют моментам времени, столбцы процессам. `p` это суммарная измеренная память
+в каждый момент, `t` вектор весов процессов. Пакет решает эту линейную систему через QR, SVD,
+нормальные уравнения с разложением Холецкого и неотрицательный МНК (NNLS), а также строит
+неотрицательное разложение `M ~ W H` (NMF). Есть генератор синтетических профилей процессов для тестов.
+
+Английская версия: [README.md](README.md). Документация: [docs/ru](docs/ru/theory.md), [docs/en](docs/en/theory.md).
+Демонстрационный ноутбук с сильными и слабыми сторонами: https://github.com/89605502155/pochep-procmat-demo
+
+## Установка
+
+```bash
+pip install pochep-procmat
+```
+
+Требуется Python 3.11–3.14 и NumPy 2.0 или новее. Страница на PyPI: https://pypi.org/project/pochep-procmat/
+
+## Пример
+
+```python
+from pochep_procmat import ProcessMemoryModel, make_process_profiles
+
+M, t_true, p = make_process_profiles(n_times=120, n_processes=4, seed=1, noise=0.01)
+model = ProcessMemoryModel("svd")
+result = model.fit(M, p)
+print(result.weights, result.relative_residual, result.rank)
+```
+
+## Лицензия
+
+MIT. Авторы: Ферубко Андрей Олегович, Казаков Олег Дмитриевич. Как цитировать: см. `CITATION.cff`.

pochep_procmat-0.0.1/docs/en/api.md

@@ -0,0 +1,13 @@
+# pochep_procmat API (version 0.0.1)
+
+- `ProcessMemoryModel(method="svd", *, rcond=1e-10, ridge=0.0, nmf_rank=None, seed=0)`: the model `M t = p`.
+  `fit(M, p)` returns a `FitResult`, `predict(M)` returns `M @ t`, property `weights`.
+- `FitResult`: `method`, `weights`, `residual_norm`, `relative_residual`, `rank`, `seconds`.
+- `solve_qr(M, p)`, `solve_svd(M, p, rcond=1e-10)`, `solve_normal_cholesky(M, p, ridge=0.0)`,
+  `solve_nnls(M, p, *, max_iter=20000, tol=1e-12)`.
+- `qr_decompose(M)`, `svd_decompose(M)`, `nmf(M, rank, *, max_iter=500, tol=1e-6, seed=0)`.
+- `effective_rank(M, rtol=1e-10)`, `cosine_similarity(a, b)`.
+- `make_process_profiles(n_times, n_processes, *, seed=0, noise=0.02, mean_block_mb=150.0)`
+  returns `(M, t_true, p)` of synthetic data.
+- `as_matrix`, `as_vector`: input checks. A wrong type raises `TypeError`, a wrong shape, an empty array
+  or NaN raises `ValueError`.

pochep_procmat-0.0.1/docs/en/theory.md

@@ -0,0 +1,25 @@
+# Theory: the model M t = p and matrix decompositions
+
+`M` is a T × r matrix: a row is a timestamp, a column is a process, and an element is the memory
+consumed by that process at that timestamp. The vector `p` of length T holds the total measured memory.
+The vector `t` of length r holds unknown process weights. The model `M t = p` looks for `t` such that
+the weighted sum of the process profiles matches the measurement.
+
+If `T > r` and the columns of `M` are linearly independent, the least-squares solution is unique.
+Then QR gives `t = R^{-1} Q^T p` with `M = Q R`, where `Q` has orthonormal columns and `R` is upper
+triangular. If the columns are dependent, `R` is singular and QR cannot give a solution. The SVD
+`M = U diag(s) V^T` then gives the minimum-norm solution `V diag(1/s) U^T p`, where singular values
+below `rcond` are dropped.
+
+The normal equations `(M^T M + λ I) t = M^T p` are solved by Cholesky factorisation. A positive ridge `λ`
+makes the system solvable when `M` is rank deficient. The price is that the condition number is squared.
+
+If the process weights must be non-negative, the problem `min ||M t - p||` with `t >= 0` (NNLS) is solved
+by projected gradient descent with step `1/L`, where `L` is the largest eigenvalue of `M^T M`.
+
+Non-negative matrix factorisation (NMF) finds `M ~ W H` with `W >= 0` and `H >= 0`. Columns of `W` can be
+read as latent profiles and rows of `H` as their shares in each process. The factors come from Lee and Seung
+multiplicative updates. The factorisation is not unique, so the result depends on the start `seed`.
+
+The package does not guarantee that recovered weights match real processes. That is the hypothesis of the
+experiment, not a property of the decompositions. See `НОВИЗНА.md` and `АНАЛИЗ.md` of the article folder.

pochep_procmat-0.0.1/docs/ru/api.md

@@ -0,0 +1,13 @@
+# API pochep_procmat (версия 0.0.1)
+
+- `ProcessMemoryModel(method="svd", *, rcond=1e-10, ridge=0.0, nmf_rank=None, seed=0)`: модель `M t = p`.
+  Методы `fit(M, p)` возвращает `FitResult`, `predict(M)` возвращает `M @ t`, свойство `weights`.
+- `FitResult`: `method`, `weights`, `residual_norm`, `relative_residual`, `rank`, `seconds`.
+- `solve_qr(M, p)`, `solve_svd(M, p, rcond=1e-10)`, `solve_normal_cholesky(M, p, ridge=0.0)`,
+  `solve_nnls(M, p, *, max_iter=20000, tol=1e-12)`.
+- `qr_decompose(M)`, `svd_decompose(M)`, `nmf(M, rank, *, max_iter=500, tol=1e-6, seed=0)`.
+- `effective_rank(M, rtol=1e-10)`, `cosine_similarity(a, b)`.
+- `make_process_profiles(n_times, n_processes, *, seed=0, noise=0.02, mean_block_mb=150.0)`
+  возвращает `(M, t_true, p)` синтетических данных.
+- `as_matrix`, `as_vector`: проверка входа. Неверный тип вызывает `TypeError`, неверная форма,
+  пустой массив или NaN вызывают `ValueError`.

pochep_procmat-0.0.1/docs/ru/theory.md

@@ -0,0 +1,32 @@
+# Теория: модель M t = p и матричные разложения
+
+Пусть `M` матрица размера T × r: строка соответствует моменту времени, столбец процессу, элемент
+равен потреблению памяти процессом в этот момент. Вектор `p` длины T содержит суммарное потребление
+памяти. Вектор `t` длины r содержит неизвестные веса процессов. Модель `M t = p` ищет `t` так,
+чтобы взвешенная сумма профилей процессов совпала с измерением.
+
+Если `T > r` и столбцы `M` линейно независимы, решение по методу наименьших квадратов единственно.
+В этом случае решение через QR дает `t = R^{-1} Q^T p`, где `M = Q R`, `Q` имеет ортонормированные
+столбцы, `R` верхнетреугольная. Если столбцы зависимы, `R` вырождена, и решение через QR не существует.
+Тогда используется SVD: `M = U diag(s) V^T`, и минимальное по норме решение равно `V diag(1/s) U^T p`,
+где малые сингулярные значения отбрасываются по порогу `rcond`.
+
+Метод нормальных уравнений `(M^T M + λ I) t = M^T p` решается разложением Холецкого. Положительный
+параметр `λ` (ridge) делает систему разрешимой при вырожденной `M`. Цена метода в том, что число
+обусловленности возводится в квадрат.
+
+Если веса процессов должны быть неотрицательными, решается задача `min ||M t - p||` при `t >= 0`
+(NNLS). В пакете она решается проекционным градиентом с шагом `1/L`, где `L` наибольшее собственное
+значение `M^T M`.
+
+Неотрицательное матричное разложение (NMF) ищет `M ~ W H` с `W >= 0` и `H >= 0`. Столбцы `W`
+можно интерпретировать как латентные профили, а строки `H` как доли этих профилей в процессах.
+Разложение находится итерациями Ли и Сына (мультипликативные обновления). Оно не единственно,
+поэтому результат зависит от начального приближения `seed`.
+
+Квантор всеобщности (∀) здесь означает: для любого момента времени t_i выполняется уравнение
+Σ_j M_ij t_j = p_i с точностью до шума. Квантор существования (∃) означает: существует такой
+вектор весов t ≥ 0, что ||M t - p|| минимально (задача NNLS).
+
+Пакет не гарантирует, что найденные веса соответствуют реальным процессам. Это гипотеза эксперимента,
+а не свойство разложений. См. `НОВИЗНА.md` и `АНАЛИЗ.md` статьи.

pochep_procmat-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pochep-procmat"
+version = "0.0.1"
+description = "Matrix decompositions (QR, SVD, Cholesky, NNLS, NMF) for the process memory model M t = p"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Andrey O. Ferubko", email = "ferubko1999@yandex.ru" },
+  { name = "Oleg D. Kazakov", email = "kazakov@bgitu.ru" },
+]
+maintainers = [
+  { name = "Andrey O. Ferubko", email = "ferubko1999@yandex.ru" },
+]
+keywords = ["matrix decomposition", "SVD", "QR", "NMF", "memory", "process", "linear model"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/89605502155/pochep-procmat"
+Repository = "https://github.com/89605502155/pochep-procmat"
+Demo = "https://github.com/89605502155/pochep-procmat-demo"
+Changelog = "https://github.com/89605502155/pochep-procmat/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pochep_procmat"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pochep_procmat-0.0.1/src/pochep_procmat/__init__.py

@@ -0,0 +1,38 @@
+"""pochep_procmat: matrix decompositions for the process memory model M t = p."""
+
+from pochep_procmat.core import (
+    as_matrix,
+    as_vector,
+    cosine_similarity,
+    effective_rank,
+    nmf,
+    qr_decompose,
+    solve_nnls,
+    solve_normal_cholesky,
+    solve_qr,
+    solve_svd,
+    svd_decompose,
+)
+from pochep_procmat.model import METHODS, FitResult, ProcessMemoryModel
+from pochep_procmat.synthetic import make_process_profiles
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "METHODS",
+    "FitResult",
+    "ProcessMemoryModel",
+    "__version__",
+    "as_matrix",
+    "as_vector",
+    "cosine_similarity",
+    "effective_rank",
+    "make_process_profiles",
+    "nmf",
+    "qr_decompose",
+    "solve_nnls",
+    "solve_normal_cholesky",
+    "solve_qr",
+    "solve_svd",
+    "svd_decompose",
+]

pochep_procmat-0.0.1/src/pochep_procmat/core.py

@@ -0,0 +1,204 @@
+"""Matrix decompositions and solvers for the linear model M @ t = p.
+
+Every public function validates its inputs and raises ``TypeError`` or
+``ValueError`` on a wrong type, shape or non-finite value.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FloatArray = NDArray[np.float64]
+
+
+def as_matrix(M: ArrayLike, name: str = "M") -> FloatArray:
+    """Return ``M`` as a finite two-dimensional float64 array.
+
+    Raises ``TypeError`` if ``M`` cannot be converted to floats and ``ValueError``
+    if it is not two-dimensional, is empty or contains NaN or infinite values.
+    """
+    try:
+        arr = np.asarray(M, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{name} must be convertible to a float array") from exc
+    if arr.ndim != 2:
+        raise ValueError(f"{name} must be two-dimensional, got {arr.ndim} dimensions")
+    if arr.size == 0:
+        raise ValueError(f"{name} must not be empty")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite values")
+    return arr
+
+
+def as_vector(p: ArrayLike, name: str = "p", length: int | None = None) -> FloatArray:
+    """Return ``p`` as a finite one-dimensional float64 array of the given length."""
+    try:
+        arr = np.asarray(p, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{name} must be convertible to a float array") from exc
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional, got {arr.ndim} dimensions")
+    if length is not None and arr.shape[0] != length:
+        raise ValueError(f"{name} must have length {length}, got {arr.shape[0]}")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite values")
+    return arr
+
+
+def _check_pair(M: ArrayLike, p: ArrayLike) -> tuple[FloatArray, FloatArray]:
+    m = as_matrix(M)
+    vec = as_vector(p, length=m.shape[0])
+    return m, vec
+
+
+def qr_decompose(M: ArrayLike) -> tuple[FloatArray, FloatArray]:
+    """Reduced QR decomposition ``M = Q R`` with ``Q`` of shape (T, r) and ``R`` of shape (r, r)."""
+    m = as_matrix(M)
+    q, r = np.linalg.qr(m, mode="reduced")
+    return q, r
+
+
+def svd_decompose(M: ArrayLike) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """Thin singular value decomposition ``M = U diag(s) V^T``.
+
+    Returns ``(U, s, Vt)`` with ``s`` sorted in decreasing order.
+    """
+    m = as_matrix(M)
+    u, s, vt = np.linalg.svd(m, full_matrices=False)
+    return u, s, vt
+
+
+def effective_rank(M: ArrayLike, rtol: float = 1e-10) -> int:
+    """Number of singular values larger than ``rtol`` times the largest one."""
+    m = as_matrix(M)
+    s = np.linalg.svd(m, compute_uv=False)
+    if s[0] == 0.0:
+        return 0
+    return int(np.sum(s > rtol * s[0]))
+
+
+def solve_qr(M: ArrayLike, p: ArrayLike) -> FloatArray:
+    """Least-squares solution of ``M t = p`` through the QR decomposition.
+
+    Requires ``M`` to have full column rank. Raises ``ValueError`` otherwise.
+    """
+    m, vec = _check_pair(M, p)
+    if effective_rank(m) < m.shape[1]:
+        raise ValueError("QR solver needs a full column rank matrix, use the svd method instead")
+    q, r = np.linalg.qr(m, mode="reduced")
+    return np.linalg.solve(r, q.T @ vec)
+
+
+def solve_svd(M: ArrayLike, p: ArrayLike, rcond: float = 1e-10) -> FloatArray:
+    """Minimum-norm least-squares solution through the truncated pseudo-inverse.
+
+    Singular values below ``rcond`` times the largest one are treated as zero.
+    """
+    m, vec = _check_pair(M, p)
+    if rcond < 0:
+        raise ValueError("rcond must be non-negative")
+    u, s, vt = np.linalg.svd(m, full_matrices=False)
+    keep = s > rcond * s[0] if s[0] > 0 else np.zeros_like(s, dtype=bool)
+    coef = np.zeros(s.shape[0])
+    coef[keep] = (u[:, keep].T @ vec) / s[keep]
+    return vt.T @ coef
+
+
+def solve_normal_cholesky(M: ArrayLike, p: ArrayLike, ridge: float = 0.0) -> FloatArray:
+    """Solve ``(M^T M + ridge I) t = M^T p`` with a Cholesky factorisation.
+
+    A positive ``ridge`` adds Tikhonov regularisation and makes the system solvable
+    for rank-deficient ``M``. With ``ridge = 0`` the matrix must be positive definite,
+    otherwise ``ValueError`` is raised.
+    """
+    m, vec = _check_pair(M, p)
+    if ridge < 0:
+        raise ValueError("ridge must be non-negative")
+    gram = m.T @ m + ridge * np.eye(m.shape[1])
+    try:
+        chol = np.linalg.cholesky(gram)
+    except np.linalg.LinAlgError as exc:
+        raise ValueError("normal matrix is not positive definite, use ridge > 0") from exc
+    y = np.linalg.solve(chol, m.T @ vec)
+    return np.linalg.solve(chol.T, y)
+
+
+def solve_nnls(
+    M: ArrayLike,
+    p: ArrayLike,
+    *,
+    max_iter: int = 20000,
+    tol: float = 1e-12,
+) -> FloatArray:
+    """Non-negative least squares ``min ||M t - p||`` subject to ``t >= 0``.
+
+    Solved by projected gradient descent with the step ``1 / L``, where ``L`` is the
+    largest eigenvalue of ``M^T M``. Stops when the relative change of ``t`` is below ``tol``.
+    """
+    m, vec = _check_pair(M, p)
+    if max_iter < 1:
+        raise ValueError("max_iter must be at least 1")
+    gram = m.T @ m
+    lipschitz = float(np.linalg.eigvalsh(gram)[-1])
+    rhs = m.T @ vec
+    t = np.zeros(m.shape[1])
+    if lipschitz == 0.0:
+        return t
+    for _ in range(max_iter):
+        grad = gram @ t - rhs
+        t_new = np.maximum(0.0, t - grad / lipschitz)
+        change = np.linalg.norm(t_new - t)
+        t = t_new
+        if change <= tol * max(1.0, np.linalg.norm(t)):
+            break
+    return t
+
+
+def nmf(
+    M: ArrayLike,
+    rank: int,
+    *,
+    max_iter: int = 500,
+    tol: float = 1e-6,
+    seed: int = 0,
+    eps: float = 1e-12,
+) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """Non-negative matrix factorisation ``M ~ W H`` by Lee and Seung multiplicative updates.
+
+    ``M`` must be non-negative. Returns ``(W, H, errors)`` where ``W`` has shape (T, rank),
+    ``H`` has shape (rank, r) and ``errors`` is the Frobenius error after each iteration.
+    The random initialisation is controlled by ``seed``.
+    """
+    m = as_matrix(M)
+    if np.any(m < 0):
+        raise ValueError("NMF needs a non-negative matrix")
+    if not isinstance(rank, (int, np.integer)) or rank < 1:
+        raise ValueError("rank must be a positive integer")
+    if rank > min(m.shape):
+        raise ValueError("rank must not exceed min(M.shape)")
+    rng = np.random.default_rng(seed)
+    scale = np.sqrt(m.mean() / rank) if m.mean() > 0 else 1.0
+    w = np.abs(rng.standard_normal((m.shape[0], rank))) * scale + eps
+    h = np.abs(rng.standard_normal((rank, m.shape[1]))) * scale + eps
+    errors: list[float] = []
+    previous = np.inf
+    for _ in range(max_iter):
+        h *= (w.T @ m) / (w.T @ w @ h + eps)
+        w *= (m @ h.T) / (w @ h @ h.T + eps)
+        err = float(np.linalg.norm(m - w @ h))
+        errors.append(err)
+        if abs(previous - err) <= tol * max(1.0, err):
+            break
+        previous = err
+    return w, h, np.asarray(errors)
+
+
+def cosine_similarity(a: ArrayLike, b: ArrayLike) -> float:
+    """Cosine of the angle between two vectors of the same length, in [-1, 1]."""
+    va = as_vector(a, name="a")
+    vb = as_vector(b, name="b", length=va.shape[0])
+    na, nb = np.linalg.norm(va), np.linalg.norm(vb)
+    if na == 0.0 or nb == 0.0:
+        raise ValueError("cosine similarity is undefined for a zero vector")
+    return float(va @ vb / (na * nb))

pochep_procmat-0.0.1/src/pochep_procmat/model.py

@@ -0,0 +1,134 @@
+"""Model M t = p: per-process weights recovered from a matrix of process memory profiles.
+
+Rows of ``M`` are timestamps, columns are processes. ``p`` is the measured total
+memory at each timestamp and ``t`` is the vector of per-process weights.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from pochep_procmat.core import (
+    FloatArray,
+    _check_pair,
+    as_matrix,
+    effective_rank,
+    nmf,
+    solve_nnls,
+    solve_normal_cholesky,
+    solve_qr,
+    solve_svd,
+)
+
+METHODS = ("qr", "svd", "cholesky", "nnls", "nmf")
+
+
+@dataclass(frozen=True)
+class FitResult:
+    """Outcome of one fit: weights, residual and cost of the chosen method."""
+
+    method: str
+    weights: FloatArray
+    residual_norm: float
+    relative_residual: float
+    rank: int
+    seconds: float
+
+
+class ProcessMemoryModel:
+    """Linear model ``M t = p`` solved by one of several decompositions.
+
+    Parameters
+    ----------
+    method:
+        One of ``"qr"``, ``"svd"``, ``"cholesky"``, ``"nnls"`` or ``"nmf"``.
+    rcond:
+        Relative cut-off for singular values in the ``"svd"`` method.
+    ridge:
+        Tikhonov term used by the ``"cholesky"`` method.
+    nmf_rank:
+        Number of latent components for the ``"nmf"`` method. The weights are then
+        obtained from the non-negative coefficients of the rank-``nmf_rank`` model.
+    seed:
+        Seed for the random initialisation of NMF.
+    """
+
+    def __init__(
+        self,
+        method: str = "svd",
+        *,
+        rcond: float = 1e-10,
+        ridge: float = 0.0,
+        nmf_rank: int | None = None,
+        seed: int = 0,
+    ) -> None:
+        if method not in METHODS:
+            raise ValueError(f"method must be one of {METHODS}, got {method!r}")
+        if rcond < 0:
+            raise ValueError("rcond must be non-negative")
+        if ridge < 0:
+            raise ValueError("ridge must be non-negative")
+        self.method = method
+        self.rcond = rcond
+        self.ridge = ridge
+        self.nmf_rank = nmf_rank
+        self.seed = seed
+        self._weights: FloatArray | None = None
+
+    @property
+    def weights(self) -> FloatArray:
+        """Weights found by the last ``fit``. Raises ``RuntimeError`` before a fit."""
+        if self._weights is None:
+            raise RuntimeError("the model is not fitted yet")
+        return self._weights
+
+    def fit(self, M: ArrayLike, p: ArrayLike) -> FitResult:
+        """Estimate ``t`` from ``M`` and ``p`` and return a :class:`FitResult`."""
+        m, vec = _check_pair(M, p)
+        start = time.perf_counter()
+        if self.method == "qr":
+            t = solve_qr(m, vec)
+        elif self.method == "svd":
+            t = solve_svd(m, vec, rcond=self.rcond)
+        elif self.method == "cholesky":
+            t = solve_normal_cholesky(m, vec, ridge=self.ridge)
+        elif self.method == "nnls":
+            t = solve_nnls(m, vec)
+        else:
+            t = self._fit_nmf(m, vec)
+        seconds = time.perf_counter() - start
+        self._weights = t
+        residual = float(np.linalg.norm(m @ t - vec))
+        norm_p = float(np.linalg.norm(vec))
+        relative = residual / norm_p if norm_p > 0 else residual
+        return FitResult(
+            method=self.method,
+            weights=t,
+            residual_norm=residual,
+            relative_residual=relative,
+            rank=effective_rank(m),
+            seconds=seconds,
+        )
+
+    def _fit_nmf(self, m: FloatArray, vec: FloatArray) -> FloatArray:
+        if np.any(m < 0):
+            raise ValueError("the nmf method needs a non-negative matrix")
+        if np.any(vec < 0):
+            raise ValueError("the nmf method needs a non-negative vector p")
+        rank = self.nmf_rank if self.nmf_rank is not None else min(m.shape)
+        w, h, _ = nmf(m, rank, seed=self.seed)
+        # The weights are fitted against the rank-limited approximation W H, and the
+        # non-negativity of t keeps them interpretable as process shares.
+        return solve_nnls(w @ h, vec)
+
+    def predict(self, M: ArrayLike) -> FloatArray:
+        """Return ``M @ t`` for the weights found by the last fit."""
+        t = self.weights
+        m = as_matrix(M)
+        if m.shape[1] != t.shape[0]:
+            raise ValueError(f"M must have {t.shape[0]} columns, got {m.shape[1]}")
+        return m @ t

pochep_procmat-0.0.1/src/pochep_procmat/synthetic.py

@@ -0,0 +1,49 @@
+"""Synthetic process memory profiles for tests and the demo notebook.
+
+The generator produces ``r`` non-negative profiles over ``T`` timestamps. Each profile
+is a block of memory that an application holds while it is running and releases after
+it stops, plus a small background noise. Nothing here models a real operating system;
+the output is synthetic by construction.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def make_process_profiles(
+    n_times: int,
+    n_processes: int,
+    *,
+    seed: int = 0,
+    noise: float = 0.02,
+    mean_block_mb: float = 150.0,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Return ``(M, t_true, p)`` with ``p = M @ t_true + noise``.
+
+    ``M`` has shape (n_times, n_processes): column ``j`` is the memory profile of process ``j``
+    in megabytes. ``t_true`` holds the true per-process weights, close to 1, and ``p`` is the
+    observed total memory with additive Gaussian noise of relative size ``noise``.
+    """
+    if n_times < 2 or n_processes < 1:
+        raise ValueError("need at least 2 timestamps and 1 process")
+    if noise < 0:
+        raise ValueError("noise must be non-negative")
+    if mean_block_mb <= 0:
+        raise ValueError("mean_block_mb must be positive")
+    rng = np.random.default_rng(seed)
+    profiles = np.zeros((n_times, n_processes))
+    for j in range(n_processes):
+        n_blocks = rng.integers(1, 4)
+        for _ in range(n_blocks):
+            start = rng.integers(0, n_times - 1)
+            length = rng.integers(1, max(2, n_times // 3))
+            stop = min(n_times, start + length)
+            height = rng.uniform(0.2, 1.8) * mean_block_mb
+            profiles[start:stop, j] += height
+    t_true = rng.uniform(0.9, 1.1, size=n_processes)
+    clean = profiles @ t_true
+    scale = np.linalg.norm(clean) / np.sqrt(n_times) if n_times else 1.0
+    p = clean + noise * scale * rng.standard_normal(n_times)
+    return profiles, t_true, p

pochep_procmat-0.0.1/tests/test_core.py

@@ -0,0 +1,121 @@
+import numpy as np
+import pytest
+
+from pochep_procmat import (
+    as_matrix,
+    as_vector,
+    cosine_similarity,
+    effective_rank,
+    nmf,
+    qr_decompose,
+    solve_nnls,
+    solve_normal_cholesky,
+    solve_qr,
+    solve_svd,
+    svd_decompose,
+)
+
+
+@pytest.fixture
+def full_rank():
+    rng = np.random.default_rng(1)
+    m = rng.uniform(0.0, 1.0, size=(40, 5))
+    t = rng.uniform(0.5, 1.5, size=5)
+    return m, t, m @ t
+
+
+def test_qr_reconstructs_matrix(full_rank):
+    m, _, _ = full_rank
+    q, r = qr_decompose(m)
+    assert q.shape == (40, 5) and r.shape == (5, 5)
+    assert np.allclose(q @ r, m)
+    assert np.allclose(q.T @ q, np.eye(5))
+
+
+def test_svd_reconstructs_and_sorts(full_rank):
+    m, _, _ = full_rank
+    u, s, vt = svd_decompose(m)
+    assert np.allclose(u @ np.diag(s) @ vt, m)
+    assert np.all(np.diff(s) <= 0)
+
+
+def test_solvers_recover_exact_weights(full_rank):
+    m, t, p = full_rank
+    for solved in (solve_qr(m, p), solve_svd(m, p), solve_normal_cholesky(m, p), solve_nnls(m, p)):
+        assert np.allclose(solved, t, atol=1e-6)
+
+
+def test_svd_matches_lstsq_on_rank_deficient():
+    m = np.array([[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [0.0, 1.0, 1.0], [1.0, 0.0, 1.0]])
+    p = np.array([1.0, 2.0, 0.5, 1.5])
+    expected = np.linalg.lstsq(m, p, rcond=None)[0]
+    assert np.allclose(solve_svd(m, p), expected, atol=1e-8)
+    assert effective_rank(m) == 2
+
+
+def test_qr_rejects_rank_deficient():
+    m = np.array([[1.0, 2.0], [2.0, 4.0], [3.0, 6.0]])
+    with pytest.raises(ValueError, match="full column rank"):
+        solve_qr(m, np.ones(3))
+
+
+def test_cholesky_needs_ridge_when_singular():
+    m = np.array([[1.0, 1.0], [1.0, 1.0], [1.0, 1.0]])
+    with pytest.raises(ValueError, match="positive definite"):
+        solve_normal_cholesky(m, np.ones(3))
+    t = solve_normal_cholesky(m, np.ones(3), ridge=1e-6)
+    assert np.allclose(m @ t, np.ones(3), atol=1e-3)
+
+
+def test_nnls_respects_non_negativity():
+    m = np.array([[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+    p = np.array([2.0, -1.0, 0.5])
+    t = solve_nnls(m, p)
+    assert np.all(t >= 0)
+    assert t[1] == pytest.approx(0.0, abs=1e-8)
+
+
+def test_nmf_is_non_negative_and_error_drops():
+    rng = np.random.default_rng(2)
+    m = rng.uniform(0.0, 1.0, size=(30, 6))
+    w, h, errors = nmf(m, 3, max_iter=300, seed=4)
+    assert np.all(w >= 0) and np.all(h >= 0)
+    assert w.shape == (30, 3) and h.shape == (3, 6)
+    assert errors[-1] <= errors[0]
+
+
+def test_nmf_exact_for_low_rank_input():
+    rng = np.random.default_rng(3)
+    base = rng.uniform(0.1, 1.0, size=(20, 2)) @ rng.uniform(0.1, 1.0, size=(2, 5))
+    w, h, errors = nmf(base, 2, max_iter=3000, tol=1e-10, seed=0)
+    assert np.linalg.norm(base - w @ h) / np.linalg.norm(base) < 1e-2
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [np.zeros((0, 3)), np.ones(5), [[1.0, np.nan]], [["a", "b"]]],
+)
+def test_as_matrix_rejects_bad_input(bad):
+    with pytest.raises((TypeError, ValueError)):
+        as_matrix(bad)
+
+
+def test_as_vector_checks_length():
+    with pytest.raises(ValueError, match="length 3"):
+        as_vector([1.0, 2.0], length=3)
+
+
+def test_nmf_rejects_negative_and_bad_rank():
+    with pytest.raises(ValueError):
+        nmf(np.array([[1.0, -1.0]]), 1)
+    with pytest.raises(ValueError):
+        nmf(np.ones((3, 3)), 4)
+    with pytest.raises(ValueError):
+        nmf(np.ones((3, 3)), 0)
+
+
+def test_cosine_similarity_bounds():
+    assert cosine_similarity([1.0, 0.0], [2.0, 0.0]) == pytest.approx(1.0)
+    assert cosine_similarity([1.0, 0.0], [0.0, 3.0]) == pytest.approx(0.0)
+    with pytest.raises(ValueError):
+        cosine_similarity([0.0, 0.0], [1.0, 1.0])

pochep_procmat-0.0.1/tests/test_model.py

@@ -0,0 +1,60 @@
+import numpy as np
+import pytest
+
+from pochep_procmat import METHODS, ProcessMemoryModel, make_process_profiles
+
+
+def test_all_methods_fit_synthetic_data():
+    m, t_true, p = make_process_profiles(120, 4, seed=5, noise=0.0)
+    for method in METHODS:
+        model = ProcessMemoryModel(method, nmf_rank=4)
+        res = model.fit(m, p)
+        assert res.method == method
+        assert res.weights.shape == (4,)
+        assert res.relative_residual < 0.2
+
+
+def test_svd_and_qr_agree_on_full_rank():
+    m, _, p = make_process_profiles(80, 3, seed=7, noise=0.01)
+    a = ProcessMemoryModel("svd").fit(m, p).weights
+    b = ProcessMemoryModel("qr").fit(m, p).weights
+    assert np.allclose(a, b, atol=1e-8)
+
+
+def test_predict_uses_fitted_weights():
+    m, _, p = make_process_profiles(60, 3, seed=9, noise=0.0)
+    model = ProcessMemoryModel("svd")
+    model.fit(m, p)
+    assert np.allclose(model.predict(m), m @ model.weights)
+
+
+def test_predict_before_fit_raises():
+    with pytest.raises(RuntimeError):
+        ProcessMemoryModel().predict(np.ones((3, 2)))
+
+
+def test_bad_method_and_parameters():
+    with pytest.raises(ValueError):
+        ProcessMemoryModel("lu")
+    with pytest.raises(ValueError):
+        ProcessMemoryModel("svd", rcond=-1.0)
+    with pytest.raises(ValueError):
+        ProcessMemoryModel("cholesky", ridge=-1.0)
+
+
+def test_fit_rejects_length_mismatch():
+    with pytest.raises(ValueError):
+        ProcessMemoryModel("svd").fit(np.ones((5, 2)), np.ones(4))
+
+
+def test_synthetic_generator_validates_input():
+    with pytest.raises(ValueError):
+        make_process_profiles(1, 3)
+    with pytest.raises(ValueError):
+        make_process_profiles(10, 3, noise=-0.1)
+
+
+def test_synthetic_generator_is_reproducible():
+    a = make_process_profiles(50, 3, seed=11)
+    b = make_process_profiles(50, 3, seed=11)
+    assert all(np.array_equal(x, y) for x, y in zip(a, b, strict=True))