portc 0.6.0__tar.gz

portc-0.6.0/.devcontainer/Dockerfile

@@ -0,0 +1,5 @@
+FROM ghcr.io/astral-sh/uv:latest AS uv
+
+FROM mcr.microsoft.com/devcontainers/base:1.2.5-noble
+
+COPY --from=uv --chown=vscode: /uv /uvx /bin/

portc-0.6.0/.devcontainer/devcontainer.json

@@ -0,0 +1,50 @@
+{
+  "name": "portc development environment",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "remoteUser": "vscode",
+  "features": {
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "22"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/home/vscode/.venv/bin/python",
+        "python.terminal.activateEnvInCurrentTerminal": true,
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "/bin/zsh"
+          }
+        }
+      },
+      "extensions": [
+        "MS-vsliveshare.vsliveshare",
+        "charliermarsh.ruff",
+        "ms-python.python",
+        "ms-toolsai.jupyter",
+        "mutantdino.resourcemonitor",
+        "njpwerner.autodocstring",
+        "streetsidesoftware.code-spell-checker",
+        "streetsidesoftware.code-spell-checker-scientific-terms",
+        "tamasfe.even-better-toml",
+        "vivaxy.vscode-conventional-commits"
+      ]
+    }
+  },
+  "containerEnv": {
+    "PYTHONUNBUFFERED": "True",
+    "WORKSPACE": "${containerWorkspaceFolder}",
+    "UV_LINK_MODE": "copy",
+    "UV_PROJECT_ENVIRONMENT": "/home/vscode/.venv"
+  },
+  "postCreateCommand": "./.devcontainer/postCreateCommand.sh",
+  "postStartCommand": "./.devcontainer/postStartCommand.sh",
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "6gb"
+  }
+}

portc-0.6.0/.devcontainer/postCreateCommand.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -euxo pipefail
+
+
+# install uv and uvx shell completions
+echo 'eval "$(uv generate-shell-completion zsh)"' >> /home/vscode/.zshrc
+echo 'eval "$(uvx --generate-shell-completion zsh)"' >> /home/vscode/.zshrc

portc-0.6.0/.devcontainer/postStartCommand.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+
+# install project with all dependencies (no GPU extras in devcontainer)
+uv sync --all-groups
+
+# install the git hook shims
+uv run prek install --prepare-hooks

portc-0.6.0/.envrc

@@ -0,0 +1 @@
+use flake

portc-0.6.0/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

portc-0.6.0/.gitattributes

@@ -0,0 +1,18 @@
+# Keep GitHub's language statistics meaningful for a pure-Python project.
+*.py linguist-language=Python
+docs/* linguist-documentation
+benches/* linguist-documentation
+*.md linguist-documentation
+*.js linguist-detectable=false
+*.css linguist-detectable=false
+
+# Mark generated files.
+**/generated/* linguist-generated=true
+
+# Binary assets.
+*.png binary
+
+# Substituted at `git archive` time so hatch-vcs can derive a version from a
+# tarball that has no .git directory.
+.git_archival.txt  export-subst
+.gitignore         export-ignore

portc-0.6.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,82 @@
+name: Bug report
+description: Report a bug or unexpected behavior in portc
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in as much detail as possible.
+        See also the "Reporting bugs" section of CONTRIBUTING.md.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug description
+      description: A clear and concise description of the bug.
+      placeholder: What went wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: |
+        A minimal, self-contained reproducer, ideally with a fixed `seed=`.
+        For accuracy problems include the number of sites, the bond dimensions,
+        `chi_out`, the `dtype` and the error metric you used.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device
+    attributes:
+      label: Device
+      options:
+        - CPU (NumPy)
+        - GPU, NVIDIA (CuPy, CUDA)
+        - GPU, AMD (CuPy, ROCm)
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: Versions of `portc`, Python, NumPy and, for GPU runs, CuPy and the CUDA/ROCm runtime.
+      render: text
+      placeholder: |
+        portc: (python -c "import portc; print(portc.__version__)")
+        Python:
+        NumPy:
+        CuPy:
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux (x86_64)
+        - Linux (aarch64 / ARM64)
+        - macOS (Apple Silicon)
+        - macOS (Intel)
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Logs, tracebacks, or any other relevant information.

portc-0.6.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://algorithmiq.github.io/portc/
+    about: Check the documentation before opening an issue.

portc-0.6.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: Feature request / Enhancement
+description: Suggest a new feature or improvement to portc
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement! Please describe your idea clearly.
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: |
+        What problem does this feature solve, or what use case does it enable?
+        Is this related to something that is currently impossible or inconvenient?
+      placeholder: I'm trying to do X, but currently I have to work around it by doing Y…
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed feature
+      description: A clear description of the feature or change you'd like to see.
+    validations:
+      required: true
+
+  - type: textarea
+    id: api_sketch
+    attributes:
+      label: Proposed API or usage example (optional)
+      description: If applicable, sketch how the feature would look from a user's perspective.
+      render: python
+      placeholder: |
+        import portc
+        # ...
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Any other relevant information, including alternative approaches you considered and why your proposal is preferred.

portc-0.6.0/.github/ISSUE_TEMPLATE/performance_issue.yml

@@ -0,0 +1,126 @@
+name: Performance issue
+description: Report a performance regression or unexpectedly slow behavior
+labels: ["performance"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a performance issue!
+        Please include benchmark results so we can reproduce and investigate.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Performance issue description
+      description: Describe the performance problem you observed.
+      placeholder: What is slower than expected, and by how much?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: |
+        Minimal code snippet that demonstrates the slow behavior, with the
+        number of sites, bond dimensions, `chi_out`, `dtype` and `device`.
+      render: python
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux (x86_64)
+        - Linux (aarch64 / ARM64)
+        - macOS (Apple Silicon)
+        - macOS (Intel)
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: input
+    id: cpu
+    attributes:
+      label: CPU model
+      placeholder: "e.g. Intel Core i9-13900K, AMD EPYC 7763, Apple M3 Pro"
+    validations:
+      required: true
+
+  - type: input
+    id: ram
+    attributes:
+      label: Total RAM
+      placeholder: "e.g. 32 GB"
+    validations:
+      required: true
+
+  - type: input
+    id: cores_used
+    attributes:
+      label: Number of cores used
+      description: How many CPU cores / threads did portc use during the run (e.g. `OMP_NUM_THREADS`)?
+      placeholder: "e.g. 8 (out of 16 physical cores)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: bench_results
+    attributes:
+      label: Benchmark results
+      description: |
+        Please include the benchmark command and output.
+
+        For the pytest benchmark suite, run for example:
+
+          uv sync --group test
+          uv run pytest -m perf
+
+        For standalone benchmarks, see `benches/`.
+      placeholder: |
+        Command:
+          uv run pytest -m perf
+
+        Output:
+          ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device
+    attributes:
+      label: Device
+      options:
+        - CPU (NumPy)
+        - GPU, NVIDIA (CuPy, CUDA)
+        - GPU, AMD (CuPy, ROCm)
+    validations:
+      required: true
+
+  - type: input
+    id: gpu
+    attributes:
+      label: GPU model and memory
+      description: Only for GPU runs.
+      placeholder: "e.g. NVIDIA A100 80 GB"
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: Versions of `portc`, Python, NumPy and, for GPU runs, CuPy and the CUDA/ROCm runtime.
+      render: text
+      placeholder: |
+        portc:
+        Python:
+        NumPy:
+        CuPy:
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context

portc-0.6.0/.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

portc-0.6.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # maintain dependencies for Python
+  - package-ecosystem: "uv"
+    directory: "/" # Location of package manifests
+    # run on the 1st and 15th day of the month
+    schedule:
+      interval: "cron"
+      cronjob: "0 3 1,15 * *"
+    open-pull-requests-limit: 10
+    ignore:
+      # for all dependencies, ignore all patch updates
+      - dependency-name: "*"
+        update-types: ["version-update:semver-patch"]
+
+  # maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+
+  # maintain dependencies for DevContainer
+  - package-ecosystem: "devcontainers"
+    directory: "/"
+    schedule:
+      interval: "monthly"

portc-0.6.0/.github/release.yml

@@ -0,0 +1,6 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]
+    labels:
+      - dependencies

portc-0.6.0/.github/scripts/check_tool_pins.py

@@ -0,0 +1,58 @@
+# ruff: noqa: INP001  (a standalone script, not part of a package)
+"""Fail if a tool is pinned to different versions in pyproject.toml and prek.toml.
+
+`uv run ruff` and the prek hook must agree, or a file can pass locally and fail
+in CI. Each tool below is pinned as ``tool==X.Y.Z`` in a dependency group and as
+``rev = "vX.Y.Z"`` on its pre-commit mirror.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+MIRRORS = {
+    "ruff": "https://github.com/astral-sh/ruff-pre-commit",
+    "ty": "https://github.com/astral-sh/ty-pre-commit",
+}
+
+
+def main() -> int:
+    """Compare the pins and report every mismatch.
+
+    Returns:
+        The process exit code: 0 if every pin agrees, 1 otherwise.
+    """
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
+    prek = tomllib.loads((ROOT / "prek.toml").read_text())
+    requirements = [
+        req
+        for group in pyproject["dependency-groups"].values()
+        for req in group
+        if isinstance(req, str)
+    ]
+    revs = {repo["repo"]: repo.get("rev") for repo in prek["repos"]}
+
+    errors = []
+    for tool, mirror in MIRRORS.items():
+        pins = {
+            m.group(1)
+            for req in requirements
+            if (m := re.fullmatch(rf"{tool}==(\S+)", req.replace(" ", "")))
+        }
+        rev = revs.get(mirror)
+        if len(pins) != 1 or rev is None:
+            errors.append(f"{tool}: expected one '{tool}==' pin and a {mirror} rev")
+        elif rev.removeprefix("v") != (pin := pins.pop()):
+            errors.append(f"{tool}: pyproject.toml pins {pin}, prek.toml pins {rev}")
+
+    for error in errors:
+        print(error, file=sys.stderr)  # noqa: T201
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

portc-0.6.0/.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,34 @@
+name: "Copilot Setup Steps"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # the job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.14"
+
+      - name: Install package
+        run: |
+          uv sync --all-groups

portc-0.6.0/.github/workflows/deploy.yml

@@ -0,0 +1,80 @@
+name: Publish portc Python sdist and wheels
+
+on:
+  release:
+    types:
+      - published
+  pull_request:
+    # PRs trigger for the "opened", "reopened", "synchronize" events (default) and
+    # "ready_for_review"
+    paths:
+      - .github/workflows/deploy.yml
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  COLUMNS: 120
+  FORCE_COLOR: 3
+
+jobs:
+  build-sdist-wheel:
+    name: Build source distribution and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # such that setuptools_scm can do its job correctly
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build SDist and Wheel
+        run: |
+          # the `build` package's console script is `pyproject-build`, not `build`
+          uvx --from build pyproject-build --verbose --sdist --wheel --installer=uv
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: cibw-dist
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs:
+      - build-sdist-wheel
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    runs-on: ubuntu-latest
+
+    # Requires a `pypi` environment (Settings > Environments) with a Trusted
+    # Publisher configured on https://pypi.org for this repo and workflow, and
+    # ideally required reviewers, since a release here cannot be undone.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/portc/
+
+    permissions:
+      id-token: write  # for PyPI's trusted publishing (OIDC); no token is stored
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          # unpacks all CIBW artifacts into dist/
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1