cvx-linalg 0.2.0__tar.gz

cvx_linalg-0.2.0/.github/actions/configure-git-auth/README.md

@@ -0,0 +1,80 @@
+# Configure Git Auth for Private Packages
+
+This composite action configures git to use token authentication for private GitHub packages.
+
+## Usage
+
+Add this step before installing dependencies that include private GitHub packages:
+
+```yaml
+- name: Configure git auth for private packages
+  uses: ./.github/actions/configure-git-auth
+  with:
+    token: ${{ secrets.GH_PAT }}
+```
+
+The `GH_PAT` secret should be a Personal Access Token with `repo` scope.
+
+## What It Does
+
+This action runs:
+
+```bash
+git config --global url."https://<token>@github.com/".insteadOf "https://github.com/"
+```
+
+This tells git to automatically inject the token into all HTTPS GitHub URLs, enabling access to private repositories.
+
+## When to Use
+
+Use this action when your project has dependencies defined in `pyproject.toml` like:
+
+```toml
+[tool.uv.sources]
+private-package = { git = "https://github.com/your-org/private-package.git", rev = "v1.0.0" }
+```
+
+## Token Requirements
+
+By default, this action will use the workflow’s built-in `GITHUB_TOKEN` (`github.token`) if no `token` input is provided or if the provided value is empty (it uses `inputs.token || github.token` internally).
+
+The `GITHUB_TOKEN` is usually sufficient when:
+
+- installing dependencies hosted in the **same repository** as the workflow, or
+- accessing **public** repositories.
+
+The default `GITHUB_TOKEN` typically does **not** have permission to read other private repositories, even within the same organization. For that scenario, you should create a Personal Access Token (PAT) with `repo` scope and store it as `secrets.GH_PAT`, then pass it to the action via the `token` input.
+
+If you configure the step as in the example (`token: ${{ secrets.GH_PAT }}`) and `secrets.GH_PAT` is not defined, GitHub Actions passes an empty string to the action. The composite action then falls back to `github.token`, so the configuration step itself still succeeds. However, any subsequent step that tries to access private repositories that are not covered by the permissions of `GITHUB_TOKEN` will fail with an authentication error.
+## Example Workflow
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Configure git auth for private packages
+        uses: ./.github/actions/configure-git-auth
+        with:
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest
+```
+
+## See Also
+
+- [PRIVATE_PACKAGES.md](../../../.rhiza/docs/PRIVATE_PACKAGES.md) - Complete guide to using private packages
+- [TOKEN_SETUP.md](../../../.rhiza/docs/TOKEN_SETUP.md) - Setting up Personal Access Tokens

cvx_linalg-0.2.0/.gitignore

@@ -0,0 +1,122 @@
+### Python template
+.idea
+.venv
+.ruff_cache
+.ty_cache
+
+# HTML outputs from docstring examples (e.g. report.save("output/..."))
+output/
+
+### Don't expose API keys, etc.
+.env
+
+__marimo__
+
+_tests
+_book
+_pdoc
+docs/notebooks/*.html
+docs/reports
+docs/reports.md
+_marimushka
+_mkdocs
+_benchmarks
+_jupyter
+_site
+
+# LaTeX build artifacts
+docs/paper/*.aux
+docs/paper/*.fdb_latexmk
+docs/paper/*.fls
+docs/paper/*.log
+docs/paper/*.out
+docs/paper/*.toc
+
+# temp file used by Junie
+.output.txt
+
+# folder used for programs, e.g. uv, uvx, task, etc.
+bin
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Generated presentation files
+presentation.html
+presentation.pdf
+*.pptx
+
+# C extensions
+*.so
+
+# .DS_Store
+.DS_Store
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+coverage.json
+*.cover
+*.py,cover
+.hypothesis/
+.benchmarks/
+.pytest_cache/
+cover/
+
+# Security scanning baselines (regenerate as needed)
+.bandit-baseline.json
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Cython debug symbols
+cython_debug/
+
+# Makefile
+local.mk
+
+.bandit-baseline.json
+

cvx_linalg-0.2.0/.rhiza/requirements/README.md

@@ -0,0 +1,27 @@
+# Requirements Folder
+
+This folder contains the development dependencies for the Rhiza project, organized by purpose.
+
+## Files
+
+- **tests.txt** - Testing dependencies (pytest, pytest-cov, pytest-html, pytest-mock, PyYAML, defusedxml, hypothesis, pytest-benchmark, pygal)
+- **marimo.txt** - Marimo notebook dependencies
+- **docs.txt** - Documentation generation dependencies (interrogate, mkdocs, mkdocs-material, mkdocstrings)
+- **tools.txt** - Development tools (pre-commit, python-dotenv, typer, ty)
+
+## Usage
+
+These requirements files are automatically installed by the `make install` command.
+
+To install specific requirement files manually:
+
+```bash
+uv pip install -r .rhiza/requirements/tests.txt
+uv pip install -r .rhiza/requirements/marimo.txt
+uv pip install -r .rhiza/requirements/docs.txt
+uv pip install -r .rhiza/requirements/tools.txt
+```
+
+## CI/CD
+
+GitHub Actions workflows automatically install these requirements as needed.

cvx_linalg-0.2.0/.rhiza/tests/README.md

@@ -0,0 +1,169 @@
+# Rhiza Test Suite
+
+This directory contains the comprehensive test suite for the Rhiza project.
+
+## Test Organization
+
+Tests are organized into purpose-driven subdirectories:
+
+### `structure/`
+Static assertions about file and directory presence. These tests verify that the repository contains the expected files, directories, and configuration structure without executing any subprocesses.
+
+- `test_project_layout.py` — Validates root-level files and directories
+- `test_requirements.py` — Validates `.rhiza/requirements/` structure
+
+### `api/`
+Makefile target validation via dry-runs. These tests verify that Makefile targets are properly defined and would execute the expected commands.
+
+- `test_makefile_targets.py` — Core Makefile targets (install, test, fmt, etc.)
+- `test_makefile_api.py` — Makefile API (delegation, extension, hooks, overrides)
+- `test_github_targets.py` — GitHub-specific Makefile targets
+
+### `integration/`
+Tests requiring sandboxed git repositories or subprocess execution. These tests verify end-to-end workflows.
+
+- `test_release.py` — Release script functionality
+- `test_book_targets.py` — Documentation book build targets
+
+### `sync/`
+Template sync, workflows, versioning, and content validation tests. These tests ensure that template synchronization and content validation work correctly.
+
+- `test_rhiza_version.py` — Version reading and workflow validation
+- `test_readme_validation.py` — README code block execution and validation
+- `test_docstrings.py` — Doctest validation across source modules
+
+#### Skipping README code blocks with `+RHIZA_SKIP`
+
+By default, every `python` and `bash` code block in `README.md` is executed or
+syntax-checked by `test_readme_validation.py`. To mark a block as intentionally
+non-runnable (e.g. illustrative snippets or environment-specific commands), add
+`+RHIZA_SKIP` to the opening fence line:
+
+~~~markdown
+```python +RHIZA_SKIP
+# This block will NOT be executed or syntax-checked
+from my_env import some_function
+some_function()
+```
+
+```bash +RHIZA_SKIP
+# This bash block will NOT be syntax-checked
+run-something --only-on-ci
+```
+~~~
+
+Markdown renderers (including GitHub) ignore everything after the first word on
+a fence line, so the block still renders as a normal highlighted code block.
+Blocks without `+RHIZA_SKIP` continue to be validated as before.
+
+### `utils/`
+Tests for utility code and test infrastructure. These tests validate the testing framework itself and utility scripts.
+
+- `test_git_repo_fixture.py` — Validates the `git_repo` fixture
+
+### `deps/`
+Dependency validation tests. These tests ensure that project dependencies are correctly specified and healthy.
+
+- `test_dependency_health.py` — Validates pyproject.toml and requirements files
+
+### `stress/`
+Stress tests that verify Rhiza's stability under heavy load. These tests execute Rhiza-specific operations under concurrent load and repeated execution to detect race conditions, resource leaks, and performance degradation.
+
+- `test_makefile_stress.py` — Makefile operations under concurrent/repeated load
+- `test_git_stress.py` — Git operations under concurrent load
+
+See [stress/README.md](stress/README.md) for detailed documentation.
+
+## Running Tests
+
+### Run all tests
+```bash
+uv run pytest .rhiza/tests/
+# or
+make test
+```
+
+### Run tests from a specific category
+```bash
+uv run pytest .rhiza/tests/structure/
+uv run pytest .rhiza/tests/api/
+uv run pytest .rhiza/tests/integration/
+uv run pytest .rhiza/tests/sync/
+uv run pytest .rhiza/tests/utils/
+uv run pytest .rhiza/tests/deps/
+uv run pytest .rhiza/tests/stress/
+```
+
+### Run stress tests with custom parameters
+```bash
+# Run all stress tests (default: 100 iterations, 10 workers)
+uv run pytest .rhiza/tests/stress/ -v
+
+# Run with fewer iterations (faster)
+uv run pytest .rhiza/tests/stress/ -v --iterations=10
+
+# Skip stress tests when running full test suite
+uv run pytest .rhiza/tests/ -v -m "not stress"
+```
+
+### Run a specific test file
+```bash
+uv run pytest .rhiza/tests/structure/test_project_layout.py
+```
+
+### Run with verbose output
+```bash
+uv run pytest .rhiza/tests/ -v
+```
+
+### Run with coverage
+```bash
+uv run pytest .rhiza/tests/ --cov
+```
+
+## Fixtures
+
+### Root-level fixtures (`conftest.py`)
+- `root` — Repository root path (session-scoped)
+- `logger` — Configured logger instance (session-scoped)
+- `git_repo` — Sandboxed git repository (function-scoped)
+
+### Category-specific fixtures
+- `api/conftest.py` — `setup_tmp_makefile`, `run_make`, `setup_rhiza_git_repo`
+- `sync/conftest.py` — `setup_sync_env`
+
+## Writing Tests
+
+### Conventions
+- Use descriptive test names that explain what is being tested
+- Group related tests in classes when appropriate
+- Use appropriate fixtures for setup/teardown
+- Add docstrings to test modules and complex test functions
+- Use `pytest.mark.skip` for tests that depend on optional features
+
+### Import Patterns
+```python
+# Import shared helpers from test_utils
+from test_utils import strip_ansi, run_make, setup_rhiza_git_repo
+
+# Import from local category conftest (for fixtures and category-specific helpers)
+from api.conftest import SPLIT_MAKEFILES, setup_tmp_makefile
+
+# Note: Fixtures defined in conftest.py are automatically available in tests
+# and don't need to be explicitly imported
+```
+
+## Test Coverage
+
+The test suite aims for high coverage across:
+- Configuration validation (structure, dependencies)
+- Makefile target correctness (api)
+- End-to-end workflows (integration)
+- Template synchronization (sync)
+- Utility code (utils)
+
+## Notes
+
+- Benchmarks are located in `tests/benchmarks/` and run via `make benchmark`
+- Integration tests use sandboxed git repositories to avoid affecting the working tree
+- All Makefile tests use dry-run mode (`make -n`) to avoid side effects

cvx_linalg-0.2.0/.rhiza/tests/stress/README.md

@@ -0,0 +1,143 @@
+# Stress Tests for Rhiza Framework
+
+This directory contains stress tests that verify the stability and performance of the Rhiza framework under heavy load conditions.
+
+## Overview
+
+Stress tests differ from regular integration tests and benchmarks:
+- **Integration tests** verify that workflows execute correctly
+- **Benchmarks** measure performance of individual operations
+- **Stress tests** verify system stability under concurrent load and repeated operations
+
+These tests focus specifically on Rhiza's core operations: Makefile execution and Git operations used by release and sync workflows.
+
+## Test Categories
+
+### 1. Makefile Stress Tests (`test_makefile_stress.py`)
+
+Tests Rhiza's Makefile operations under stress:
+- Concurrent invocations of targets (help, dry-run)
+- Repeated executions to detect resource leaks
+- Parallel variable printing and Makefile parsing
+
+### 2. Git Operations Stress Tests (`test_git_stress.py`)
+
+Tests Git operations used by Rhiza (release scripts, sync) under concurrent load:
+- Concurrent git status/log/diff/show commands
+- Repeated git operations (status, log, branch, rev-parse)
+- Rapid git rev-parse (used in release script)
+
+## Running Stress Tests
+
+### Run all stress tests
+```bash
+uv run pytest .rhiza/tests/stress/ -v
+```
+
+### Run specific stress test category
+```bash
+uv run pytest .rhiza/tests/stress/test_makefile_stress.py -v
+uv run pytest .rhiza/tests/stress/test_git_stress.py -v
+```
+
+### Run with custom iteration count
+```bash
+# Reduce iterations for faster testing
+uv run pytest .rhiza/tests/stress/ -v --iterations=10
+
+# Increase iterations for more thorough testing
+uv run pytest .rhiza/tests/stress/ -v --iterations=500
+```
+
+### Run with custom worker count
+```bash
+# Test with more concurrent workers
+uv run pytest .rhiza/tests/stress/ -v --workers=20
+```
+
+### Skip stress tests (when running full test suite)
+```bash
+uv run pytest .rhiza/tests/ -v -m "not stress"
+```
+
+## Test Markers
+
+All tests in this directory are marked with `@pytest.mark.stress` to allow selective execution:
+
+```python
+@pytest.mark.stress
+def test_concurrent_operations():
+    # Test concurrent operations
+    pass
+```
+
+## Expected Behavior
+
+Stress tests should:
+1. **Pass consistently** - No flakiness or race conditions
+2. **Complete in reasonable time** - Generally < 60 seconds per test
+3. **Clean up resources** - No leaked file handles, processes, or temporary files
+4. **Report clear failures** - When failures occur, provide actionable error messages
+
+## Acceptance Criteria
+
+For Rhiza framework stress tests, we aim for:
+- **100% success rate** - All operations should complete successfully
+- **No resource leaks** - Memory and file handles should be cleaned up
+- **Deterministic behavior** - Tests should produce consistent results
+- **Reasonable performance** - Operations should complete within expected time bounds
+
+## Troubleshooting
+
+### Tests timeout
+- Reduce iteration count: `pytest --iterations=10`
+- Reduce worker count: `pytest --workers=5`
+- Check system resources (CPU, memory, disk)
+
+### Intermittent failures
+- Run with verbose output: `pytest -vv`
+- Check for resource contention with other processes
+- Verify git configuration (may affect git operations)
+
+### Out of memory errors
+- Reduce concurrent workers
+- Check for memory leaks in test code
+- Ensure proper cleanup in fixtures
+
+## Contributing
+
+When adding new stress tests:
+1. Use the `@pytest.mark.stress` decorator
+2. Use provided fixtures (`stress_iterations`, `concurrent_workers`)
+3. Ensure proper cleanup (use context managers or fixtures)
+4. Document expected behavior and acceptance criteria
+5. Keep tests focused on one stress scenario
+6. Provide clear assertion messages
+
+Example:
+```python
+import pytest
+import concurrent.futures
+
+@pytest.mark.stress
+def test_concurrent_operation(stress_iterations, concurrent_workers):
+    """Test concurrent execution of operation X."""
+    
+    def perform_operation():
+        # Operation to stress test
+        return True
+    
+    with concurrent.futures.ThreadPoolExecutor(max_workers=concurrent_workers) as executor:
+        futures = [executor.submit(perform_operation) for _ in range(stress_iterations)]
+        results = [f.result() for f in concurrent.futures.as_completed(futures)]
+    
+    success_rate = sum(results) / len(results)
+    assert success_rate == 1.0, f"Expected 100% success rate, got {success_rate * 100:.1f}%"
+```
+
+## See Also
+
+- [Main Test README](../README.md) - Overview of all test categories
+- [Integration Tests](../integration/) - End-to-end workflow tests
+- [Benchmarks](../../../tests/benchmarks/) - Performance benchmarks
+- [Property Tests](../../../tests/property/) - Property-based tests

cvx_linalg-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jebel Quant Research
+
+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.

cvx_linalg-0.2.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: cvx-linalg
+Version: 0.2.0
+Summary: Linear algebra utilities for portfolio optimization
+Project-URL: repository, https://github.com/Jebel-Quant/linalg
+Author-email: Thomas Schmelzer <thomas.schmelzer@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3 :: Only
+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.0
+Requires-Dist: polars>=1.0.0
+Description-Content-Type: text/markdown
+
+# cvx-linalg
+
+Linear algebra utilities for portfolio optimization, part of the [jebel-quant](https://github.com/jebel-quant) ecosystem.
+
+## Installation
+
+```bash
+pip install cvx-linalg
+```
+
+## Usage
+
+```python
+from cvx.linalg import cholesky, pca, rand_cov, valid
+```
+
+## Functions
+
+- **`cholesky(cov)`** — Upper triangular Cholesky factor R such that R.T @ R = cov
+- **`pca(returns, n_components)`** — Principal Component Analysis via SVD
+- **`rand_cov(n, seed)`** — Random positive semi-definite covariance matrix
+- **`valid(matrix)`** — Extract valid submatrix by removing rows/columns with non-finite diagonal entries

cvx_linalg-0.2.0/README.md

@@ -0,0 +1,22 @@
+# cvx-linalg
+
+Linear algebra utilities for portfolio optimization, part of the [jebel-quant](https://github.com/jebel-quant) ecosystem.
+
+## Installation
+
+```bash
+pip install cvx-linalg
+```
+
+## Usage
+
+```python
+from cvx.linalg import cholesky, pca, rand_cov, valid
+```
+
+## Functions
+
+- **`cholesky(cov)`** — Upper triangular Cholesky factor R such that R.T @ R = cov
+- **`pca(returns, n_components)`** — Principal Component Analysis via SVD
+- **`rand_cov(n, seed)`** — Random positive semi-definite covariance matrix
+- **`valid(matrix)`** — Extract valid submatrix by removing rows/columns with non-finite diagonal entries

cvx_linalg-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "cvx-linalg"
+version = "0.2.0"
+description = "Linear algebra utilities for portfolio optimization"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=2.0.0",
+    "polars>=1.0.0",
+]
+authors = [{name = "Thomas Schmelzer", email = "thomas.schmelzer@gmail.com"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+repository = "https://github.com/Jebel-Quant/linalg"
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cvx"]
+
+[tool.hatch.build]
+include = [
+    "LICENSE",
+    "README.md",
+    "src/cvx/linalg",
+]
+
+[tool.interrogate]
+fail-under = 100
+ignore-init-method = true
+ignore-magic = true
+
+[tool.deptry.package_module_name_map]
+numpy = "numpy"
+polars = "polars"

cvx_linalg-0.2.0/src/cvx/linalg/__init__.py

@@ -0,0 +1,40 @@
+"""Linear algebra utilities for risk models.
+
+This subpackage provides linear algebra utilities commonly used in risk modeling,
+including Cholesky decomposition, Principal Component Analysis, and matrix
+validation.
+
+Example:
+    >>> import numpy as np
+    >>> from cvx.linalg import cholesky, pca, rand_cov, valid
+    >>> # Cholesky decomposition
+    >>> cov = np.array([[4.0, 2.0], [2.0, 5.0]])
+    >>> R = cholesky(cov)
+    >>> np.allclose(R.T @ R, cov)
+    True
+
+Functions:
+    cholesky: Compute upper triangular Cholesky decomposition
+    pca: Compute principal components of return data
+    rand_cov: Generate a random positive semi-definite covariance matrix
+    valid: Extract valid submatrix from a matrix with NaN values
+
+"""
+
+#    Copyright 2023 Stanford University Convex Optimization Group
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+from .cholesky import cholesky as cholesky
+from .pca import pca as pca
+from .rand_cov import rand_cov as rand_cov
+from .valid import valid as valid

cvx_linalg-0.2.0/src/cvx/linalg/cholesky.py

@@ -0,0 +1,117 @@
+"""Cholesky decomposition utilities for covariance matrices.
+
+This module provides a function to compute the upper triangular Cholesky
+decomposition of a positive definite covariance matrix.
+
+Example:
+    Compute the Cholesky decomposition of a covariance matrix:
+
+    >>> import numpy as np
+    >>> from cvx.linalg import cholesky
+    >>> # Create a positive definite matrix
+    >>> cov = np.array([[4.0, 2.0], [2.0, 5.0]])
+    >>> # Compute upper triangular Cholesky factor
+    >>> R = cholesky(cov)
+    >>> # Verify: R.T @ R = cov
+    >>> np.allclose(R.T @ R, cov)
+    True
+
+"""
+
+#    Copyright 2023 Stanford University Convex Optimization Group
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+from __future__ import annotations
+
+import numpy as np
+from numpy.linalg import cholesky as _cholesky
+
+
+def cholesky(cov: np.ndarray) -> np.ndarray:
+    """Compute the upper triangular part of the Cholesky decomposition.
+
+    This function computes the Cholesky decomposition of a positive definite matrix
+    and returns the upper triangular matrix R such that R^T @ R = cov.
+
+    The Cholesky decomposition is useful in portfolio optimization because it
+    provides an efficient way to compute portfolio risk as ||R @ w||_2, where
+    w is the portfolio weights vector.
+
+    Args:
+        cov: A positive definite covariance matrix of shape (n, n).
+
+    Returns:
+        The upper triangular Cholesky factor R of shape (n, n).
+
+    Example:
+        Basic usage with a simple covariance matrix:
+
+        >>> import numpy as np
+        >>> from cvx.linalg import cholesky
+        >>> # Identity matrix
+        >>> cov = np.eye(3)
+        >>> R = cholesky(cov)
+        >>> np.allclose(R, np.eye(3))
+        True
+
+        With a more complex covariance matrix:
+
+        >>> cov = np.array([[1.0, 0.5, 0.0],
+        ...                 [0.5, 1.0, 0.5],
+        ...                 [0.0, 0.5, 1.0]])
+        >>> R = cholesky(cov)
+        >>> np.allclose(R.T @ R, cov)
+        True
+
+        Verify upper triangular structure:
+
+        >>> R = cholesky(np.array([[4.0, 2.0], [2.0, 5.0]]))
+        >>> # R is upper triangular (zeros below diagonal)
+        >>> bool(np.allclose(R[1, 0], 0.0))
+        True
+        >>> bool(R[0, 0] > 0 and R[1, 1] > 0)  # Positive diagonal
+        True
+
+        Portfolio risk computation via Cholesky factor:
+
+        >>> cov = np.array([[0.04, 0.01], [0.01, 0.09]])
+        >>> R = cholesky(cov)
+        >>> w = np.array([0.6, 0.4])
+        >>> # Risk via Cholesky: ||R @ w||_2
+        >>> risk_chol = np.linalg.norm(R @ w)
+        >>> # Risk via covariance: sqrt(w^T @ cov @ w)
+        >>> risk_cov = np.sqrt(w @ cov @ w)
+        >>> bool(np.isclose(risk_chol, risk_cov))
+        True
+
+        Relationship between upper (R) and lower (L) triangular factors:
+
+        >>> cov = np.array([[9.0, 3.0], [3.0, 5.0]])
+        >>> R = cholesky(cov)
+        >>> L = np.linalg.cholesky(cov)  # numpy returns lower triangular
+        >>> # R = L^T
+        >>> np.allclose(R, L.T)
+        True
+        >>> # Both reconstruct the covariance
+        >>> np.allclose(L @ L.T, cov)
+        True
+        >>> np.allclose(R.T @ R, cov)
+        True
+
+    Note:
+        This function returns the upper triangular factor (R), whereas
+        numpy.linalg.cholesky returns the lower triangular factor (L).
+        The relationship is: L @ L^T = cov and R^T @ R = cov, where R = L^T.
+
+    """
+    return _cholesky(cov).transpose()

cvx_linalg-0.2.0/src/cvx/linalg/pca.py

@@ -0,0 +1,220 @@
+#    Copyright 2023 Stanford University Convex Optimization Group
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+"""PCA analysis (pure NumPy implementation).
+
+This module provides Principal Component Analysis (PCA) for dimensionality
+reduction of return data. PCA is commonly used to construct factor models
+for portfolio optimization.
+
+Example:
+    Perform PCA on stock returns:
+
+    >>> import numpy as np
+    >>> import polars as pl
+    >>> from cvx.linalg import pca
+    >>> # Create sample returns data
+    >>> np.random.seed(42)
+    >>> returns = pl.DataFrame(
+    ...     np.random.randn(100, 5),
+    ...     schema=['A', 'B', 'C', 'D', 'E']
+    ... )
+    >>> # Compute PCA with 3 components
+    >>> result = pca(returns, n_components=3)
+    >>> # Access explained variance
+    >>> len(result.explained_variance)
+    3
+    >>> # Access factors (principal components)
+    >>> result.factors.shape
+    (100, 3)
+    >>> # Access factor exposures (loadings)
+    >>> result.exposure.shape
+    (3, 5)
+
+"""
+
+from __future__ import annotations
+
+from collections import namedtuple
+
+import numpy as np
+import polars as pl
+
+PCA = namedtuple(
+    "PCA",
+    ["explained_variance", "factors", "exposure", "cov", "systematic", "idiosyncratic"],
+)
+"""Named tuple containing the results of PCA analysis.
+
+Attributes:
+    explained_variance: Explained variance ratio for each component.
+        An array of shape (n_components,) where each element represents
+        the proportion of total variance explained by that component.
+    factors: Factor returns (principal components) as a DataFrame.
+        Shape is (n_samples, n_components). Each column is a factor.
+    exposure: Factor exposures (loadings) for each asset as a DataFrame.
+        Shape is (n_components, n_assets). Each row contains the loadings
+        of one component on all assets.
+    cov: Covariance matrix of the factors as a DataFrame.
+        Shape is (n_components, n_components).
+    systematic: Systematic returns explained by the factors as a DataFrame.
+        Shape is (n_samples, n_assets). This is the part of returns
+        explained by the factor model.
+    idiosyncratic: Idiosyncratic returns not explained by factors as a DataFrame.
+        Shape is (n_samples, n_assets). This is the residual part of returns.
+
+Example:
+    >>> import numpy as np
+    >>> import polars as pl
+    >>> from cvx.linalg import pca
+    >>> np.random.seed(42)
+    >>> returns = pl.DataFrame(np.random.randn(50, 4))
+    >>> result = pca(returns, n_components=2)
+    >>> # Check explained variance sums to less than 1
+    >>> result.explained_variance.sum() < 1
+    True
+    >>> # Systematic + idiosyncratic approximately equals original
+    >>> np.allclose(
+    ...     result.systematic.to_numpy() + result.idiosyncratic.to_numpy(),
+    ...     returns.to_numpy(),
+    ...     atol=1e-10
+    ... )
+    True
+
+"""
+
+
+def pca(returns: pl.DataFrame, n_components: int = 10) -> PCA:
+    """Compute the first n principal components for a return matrix using SVD.
+
+    This function performs Principal Component Analysis on asset returns to
+    extract the main sources of variance. The results can be used to construct
+    a factor model for portfolio optimization.
+
+    Args:
+        returns: DataFrame of asset returns with shape (n_samples, n_assets).
+            Rows represent time periods, columns represent assets.
+        n_components: Number of principal components to extract. Defaults to 10.
+
+    Returns:
+        PCA named tuple containing:
+            - explained_variance: Ratio of variance explained by each component
+            - factors: Factor returns (scores)
+            - exposure: Factor exposures (loadings)
+            - cov: Factor covariance matrix
+            - systematic: Returns explained by factors
+            - idiosyncratic: Residual returns
+
+    Example:
+        Basic PCA on synthetic returns:
+
+        >>> import numpy as np
+        >>> import polars as pl
+        >>> from cvx.linalg import pca
+        >>> np.random.seed(42)
+        >>> # Create returns with 100 periods and 10 assets
+        >>> returns = pl.DataFrame(np.random.randn(100, 10))
+        >>> result = pca(returns, n_components=3)
+        >>> # First component explains most variance
+        >>> bool(result.explained_variance[0] > result.explained_variance[1])
+        True
+        >>> # Factors are orthogonal
+        >>> factor_corr = np.corrcoef(result.factors.to_numpy().T)
+        >>> bool(np.allclose(factor_corr, np.eye(3), atol=0.1))
+        True
+
+        Verifying variance decomposition (systematic + idiosyncratic = total):
+
+        >>> np.random.seed(123)
+        >>> returns = pl.DataFrame(np.random.randn(50, 5))
+        >>> result = pca(returns, n_components=3)
+        >>> # Systematic variance + idiosyncratic variance ≈ total variance
+        >>> total_var = np.var(returns.to_numpy(), axis=0, ddof=1).sum()
+        >>> systematic_var = np.var(result.systematic.to_numpy(), axis=0, ddof=1).sum()
+        >>> idio_var = np.var(result.idiosyncratic.to_numpy(), axis=0, ddof=1).sum()
+        >>> # Note: small differences due to demeaning
+        >>> bool(np.isclose(systematic_var + idio_var, total_var, rtol=0.1))
+        True
+
+        Exposure matrix has orthonormal rows (loadings are orthogonal):
+
+        >>> np.random.seed(42)
+        >>> returns = pl.DataFrame(np.random.randn(100, 6))
+        >>> result = pca(returns, n_components=3)
+        >>> # V^T @ V should be identity (orthonormal loadings)
+        >>> VtV = result.exposure.to_numpy() @ result.exposure.to_numpy().T
+        >>> bool(np.allclose(VtV, np.eye(3), atol=1e-10))
+        True
+
+        Explained variance is ordered (first component explains most):
+
+        >>> all(result.explained_variance[i] >= result.explained_variance[i+1]
+        ...     for i in range(len(result.explained_variance)-1))
+        True
+
+        Reconstructing returns from factors and exposures:
+
+        >>> # systematic = factors @ exposure (plus mean)
+        >>> reconstructed = result.factors.to_numpy() @ result.exposure.to_numpy()
+        >>> # Should match systematic (centered part)
+        >>> centered_systematic = result.systematic.to_numpy() - returns.to_numpy().mean(axis=0)
+        >>> bool(np.allclose(reconstructed, centered_systematic, atol=1e-10))
+        True
+
+    """
+    # Demean the returns
+    x = returns.to_numpy()
+    x_mean = x.mean(axis=0)
+    x_centered = x - x_mean
+
+    # Singular Value Decomposition
+    # x = u s V^T, where columns of V are principal axes
+    u, s_full, vt = np.linalg.svd(x_centered, full_matrices=False)
+
+    # Take only the first n components
+    u = u[:, :n_components]
+    s = s_full[:n_components]
+    vt = vt[:n_components, :]
+
+    pc_names = [f"PC{i + 1}" for i in range(n_components)]
+
+    # Factor exposures (loadings): each component's weight per asset
+    exposure = pl.DataFrame(vt, schema=returns.columns)
+
+    # Factor returns (scores): projection of data onto components
+    factors = pl.DataFrame(u * s, schema=pc_names)
+
+    # Explained variance ratio (normalize by total variance across ALL components)
+    explained_variance = (s**2) / np.sum(s_full**2)
+
+    # Covariance of factor returns
+    cov = pl.DataFrame(np.cov((u * s).T), schema=pc_names)
+
+    # Systematic + Idiosyncratic returns
+    systematic = pl.DataFrame(
+        (u * s) @ vt + x_mean,
+        schema=returns.columns,
+    )
+    idiosyncratic = pl.DataFrame(
+        x_centered - (u * s) @ vt,
+        schema=returns.columns,
+    )
+
+    return PCA(
+        explained_variance=explained_variance,
+        factors=factors,
+        exposure=exposure,
+        cov=cov,
+        systematic=systematic,
+        idiosyncratic=idiosyncratic,
+    )

cvx_linalg-0.2.0/src/cvx/linalg/rand_cov.py

@@ -0,0 +1,106 @@
+"""Random covariance matrix generation utilities.
+
+This module provides functions for generating random positive semi-definite
+covariance matrices. These are useful for testing and simulation purposes.
+
+Example:
+    Generate a random covariance matrix:
+
+    >>> import numpy as np
+    >>> from cvx.linalg import rand_cov
+    >>> # Generate a 5x5 random covariance matrix
+    >>> cov = rand_cov(5, seed=42)
+    >>> cov.shape
+    (5, 5)
+    >>> # Verify it's symmetric
+    >>> bool(np.allclose(cov, cov.T))
+    True
+    >>> # Verify it's positive semi-definite
+    >>> bool(np.all(np.linalg.eigvals(cov) >= -1e-10))
+    True
+
+"""
+
+#    Copyright 2023 Stanford University Convex Optimization Group
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+from __future__ import annotations
+
+import numpy as np
+
+
+def rand_cov(n: int, seed: int | None = None) -> np.ndarray:
+    """Construct a random positive semi-definite covariance matrix of size n x n.
+
+    The matrix is constructed as A^T @ A where A is a random n x n matrix with
+    elements drawn from a standard normal distribution. This ensures the result
+    is symmetric and positive semi-definite.
+
+    Args:
+        n: Size of the covariance matrix (n x n).
+        seed: Random seed for reproducibility. If None, uses the current
+            random state.
+
+    Returns:
+        A random positive semi-definite n x n covariance matrix.
+
+    Example:
+        Generate a reproducible random covariance matrix:
+
+        >>> import numpy as np
+        >>> from cvx.linalg import rand_cov
+        >>> cov1 = rand_cov(3, seed=42)
+        >>> cov2 = rand_cov(3, seed=42)
+        >>> np.allclose(cov1, cov2)
+        True
+
+        Verify positive definiteness via Cholesky decomposition:
+
+        >>> cov = rand_cov(5, seed=123)
+        >>> # If Cholesky succeeds without error, matrix is positive definite
+        >>> L = np.linalg.cholesky(cov)
+        >>> bool(np.allclose(L @ L.T, cov))
+        True
+
+        Eigenvalue verification:
+
+        >>> cov = rand_cov(3, seed=99)
+        >>> eigenvalues = np.linalg.eigvalsh(cov)
+        >>> # All eigenvalues should be positive for PD matrix
+        >>> bool(np.all(eigenvalues > 0))
+        True
+
+        Different seeds produce different matrices:
+
+        >>> cov1 = rand_cov(3, seed=1)
+        >>> cov2 = rand_cov(3, seed=2)
+        >>> bool(not np.allclose(cov1, cov2))
+        True
+
+        Without seed, consecutive calls may differ (random state):
+
+        >>> # These may or may not be equal depending on random state
+        >>> cov_a = rand_cov(2, seed=None)
+        >>> cov_b = rand_cov(2, seed=None)
+        >>> cov_a.shape == cov_b.shape == (2, 2)
+        True
+
+    Note:
+        The generated matrix is guaranteed to be positive semi-definite because
+        it is constructed as A^T @ A. In practice, it will typically be positive
+        definite (all eigenvalues strictly positive) unless n is very large.
+
+    """
+    rng = np.random.default_rng(seed)
+    a = rng.standard_normal((n, n))
+    return np.transpose(a) @ a

cvx_linalg-0.2.0/src/cvx/linalg/valid.py

@@ -0,0 +1,138 @@
+"""Matrix validation utilities for handling non-finite values.
+
+This module provides functions for validating and cleaning matrices that may
+contain non-finite values (NaN or infinity). This is particularly useful when
+working with financial data where missing values are common.
+
+Example:
+    Extract the valid submatrix from a covariance matrix with missing data:
+
+    >>> import numpy as np
+    >>> from cvx.linalg import valid
+    >>> # Create a covariance matrix with some NaN values on diagonal
+    >>> cov = np.array([[np.nan, 0.5, 0.2],
+    ...                 [0.5, 2.0, 0.3],
+    ...                 [0.2, 0.3, np.nan]])
+    >>> # Get valid indicator and submatrix
+    >>> v, submatrix = valid(cov)
+    >>> v  # Second row/column is valid
+    array([False,  True, False])
+    >>> submatrix
+    array([[2.]])
+
+"""
+
+#    Copyright 2023 Stanford University Convex Optimization Group
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+from __future__ import annotations
+
+import numpy as np
+
+
+def valid(matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Extract the valid subset of a matrix by removing rows/columns with non-finite values.
+
+    This function identifies rows and columns in a square matrix that contain
+    non-finite values (NaN or infinity) on the diagonal and removes them,
+    returning both the indicator vector and the resulting valid submatrix.
+
+    This is useful when working with covariance matrices where some assets
+    may have missing or invalid data.
+
+    Args:
+        matrix: A square n x n matrix to be validated. Typically a covariance
+            or correlation matrix.
+
+    Returns:
+        A tuple containing:
+            - v: Boolean vector of shape (n,) indicating which rows/columns are
+              valid (True for valid, False for invalid).
+            - submatrix: The valid submatrix with invalid rows/columns removed.
+              Shape is (k, k) where k is the number of True values in v.
+
+    Raises:
+        AssertionError: If the input matrix is not square (n x n).
+
+    Example:
+        Basic usage with a covariance matrix:
+
+        >>> import numpy as np
+        >>> from cvx.linalg import valid
+        >>> # Create a 3x3 matrix with one invalid entry
+        >>> cov = np.array([[1.0, 0.5, 0.2],
+        ...                 [0.5, np.nan, 0.3],
+        ...                 [0.2, 0.3, 1.0]])
+        >>> v, submatrix = valid(cov)
+        >>> v
+        array([ True, False,  True])
+        >>> submatrix
+        array([[1. , 0.2],
+               [0.2, 1. ]])
+
+        Handling a fully valid matrix:
+
+        >>> cov = np.array([[1.0, 0.5], [0.5, 1.0]])
+        >>> v, submatrix = valid(cov)
+        >>> v
+        array([ True,  True])
+        >>> np.allclose(submatrix, cov)
+        True
+
+        Handling infinity values:
+
+        >>> cov = np.array([[1.0, 0.5, 0.2],
+        ...                 [0.5, np.inf, 0.3],
+        ...                 [0.2, 0.3, 1.0]])
+        >>> v, submatrix = valid(cov)
+        >>> v
+        array([ True, False,  True])
+        >>> submatrix
+        array([[1. , 0.2],
+               [0.2, 1. ]])
+
+        Multiple invalid entries:
+
+        >>> cov = np.array([[np.nan, 0.1, 0.2, 0.3],
+        ...                 [0.1, 2.0, 0.4, 0.5],
+        ...                 [0.2, 0.4, np.nan, 0.6],
+        ...                 [0.3, 0.5, 0.6, 3.0]])
+        >>> v, submatrix = valid(cov)
+        >>> v
+        array([False,  True, False,  True])
+        >>> submatrix.shape
+        (2, 2)
+        >>> submatrix
+        array([[2. , 0.5],
+               [0.5, 3. ]])
+
+        Non-square matrix raises assertion:
+
+        >>> try:
+        ...     valid(np.array([[1, 2, 3], [4, 5, 6]]))
+        ... except AssertionError:
+        ...     print("Caught assertion error for non-square matrix")
+        Caught assertion error for non-square matrix
+
+    Note:
+        The function checks only the diagonal elements for validity. It assumes
+        that if the diagonal is finite, the entire row/column is valid. This is
+        a common assumption for covariance matrices.
+
+    """
+    # make sure matrix  is quadratic
+    if matrix.shape[0] != matrix.shape[1]:
+        raise AssertionError
+
+    v = np.isfinite(np.diag(matrix))
+    return v, matrix[:, v][v]