fatqat 0.1.0a1__tar.gz

fatqat-0.1.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## Description
+
+<!-- Explain what changed, why this approach was chosen, and any architectural or public API impact. -->
+
+## Related issues or PRs
+
+<!-- Link related items. Use "Fixes #1184" when the PR should close an issue. -->
+
+## AI Tools Usage Disclosure
+
+**AI tools used:** `None`
+
+<!--
+If AI tools were used, replace "None" with:
+- Tool/model: how it was used
+e.g. generating code, summarizing changes, adding examples, adding tests, refining language
+-->
+
+## Checklist
+
+<!-- Make the following checks before ticking them. -->
+- [ ] I have investigated the relevant code and confirmed that the chosen design fits the existing architecture and reuses existing functionality where possible.
+- [ ] I have added or updated tests where appropriate and run the relevant checks. I avoided duplicate coverage and unnecessary overtesting.
+- [ ] I have updated the relevant documentation, or confirmed that no changes are needed. The documentation is clear, concise, and avoids repetitive or mechanical wording.
+- [ ] I have run Black (`python -m black --check --diff src tests conftest.py`) and Pylint (`python -m pylint src/fatqat tests conftest.py`).
+<!-- This box must be completed manually by the human contributor, not by an AI agent. -->
+- [ ] I have reviewed and understand the entire change and can explain its design and architectural fit.
+
+<!-- If the contribution is not ready for review, open it as a draft and leave unfinished items unchecked. -->

fatqat-0.1.0a1/.github/workflows/build.yaml

@@ -0,0 +1,70 @@
+name: Build and optionally publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm_ref:
+        description: Type the selected branch or tag name to publish (leave blank to build only)
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build and check distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+
+      - name: Verify publishing request
+        if: inputs.confirm_ref != ''
+        env:
+          CONFIRM_REF: ${{ inputs.confirm_ref }}
+          RELEASE_REF: ${{ github.ref_name }}
+          REF_TYPE: ${{ github.ref_type }}
+        run: |
+          python -m pip install --no-deps dist/*.whl
+          python - <<'PY'
+          import os
+          from importlib.metadata import version
+          from packaging.version import Version
+
+          if os.environ["CONFIRM_REF"] != os.environ["RELEASE_REF"]:
+              raise SystemExit("Confirmation must exactly match the selected branch or tag.")
+
+          release = Version(version("fatqat"))
+          if release.is_devrelease or release.local is not None:
+              raise SystemExit("Development and local versions cannot be published to PyPI.")
+          if os.environ["REF_TYPE"] == "tag" and os.environ["RELEASE_REF"] != f"v{release}":
+              raise SystemExit("Tag and package version differ.")
+          PY
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    if: inputs.confirm_ref != '' && github.repository == 'spaceqat/fatqat'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

fatqat-0.1.0a1/.github/workflows/lint.yml

@@ -0,0 +1,43 @@
+name: Lint
+
+on:
+  push:
+    branches: [main, "v*"]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, "v*"]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Verify generated documentation is not tracked
+        run: |
+          tracked_generated="$(git ls-files -- \
+            ':(glob)docs/mkdocs/*/assets/generated/**' \
+            ':(glob)docs/mkdocs/*/downloads/tutorials/**' \
+            ':(glob)docs/mkdocs/*/tutorials/**' \
+            docs/mkdocs/tutorial-results)"
+          if [ -n "$tracked_generated" ]; then
+            printf 'Generated documentation files must not be tracked:\n%s\n' "$tracked_generated"
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . --group dev --group lint --group qiskit
+
+      - name: Check formatting (black)
+        run: python -m black --check --diff src tests conftest.py
+
+      - name: Static analysis (pylint)
+        run: python -m pylint src/fatqat tests conftest.py

fatqat-0.1.0a1/.github/workflows/tests.yml

@@ -0,0 +1,52 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, "v*"]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, "v*"]
+
+jobs:
+  test:
+    name: ${{ matrix.check_name }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - check_name: Tests (Ubuntu)
+            os: ubuntu-latest
+            python-version: "3.12"
+            dependency_group: test-full
+            run_doctests: true
+          - check_name: Tests (Windows)
+            os: windows-latest
+            python-version: "3.13"
+            dependency_group: dev
+            run_doctests: false
+          - check_name: Tests (macOS)
+            os: macos-latest
+            python-version: "3.14"
+            dependency_group: dev
+            run_doctests: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . --group ${{ matrix.dependency_group }}
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Run doctests
+        if: matrix.run_doctests
+        run: python -m pytest -p scipy_doctest --doctest-modules --pyargs fatqat

fatqat-0.1.0a1/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.venv-mkdocs/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/
+# Material for MkDocs build output.
+docs/mkdocs/site/
+docs/mkdocs/*/assets/generated/
+docs/mkdocs/*/downloads/tutorials/
+docs/mkdocs/*/tutorials/
+docs/mkdocs/tutorial-results/
+
+# Superpowers working artifacts (specs, plans, reviews) — not part of the code
+docs/superpowers/
+.claude/
+.superpowers/
+
+# Design docs — nested git repo with its own history, versioned separately
+docs/design/
+
+# Local git worktrees used for isolated subagent-driven development
+.worktrees/
+benchmarks/
+
+# uv is optional, per-user tooling; a local lockfile is a user artifact
+uv.lock

fatqat-0.1.0a1/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/mkdocs/requirements.txt
+    - method: pip
+      path: .

fatqat-0.1.0a1/AGENTS.md

@@ -0,0 +1,31 @@
+# AI-assisted implementation guide
+
+This file contains repository-specific instructions for coding agents. Read
+and follow [CONTRIBUTING.md](CONTRIBUTING.md); it is authoritative for
+architecture, tests, documentation, validation, AI disclosure, authorship, and
+project communication.
+
+- Before changing code, inspect the relevant implementation, tests, public
+  documentation, and nearby repository conventions. Treat examples and
+  existing implementations as guidance, not templates to copy mechanically.
+- Keep changes within the requested scope. Do not add unrelated refactors,
+  dependency changes, cleanup, or repository-wide formatting.
+- Prefer the smallest readable, backward-compatible change. Preserve public
+  behavior unless the task explicitly changes it, and do not expand the public
+  API without prior discussion. Breaking changes require prior discussion and
+  should normally follow a documented deprecation path. Add complexity for
+  performance only when benchmarks justify it.
+- Reuse established abstractions. Private implementation details may change
+  when public behavior and architectural boundaries remain intact.
+- Make reasonable private implementation choices and state material
+  assumptions, but do not turn an inference or assumption into a public
+  contract without explicit direction. Stop when requirements conflict or a
+  decision would create a broad, difficult-to-reverse public API or
+  architectural commitment.
+- Do not weaken, skip, or remove tests, lint rules, warnings, error handling,
+  or validation merely to make a change pass.
+- If blocked, report the exact cause, the smallest safe alternative, and any
+  public API or behavior impact.
+- Do not complete the human-only confirmation in
+  `.github/PULL_REQUEST_TEMPLATE.md`, or perform public GitHub communication
+  on the contributor's behalf.

fatqat-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0a1
+
+First alpha release of FatQat, a quantum-computing toolkit built around
+the `Program` authoring interface.
+
+- Author gates, measurements, reset, classical conditions, parameterized
+  programs, logical qudits, and direct physical controls.
+- Run general simulations, hardware-profile simulations, and Hamiltonian
+  emulations through a shared `Job`/`Result` workflow.
+- Explore noise, parameter sweeps, states, samples, and observables.
+- Compile supported logical programs for hardware targets, including
+  neutral-atom placement and routing.
+- Work with OpenQASM and optional Qiskit integration, draw programs, and
+  follow executable algorithm and physics tutorials.
+
+Requires Python 3.12 or newer. This is an alpha release: interfaces may change
+between releases. Pin the exact package version for reproducible studies.

fatqat-0.1.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# 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, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

fatqat-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,198 @@
+# Contributing to fatqat
+
+Contributions to fatqat are welcome. Development setup and test commands are
+documented in the [README](README.md#development). Contributors should discuss
+substantial features or architectural changes with the maintainers before
+investing in a large implementation.
+
+## AI tools usage policy
+
+fatqat welcomes the use of AI tools to improve efficiency and the quality of
+work. Contributors may use these tools provided that the following guidelines
+are followed. The policy applies to code, tests, documentation, issues, pull
+requests, reviews, discussions, and comments.
+
+AI tools may help a contributor:
+
+- explore the codebase and understand how components interact;
+- brainstorm approaches and compare design options;
+- draft code, tests, or documentation;
+- review an implementation for possible bugs or improvements.
+
+However, the contributor must independently validate architectural decisions,
+review all generated output and test applicable changes.
+
+### 1. Accountability
+
+By submitting a change, the human contributor accepts responsibility for its quality,
+including any AI-generated material it contains.
+
+The contributor must:
+
+- ensure the contribution meets the project's quality and testing standards;
+- understand how the change works and enough of the related existing code to
+  trace how the change interacts with the rest of the package;
+- explain why the approach was chosen, including relevant alternatives and trade-offs;
+- explain how the behavior was verified and respond substantively to questions
+  during review.
+
+This does not require memorizing every line or knowing the internals of every
+dependency. It requires enough command of the contribution to locate and
+explain the relevant behavior, reason about its consequences, and debug or
+maintain it after merge. A change the contributor cannot explain and maintain is not ready for
+review.
+
+### 2. Transparency
+
+The `AI Tools Usage Disclosure` field in the pull-request template is mandatory.
+If no AI tool was used, the contributor must state so clearly.
+If AI tools were used, the disclosure must name the tools and briefly
+explain how they were used.
+
+### 3. Authorship and legal responsibility
+
+The contributor must have the right to submit every part of the contribution
+and must respect third-party licenses and the terms of the AI tool.
+The contributor must check AI-generated material for copied or derived
+third-party content and must not submit material under incompatible licensing
+terms.
+
+An AI system, model, or agent must not sign commits or be listed as an author or
+co-author. This includes `Author` and `Co-authored-by`, and `Signed-off-by`
+metadata. Any such entries must be removed from the proposed commits before submission.
+
+### 4. GitHub communication and prohibited uses
+
+Project communication is expected to be directly with the contributor, not an
+agent. Translation and grammar assistance are welcome, but issues, pull-request
+descriptions, and review replies must express the contributor's own understanding and judgment.
+
+AI-assisted descriptions and summaries are permitted, but should be reviewed for
+clarity, relevance, and concision. Avoid lengthy or generic content that adds little
+useful information or obscures the contributor's own explanation and reasoning.
+Lengthy file-by-file summaries, generic background, and repetition
+can obscure information needed for review and may be returned for rewriting.
+
+Autonomous or unattended agents must not drive the communication on GitHub.
+The contributor must personally direct every public interaction.
+Repository-owned maintenance bots and other
+automation explicitly approved by the maintainers are exempt.
+
+### 5. Enforcement
+
+Maintainers may ask the contributor to explain a change, rewrite a description,
+provide verification, or reduce the scope. Maintainers may decline or close a
+contribution if the contributor cannot demonstrate understanding and ownership,
+violates this policy, or if the effort required to review the contribution would
+outweigh its likely benefit to the project.
+
+## Code changes and validation
+
+Install fatqat in editable mode with the full test and lint environment:
+
+```sh
+python -m pip install --upgrade pip
+python -m pip install --editable . --group test-full --group lint
+```
+
+The `test-full` group includes the core `dev` tests and optional integration
+dependencies. Use `dev` alone only for lightweight local work that does not need
+those integrations.
+
+Run the narrowest relevant tests while developing a change. Before requesting
+review, run the full test and lint checks:
+
+```sh
+python -m pytest
+python -m black --check --diff src tests conftest.py
+python -m pylint src/fatqat tests conftest.py
+```
+
+New behavior and bug fixes should have focused tests. Test observable behavior,
+public contracts, and meaningful failure cases rather than private helpers,
+internal call sequences, or data layouts. Before adding a test, check whether
+an existing test already protects the behavior; extend or parameterize it when
+that remains clear, and avoid duplicate cases that would fail for the same
+regression. Seed stochastic tests and use appropriate numerical tolerances.
+
+## Documentation
+
+Documentation is part of fatqat's public interface. A contribution that changes
+public behavior, configuration, defaults, return values, result fields, or
+errors must update the corresponding documentation in the same pull request.
+
+### Put information in the right place
+
+- User guides in `docs/mkdocs/en/guide/` provide pedagogical explanations of
+  concepts and workflows. They should develop topics progressively and give
+  readers the context needed to understand how the pieces fit together.
+- API pages in `docs/mkdocs/en/api/`, together with public docstrings, define the
+  complete public contract. Docstrings should provide concise reference
+  material that remains useful through Python `help()`.
+- Tutorials in `docs/mkdocs/tutorial-sources/en/` present substantial executable
+  workflows or studies. Their Markdown sources are canonical; pages, figures,
+  scripts, and notebooks are generated.
+
+A public class with substantial behavior or configuration should have its own
+API page. Begin with why and when a user would choose it, then explain its
+behavior, constraints, and configuration, include a minimal example, and finish
+with the generated API reference. Explain shared behavior once and link to it
+from the relevant pages.
+
+### Contributing tutorials
+
+Tutorial contributors should follow the
+[executable tutorial instructions](docs/mkdocs/README.md#add-executable-tutorials).
+They cover the canonical Markdown source, required metadata and accessible
+figures, learning and reproducibility expectations, executable cells, optional
+Jupytext conversion, and generated outputs.
+
+### Writing style and API documentation
+
+Write for someone trying to use the feature, not someone tracing its
+implementation. Lead with what the API enables, how to use it, and what behavior
+to expect. Use direct, concrete language and active voice, and keep terminology
+consistent across code, guides, and API pages. Internal planning, caching, and
+execution details belong in user documentation only when they affect public
+behavior or define an extension contract.
+
+If AI tools assist with documentation, revise the result to match the project's
+established style. Let the subject and the user's needs determine the depth and
+structure; do not force every page or section into the same pattern or level of
+detail. Cut generic or repeated framing, stock phrasing, mechanical transitions,
+and tables or checklists that do not make the material easier to understand or
+navigate.
+
+A public docstring is a concise reference that must also read well through
+Python `help()`. Begin with a one-sentence summary, then add a short behavioral
+description when it is useful. Use `Args`, `Returns`, and `Raises` as applicable,
+and include `Examples` only when an example materially clarifies the API. List
+arguments in signature order, and prefer simple labels and lists to tables,
+Sphinx directives, or underlined section headings.
+
+Options need enough information for a user to choose and combine them correctly.
+State each option's accepted values and default, explain its user-visible effect
+and when it applies or has no effect, and identify incompatible combinations and
+relevant errors. If the accepted values form a small finite set, list every value
+explicitly. For a dictionary argument, document each public key separately with
+its name, accepted type, default, user-visible effect, and important compatibility
+constraints. For example:
+
+```text
+simulation_config: Optional execution controls. Accepted keys are:
+
+    - "seed" (int | None, default None): Random seed.
+    - "mode" (str, "auto" | "thread", default "auto"): Execution mode.
+```
+
+Where relevant, also explain object lifetime and ownership, reuse guarantees,
+and support for concurrent calls. Examples should be minimal, executable, and
+focused on one behavior. Use the repository's normal import style, and seed
+stochastic examples when showing exact output.
+
+### Validate documentation changes
+
+Before submitting documentation changes, follow the
+[documentation build and validation instructions](docs/mkdocs/README.md#validate-before-submission).
+They cover the pinned environment, warnings-as-errors build, rendered output,
+public docstrings, verification against the implementation, and diff checks.