qufin 0.1.0__tar.gz

qufin-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

qufin-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: []

qufin-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug Report
+about: Report a bug in qufin
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. Install qufin version X.X.X
+2. Run the following code:
+
+```python
+# Minimal code to reproduce the issue
+```
+
+3. Observe the error.
+
+## Expected Behavior
+
+Describe what you expected to happen.
+
+## Actual Behavior
+
+Describe what actually happened. Include the full error traceback if applicable.
+
+```
+Paste error output here
+```
+
+## Environment
+
+- **Python version**: (e.g., 3.12.0)
+- **qufin version**: (e.g., 0.1.0)
+- **OS**: (e.g., Ubuntu 24.04, Windows 11, macOS 15)
+- **Qiskit version** (if relevant): (e.g., 2.4.1)
+- **Installation method**: (e.g., pip, from source)
+
+## Additional Context
+
+Add any other relevant information, logs, or screenshots.

qufin-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement for qufin
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of the feature you are requesting.
+
+## Use Case
+
+Explain the problem this feature would solve or the workflow it would enable. Include references to relevant financial models, quantum algorithms, or academic papers if applicable.
+
+## Proposed Solution
+
+Describe your preferred approach to implementing this feature. If you have considered alternatives, list them here with trade-offs.
+
+## Additional Context
+
+Add any other information, references, or examples that support this request.

qufin-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## Summary
+
+Describe the changes in this PR and the motivation behind them.
+
+Closes #(issue number)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Performance improvement
+- [ ] Refactor (no functional changes)
+- [ ] Documentation update
+- [ ] CI/CD or build configuration change
+
+## Checklist
+
+- [ ] Tests pass locally (`pytest -m "not hardware and not slow"`)
+- [ ] Lint is clean (`ruff check src/ tests/`)
+- [ ] Code is formatted (`ruff format --check src/ tests/`)
+- [ ] Type checks pass (`mypy`)
+- [ ] New code has tests with adequate coverage
+- [ ] Public APIs have docstrings
+- [ ] CHANGELOG.md updated (if applicable)
+
+## Notes for Reviewers
+
+Add any context that would help reviewers understand the changes.

qufin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not hardware and not slow" --cov=qufin --cov-report=xml
+      - uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: |
+          mypy src/qufin/backtesting/ \
+               src/qufin/risk/classical_var.py \
+               src/qufin/risk/stress.py \
+               src/qufin/risk/counterparty.py \
+               src/qufin/portfolio/classical/
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install bandit pip-audit
+      - run: bandit -r src/qufin/ -ll -q
+      - run: pip install -e . && pip-audit
+        continue-on-error: true
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]" mkdocs mkdocs-material "mkdocstrings[python]"
+      - run: mkdocs build --strict
+        continue-on-error: true
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test, lint, typecheck]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qufin
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

qufin-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.hypothesis/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Data cache
+data/*.parquet
+data/*.csv
+!data/README.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docs build
+docs/_build/
+site/
+
+# Benchmark outputs
+benchmarks/leaderboard.md
+benchmarks/leaderboard.json
+benchmarks/results/
+
+# Secrets
+.env
+*.key
+credentials.json
+rel.md
+plan.md
+guide/

qufin-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout

qufin-0.1.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-11
+
+### Added
+
+#### Portfolio Optimization
+- Mean-variance optimization with CVXPY (MIQP with GLPK_MI fallback)
+- Black-Litterman model
+- Risk parity optimization
+- Hierarchical Risk Parity (HRP)
+- QAOA optimizer with X, XY-ring, XY-full, and Grover mixers (CVaR objective, Dicke init)
+- QUBO formulation with cardinality, sector, turnover, and transaction cost constraints
+- One-hot and binary variable encoding
+- Exhaustive QUBO solver for exact reference solutions
+
+#### Option Pricing
+- Black-Scholes analytical pricing with full Greeks (delta, gamma, theta, vega, rho)
+- Black-Scholes functional API with implied volatility solver
+- CRR binomial tree (European and American exercise)
+- Monte Carlo engine with antithetic variates (European, Asian, barrier)
+- Bermudan, lookback, cliquet, and autocallable exotic options
+
+#### Quantum Amplitude Estimation
+- Canonical QAE
+- Iterative QAE (IQAE)
+- Maximum Likelihood QAE (MLAE)
+- Fourier QAE (FQAE)
+
+#### Risk Management
+- Historical, parametric, and Monte Carlo VaR
+- Conditional VaR (CVaR / Expected Shortfall)
+- Stress testing framework
+- Counterparty credit valuation adjustment (CVA/DVA)
+- Credit risk modeling with Gaussian and NIG copula
+
+#### Backtesting
+- Walk-forward backtesting engine
+- 15 performance metrics
+- Transaction cost modeling
+
+#### Data Layer
+- Yahoo Finance integration
+- FRED macroeconomic data
+- Synthetic data generators (GBM, Heston, Merton jump-diffusion)
+- Local caching system
+
+#### Noise Simulation
+- 4 device noise profiles
+- Zero-noise extrapolation (ZNE)
+- Twirled readout error extinction (TREX)
+- Readout error calibration
+
+#### Machine Learning
+- Quantum kernel methods
+- Variational Quantum Classifier (VQC)
+- Quantum reservoir computing
+
+#### Backends
+- MockBackend for unit testing
+- Qiskit Aer simulator backend
+- Noisy Aer backend with device profiles
+- IBM Runtime backend interface
+
+#### Benchmarks
+- 150+ benchmark entries across 15, 25, and 50 asset universes
+- Classical comparison baselines
+- Quantum scaling analysis
+- Quantum advantage metrics
+
+#### Infrastructure
+- MkDocs Material documentation site
+- GitHub Actions CI/CD pipeline
+- Linting with ruff, type checking with mypy, security with bandit, dependency audit with pip-audit
+
+[0.1.0]: https://github.com/anonymousAAK/qufin/releases/tag/v0.1.0

qufin-0.1.0/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "qufin: Research-grade quantum algorithms for quant finance"
+authors:
+  - given-names: Adarsh
+license: Apache-2.0
+repository-code: "https://github.com/qufinance/qufin"
+keywords:
+  - quantum computing
+  - finance
+  - portfolio optimization
+  - option pricing
+  - amplitude estimation
+  - QAOA

qufin-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+- The use of sexualized language or imagery
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

qufin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to qufin
+
+Thank you for your interest in contributing to qufin. This guide covers the workflow and standards for contributions.
+
+## Getting Started
+
+1. Fork the repository on GitHub.
+2. Clone your fork and create a feature branch:
+
+```bash
+git clone https://github.com/<your-username>/qufin.git
+cd qufin
+git checkout -b feature/your-feature-name
+```
+
+3. Install the package in development mode with all extras:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Development Workflow
+
+### Running Tests
+
+Run the fast test suite (excludes hardware and slow integration tests):
+
+```bash
+pytest -m "not hardware and not slow"
+```
+
+Run the full suite including slow tests:
+
+```bash
+pytest
+```
+
+### Linting and Formatting
+
+Check for lint issues:
+
+```bash
+ruff check src/ tests/
+```
+
+Auto-format code:
+
+```bash
+ruff format src/ tests/
+```
+
+### Type Checking
+
+Run mypy on modules that have strict typing enabled:
+
+```bash
+mypy src/qufin/
+```
+
+## Code Style
+
+- **Formatter/linter**: ruff (configured in `pyproject.toml`)
+- **Line length**: 100 characters
+- **Variable naming**: Standard finance and mathematics conventions are acceptable for variable names (e.g., `S` for spot price, `K` for strike, `T` for time to maturity, `sigma` for volatility, `mu` for drift). Use descriptive names for everything else.
+- **Docstrings**: Google style. All public functions and classes must have docstrings.
+- **Type hints**: Required for all public function signatures.
+
+## Pull Request Requirements
+
+Before submitting a PR, verify the following:
+
+- [ ] All tests pass (`pytest -m "not hardware and not slow"`)
+- [ ] No lint errors (`ruff check src/ tests/`)
+- [ ] Code is formatted (`ruff format --check src/ tests/`)
+- [ ] Type checks pass on modified modules (`mypy`)
+- [ ] New functionality includes tests
+- [ ] Docstrings are present for all public APIs
+
+## Submitting a Pull Request
+
+1. Push your branch to your fork.
+2. Open a pull request against the `main` branch of the upstream repository.
+3. Fill out the PR template completely.
+4. Ensure CI checks pass.
+
+A maintainer will review your PR and may request changes. Please respond to feedback promptly.
+
+## Reporting Issues
+
+Use the GitHub issue templates for bug reports and feature requests. Provide as much detail as possible to help us reproduce and address the issue.

qufin-0.1.0/GOVERNANCE.md

@@ -0,0 +1,25 @@
+# Governance
+
+## Current model: BDFL (Year 1)
+
+qufin is currently maintained by a single developer (Adarsh) with final say
+on all decisions. This is the "Benevolent Dictator For Life" model, appropriate
+for a solo project in its first year.
+
+## Transition trigger (Year 2+)
+
+When the project has 3 or more external contributors with 5+ merged PRs each,
+governance transitions to a 3-person Steering Council with rotating chair.
+
+## Contributor ladder
+
+1. **Contributor** - Anyone with a merged PR
+2. **Triager** - Issue triage rights (after 3+ merged PRs)
+3. **Committer** - Merge rights on assigned modules (after 5+ merged PRs)
+4. **Maintainer** - Release rights (Steering Council members)
+
+## Decision process
+
+- Minor decisions (bug fixes, docs): maintainer discretion
+- Moderate decisions (new features, API changes): RFC in GitHub Discussions
+- Major decisions (architecture, licensing): Steering Council vote (future)