xpcsjax 0.1.0__tar.gz

xpcsjax-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.hdf5 filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+
+# Tiny deterministic parity golden fixtures (KB-scale) are committed as regular
+# git blobs, NOT LFS: CI's actions/checkout has no `lfs: true`, so LFS pointers
+# arrive in the work tree and np.load fails with UnpicklingError. Override the
+# blanket *.npz/*.npy LFS rules above for this dir only. Keep `-text` (binary)
+# so EOL normalization never corrupts the .npz zip archives.
+tests/parity/_golden/** !filter !diff !merge -text

xpcsjax-0.1.0/.github/codeql/codeql-config.yml

@@ -0,0 +1,59 @@
+name: "xpcsjax CodeQL config"
+
+# Keep the security-and-quality suite (security rules + maintainability rules),
+# but filter out the maintainability rules that are either (a) already owned and
+# enforced by ruff / mypy in CI, or (b) structural false positives against
+# xpcsjax's intentional architecture (lazy ``__getattr__`` import-cycle breaking,
+# optional-dependency import guards, ``typing.Protocol`` stub bodies).
+#
+# The genuine *security* rules and the real-bug correctness rules
+# (py/uninitialized-local-variable, py/call/*, py/comparison-of-identical-expressions,
+# py/unreachable-statement, py/empty-except, py/multiple-definition,
+# py/non-iterable-in-for-loop, ...) stay ACTIVE so future regressions are caught.
+queries:
+  - uses: security-and-quality
+
+# Test fixtures and Sphinx docs are not shipped product code; security-and-quality
+# maintainability scanning of them is pure noise (duplicate imports in fixtures,
+# intentionally-unreachable test branches, Sphinx config globals read by Sphinx).
+paths-ignore:
+  - tests
+  - docs
+
+query-filters:
+  # --- Import / local-variable hygiene: owned by ruff (F401, F811, F841, I) and
+  #     enforced by `make verify` / `make lint`. CodeQL only adds false positives
+  #     here because its flow analysis flags the optional-import guard idiom
+  #     (`try: import X; HAS_X = True / except ImportError: X = None`) and
+  #     redefinition shadowing that Pyflakes intentionally allows.
+  - exclude:
+      id: py/unused-import
+  - exclude:
+      id: py/unused-local-variable
+  - exclude:
+      id: py/repeated-import
+  - exclude:
+      id: py/import-and-import-from
+  - exclude:
+      id: py/import-own-module
+  # --- Unused module-level globals: dominated by false positives on cross-module
+  #     data tables / singletons / TypeVars (used via `from module import X`) and
+  #     on optional-dependency availability flags (HAS_JAX, HAS_NUMPY, ...).
+  - exclude:
+      id: py/unused-global-variable
+  # --- Cyclic imports: xpcsjax's public API is lazy-loaded via a module-level
+  #     `__getattr__` and `TYPE_CHECKING` forward refs specifically to break these
+  #     cycles. The "may not be defined" warning never materializes at runtime.
+  - exclude:
+      id: py/cyclic-import
+  - exclude:
+      id: py/unsafe-cyclic-import
+  # --- `def method(self) -> T: ...` Protocol / ABC stub bodies. The `...` Ellipsis
+  #     expression statement is the idiomatic stub body (PEP 544); flagging it as
+  #     "no effect" is a false positive.
+  - exclude:
+      id: py/ineffectual-statement
+  # --- Single-call lambdas: a style preference outside ruff's enforced set; low
+  #     signal and overlaps with intentional closures that reorder/partial args.
+  - exclude:
+      id: py/unnecessary-lambda

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

@@ -0,0 +1,86 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref to save runner minutes.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Platform-independent checks run once (fast) and gate the expensive matrix.
+  lint:
+    name: Lint, types, audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+      - name: Sync deps
+        run: uv sync --extra dev
+      - name: Export locked requirements for audit
+        # uv run pip-audit by itself audits the active venv; exporting first
+        # makes the audited set explicit and lets pip-audit cross-reference
+        # against the uv.lock-pinned versions rather than any installed state.
+        run: uv export --format requirements-txt --no-hashes -o requirements-audit.txt
+      - name: Dependency vulnerability scan
+        run: uv run pip-audit --requirement requirements-audit.txt --desc
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy xpcsjax
+
+  test:
+    name: Test (${{ matrix.os }}, py${{ matrix.python-version }})
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    # py3.14 is informational: jax/PySide6 wheels may not yet exist for a
+    # freshly-released interpreter, so a 3.14 failure must not fail the run.
+    # Drop this and the 3.14 matrix entry once 3.14 is a supported target.
+    continue-on-error: ${{ matrix.python-version == '3.14' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+      - name: Install Qt system libraries (headless PySide6, Linux only)
+        # PySide6 (pulled in via the pytest-qt plugin) links libEGL/libGL at
+        # import time, which the bare ubuntu runner lacks -> pytest aborts with
+        # `ImportError: libEGL.so.1`. The minimal runtime set lets Qt run under
+        # the offscreen platform (QT_QPA_PLATFORM below). macOS and Windows
+        # runners ship the system GL stack and the PySide6 wheels bundle Qt, so
+        # no equivalent install is needed there.
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libegl1 libgl1 libxkbcommon0 libdbus-1-3
+      - name: Sync deps
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+      - name: Test
+        env:
+          JAX_ENABLE_X64: "1"
+          QT_QPA_PLATFORM: offscreen
+          # NOTE: do NOT set XPCSJAX_RUN_CHARACTERIZATION here. That gate runs a
+          # LIVE fit against the upstream `homodyne` package using datasets at
+          # maintainer-local absolute paths (/home/.../Projects/data/...), so it
+          # only runs on a maintainer machine and self-skips in CI by design.
+          # The portable heterodyne parity + cross-mode suites run unconditionally.
+        run: uv run pytest -v

xpcsjax-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly re-scan catches advisories published after the last code change.
+    - cron: "27 4 * * 1"
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # upload SARIF results
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@84498526a009a99c875e83ef4821a8ba52de7c22  # codeql-bundle-v2.25.5
+        with:
+          languages: python
+          # Query suite, path scoping, and noise-rule filters live in the config
+          # file so they are reviewable in one place. The suite is still
+          # security-and-quality; the config filters out maintainability rules
+          # already owned by ruff/mypy or that are structural false positives
+          # against xpcsjax's lazy-import / optional-dependency architecture.
+          config-file: ./.github/codeql/codeql-config.yml
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@84498526a009a99c875e83ef4821a8ba52de7c22  # codeql-bundle-v2.25.5
+        with:
+          category: "/language:python"

xpcsjax-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Sphinx build (strict -W)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+      - name: Install Qt system libraries (autodoc may import PySide6)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libegl1 libgl1 libxkbcommon0 libdbus-1-3
+      - name: Sync docs deps
+        run: uv sync --extra docs
+      - name: Build docs (warnings are errors)
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: uv run sphinx-build -W -b html docs/source docs/_build/html
+      - name: Upload built HTML
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: html-docs
+          path: docs/_build/html

xpcsjax-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+# Publish xpcsjax to PyPI when a GitHub Release is published.
+#
+# Authentication is PyPI Trusted Publishing (OIDC) -- there is NO API token
+# secret. The `build` job runs the project's own build code with NO
+# credentials; only the minimal `publish` job is granted the short-lived OIDC
+# token (id-token: write) and runs in the protected `pypi` environment. This
+# build/publish split follows the PyPA Trusted Publishing guidance so build
+# code can never reach the publishing credential.
+#
+# One-time setup before the first run: register a Trusted Publisher on PyPI
+# (https://pypi.org/manage/account/publishing/) with
+#   owner=imewei  repository=xpcsjax  workflow=release.yml  environment=pypi
+on:
+  release:
+    types: [published]
+  # Manual fallback (e.g. to publish a tag that predates this workflow, or to
+  # retry a failed upload). The version guard below is skipped for this path.
+  workflow_dispatch:
+
+# Never cancel an in-flight publish; a half-cancelled upload is worse than a
+# duplicate run (PyPI rejects re-uploads of an existing version idempotently).
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Verify package version matches the release tag
+        # Guard against publishing a build whose version disagrees with the tag
+        # that triggered the release (e.g. pyproject not bumped). Reads the
+        # version with stdlib tomllib -- no project install needed. Skipped on
+        # workflow_dispatch, where there is no release tag.
+        if: github.event_name == 'release'
+        run: |
+          pkg_version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          tag="${GITHUB_REF_NAME#v}"
+          echo "package version: $pkg_version | release tag: $tag"
+          if [ "$pkg_version" != "$tag" ]; then
+            echo "::error::pyproject version '$pkg_version' does not match release tag '$tag'"
+            exit 1
+          fi
+      - name: Check distribution metadata
+        run: uvx twine check --strict dist/*
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The `pypi` environment is where the Trusted Publisher is registered on
+    # PyPI; add required reviewers / branch filters here to gate releases.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xpcsjax
+    permissions:
+      id-token: write  # mint the OIDC token PyPI verifies (Trusted Publishing)
+      contents: read
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0

xpcsjax-0.1.0/.gitignore

@@ -0,0 +1,342 @@
+# ============================================================================
+# xpcsjax .gitignore — derived from homodyne/heterodyne, NLSQ-only
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# Python Bytecode & Compiled Files
+# ----------------------------------------------------------------------------
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+*.dylib
+*.dll
+
+# ----------------------------------------------------------------------------
+# Distribution / Packaging
+# ----------------------------------------------------------------------------
+# Note: xpcsjax uses hatchling with a hard-coded version in pyproject.toml,
+# so there is no auto-generated `xpcsjax/_version.py` (unlike homodyne /
+# heterodyne, which use setuptools_scm). Do not add a _version.py rule.
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.whl
+MANIFEST
+
+# ----------------------------------------------------------------------------
+# Installer & Package Managers
+# ----------------------------------------------------------------------------
+pip-log.txt
+pip-delete-this-directory.txt
+.pypirc
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Dependency management lockfiles (we commit uv.lock; ignore the others)
+Pipfile.lock
+poetry.lock
+pdm.lock
+.pdm-python
+.pdm-build/
+.pixi/
+pixi.lock
+__pypackages__/
+
+# ----------------------------------------------------------------------------
+# Virtual Environments
+# ----------------------------------------------------------------------------
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.conda/
+conda-env/
+
+# ----------------------------------------------------------------------------
+# Testing & Coverage
+# ----------------------------------------------------------------------------
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+.benchmarks/
+# Root-level perf-benchmark scratch (e.g. bench_*.py, baseline.json). Anchored
+# with a leading slash so the committed tests/benchmarks/ suite stays tracked.
+/benchmarks/
+.test-runs/
+test_report*/
+test_reports/
+test-results.xml
+bandit*re*.json
+pip_audit_report.json
+
+# IMPORTANT: do NOT ignore tests/characterization/fixtures/ — those are the
+# homodyne parity baselines and are the parity contract (see CLAUDE.md).
+
+# ----------------------------------------------------------------------------
+# Type Checkers, Linters & Caches
+# ----------------------------------------------------------------------------
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+.pylint_cache/
+.nlsq_cache/
+.cache/
+
+# ----------------------------------------------------------------------------
+# Documentation
+# ----------------------------------------------------------------------------
+# Sphinx is not configured in xpcsjax (docs/ holds design specs only).
+# Keep these patterns for future Sphinx adoption.
+docs/_build/
+docs/build/
+doc/build/
+.doctrees/
+*.doctree
+docs/source/_autosummary/
+docs/source/_generated/
+docs/source/api/generated/
+docs/superpowers/
+
+# MkDocs
+/site
+
+# ----------------------------------------------------------------------------
+# Jupyter / IPython / Marimo
+# ----------------------------------------------------------------------------
+.ipynb_checkpoints
+*.ipynb_checkpoints/
+*/.ipynb_checkpoints/*
+profile_default/
+ipython_config.py
+.jupyter/
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# ----------------------------------------------------------------------------
+# IDEs & Editors
+# ----------------------------------------------------------------------------
+.idea/
+.vscode/
+*.code-workspace
+.spyderproject
+.spyproject
+.ropeproject
+*.swp
+*.swo
+\#*\#
+.\#*
+tempCodeRunnerFile.py
+
+# ----------------------------------------------------------------------------
+# AI-Powered Development Tools (state, caches, sessions)
+# ----------------------------------------------------------------------------
+.agent/
+.agents/
+.antigravitycli/
+.claude/
+.claude-progress.md
+.claude-scratch
+.code/
+.codex/
+.cursor/
+.cursorignore
+.cursorindexingignore
+.gemini/
+.remember/
+.serena/
+.specify/
+.ultra-think/
+.ultracode/
+.abstra/
+.firecrawl/
+agent-os/
+
+# AI assistant project memos
+# ----------------------------------------------------------------------------
+# Treated as local-only AI scratch — same policy as homodyne / heterodyne.
+# Each developer maintains their own onboarding notes for their AI assistant
+# of choice; nothing about these files is load-bearing for the project's
+# build, tests, or distribution. To flip the policy and check one of these
+# in (e.g. as a shared onboarding contract), remove the corresponding line.
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+WARP.md
+
+# Other AI-assistant notes that remain local-only
+GROK.md
+HERMES.md
+OPENROUTER.md
+codex.md
+
+# Multi-model review outputs
+three-brain-out/
+
+# Git
+.worktrees/
+
+# ----------------------------------------------------------------------------
+# Operating System
+# ----------------------------------------------------------------------------
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+.directory
+
+# ----------------------------------------------------------------------------
+# Logs & Temporary Files
+# ----------------------------------------------------------------------------
+*.log
+.research-log.jsonl
+*.tmp
+*.temp
+*.bak
+*.backup
+*.orig
+*~
+tmp/
+
+# ----------------------------------------------------------------------------
+# Profiling
+# ----------------------------------------------------------------------------
+*.prof
+*.lprof
+.prof/
+profiling/
+
+# ----------------------------------------------------------------------------
+# Cython
+# ----------------------------------------------------------------------------
+cython_debug/
+*.c
+*.cpp
+# Uncomment if you ever ship Cython sources to keep:
+# !src/**/*.c
+# !src/**/*.cpp
+
+# ----------------------------------------------------------------------------
+# Translations & Misc
+# ----------------------------------------------------------------------------
+*.mo
+*.pot
+*.sage.py
+celerybeat-schedule
+celerybeat.pid
+node_modules/
+
+# ----------------------------------------------------------------------------
+# xpcsjax-specific
+# ----------------------------------------------------------------------------
+# Analysis results and outputs
+xpcsjax_results/
+xpcsjax_analysis_results/
+xpcsjax_analysis_results.json
+.xpcsjax_cache/
+# Root-level app-state cache (e.g. cache/projects.json). Anchored with a
+# leading slash so any tracked cache/ deeper in the tree stays unaffected.
+/cache/
+
+# Scientific Computing & Data (results, not test fixtures)
+# Tests fixtures live under tests/characterization/fixtures/ and MUST be
+# committed — those are the parity oracle baselines.
+*.h5
+*.hdf5
+*.mat
+*.npy
+*.npz
+!tests/characterization/fixtures/**/*.h5
+!tests/characterization/fixtures/**/*.hdf5
+!tests/characterization/fixtures/**/*.npy
+!tests/characterization/fixtures/**/*.npz
+# Committed golden snapshots for the Phase-1.0 homodyne engine preservation suite
+!tests/parity/_golden/**/*.npz
+
+# Run artifacts
+phi_angles_list.txt
+
+# Task / work-in-progress scratch
+TASK_GROUP_*.md
+fix-imports/
+.optimization/
+scripts/dev_cleanup/
+plans/
+
+# Temporary analysis / review reports
+PROGRESS.md
+commit_*_review.json
+commit_*_breaking_changes.json
+git_workflow_summary_*.md
+code_quality_fixes_summary.md
+codebase_analysis.md
+DEBUG_REPORT.md
+PRODUCTION_READINESS_REPORT.md
+SCIENTIFIC_VALIDATION_REPORT.md
+DOCUMENTATION_POLISH_SUMMARY.md
+PERFORMANCE_ANALYSIS_REPORT.md
+ARCHITECTURE_REVIEW.md
+T0*_test_failure_analysis.md
+T0*_integration_test_analysis.md
+
+# ----------------------------------------------------------------------------
+# Graphify (Knowledge Graph & Semantic Cache)
+# ----------------------------------------------------------------------------
+graphify-out/cache/
+graphify-out/.graphify_python
+graphify-out/.graphify_*.json
+graphify-out/.graphify_*.txt
+graphify-out/.obsidian/
+graphify-out/_COMMUNITY_*.md
+graphify-out/20*/
+
+# Generated by CI / `make security` for pip-audit (SEC-3); never commit
+requirements-audit.txt
+
+# subagent-driven-development scaffolding (briefs/reports/diffs) — never commit
+/sdd/
+
+# The hand-authored GUI PyInstaller spec is a tracked deliverable (overrides *.spec)
+!packaging/xpcsjax-gui.spec

xpcsjax-0.1.0/.graphifyignore

@@ -0,0 +1,23 @@
+# .graphifyignore
+node_modules/
+dist/
+*.generated.py
+
+# only index src/, ignore everything else
+*
+!xpcsjax/
+!xpcsjax/**
+!docs/
+!docs/**
+docs/_build/
+docs/_build/**
+docs/source/_build/
+docs/source/_build/**
+docs/_autosummary/
+docs/_autosummary/**
+docs/superpowers/
+docs/superpowers/**
+!tests
+!tests/**
+!scripts
+!scripts/**