pytycho 0.2.0__tar.gz

pytycho-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "beeson-group",
+  "owner": {
+    "name": "Beeson Group"
+  },
+  "metadata": {
+    "description": "Agent skills for the Beeson Group's astrodynamics tools"
+  },
+  "plugins": [
+    {
+      "name": "tycho",
+      "source": "./",
+      "description": "Write TyCHO scenes with pytycho and render them as one self-contained HTML page",
+      "version": "0.2.0",
+      "category": "visualization"
+    }
+  ]
+}

pytycho-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "tycho",
+  "version": "0.2.0",
+  "description": "Write TyCHO scenes with pytycho from NumPy arrays and render them as one self-contained HTML page",
+  "author": {
+    "name": "Claudio Vestini"
+  },
+  "homepage": "https://pytycho.readthedocs.io/",
+  "repository": "https://github.com/beeson-group/tycho",
+  "license": "Apache-2.0",
+  "keywords": ["astrodynamics", "visualization", "three-body", "pytycho"]
+}

pytycho-0.2.0/.github/check_versions.py

@@ -0,0 +1,46 @@
+"""Fails unless pytycho, the npm package, and the Claude Code plugin carry the same version.
+
+Given a tag such as ``v0.2.0``, it also fails unless the tag names this version and CHANGELOG.md has a
+section for it. A release thus cannot go out with mismatched versions or without its notes. The script
+uses only the standard library.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def versions() -> dict[str, str]:
+    init = (ROOT / "src" / "pytycho" / "__init__.py").read_text(encoding="utf-8")
+    match = re.search(r'^__version__ = "([^"]+)"', init, re.MULTILINE)
+    marketplace = json.loads((ROOT / ".claude-plugin" / "marketplace.json").read_text(encoding="utf-8"))
+    return {
+        "src/pytycho/__init__.py": match.group(1) if match else "<missing>",
+        "web/package.json": json.loads((ROOT / "web" / "package.json").read_text(encoding="utf-8"))["version"],
+        ".claude-plugin/plugin.json": json.loads((ROOT / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))["version"],
+        ".claude-plugin/marketplace.json": next(p["version"] for p in marketplace["plugins"] if p["name"] == "tycho"),
+    }
+
+
+def main(argv: list[str]) -> str | None:
+    found = versions()
+    if len(set(found.values())) != 1:
+        return "versions disagree: " + ", ".join(f"{path} {v}" for path, v in found.items())
+    version = next(iter(found.values()))
+    if argv:
+        tag = argv[0]
+        if tag != f"v{version}":
+            return f"tag {tag} does not name version {version}"
+        changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+        if f"## [{version}]" not in changelog:
+            return f"CHANGELOG.md does not have a section ## [{version}]"
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

pytycho-0.2.0/.github/dependabot.yml

@@ -0,0 +1,42 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns:
+          - "*"
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      pre-commit:
+        patterns:
+          - "*"
+  - package-ecosystem: "pip"
+    directory: "/docs"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      docs:
+        patterns:
+          - "*"
+  - package-ecosystem: "npm"
+    directory: "/web"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      npm:
+        patterns:
+          - "*"

pytycho-0.2.0/.github/release.yml

@@ -0,0 +1,5 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]
+      - pre-commit-ci[bot]

pytycho-0.2.0/.github/workflows/cd.yml

@@ -0,0 +1,152 @@
+name: CD
+
+# On a published release, this workflow uploads pytycho to PyPI and @beeson-group/tycho to npm, both through
+# trusted publishing with OpenID Connect, hence it does not store any token. The runtime is built once, thus
+# both packages carry the same bundle, and neither is published unless both build and pass their tests. A
+# manual run uploads pytycho to TestPyPI as a release candidate and does not publish to npm, which lacks a
+# test registry. Trusted publishing to npm needs an existing package, and @beeson-group/tycho exists there.
+
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false  # never cancel a publish halfway
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  runtime:
+    name: Build, test, and pack the runtime
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: The versions agree and match the tag on a release
+        env:
+          TAG: ${{ github.event_name == 'release' && github.ref_name || '' }}
+        run: python3 .github/check_versions.py ${TAG:+"$TAG"}
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          package-manager-cache: false  # a release workflow does not use a cache
+      - name: Test, then pack, which checks the notices and builds the bundles and the types
+        working-directory: web
+        run: npm ci && npm run typecheck && npm test && npm pack
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: npm-package
+          path: web/beeson-group-tycho-*.tgz
+          if-no-files-found: error
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: runtime
+          path: src/pytycho/_static/tycho.js
+          if-no-files-found: error
+
+  dist:
+    name: Build and check the distributions
+    needs: [runtime]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: runtime
+          path: src/pytycho/_static
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: false  # a release workflow does not use a cache
+      - run: uv run pytest
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - name: The wheel carries the runtime and the notices
+        run: |
+          unzip -l dist/*.whl | tee wheel.txt
+          for f in pytycho/_static/tycho.js licenses/LICENSE licenses/NOTICE licenses/THIRD_PARTY_NOTICES.md; do
+            grep -q "$f" wheel.txt || { echo "::error::the wheel has no $f"; exit 1; }
+          done
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Packages
+          path: dist/*
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' && github.event.action == 'published'
+    needs: [dist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pytycho
+    permissions:
+      id-token: write  # trusted publishing and the attestations need it
+      attestations: write  # actions/attest writes the attestations
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: Packages
+          path: dist
+      - name: Generate artifact attestations for the sdist and the wheel
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: "dist/*"
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: [dist]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pytycho
+    permissions:
+      id-token: write  # trusted publishing needs it
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: Packages
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-npm:
+    name: Publish to npm
+    if: github.event_name == 'release' && github.event.action == 'published'
+    needs: [runtime, dist]
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/@beeson-group/tycho
+    permissions:
+      contents: read
+      id-token: write  # trusted publishing and provenance need it
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: npm-package
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24  # trusted publishing needs npm 11.5.1 or later, and Node 24.21 bundles npm 11.19
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+      - run: npm publish ./beeson-group-tycho-*.tgz --access public

pytycho-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,159 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  lint:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uvx pre-commit run --all-files --show-diff-on-failure
+
+  tests:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.runs-on }}
+    runs-on: ${{ matrix.runs-on }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        runs-on: [ubuntu-latest]
+        include:
+          - python-version: "3.10"
+            runs-on: macos-latest
+          - python-version: "3.14"
+            runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run pytest --durations=10
+
+  lowest:
+    name: Python 3.10 at the lowest direct dependencies
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.10"
+      - run: uv run --resolution lowest-direct pytest
+
+  web:
+    name: Runtime
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - name: Pack, which checks the notices and builds the bundles and the types
+        run: npm pack
+      - run: npx --yes publint@0.3 --strict
+      - run: npx --yes @arethetypeswrong/cli@0.18 ./beeson-group-tycho-*.tgz --profile esm-only --exclude-entrypoints ./iife
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: runtime
+          path: src/pytycho/_static/tycho.js
+          if-no-files-found: error
+
+  dist:
+    name: Distributions
+    needs: [web]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: runtime
+          path: src/pytycho/_static
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: python3 .github/check_versions.py
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - name: The wheel carries the runtime and the notices, and the sdist does not carry example data
+        run: |
+          unzip -l dist/*.whl | tee wheel.txt
+          for f in pytycho/_static/tycho.js licenses/LICENSE licenses/NOTICE licenses/THIRD_PARTY_NOTICES.md; do
+            grep -q "$f" wheel.txt || { echo "::error::the wheel has no $f"; exit 1; }
+          done
+          if tar -tzf dist/*.tar.gz | grep -E '^[^/]+/examples/.*\.(csv|tys|tyd|html)$'; then
+            echo "::error::the sdist carries example data"; exit 1
+          fi
+      - name: The installed wheel writes a page that carries the runtime and its notices
+        run: |
+          uv venv /tmp/wheel-env
+          uv pip install --python /tmp/wheel-env/bin/python dist/*.whl
+          /tmp/wheel-env/bin/python - <<'EOF'
+          import numpy as np
+          import pytycho as ty
+
+          scene = ty.Scene(title="smoke")
+          frame = scene.frame("f", axes=("x", "y", "z"))
+          loop = scene.track_set("loop", frame=frame, periodic=True)
+          t = np.linspace(0.0, 2.0 * np.pi, 50)
+          loop.add(np.column_stack([np.cos(t), np.sin(t)]))
+          scene.clock(channels=["@index"], steps=50)
+          scene.view("main", frame=frame, driver=ty.driver(loop, 0), layers=[ty.track(loop)])
+          scene.panel("p", "main")
+          scene.write_html("smoke.html")
+          page = open("smoke.html", encoding="utf-8").read()
+          assert "This bundle contains" in page and "three 0." in page, "the page has no notice banner"
+          EOF
+
+  pass:
+    name: All checks pass
+    if: always()
+    needs: [lint, tests, lowest, web, dist]
+    runs-on: ubuntu-slim
+    timeout-minutes: 2
+    permissions: {}
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+        with:
+          jobs: ${{ toJSON(needs) }}

pytycho-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# build outputs
+web/node_modules/
+web/dist/
+src/pytycho/_static/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.nox/
+.mypy_cache/
+.ruff_cache/
+docs/_build/
+docs/_extra/
+
+# copied into web/ by its prepack script, from the repository root
+web/LICENSE
+web/NOTICE
+web/AUTHORS
+web/THIRD_PARTY_NOTICES.md
+web/*.tgz
+
+# example inputs computed with PyDyLAN, which are not distributed
+examples/**/data/
+
+# generated by examples
+examples/**/*.tyd
+examples/**/*.tys
+examples/**/*.html
+examples/**/*.png
+
+# local environment
+.venv/
+.DS_Store
+
+# editor-local language-server settings
+.zed/

pytycho-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,84 @@
+# The lint job of .github/workflows/ci.yml runs these hooks, and Dependabot updates each rev monthly.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v6.0.0"
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]  # the conformance corpus has cases of several hundred KB
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: name-tests-test
+        args: ["--pytest-test-first"]
+      - id: trailing-whitespace
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: "v1.10.0"
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.16.10"
+    hooks:
+      - id: ruff-check
+        args: ["--fix", "--show-fixes"]
+      - id: ruff-format
+
+  # pyright is used because src passes its standard mode as written, while mypy would need code changes
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: "v1.1.414"
+    hooks:
+      - id: pyright
+        files: ^(src|tests|examples)/
+        additional_dependencies: ["numpy", "pytest", "jsonschema"]
+
+  # prettier runs in check mode, since the TypeScript follows web/.prettierrc.json and is reformatted by hand
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.9.9"
+    hooks:
+      - id: prettier
+        entry: prettier --check --ignore-unknown
+        files: ^web/(src|test|scripts)/
+        types_or: [ts, javascript]
+        exclude: ^web/src/scene\.gen\.ts$  # web/scripts/gen-types.mjs writes it, and a test compares it verbatim
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: "v2.4.3"
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli; python_version<'3.11'
+
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|PyDylan|Pydylan|PyTycho
+        exclude: ^\.pre-commit-config\.yaml$
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "0.26"
+    hooks:
+      - id: validate-pyproject
+        additional_dependencies: ["validate-pyproject-schema-store[all]"]
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: "0.38.2"
+    hooks:
+      - id: check-dependabot
+      - id: check-github-workflows
+      - id: check-readthedocs
+
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: "v1.30.1"
+    hooks:
+      - id: zizmor

pytycho-0.2.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs serves the site at https://pytycho.readthedocs.io/. It builds the latest version on each push to
+# main, the stable version from the highest release tag, and a preview for each pull request, linked from its checks.
+# docs/conf.py puts src/ on the path, hence the build installs only the docs toolchain and NumPy, not the package.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

pytycho-0.2.0/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+TyCHO has two halves, which are released together at one version. pytycho (Python) writes a scene, i.e. the scene document `scene.tys` (JSON that specifies what to draw) and the data container `data.tyd` (the arrays), from NumPy arrays. It then inlines the browser runtime (TypeScript, `@beeson-group/tycho`) into one HTML page, which draws the scene.
+
+## Layout
+
+- `src/pytycho/` holds the `Scene` builder (`scene.py`), the data container (`container.py`), the evaluator (`_evaluate.py`, which computes what each panel draws at a frame index), thinning (`_thin.py`, which keeps a subset of the stored samples), and the page writer (`html.py`, `template.html`). Its `_static/tycho.js` is the built runtime, which is gitignored and shipped in the wheel, hence it has to be built in a fresh checkout before pytycho can write a page.
+- `web/src/` holds the runtime, i.e. the container and scene readers, the evaluator (`evaluate/`), and the `<tycho-viewer>` element with its renderer (`runtime/`). The file `scene.gen.ts` is generated from the schema by `npm run gen:types`. Never edit it by hand, since a test fails when it differs from the types generated from the schema.
+- `spec/` holds the format rules, the JSON Schema, and the conformance corpus, i.e. scenes with the answers that both evaluators must give.
+- `tests/` holds the pytest suite, and `web/test/` holds the vitest suite of the runtime.
+- `examples/` holds the Broucke example, which builds its page from `broucke-input.tyd`, a file attached to each GitHub Release. The input and the outputs are gitignored.
+- `docs/` holds the Sphinx site. `skills/tycho/` holds the agent skill for people who use pytycho, and `.claude-plugin/` holds its plugin manifests, which make the repository a Claude Code plugin marketplace.
+
+## Commands
+
+```sh
+npm --prefix web ci && npm --prefix web run build   # the runtime, into web/dist and src/pytycho/_static
+npm --prefix web test && npm --prefix web run typecheck
+uv run pytest
+uvx pre-commit run --all-files                      # ruff, pyright, prettier --check, codespell, schema checks
+uvx nox -s docs                                     # the site, into docs/_build/html
+uvx nox -s build                                    # the sdist and the wheel, into dist/
+python3 .github/check_versions.py                   # the four version fields agree
+```
+
+## Conventions
+
+- Python lines run to 140 columns and are formatted by ruff. TypeScript lines run to 160 columns, use single quotes, and are checked by prettier, which only reports a misformatted file. Run `npx prettier --write <file>` from `web/` to apply the change.
+- Where the Python and the TypeScript evaluators disagree, the answer in the corpus in `spec/` holds. Reword the rule to match it, add a case when the corpus does not cover the disagreement, and then fix both implementations.
+- A version bump touches `src/pytycho/__init__.py`, `web/package.json`, and the two files in `.claude-plugin/` together, and `python3 .github/check_versions.py` fails while the four disagree.
+- Every user-visible change gets a line under `## [Unreleased]` in `CHANGELOG.md`, since this section becomes the notes of the next release.

pytycho-0.2.0/AUTHORS

@@ -0,0 +1,7 @@
+# The TyCHO Authors
+
+The people who hold copyright in TyCHO, which the file NOTICE names together as "The TyCHO Authors".
+
+- Claudio Vestini, Beeson Group, Princeton University
+- Nina Karampela, Beeson Group, Princeton University
+- Jack Sydney Schwartz, Beeson Group, Princeton University

pytycho-0.2.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to TyCHO are recorded here, for both packages, `pytycho` on PyPI and `@beeson-group/tycho` on npm, which are released together at one version. The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and the versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0, a breaking change, i.e. one after which existing code or files may stop working, bumps the minor version, and a fix bumps the patch version.
+
+The two file formats are versioned apart from the packages, i.e. either format version may stay the same across a package release. The notes of each release therefore give the versions of the scene document `scene.tys` and the data container `data.tyd` that the packages read and write.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-06
+
+Version 0.2.0 introduces the scene grammar, i.e. a general vocabulary from which a visualization is declared. The packages at this version write and read scene format 0.2, which may still change incompatibly until 1.0, and data container version 1.
+
+### Added
+
+- TyCHO describes each scene in a scene grammar. A scene is two files, which a Python script writes from NumPy arrays and the browser interprets. The grammar covers track sets (collections of trajectories) with per-sample channels (numbers stored at every sample, such as the time), bodies (named points), a tree of reference frames, variables, one clock, views with layers, panels, controls, and readouts. The rules of the grammar are numbered in `spec/tycho-scene.md`, and `spec/scene.schema.json` gives its structure. The conformance corpus in `spec/conformance/` holds scenes with the answers an evaluator must give, and both the Python and the TypeScript evaluators pass it.
+- Two files store a scene. The scene document `scene.tys` is JSON that refers to the arrays by name and specifies what they are. The data container `data.tyd` holds a `TYCD` magic number, a JSON header, and named little-endian typed arrays. Each array is stored raw or, when this is smaller, compressed without loss in chunks of about 1 MiB. The compression takes the bit pattern of each number, replaces each row by its difference from the row before (delta coding), groups the bytes by their position within each number (byte shuffling), and deflates the result. A browser inflates, i.e. decompresses, these chunks with its native `DecompressionStream`, and a reader can decode one chunk at a time. The input of the Broucke example takes 60 percent of its raw size, and its page takes 12.7 MB, against 22.1 MB with the whole container gzipped.
+- pytycho provides the `Scene` builder, thinning, and `evaluate`. The builder checks every call, then checks the whole scene for every value its variables can take, and reports each failure with the number of the rule it breaks. Thinning keeps a subset of the stored samples, selected by arclength, measured in the frames listed in the call, by default the frame of the set. The function `evaluate` returns what the browser draws for a frame index, so that a test can check what a scene draws without a browser.
+- The runtime provides the `<tycho-viewer>` element, which draws any scene in panels that can be rearranged by drag and drop. Each panel keeps separate values of the panel-scoped variables, e.g. the frame that it shows. The element draws sliders, tabs, toggles, a transport (the controls that play and pause the clock and switch its active channel), and readouts.
+- Playback runs at the refresh rate of the display. Every refresh draws at the progress given by the wall time, i.e. the real time elapsed, and this progress may lie between two frame indices. The layers under the first layer that takes a clock reading do not move with the animation. They are drawn once per panel, until the camera or these layers change, and copied back every frame. Body trails are read from positions kept per lap, so that a frame copies a trail instead of computing it. The frame rate shown counts the frames drawn in the last second. The script `web/scripts/frame-profile.mjs` measures what a frame of an example page costs, in headless Chrome.
+- The viewer exports an MP4 video of its current state, from its controls or through `exportVideo`. The video is encoded in the browser itself, with the WebCodecs API and the mp4-muxer library.
+- The npm package ships type declarations, which let TypeScript check code that uses the package.
+- A track set stores its positions and channels as float32 by default. pytycho now stores a clock channel as float64 in a float32 set when float32 would round the ends of a step between samples by more than 1% of the step, or would make the channel nonmonotone. A nonmonotone channel would break rule T3, under which a clock channel increases or decreases strictly along every track. The argument `track_set(channel_dtypes=)` sets the stored dtype of a channel by hand.
+- `build_html` embeds the container as base64 text without further compression, since its arrays are already compressed. It rejects a scene or data whose base64 is longer than 536,870,888 characters, the most that Chrome holds in one string, since a longer text would leave the page empty.
+- Both container readers reject a view key or an encoding they do not know (rule D2), since a reader that ignored either could read the bytes wrongly. Section 1 of the spec specifies which changes bump the container version (rule D3). `Container.parse` in the runtime and the `load` method of the element return promises, since they inflate the encoded views, which the browser does asynchronously.
+- The Broucke example reads its trajectories from `broucke-input.tyd`, a data container attached to each GitHub Release. It imports only NumPy, pytycho, and the standard library, hence it runs without PyDyLAN.
+- An agent skill, `skills/tycho/SKILL.md`, sets out the scene grammar for a coding agent. It can be installed as a Claude Code plugin from this repository or with `npx skills add beeson-group/tycho`.
+- The npm package bundles three.js and mp4-muxer, and it does not have any runtime dependencies, hence installing it does not install any other package.
+- Both packages declare the license `Apache-2.0 AND MIT`, since the bundle carries MIT-licensed code, and they ship `NOTICE` and `THIRD_PARTY_NOTICES.md`. Every bundle starts with a comment listing the bundled packages. Every page that pytycho writes inlines the bundle, and thus carries the same comment.
+
+[Unreleased]: https://github.com/beeson-group/tycho/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/beeson-group/tycho/releases/tag/v0.2.0