Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 67 additions & 11 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
name: Publish to PyPI

on:
push:
branches: [master]
release:
types: [published]

permissions:
contents: read

concurrency:
group: pypi-${{ github.event.release.tag_name }}
cancel-in-progress: false

jobs:
validate-release:
name: Check release version
Expand All @@ -19,44 +17,72 @@ jobs:
timeout-minutes: 5
outputs:
source_sha: ${{ steps.package.outputs.source_sha }}
version: ${{ steps.package.outputs.version }}
publish: ${{ steps.package.outputs.publish }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.release.tag_name }}
ref: ${{ github.event_name == 'release' && format('refs/tags/{0}', github.event.release.tag_name) || github.sha }}
persist-credentials: false
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Require a tag matching the package version
- name: Validate the package version and check PyPI
id: package
env:
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
python - <<'PY'
python - <<'PY' >> "$GITHUB_OUTPUT"
import json
import os
import tomllib
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import urlopen

project = tomllib.loads(Path("pyproject.toml").read_text())["project"]
expected = f"v{project['version']}"
if project["name"] != "particlegan":
raise SystemExit("Expected the particlegan package")
version = project["version"]
expected = f"v{version}"
tag = os.environ["RELEASE_TAG"]
if project["name"] != "particlegan" or tag != expected:
event = os.environ["GITHUB_EVENT_NAME"]
if event == "release" and tag != expected:
raise SystemExit(f"Expected particlegan release {expected}, got {tag!r}")
print(f"Validated {project['name']} {project['version']}")
publish = True
if event == "push":
try:
with urlopen(f"https://pypi.org/pypi/particlegan/{quote(version, safe='')}/json", timeout=15) as response:
published = json.load(response)
except HTTPError as error:
if error.code != 404:
raise
else:
if published["info"]["name"].lower() != "particlegan":
raise SystemExit("PyPI returned a different project")
publish = not published["urls"]
print(f"version={version}")
print(f"publish={str(publish).lower()}")
PY
echo "source_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

checks:
name: Test and build release
needs: validate-release
if: needs.validate-release.outputs.publish == 'true'
uses: ./.github/workflows/tests.yml
with:
source_ref: ${{ needs.validate-release.outputs.source_sha }}

publish:
name: Publish tested distributions
needs: checks
needs: [validate-release, checks]
runs-on: ubuntu-latest
timeout-minutes: 10
concurrency:
group: pypi-${{ needs.validate-release.outputs.version }}
cancel-in-progress: false
environment:
name: pypi
url: https://pypi.org/project/particlegan/
Expand All @@ -69,3 +95,33 @@ jobs:
path: dist/
- name: Publish to PyPI with Trusted Publishing
uses: pypa/gh-action-pypi-publish@release/v1
with:
skip-existing: true

github-release:
name: Publish tested source to GitHub
if: github.repository == 'HyperGAN/ParticleGAN' && github.event_name == 'push' && github.ref == 'refs/heads/master'
needs: [validate-release, publish]
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
concurrency:
group: github-release-${{ needs.validate-release.outputs.version }}
cancel-in-progress: false
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: python-package-distributions
path: dist/
- name: Verify PyPI and publish the source release
env:
GH_TOKEN: ${{ github.token }}
run: python scripts/publish_github_source.py publish
7 changes: 4 additions & 3 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,10 @@ jobs:
assert MoGParticlePrior(sigma=0.1).sample(2)[0].shape == (2, 4)
assert DDGAN().steps == 4
default = get_recipe()
assert DEFAULT_RECIPE == "empf"
assert default.optimizer_dense_profile == "newton_schulz_hybrid_v1"
assert default.optimizer_svd_backend == "batched"
assert DEFAULT_RECIPE == "unified_v11"
assert default.optimizer_family == "unified_v11_equil"
assert default.critic_formulation == "unified_v11"
assert default.prior_regularizer == "unified_v11"
assert default.training_precision == "bf16_channels_last"
assert default == get_recipe(DEFAULT_RECIPE)
assert Recipe(**get_recipe_fields()) == default
Expand Down
Binary file modified 100gaussians.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
48 changes: 48 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,53 @@
# Changelog

## 0.11.0 — 2026-11-20

- **Default Unified 4-Law research selection (`DEFAULT_RECIPE = "unified_v11"`).**
Promote `unified_v11` (matching [`unified-v11`](configs/forge/ideas/unified-v11.json),
[`particlegan/unified_v11.py`](particlegan/unified_v11.py)) as the public default
trainer preset while preserving explicit `get_recipe("minimal")`, `get_recipe("empf")`
(`empf-v8`), `get_recipe("rhbi_optimized")` (`rhbi-v12`), `get_recipe("rhbi")`
(`rhbi-v1`), `get_recipe("bispf_optimized")`, and `Recipe.from_dict(saved_fields)`
historical restoration (`particlegan/recipe_compat.py` untouched). `unified_v11`
runs with strictly **`0` `torch.autograd.grad`, `0` `svd`/`svdvals`, `0` `eigh`/`eigvalsh`,
and `0` `pinv`** across every forward, backward, penalty, transport, conditional fiber
bank, prior, and optimizer path, uniting all four GAN laws with fused `Z=[X,Y]` Quintic
Tikhonov polar equilibration, zero-`autograd.grad`/zero-`pinv` analytic `direction_blend`,
zero-`eigh` cyclic-Jacobi cross-batch conditional fiber operator matching, and
scale-invariant `k=4` density-ratio orphan macro-transport. Across `9` concluded Forge
studies on `NVIDIA RTX A6000` (seed `0`, see
[`reports/forge/studies/r4-solution-complete.md`](reports/forge/studies/r4-solution-complete.md)
and the [technique inventory](reports/forge/technique-inventory.md)), `unified-v11`
leads the canonical leaderboard at **`95/115` counted view requirements** (`27/27`
Tier 1, `68/78` Tier 2), **`40/69` full-suite passes** (`6` FAIL, `11` not measured,
`12` blocked), **`50/68` stretch view assignments**, and **`41/47` Tiers 1–2
`discriminator_stability` PASS** (`55/62` deduplicated unique runnable tasks PASS;
`90.24 ms/step` median and `1,372.60 MiB` allocated VRAM on matched 66-cell
`dcgan_performance_r256`, `89.19 ms/step` in `readout-1e5fb235`), including `11/11`
required Tier 1, `3/3` precision (`fp32`/`mxfp8`/`nvfp4`),
`model_ddgan_gaussian_chain`, `3/3` extreme Nash imbalance, `2/2` causal isolation, `5/5`
shift/rail recovery, `3/3` `7.5k` ring endurance, `6/7` 16-layer strange architectures,
`15/17` Tier-3 `14k` holdout (`grid100_14k` and `rotated100_14k`), and `3/4` runnable
Tier-4 tasks — ahead of `empf-v8` (`83/115`, `23/69`, `129.72 ms/step`) and `rhbi-v12`
(`83/115`, `33/69`, `590.59 ms/step`). Forge screening calibration remains provisional
(`BLOCKED` under
`criteria-v1.json`; see [`reports/forge/studies/r3-calibration-holdout.md`](reports/forge/studies/r3-calibration-holdout.md)),
and remaining failures (`staggered100` / `staggered100_14k`, `grid100_res16_tanh`,
`five_word_joint_hold`, `model_ddgan_bimodal_chain`, `model_ae_ddgan_gaussian_chain`,
`interp_img_patch_shift`, `interp_saddle_barycentric`, plus `12` unimplemented Tier-4
stretch hosts) stay explicitly disclosed.
- **Minimal-Principle `<900`-LOC fast core (`preset="minimal"`, `particlegan/minimal.py`).**
Add the self-contained `899`-LOC, zero-sibling-import core (`minimal-v2`) with zero
`autograd.grad`, zero SVD/`eigh`/`pinv`, and zero Newton-Schulz (`55.50 ms/step` and
`1344.84 MiB` peak allocated VRAM on `dcgan_performance_r256`, `6/6` PASS; see
[`reports/forge/studies/r4-minimal-core.md`](reports/forge/studies/r4-minimal-core.md)).
- **The Four Laws of Stable, Energy-Efficient GAN Convergence ([`docs/four-laws.md`](docs/four-laws.md)) & Occam's Razor causal ablation (Rounds 1–4).**
Document the four laws proved across Rounds 1–4 — Law 1 (Measure & Prior Topology: `t1_prior`, `t1_coupling`), Law 2 (First-Order Zero-`autograd.grad` Critic Geometry: `t2_secant`), Law 3 (Scale–Mass–Fiber Gauge Identifiability: `rgdt`, `cond_fiber`), and Law 4 (Function-Space Two-Player Equilibration & Depth/Rail Trust: `t4_nash`, `t4_nash_v3`, `t4_arch`) — together with unified synthesis (`unified_v4`..`unified_v11`), bounded Tier-3/Tier-4 calibration holdout audits (`r3-calibration-holdout`), and Round-4 Track 2's 8-arm Occam's Razor causal knockout study (`r4-occam-ablation-razor`, showing the four laws collapse into Two Mathematical Halves with depth-gated 2D Newton-Schulz strictly on `L > 5` skip-free MLPs while identifying redundant epicycles).
- **Automated release pipeline from `master`.**
Publish new versions automatically to PyPI via Trusted Publishing on `master` merges and
publish a verified GitHub source release at the tested commit after PyPI succeeds
(`.github/workflows/release.yml`, `scripts/publish_github_source.py`).

## 0.10.1 — 2026-11-16

- **Default EMPF research selection (`DEFAULT_RECIPE = "empf"`).**
Expand Down
65 changes: 40 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ critic penalty and prior regularizer.
Requires Python 3.11+. PyTorch and NumPy are installed as dependencies.

```bash
python -m pip install particlegan # the library (0.10.1)
python -m pip install particlegan # the library (0.11.0)
```

To run the examples, experiments and tests, install from source with the extras you need:
Expand Down Expand Up @@ -67,17 +67,22 @@ for _ in range(recipe.total_steps):
samples = trainer.sample(1024)
```

`get_recipe()` returns the default recipe, **EMPF** (*Exponential Moving Prototype
Flow*, `DEFAULT_RECIPE = "empf"` in [particlegan/recipes.py](particlegan/recipes.py)).
It uses a clock-free online *e-means* sufficient-statistics prototype bank,
mass-weighted prototype-to-fake Sinkhorn OT, a state-driven settling Born-Infeld
critic penalty (`EMPFCriticPenalty`, `ebi_beta = 6.0`), a DoF-aware EMPF prior
regularizer (`prior_reg = 0.01`), and zero-momentum DualNorm
(`newton_schulz_hybrid_v1`, `batched` SVD, `bf16_channels_last`) at constant rates.
Explicit `get_recipe("rhbi_optimized")`, `get_recipe("rhbi")` and
`get_recipe("bispf_optimized")` retain named presets. The acronyms are expanded in the
[research glossary](RESEARCH_GLOSSARY.md#acronyms-and-short-names), and the
[recipe settings and evidence](docs/api.md#recipes-and-defaults) explain the configuration.
`get_recipe()` returns the default recipe, **Unified** (`DEFAULT_RECIPE = "unified_v11"` in
[particlegan/recipes.py](particlegan/recipes.py), matching `unified-v11`).
It unites all four GAN laws with strictly **zero `torch.autograd.grad`, zero SVD, zero `eigh`,
and zero `pinv`**: Law 1 streaming Laguerre-Pythagorean prototype prior & orthogonal pullback
isometry (`prior_reg = 0.02`), Law 2 first-order Born-Infeld secant critic with zero-mean
logit gauge (`ebi_beta = 12.0`), Law 3 scale-invariant `k=4` density-ratio orphan
macro-transport & zero-`eigh` cross-batch conditional fiber operator bank, and Law 4 fused
`Z=[X,Y]` Quintic Tikhonov polar equilibration with zero-`pinv` analytic `direction_blend`
and `bf16_channels_last` conv training at constant rates.
Explicit `get_recipe("minimal")` (`<900`-LOC zero-Newton-Schulz fast core),
`get_recipe("empf")` (`empf-v8`), `get_recipe("rhbi_optimized")` (`rhbi-v12`),
`get_recipe("rhbi")` and `get_recipe("bispf_optimized")` retain named presets. See
**[The Four Laws of Stable, Energy-Efficient GAN Convergence](docs/four-laws.md)** for the
first-principles derivation and Occam's Razor ablation behind `unified_v11` and `minimal`, the
[research glossary](RESEARCH_GLOSSARY.md#acronyms-and-short-names) for acronyms, and the
[recipe settings and evidence](docs/api.md#recipes-and-defaults) for configuration details.

Without `prior=`, the trainer builds a randomly drawn particle table. Networks
and device placement belong to the caller. The trainer does not reinitialize
Expand Down Expand Up @@ -109,14 +114,23 @@ metrics, receipts and training GIFs. Other report pages are historical records.
What the evidence does and does not show today:

- **The default is a research selection, not a qualified winner.** In the
[technique inventory](reports/forge/technique-inventory.md), the selected EMPF recipe
(`empf-v8`, `DEFAULT_RECIPE = "empf"`) ties `rhbi_optimized` (`rhbi-v12`) at **83/115**
counted view requirements (`27/27` Tier 1 PASS, `56/78` Tier 2, `0/10` Tier 3) with
**23 PASS**, **17 FAIL**, 8 not measured and 16 blocked across the 64-test fixed suite
(ahead of `bispf_optimized` at `81/115` and `18/64`; explicit `rhbi_optimized` reaches
`33/64` PASS and `35/63` stretch view assignments on the Forge suite). Forge's screening
calibration (`BLOCKED`), Tier 2/3 full-tier gates and untouched holdout confirmation
remain open.
[technique inventory](reports/forge/technique-inventory.md) and
[Round-4 solution-complete study](reports/forge/studies/r4-solution-complete.md),
the selected Unified recipe (`unified-v11`, `DEFAULT_RECIPE = "unified_v11"`) leads
screening at **`95/115` counted view requirements** (`27/27` Tier 1, `68/78` Tier 2),
**`40/69` full-suite passes** (`6` FAIL, `11` not measured, `12` blocked), **`50/68`
stretch view assignments**, and **`41/47` Tiers 1–2 `discriminator_stability` PASS**
(`55/62` deduplicated unique runnable tasks PASS across 9 studies; `90.24 ms/step` median
and `1,372.60 MiB` allocated VRAM on matched 66-cell `dcgan_performance_r256`) — ahead of
`rhbi_optimized` (`rhbi-v12`, `83/115`, `33/69`, `590.59 ms/step`), `empf` (`empf-v8`,
`83/115`, `23/69`, `129.72 ms/step`), and `bispf_optimized` (`81/115`, `18/69`), while
`get_recipe("minimal")` offers an `899`-LOC zero-Newton-Schulz fast core (`55.50 ms/step`
on `r256`). Forge's screening calibration remains provisional (`BLOCKED` under
`criteria-v1.json`; see [r3-calibration-holdout](reports/forge/studies/r3-calibration-holdout.md)),
Tier 2/3 full-tier qualification is incomplete, and remaining failures (`staggered100` /
`staggered100_14k`, `grid100_res16_tanh`, `five_word_joint_hold`,
`model_ddgan_bimodal_chain`, `model_ae_ddgan_gaussian_chain`, `interp_img_patch_shift`,
`interp_saddle_barycentric`, plus `12` unimplemented Tier-4 stretch hosts) stay visible.
- **Controlled prior comparison** ([matched prior ablation, 2026-10-25](reports/prior-ablation-2026-10-25/README.md)).
Each arm changes only the prior policy. Architecture, data, budget, seed 0 and
the initial table are the same. These are one-seed diagnostics with no
Expand Down Expand Up @@ -154,15 +168,15 @@ What the evidence does and does not show today:

### The 100-Gaussian animations

These three animations use different historical or opt-in recipes rather than the current `empf` default.
The lead [`100gaussians.gif`](100gaussians.gif) shows actual training of the current **0.11.0 default** (`get_recipe()` = `unified_v11`) on the Forge `grid100` `MoGParticlePrior(20000, σ=0.025, standardize=False)` cohort; the other two animations retain their archived 0.9.1 and opt-in E22 identities.

| Animation | Recipe | What it shows | Pass/fail metric | Result |
| --- | --- | --- | --- | --- |
| [`100gaussians.gif`](100gaussians.gif) | **Archived 0.9.0 default** (`get_recipe("bispf_optimized", optimizer_svd_backend="native", training_precision="float32")`). | 100-Gaussian grid, public deterministic initialization, protocol seed 0, 20,000 updates. | All 100 modes with ≥10 samples within 3σ, **and** `hq` (share of samples within 3σ) ≥ 0.95, at each of 5 terminal checks. | **FAIL**: 100/100 modes, but `hq` 42.1% ([receipt](reports/readme-100gaussians/README.md#current-default)) |
| [`100gaussians.gif`](100gaussians.gif) | **0.11.0 default** (`get_recipe()` = `unified_v11`) with the Forge `grid100` task prior (`MoGParticlePrior(20000, σ=0.025, standardize=False)`). | 100-Gaussian grid, public deterministic initialization, protocol seed 0, 7,000 updates (live weights, clean sampling, 260.5 s on RTX A6000). | All 100 modes with ≥10 samples within 3σ, **and** `hq` (share of samples within 3σ) ≥ 0.95, at each of 5 terminal checks. | **PASS**: 100/100 modes, `hq` 98.52% (5/5 terminal checks 98.52%–99.39%), Mode TV `0.04555`, Sliced W1 `0.08353`, core width ratio `0.957` ([receipt](reports/readme-100gaussians/README.md#current-default); archived 0.9.0 `ParticlePrior` FAIL retained [here](reports/readme-100gaussians/README.md#archived-090-default-particleprior-cohort)) |
| [stripes GIF](reports/forge/bispf-throughput/media/bispf-throughput-v1/img_stripes2.gif) | **Archived 0.9.1 default** (`get_recipe("bispf_optimized")`, batched SVD, BF16/channels-last) | Fixed 600-update `img_stripes2` image task | The task's declared Forge gate, including all required modes | **PASS** ([readout](reports/forge/bispf-throughput/README.md)) |
| [E22 GIF](reports/e22-animation/e22-100gaussians.gif) | **Not the default.** Opt-in preset `get_recipe("e22", ...)` with an identity `nn.Linear(2, 2)` generator, a 20,000-row table, batch 2,048 and seed 1234 | Grid, rotated and staggered 100-Gaussian layouts, 7,000 updates each | Native gates: worst live precision over the last 5 checks ≥ 0.97 and worst centre error ≤ 0.20σ | **PASS** on all three layouts (precision .9822–.9851); the animation draws reach `hq` 98.3–98.6% ([E22 results](docs/e22.md#results), [animation](reports/e22-animation/README.md)). In the Forge suite, E22 is 0/115: its policy cohort is blocked or incompatible with the current task definitions. |

![Archived 0.9.0 default on the 100-Gaussian grid: particle outputs, target modes and numerical learning curves (FAIL: hq 42.1% < 95%)](100gaussians.gif)
![0.11.0 default (unified_v11, MoGParticlePrior) on the 100-Gaussian grid: particle outputs, target modes and numerical learning curves (PASS: 100/100 modes, hq 98.5%)](100gaussians.gif)

![Actual training of the 0.9.1 BISPF default on the stripes task, with numerical quality observations (PASS)](reports/forge/bispf-throughput/media/bispf-throughput-v1/img_stripes2.gif)

Expand All @@ -186,9 +200,10 @@ qualification and review of the winner. The
acquisition, settling, endurance and recovery required again.

**Changing the default.** A promotion changes one line in
[particlegan/recipes.py](particlegan/recipes.py): `DEFAULT_RECIPE = "empf"`.
[particlegan/recipes.py](particlegan/recipes.py): `DEFAULT_RECIPE = "unified_v11"`.
All model-family factories inherit that trainer preset. Explicit presets such as
`get_recipe("rhbi_optimized")`, `get_recipe("rhbi")`, `get_recipe("bispf_optimized")` and
`get_recipe("minimal")`, `get_recipe("empf")`, `get_recipe("rhbi_optimized")`,
`get_recipe("rhbi")`, `get_recipe("bispf_optimized")` and
`get_recipe("ka2")` remain available. This is the owner-selected research default;
Forge calibration remains provisional (`BLOCKED`), Tier 2/3 qualification is incomplete,
and untouched holdout confirmation remains open.
Expand Down
Loading
Loading