dual-vade 0.1.0__tar.gz

dual_vade-0.1.0/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "Please cite this software when using the package."
+type: software
+title: "Dual-VaDE: unsupervised neural image clustering"
+version: 0.1.0
+authors:
+  - family-names: Zheng
+    given-names: Wugeng
+repository-code: "https://github.com/ZhengWugeng/dual-vade"
+license: MIT
+abstract: >-
+  Unsupervised image clustering with VaDE, Freq-VaDE, and Dual-VaDE.
+  Train neural networks on user-provided images, fit a post-hoc GMM,
+  and save complete local models for later inference.
+keywords:
+  - clustering
+  - variational autoencoder
+  - unsupervised learning

dual_vade-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wugeng Zheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dual_vade-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+include README.md pyproject.toml MANIFEST.in CITATION.cff LICENSE
+include release-approval.json requirements-release.txt
+recursive-include src *.py
+include examples/train_local.py
+include tools/check_release.py
+include docs/BUNDLE_FORMAT.md docs/TRAINING.md docs/source_provenance.json
+include docs/RELEASING.md
+prune model_bundles
+prune research_inputs
+prune .git
+prune .github
+prune .codex
+prune build
+prune dist
+global-exclude __pycache__ *.py[cod]
+global-exclude *.pth *.pt *.npz *.npy *.joblib *.pkl
+# No data, model assets, previews, private credentials, or mailbox files.
+global-exclude *.nii *.nii.gz *.dcm *.png *.jpg *.jpeg *.eml
+global-exclude .env .env.* .pypirc *.pem *.key

dual_vade-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: dual-vade
+Version: 0.1.0
+Summary: Unsupervised image clustering with trainable VaDE, Freq-VaDE, and Dual-VaDE
+Author: Wugeng Zheng
+Maintainer: Wugeng Zheng
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ZhengWugeng/dual-vade
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.6
+Requires-Dist: scikit-learn>=1.3
+Dynamic: license-file
+
+# Dual-VaDE
+
+Unsupervised neural image clustering with VaDE, Freq-VaDE, and Dual-VaDE.
+Author and maintainer: Wugeng Zheng. Code license: MIT.
+
+## Installation
+
+```text
+python -m pip install dual-vade
+```
+
+Requires Python 3.10 or newer. Runtime dependencies are NumPy, PyTorch, and
+scikit-learn. For GPU use, install a PyTorch build compatible with your GPU and
+driver before installing this package. Use `device="cpu"` for CPU operation.
+
+Give the model your prepared images, train without labels, save the complete
+model, and reload it for inference on new images. There is no required dataset,
+official pretrained model, model registry, or automatic model download.
+The interface encapsulates neural training and GMM fitting; it does not claim
+source-code or weight secrecy.
+
+## Train, cluster, and save
+
+```python
+from dual_vade import DualVaDE
+
+# images: a float array shaped (N, 128, 128), with values in [0, 1].
+# No ground-truth labels are passed to fit.
+model = DualVaDE(n_clusters=3, device="cuda")
+model.fit(images, epochs=200, verbose=True)
+labels = model.predict(images)
+model.save("my_model")
+
+# Later, with no training data or further fitting:
+restored = DualVaDE.load("my_model", device="cpu")
+new_labels = restored.predict(new_images)
+probabilities = restored.predict_proba(new_images)
+embeddings = restored.transform(new_images)
+```
+
+`fit` trains the neural encoders, decoder, and native mixture prior, then fits a
+separate diagonal GMM to the final training posterior means. It is not a GMM-only
+refit. A new constructor starts from random neural weights. Calling `fit` again,
+or after loading your own saved model, continues those weights with a new
+optimizer and final GMM. `fit` returns `self`; `predict` returns cluster IDs.
+The user chooses `n_clusters`; the package does not select it automatically or
+assign semantic names to clusters.
+
+## Model choices
+
+- `VaDE(n_clusters=3, ...)`: spatial-only.
+- `FreqVaDE(n_clusters=3, spectral="reim", ...)`: frequency-only.
+- `DualVaDE(n_clusters=3, spectral="reim", ...)`: spatial and frequency branches.
+
+The four spectral choices are `fullfreq`, `lowfreq`, `polarfreq`, and `reim`.
+ReIm is the default for FreqVaDE and DualVaDE. The old internal FullCplx source
+is named PolarFreq publicly. Together with VaDE, this provides nine training
+configurations. The preserved network implementations are unchanged.
+
+## Input requirements
+
+Supply finite, real-valued grayscale image arrays shaped `(N,H,W)` or
+`(N,1,H,W)`, already scaled to `[0,1]`. All images must match the constructor's
+`image_size`: default 128, or a power of two at least 64. Training requires at
+least `max(2, n_clusters)` images; practical training usually needs more data.
+
+The same format applies to medical or non-medical images; no specific dataset is
+required. RGB images, 3D volumes, and file-directory paths are not direct inputs.
+The package does not silently resize, normalize, register, or convert raw images.
+Use the same preparation at training and prediction time. Train only on your
+training split when evaluating held-out generalization.
+
+`examples/train_local.py` reads your prepared `.npy` array or a `.npz` archive
+containing `images`. See `docs/TRAINING.md` for the API, training recipe, and
+lifecycle, and `docs/BUNDLE_FORMAT.md` for saved model contents.
+
+## Saved models and scope
+
+`save("my_model")` creates a new directory containing `config.json`,
+`model_state.pth`, `clusterer.npz`, and `manifest.json`. A network `.pth` alone
+cannot restore the full clustering pipeline. Loading and prediction never train
+or fit a GMM. The package does not upload your images or saved models.
+
+The MIT license covers this software, not rights to anyone's input data. This
+release distributes neither datasets nor official pretrained weights/GMMs.
+Users are responsible for the permissions applicable to their data and any
+models they choose to share. Outputs are cluster IDs, not clinical diagnoses.
+
+## Validation
+
+The installed code-only rc3 wheel passed HPG job `46757892` on RTX PRO 6000.
+All nine configurations trained on generated non-medical grayscale images,
+without external data or pretrained assets. Neural parameter updates, final GMM,
+held-out inference, saved-model GPU/CPU reload, CPU training, continued training,
+and the CLI example passed. See `docs/TRAINING_VALIDATION_CODE_ONLY.json`.
+The published TestPyPI wheel then passed the same nine-configuration checks in
+job `46761432`, installed into a fresh package venv with the validated HPG
+scientific dependencies. Its origin and API hash were verified, with no source
+checkout used for package imports. See `docs/TESTPYPI_INSTALL_VALIDATION.json`.
+Short functional checks do not establish clustering quality on a user's dataset.
+Historical results are retained in `docs/VALIDATION_STATUS.md`.

dual_vade-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Dual-VaDE
+
+Unsupervised neural image clustering with VaDE, Freq-VaDE, and Dual-VaDE.
+Author and maintainer: Wugeng Zheng. Code license: MIT.
+
+## Installation
+
+```text
+python -m pip install dual-vade
+```
+
+Requires Python 3.10 or newer. Runtime dependencies are NumPy, PyTorch, and
+scikit-learn. For GPU use, install a PyTorch build compatible with your GPU and
+driver before installing this package. Use `device="cpu"` for CPU operation.
+
+Give the model your prepared images, train without labels, save the complete
+model, and reload it for inference on new images. There is no required dataset,
+official pretrained model, model registry, or automatic model download.
+The interface encapsulates neural training and GMM fitting; it does not claim
+source-code or weight secrecy.
+
+## Train, cluster, and save
+
+```python
+from dual_vade import DualVaDE
+
+# images: a float array shaped (N, 128, 128), with values in [0, 1].
+# No ground-truth labels are passed to fit.
+model = DualVaDE(n_clusters=3, device="cuda")
+model.fit(images, epochs=200, verbose=True)
+labels = model.predict(images)
+model.save("my_model")
+
+# Later, with no training data or further fitting:
+restored = DualVaDE.load("my_model", device="cpu")
+new_labels = restored.predict(new_images)
+probabilities = restored.predict_proba(new_images)
+embeddings = restored.transform(new_images)
+```
+
+`fit` trains the neural encoders, decoder, and native mixture prior, then fits a
+separate diagonal GMM to the final training posterior means. It is not a GMM-only
+refit. A new constructor starts from random neural weights. Calling `fit` again,
+or after loading your own saved model, continues those weights with a new
+optimizer and final GMM. `fit` returns `self`; `predict` returns cluster IDs.
+The user chooses `n_clusters`; the package does not select it automatically or
+assign semantic names to clusters.
+
+## Model choices
+
+- `VaDE(n_clusters=3, ...)`: spatial-only.
+- `FreqVaDE(n_clusters=3, spectral="reim", ...)`: frequency-only.
+- `DualVaDE(n_clusters=3, spectral="reim", ...)`: spatial and frequency branches.
+
+The four spectral choices are `fullfreq`, `lowfreq`, `polarfreq`, and `reim`.
+ReIm is the default for FreqVaDE and DualVaDE. The old internal FullCplx source
+is named PolarFreq publicly. Together with VaDE, this provides nine training
+configurations. The preserved network implementations are unchanged.
+
+## Input requirements
+
+Supply finite, real-valued grayscale image arrays shaped `(N,H,W)` or
+`(N,1,H,W)`, already scaled to `[0,1]`. All images must match the constructor's
+`image_size`: default 128, or a power of two at least 64. Training requires at
+least `max(2, n_clusters)` images; practical training usually needs more data.
+
+The same format applies to medical or non-medical images; no specific dataset is
+required. RGB images, 3D volumes, and file-directory paths are not direct inputs.
+The package does not silently resize, normalize, register, or convert raw images.
+Use the same preparation at training and prediction time. Train only on your
+training split when evaluating held-out generalization.
+
+`examples/train_local.py` reads your prepared `.npy` array or a `.npz` archive
+containing `images`. See `docs/TRAINING.md` for the API, training recipe, and
+lifecycle, and `docs/BUNDLE_FORMAT.md` for saved model contents.
+
+## Saved models and scope
+
+`save("my_model")` creates a new directory containing `config.json`,
+`model_state.pth`, `clusterer.npz`, and `manifest.json`. A network `.pth` alone
+cannot restore the full clustering pipeline. Loading and prediction never train
+or fit a GMM. The package does not upload your images or saved models.
+
+The MIT license covers this software, not rights to anyone's input data. This
+release distributes neither datasets nor official pretrained weights/GMMs.
+Users are responsible for the permissions applicable to their data and any
+models they choose to share. Outputs are cluster IDs, not clinical diagnoses.
+
+## Validation
+
+The installed code-only rc3 wheel passed HPG job `46757892` on RTX PRO 6000.
+All nine configurations trained on generated non-medical grayscale images,
+without external data or pretrained assets. Neural parameter updates, final GMM,
+held-out inference, saved-model GPU/CPU reload, CPU training, continued training,
+and the CLI example passed. See `docs/TRAINING_VALIDATION_CODE_ONLY.json`.
+The published TestPyPI wheel then passed the same nine-configuration checks in
+job `46761432`, installed into a fresh package venv with the validated HPG
+scientific dependencies. Its origin and API hash were verified, with no source
+checkout used for package imports. See `docs/TESTPYPI_INSTALL_VALIDATION.json`.
+Short functional checks do not establish clustering quality on a user's dataset.
+Historical results are retained in `docs/VALIDATION_STATUS.md`.

dual_vade-0.1.0/docs/BUNDLE_FORMAT.md

@@ -0,0 +1,31 @@
+# User model bundle, schema version 1
+
+A complete saved model contains four files:
+
+- `config.json`: schema version, model ID, method (`vade`, `freq`, `dual`),
+  spectral representation (`none`, `fullfreq`, `lowfreq`, `polarfreq`, `reim`),
+  `n_clusters`, `latent_dim`, `image_size`, random seed, and input metadata.
+- `model_state.pth`: a plain PyTorch state dict, including inference buffers.
+- `clusterer.npz`: the fitted post-hoc diagonal GMM, with numeric arrays
+  `weights`, `means`, and `covariances`, in fixed component order.
+- `manifest.json`: schema version, SHA-256 checksums, training origin, history,
+  GMM details, and parent-bundle identity when training continues from a saved model.
+
+Input metadata declares `intensity_range: [0,1]`, `normalization: "none"`,
+and `resize: "none"`. Inputs must already satisfy that contract. This format
+is not restricted to a particular dataset and is not a raw-image preprocessing
+pipeline. Prediction must use the same input preparation as training.
+
+The post-hoc clusterer is distinct from the neural network's native mixture prior.
+Both network and clusterer must be retained. Loading never fits either component.
+Training images, labels, subject IDs, per-image embeddings, and optimizer states
+are not saved. A later fit continues weights, not an interrupted optimizer run.
+
+The loader verifies checksums, uses `weights_only=True` for the state dict and
+`allow_pickle=False` for the GMM arrays, and validates dimensions and finite
+parameters. A local manifest detects corruption; it is not an independent proof
+that a model from someone else is trustworthy. Load models from trusted sources.
+
+`save` never overwrites an existing destination. Saving a loaded model without
+further training copies its four original files byte-for-byte. Further training
+changes only the in-memory model and any new export, not the source folder.

dual_vade-0.1.0/docs/RELEASING.md

@@ -0,0 +1,113 @@
+# Code-only release checklist
+
+## Scope
+
+Stable release preparation `0.1.0`, author and maintainer Wugeng Zheng. The only supported
+workflow is user images -> full neural fit -> post-hoc GMM -> save/load/predict.
+The three classes expose nine training configurations. There is no official
+pretrained entry point, registry, model hosting requirement, or dataset helper.
+The package contains no dataset, trained weights, or fitted GMM assets.
+
+The user confirmed team authorship and the supervisor's request to publish on
+2026-10-19. MIT applies to the package code. This is not a license for user data
+or a blanket license for user-trained model assets. A separate OASIS agreement
+or official-weight redistribution check is not a prerequisite for this code-only
+release, which distributes neither. Users must comply with terms of their own data.
+
+`release-approval.json` records code rights and the code-only scope. On 2026-10-19,
+the user separately approved formal PyPI `0.1.0` after TestPyPI validation passed.
+Per-index and per-version allowlists limit authorization to TestPyPI `0.1.0rc3`
+and PyPI `0.1.0`. A later version needs a new approval record. Model redistribution,
+public asset URLs, and pretrained download checks are not release gates. Do not
+upload historical private model bundles.
+
+## Private verification
+
+The prior rc2 fit API passed HPG job 46754905. Removing download interfaces changes
+the inference source hash, so that record does not authorize the rc3 candidate.
+`tools/run_hpg_training.sbatch` builds and installs the current wheel in a Slurm
+Pro 6000 allocation and trains all nine configurations on generated non-medical
+grayscale images. No reference dataset or pretrained assets are needed. It also
+checks CPU training, model save/reload, continued training from a user's saved
+model, held-out probability contracts, the CLI example, source-wheel rebuild,
+MIT metadata, and expected public-upload refusal.
+
+The code-only validation passed as HPG job 46757892 (COMPLETED, exit 0:0).
+`docs/TRAINING_VALIDATION_CODE_ONLY.json` retains the report, and the matching
+source hash/job are recorded in `release-approval.json`. The original wheel and
+source distribution were downloaded, hash-verified, and retained in ignored
+`dist/0.1.0rc3-hpg46757892/`. Citation, MIT metadata, strict Twine checks, source
+rebuild, and the expected refusal of both public upload gates passed as well.
+Short validation is not an accuracy claim. Public test upload is now separately
+authorized. TestPyPI installation and full training/save-load verification then
+passed GPU job 46761432; the evidence is recorded in `testpypi_install_validation`.
+Formal PyPI 0.1.0 is now separately authorized; its final build and upload are pending.
+
+## Publication sequence
+
+1. Review package contents and Git history for private files, credentials, data,
+   old model assets, and required upstream notices before making anything public.
+2. Complete the TestPyPI pending publisher, if still missing. The user enters any
+   password/MFA themselves. Never read, store, or request these values.
+3. Configure GitHub environments `testpypi` and `pypi`, matching Trusted Publishing.
+   Review branch/environment protections before enabling upload.
+4. With explicit authorization, publish the reviewed code repository and set
+   `public_release_authorized` with a non-sensitive approval reference.
+5. Dispatch `publish.yml` on main, target `testpypi`, with confirmation
+   `PUBLISH dual-vade testpypi`. TestPyPI is public, not private storage.
+6. In an HPG GPU allocation, install dependencies from PyPI, install this package
+   from TestPyPI using `--no-deps`, and verify training, save/load, and prediction.
+   Record the job ID and version in `testpypi_install_validation`.
+7. Set the package, citation, and public version to `0.1.0`; rebuild and review.
+   Obtain formal release approval, then dispatch target `pypi` with confirmation
+   `PUBLISH dual-vade pypi`. Verify clean installation of the published package.
+
+The workflow remains manual-only and build-only by default. No push/tag trigger
+publishes anything. No passwords or long-lived API tokens are needed by the
+prepared OIDC upload workflow. Do not replace an already uploaded file/version.
+
+## Account setup last observed: 2026-10-19
+
+PyPI account `zhengwugeng` registered a pending publisher for project `dual-vade`,
+owner `ZhengWugeng`, repository `dual-vade`, workflow `publish.yml`, environment
+`pypi`. TestPyPI has the matching publisher with environment `testpypi`;
+the user completed sensitive confirmations personally. The GitHub code repository
+is public. Its `testpypi` environment permits only the `main` branch. Workflow run
+39357159452 on commit 145461c successfully built and published `0.1.0rc3` to
+TestPyPI on 2026-10-19 at 22:07 EDT. The formal PyPI job was skipped. Published
+artifact hashes and matching runtime sources were verified; the release receipt
+is `docs/TESTPYPI_RELEASE.json`. HPG index-install validation passed job 46761432;
+its public summary is `docs/TESTPYPI_INSTALL_VALIDATION.json` and its detailed
+training report is `docs/TESTPYPI_TRAINING_VALIDATION.json`.
+Formal PyPI 0.1.0 is now explicitly authorized; build/upload are being prepared.
+
+After either index upload, `tools/run_hpg_testpypi.sbatch` must use the exact published version,
+public wheel SHA-256, and validated training API hash. It installs a fresh copy of
+the package from the explicitly selected index (`--no-deps`, no fallback index), reusing the validated
+HPG scientific dependencies. The package itself must resolve inside the new venv,
+not the checkout. The full nine-configuration verification runs on Pro 6000. This
+is not a claim of reinstalling the entire CUDA/PyTorch dependency stack.
+
+## HPG runtime reuse detail
+
+The selected HPG Python is already a virtual environment. A child venv with
+`--system-site-packages` does not expose the parent venv's installed packages;
+job 46760982 therefore installed the test wheel but failed before training.
+The corrected installer uses a fresh package venv and a .pth entry for only the
+selected parent's site-packages. It records exact dependency locations/versions
+and checks visibility first. User-site and checkout PYTHONPATH stay disabled.
+The package-origin and pinned wheel/API checks remain unchanged. Do not interpret
+successful pip installation alone as successful model/runtime validation.
+
+## Formal 0.1.0 authorization
+
+The user approved formal publication after job 46761432 passed. Package, citation,
+and public version are now 0.1.0; inference.py, training.py, and all four network
+implementations are unchanged. The formal gate additionally binds the TestPyPI
+installation record to this exact training API hash. The workflow still requires
+manual dispatch on main with `PUBLISH dual-vade pypi`; no push/tag auto-publishes.
+
+The existing HPG installer supports `DUAL_VADE_INDEX_TARGET=pypi` as well as its
+original `testpypi` default. It uses a fixed official index/JSON endpoint for each,
+checks the public wheel hash before installation, and reruns all nine configurations
+from the installed package. Formal-index results use `pypi-install-validation.json`.

dual_vade-0.1.0/docs/TRAINING.md

@@ -0,0 +1,104 @@
+# Neural training and complete-model inference
+
+## Public API
+
+```python
+from dual_vade import DualVaDE, FreqVaDE, VaDE
+
+model = DualVaDE(
+    n_clusters=3, spectral="reim", latent_dim=32, image_size=128,
+    device="cuda", batch_size=16, random_state=123,
+)
+model.fit(train_images, epochs=200, learning_rate=1.5e-4, verbose=True)
+labels = model.predict(test_images)
+model.save("my_model")
+restored = DualVaDE.load("my_model", device="cpu")
+labels = restored.predict(test_images)
+```
+
+`FreqVaDE` has the same spectral choices. Use `VaDE(n_clusters=3, ...)` without
+a spectral argument for the spatial baseline. Methods use sklearn-style
+fit/predict calls; full sklearn estimator/cloning/GridSearchCV compatibility is
+not claimed.
+
+Only images explicitly passed to `fit` are used for neural optimization or final
+GMM fitting. Do not concatenate held-out/test data into that call. The local training
+example treats every image in its input file as training data; separate your
+held-out data before invoking it. `predict`,
+`predict_proba`, `transform`, `reconstruct`, `save`, and `load` never train a model.
+No external dataset, pretrained weights, labels, or model download is needed.
+Train on your own compatible images; choose the cluster count with n_clusters.
+
+## Input contract
+
+Prepared finite grayscale arrays, `(N,H,W)` or `(N,1,H,W)`, with intensities in
+[0,1]. Constructor image_size is a power of two >=64, default 128. At least
+`max(2, n_clusters)` training images are required. No registration, resizing,
+RGB conversion, normalization, or raw-volume preprocessing is hidden in fit.
+Maintain the same input convention at prediction time.
+
+## What fit actually does
+
+1. Put the neural network in training mode and enable all neural parameters.
+2. For each epoch, shuffle only the supplied training images; evaluate the
+   variational encoder/decoder and trainable native mixture-prior objective;
+   backpropagate, clip gradients, and take AdamW optimizer steps.
+3. After the final neural epoch, switch to evaluation mode and collect posterior
+   means for those same training images, in their original supplied order.
+4. Fit a separate sklearn diagonal GMM to those means, with the requested K.
+5. Commit the fitted GMM and training history to the model and return `self`.
+
+Defaults: AdamW learning rate 1.5e-4, weight decay 2e-4, gradient norm clip 5,
+cosine decay to min(5e-5, initial learning rate). Loss weights are reconstruction
+BCE 0.2, fused/spatial KL 0.01, native GMM negative log-likelihood 0.05, and mixture
+balance 0.01. Dual FullFreq/ReIm/PolarFreq also use branch-level KL 0.01 per branch;
+LowFreq retains its original concat recipe without those extra branch terms.
+The post-hoc GMM uses float64 embeddings, diagonal covariance, ten restarts,
+reg_covar 1e-4, and at most 200 EM iterations. Non-finite gradients/losses or a
+non-converged final GMM fail rather than silently creating a different K model.
+
+This is a shared user-training pipeline, not a promise to reproduce every original
+family/seed's complete epoch-dependent research schedule, early stopping, or paper
+metrics. It does not select checkpoints using test data and does not repeatedly
+refit GMMs during neural epochs. Training quality on a new dataset needs its own
+evaluation.
+
+## Lifecycle and reproducibility
+
+- New constructors create random networks; inference/save raises NotFittedError
+  until fit succeeds. `epochs=0` is rejected: fit cannot be a GMM-only shortcut.
+- A loaded user-saved model already supports inference. Calling fit on
+  it continues its current neural weights, using a fresh optimizer and final GMM.
+  Repeated fit likewise continues weights; construct a new object for a fresh start.
+- Prediction never updates weights, BatchNorm statistics, or GMM parameters.
+- Basic invalid options/input are rejected before invalidating an existing model.
+  Once training starts, failure invalidates inference/save until a successful fit
+  or a new load; original on-disk bundles are never changed by fitting.
+- `history_` records epoch losses and learning rates; `n_iter_` records the most
+  recent successful fit's epoch count. They survive saving/loading.
+- `random_state` defaults to 123 and controls initialization, shuffling, sampling,
+  dropout, and GMM initialization. Seeded initialization/training restores the
+  caller's NumPy and relevant Torch RNG states. None uses unseeded randomness.
+
+## Saved model
+
+`save` creates a new directory and never overwrites an existing one:
+
+```text
+my_model/
+    config.json
+    model_state.pth
+    clusterer.npz
+    manifest.json
+```
+
+The config stores architecture/input settings. The state dict includes network
+parameters and inference buffers. NPZ contains fixed post-hoc weights, means, and
+diagonal covariances. Manifest records SHA-256 values, training origin, epochs,
+optimizer-step count, history, GMM details, and parent bundle identity when relevant.
+It does not store training images, subject IDs, or per-sample embeddings/labels.
+
+Loading requires no training dataset, gradient updates, or GMM re-fitting.
+Optimizer/scheduler states are not saved: a later fit continues weights, not an
+exact interrupted optimizer run. Continued-training outputs retain user-trained provenance. Saving an unmodified
+loaded model copies its verified bundle byte-for-byte and preserves its history.

dual_vade-0.1.0/docs/source_provenance.json

@@ -0,0 +1,22 @@
+[
+  {
+    "source": "1_FullFreq-GMVAE/models/vae.py",
+    "package_file": "src/dual_vade/_models/fullfreq.py",
+    "sha256": "893f5f157cf13b03cdb8eca4b2e0c91e14116ee37050f7f0db3c700c970e78e9"
+  },
+  {
+    "source": "2_LowFreq-GMVAE/models/vae.py",
+    "package_file": "src/dual_vade/_models/lowfreq.py",
+    "sha256": "329ed5758cf89478f35d2dbefbffe9de94d5589a3c4883e2ceb41fb7a11cb1d7"
+  },
+  {
+    "source": "3_ReIm-GMVAE/models/vae.py",
+    "package_file": "src/dual_vade/_models/reim.py",
+    "sha256": "8332a9d1cac901edcb3e3676d1662335e43a7adef056d755e351c19a8f52668f"
+  },
+  {
+    "source": "4_FullCplx-GMVAE/models/vae.py",
+    "package_file": "src/dual_vade/_models/polarfreq.py",
+    "sha256": "fda98c02074974b0564347b26cc9efd07b37647421d7c439dc8ecef2c3db1caa"
+  }
+]

dual_vade-0.1.0/examples/train_local.py

@@ -0,0 +1,37 @@
+"""Train a new Dual-VaDE on prepared local images, then save the complete model."""
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from dual_vade import DualVaDE
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--images", type=Path, required=True, help="Training images only: prepared .npy array or .npz with an images key")
+    parser.add_argument("--output", type=Path, required=True, help="A new model directory")
+    parser.add_argument("--n-clusters", type=int, default=3)
+    parser.add_argument("--spectral", choices=("fullfreq", "lowfreq", "polarfreq", "reim"), default="reim")
+    parser.add_argument("--epochs", type=int, default=200)
+    parser.add_argument("--batch-size", type=int, default=16)
+    parser.add_argument("--device", choices=("cpu", "cuda"), default="cpu")
+    args = parser.parse_args()
+    args.images = args.images.expanduser()
+    args.output = args.output.expanduser()
+    if args.output.exists():
+        parser.error("Output directory already exists; choose a new path")
+    if args.images.suffix == ".npz":
+        with np.load(args.images, allow_pickle=False) as saved:
+            images = saved["images"]
+    else:
+        images = np.load(args.images, allow_pickle=False)
+    model = DualVaDE(n_clusters=args.n_clusters, spectral=args.spectral,
+                     device=args.device, batch_size=args.batch_size)
+    model.fit(images, epochs=args.epochs, verbose=True)
+    model.save(args.output)
+    print(f"Saved complete trained model to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

dual_vade-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dual-vade"
+version = "0.1.0"
+description = "Unsupervised image clustering with trainable VaDE, Freq-VaDE, and Dual-VaDE"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Wugeng Zheng"}]
+maintainers = [{name = "Wugeng Zheng"}]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "torch>=2.6", "scikit-learn>=1.3"]
+
+[project.urls]
+Repository = "https://github.com/ZhengWugeng/dual-vade"
+
+[tool.setuptools.packages.find]
+where = ["src"]

dual_vade-0.1.0/release-approval.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": 1,
+  "release_scope": "trainable-code-only",
+  "code_rights_confirmed": true,
+  "public_release_authorized": true,
+  "approval_record": "2026-10-19: user confirmed team authorship and supervisor instruction to publish code for training user-provided images, with no official model or dataset distribution. User approved public GitHub and TestPyPI 0.1.0rc3, then explicitly approved formal PyPI 0.1.0 after successful HPG TestPyPI install/training validation 46761432. Authorization is limited to these versions.",
+  "testpypi_install_validation": {
+    "hpg_job_id": "46761432",
+    "version": "0.1.0rc3",
+    "training_api_sha256": "09f16c8afa85a5ffd999df68b6efeb216b41a97ed9d57f2688ec513421c14459",
+    "wheel_sha256": "19343ed5f0b781e0c0fda15711c14eeac811b1283bff3e7a736736feec8377a6"
+  },
+  "training_validation": {
+    "hpg_job_id": "46757892",
+    "training_api_sha256": "09f16c8afa85a5ffd999df68b6efeb216b41a97ed9d57f2688ec513421c14459"
+  },
+  "authorized_publish_targets": [
+    "testpypi",
+    "pypi"
+  ],
+  "authorized_publish_versions": {
+    "testpypi": "0.1.0rc3",
+    "pypi": "0.1.0"
+  }
+}

dual_vade-0.1.0/requirements-release.txt

@@ -0,0 +1,9 @@
+# Build/validation tools only; these are not inference dependencies.
+build==1.3.0
+twine==6.2.0
+cffconvert==2.0.0
+PyYAML==6.0.2
+packaging==25.0
+setuptools==80.9.0
+wheel==0.46.3
+tomli>=2,<3; python_version < "3.11"

dual_vade-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dual_vade-0.1.0/src/dual_vade/__init__.py

@@ -0,0 +1,5 @@
+"""Unsupervised neural image clustering: fit, predict, save, and load."""
+from .inference import DualVaDE, FreqVaDE, VaDE
+
+__version__ = "0.1.0"
+__all__ = ["DualVaDE", "FreqVaDE", "VaDE"]