vine-denoising-copula 0.4.0__tar.gz

vine_denoising_copula-0.4.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+Published versions are immutable. The NeurIPS 2026 paper pins v0.2.6;
+its checkpoints and reproduction archives remain available.
+
+## v0.4.0 — 2026-11-13
+
+- Separate pretrained model construction from the training engine. The base
+  install no longer requires pyvinecopulib, Matplotlib, HDF5, Hydra or
+  scikit-learn; use `[train]`, `[baselines]`, `[viz]` and `[data]` as needed.
+- Require Python 3.11 or later and test Python 3.11–3.13.
+- Add installed-model checks and TestPyPI/PyPI Trusted Publishing. Model
+  weights, constructor calculations and inference defaults are unchanged.
+
+
+- Name the probability-mass histogram `vdc.data.hist.scatter_to_mass_hist`
+  and retain `scatter_to_hist` as a compatibility alias. Document the distinct
+  density normalization required by pretrained inference, and test that
+  input contract through the public estimator. Histogram values and model
+  outputs are unchanged.
+- Add a portable reproduction and reference results for the histogram
+  normalization failure reported in issue #8.
+
+## v0.3.0 — 2026-11-12
+
+- Rewrite the README and the documentation landing page with the method overview, results
+  figures, pretrained-model table, training commands and reproduction guide.
+- Keep maintained entry points in `scripts/`; move the GridUNet workflow scripts to
+  `scripts/legacy/` and remove the two deprecated demo shims (use `examples/`).
+- Gather all NeurIPS 2026 reproduction material in `paper/`: the experiment runners and
+  reference outputs (formerly `projects/neurips2026/`), the figure and table generators with
+  their saved inputs (formerly distributed only as a release archive) and the ablation training
+  configurations (formerly in `configs/train/`). Saved outputs, runner defaults and numerical
+  behavior are unchanged; [`paper/README.md`](paper/README.md) maps every figure and table to
+  its script, inputs and runner.
+- Add the opt-in linear-grid estimator of the paper's exploratory retraining
+  appendix: `LinearGridCopula` (consistent PDF, h and inverse-h functions),
+  `VineCopulaModel(pair_estimator="linear_grid", ...)`,
+  `VineCopulaModel.from_pretrained` and `estimate_pair_copula_from_samples`.
+  Defaults and the results of `vdc-denoiser-m64-v1` are unchanged.
+- Add configurable conditional clipping (`conditional_clip_eps`, default 1e-6).
+- Release `vdc-denoiser-m64-v2` and `vdc-denoiser-m128-v2` on Hugging Face (manifests pin the
+  upload revisions) and their training pilot `vdc-linear-grid-pilot`; `checkpoint_path=` loads a
+  hash-verified local copy of any registered model.
+- Add their pretraining, continuous-mixture data and fine-tuning recipes
+  (`scripts/train_linear_grid_estimator.py`, `configs/train/linear_grid_*.yaml`).
+- Fix `stage_release_bundle` for manifests without local source files.
+
+Details: [linear-grid estimators](docs/IMPROVED_ESTIMATORS.md).
+
+## v0.2.7 — 2026-11-12
+
+- Correct Joe/BB1/BB7 training samples and BB density targets; test against analytic CDFs.
+- Correct Frank/Joe conditional CDFs, BB rotations and mixture counts; reject invalid conditional training pairs.
+- Replace obsolete API examples with programs using the released model loader.
+- Correct API signatures and document numerical limits and opt-in batching.
+- Simplify installation, consolidate release documentation and expand CI coverage.
+- Keep manuscript production and internal research records outside the library.
+
+Details: [v0.2.7 release notes](docs/releases/RELEASE_NOTES_v0.2.7.md).
+
+## Earlier releases
+
+- [v0.2.6](docs/releases/RELEASE_NOTES_v0.2.6.md)
+- [v0.2.5](docs/releases/RELEASE_NOTES_v0.2.5.md)
+- [v0.2.4](docs/releases/RELEASE_NOTES_v0.2.4.md)
+- [v0.2.3](docs/releases/RELEASE_NOTES_v0.2.3.md)
+- [v0.2.2](docs/releases/RELEASE_NOTES_v0.2.2.md)
+- [v0.2.1](docs/releases/RELEASE_NOTES_v0.2.1.md)
+- [v0.2.0](docs/releases/RELEASE_NOTES_v0.2.0.md)
+- [v0.1.1](docs/releases/RELEASE_NOTES_v0.1.1.md)
+- [v0.1.0](docs/releases/RELEASE_NOTES_v0.1.0.md)

vine_denoising_copula-0.4.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the repository. If you use the VDC method, please also cite the associated paper."
+title: "Vine Denoising Copula (VDC)"
+abstract: >-
+  Vine Denoising Copula (VDC) is an amortized vine-copula pipeline that
+  trains one bivariate denoising density operator and reuses it across
+  all vine edges. The project provides the trained edge estimator,
+  inference code for D-/C-/R-vines, IPFP projection, information-theoretic
+  estimators (MI, TC), and released-model verification tooling.
+authors:
+  - family-names: "Safaai"
+    given-names: "Houman"
+    affiliation: "Kempner Institute at Harvard University"
+license: MIT
+repository-code: "https://github.com/KempnerInstitute/vine-denoising-copula"
+url: "https://huggingface.co/hsafaai/vdc-denoiser-m64-v1"
+keywords:
+  - copula
+  - vine copula
+  - density estimation
+  - mutual information
+  - total correlation
+  - amortized inference
+version: "0.4.0"
+date-released: 2026-11-13
+preferred-citation:
+  type: conference-paper
+  title: "Amortized Vine Copulas for High-Dimensional Density and Information Estimation"
+  authors:
+    - family-names: "Safaai"
+      given-names: "Houman"
+      affiliation: "Kempner Institute for the Study of Natural and Artificial Intelligence at Harvard University"
+  year: 2026
+  collection-title: "Advances in Neural Information Processing Systems"
+  conference:
+    name: "NeurIPS 2026"

vine_denoising_copula-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Start from `main`, the maintained public library branch. Keep changes focused
+and open a pull request with the problem, resulting behavior and verification.
+Use tagged releases and explicit checkpoint hashes for scientific reproduction.
+
+## Development environment
+
+```bash
+python -m pip install -e '.[dev,train,data,viz]'
+python -m pytest tests
+```
+
+A CPU is sufficient for the tests. Optional compiled-sampler tests require a
+C++17/OpenMP compiler; tests that require unavailable artifacts report a skip.
+Do not describe skipped checks as passed. Avoid downloading large checkpoints
+in unit tests; use a separate integration check for the released model.
+
+## Repository organization
+
+- `vdc/`: reusable models, data utilities, training and inference.
+- `scripts/`: software entry points and model/data tools.
+- `examples/`: small programs using the public API.
+- `docs/`: user and maintainer documentation.
+- `paper/`: everything paper-specific: experiment runners, figure and table
+  generators with their compact saved inputs, reference outputs and the
+  ablation training configurations of the NeurIPS 2026 paper.
+
+Keep paper material in `paper/`; it imports `vdc` and is not installed with the
+package. Saved inputs there are immutable: their hashes are recorded in
+`MANIFEST.json` files and checked by the figure scripts. Keep manuscript
+builds, cluster launchers and internal research notes outside this repository.
+Do not commit credentials, personal storage paths, scheduler accounts, raw
+datasets or model weights.
+
+## Numerical changes
+
+Keep estimator changes separate from organization and documentation work. Test
+fixed inputs, model serialization, seeds and relevant numerical outputs. Do not
+change a scientific experiment's source pin solely because a newer release
+imports successfully. Preserve historical release tags and publish numerical
+changes in the changelog.
+
+Use markers, line styles, hatches or labels in addition to color in examples.
+Document shapes, units, random-state behavior and unsupported combinations.
+See the [release guide](docs/RELEASING.md) before publishing a version.

vine_denoising_copula-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Vine Denoising Copula Authors
+
+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.

vine_denoising_copula-0.4.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE README.md CHANGELOG.md CONTRIBUTING.md CITATION.cff
+recursive-include docs *.md *.html *.css
+recursive-include configs *.yaml *.md
+recursive-include examples *.py *.md
+include examples/diagnostics/histogram_normalization/reference_results.json
+recursive-include scripts *.py
+recursive-include tests *.py
+include vdc/vine/compiled_sampler.cpp

vine_denoising_copula-0.4.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: vine-denoising-copula
+Version: 0.4.0
+Summary: Vine Denoising Copula for high-dimensional vine-copula modeling and information estimation
+Author-email: Houman Safaai <houman_safaai@harvard.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/KempnerInstitute/vine-denoising-copula
+Project-URL: Repository, https://github.com/KempnerInstitute/vine-denoising-copula
+Project-URL: Issues, https://github.com/KempnerInstitute/vine-denoising-copula/issues
+Project-URL: Documentation, https://kempnerinstitute.github.io/vine-denoising-copula/
+Keywords: copulas,vine copulas,density estimation,mutual information,machine learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: filelock>=4.2.1
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: train
+Requires-Dist: matplotlib>=3.7.0; extra == "train"
+Requires-Dist: h5py>=3.8.0; extra == "train"
+Requires-Dist: hydra-core>=1.3.0; extra == "train"
+Requires-Dist: pyvinecopulib<0.8,>=0.7.5; extra == "train"
+Provides-Extra: baselines
+Requires-Dist: pyvinecopulib<0.8,>=0.7.5; extra == "baselines"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: ruff>=0.0.270; extra == "dev"
+Requires-Dist: black>=23.3.0; extra == "dev"
+Requires-Dist: mypy>=1.3.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest>=7.3.0; extra == "dev"
+Requires-Dist: hypothesis>=6.75.0; extra == "dev"
+Requires-Dist: ipython>=8.12.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.3.0; extra == "test"
+Requires-Dist: hypothesis>=6.75.0; extra == "test"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7.0; extra == "viz"
+Requires-Dist: seaborn>=0.12.0; extra == "viz"
+Requires-Dist: pandas>=2.0.0; extra == "viz"
+Provides-Extra: data
+Requires-Dist: h5py>=3.8.0; extra == "data"
+Requires-Dist: pandas>=2.0.0; extra == "data"
+Requires-Dist: openpyxl>=3.1.0; extra == "data"
+Provides-Extra: release
+Requires-Dist: build>=1.2.0; extra == "release"
+Requires-Dist: huggingface-hub>=0.20.0; extra == "release"
+Provides-Extra: tracking
+Requires-Dist: wandb>=0.15.0; extra == "tracking"
+Provides-Extra: r-baselines
+Requires-Dist: rpy2>=3.5.0; extra == "r-baselines"
+Provides-Extra: paper-baselines
+Requires-Dist: pyvinecopulib<0.8,>=0.7.5; extra == "paper-baselines"
+Requires-Dist: scikit-learn>=1.2.0; extra == "paper-baselines"
+Requires-Dist: matplotlib>=3.7.0; extra == "paper-baselines"
+Requires-Dist: copulas>=0.13.0; extra == "paper-baselines"
+Requires-Dist: ennemi>=1.4.0; extra == "paper-baselines"
+Requires-Dist: pytorch-lightning>=2.1.0; extra == "paper-baselines"
+Dynamic: license-file
+
+<div align="center">
+
+# Vine Denoising Copula (VDC)
+
+**Amortized vine copulas for high-dimensional density and information estimation**
+
+[![CI](https://github.com/KempnerInstitute/vine-denoising-copula/actions/workflows/ci.yml/badge.svg)](https://github.com/KempnerInstitute/vine-denoising-copula/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://kempnerinstitute.github.io/vine-denoising-copula/)
+[![Paper](https://img.shields.io/badge/NeurIPS-2026-8c1515)](https://arxiv.org/abs/2604.20568)
+[![Model](https://img.shields.io/badge/%F0%9F%A4%97%20model-vdc--denoiser--m64--v1-yellow)](https://huggingface.co/hsafaai/vdc-denoiser-m64-v1)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[Paper](https://arxiv.org/abs/2604.20568) · [Documentation](https://kempnerinstitute.github.io/vine-denoising-copula/) · [Quick start](#quick-start) · [Pretrained models](#pretrained-models) · [Reproduce the paper](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md)
+
+</div>
+
+![VDC overview: one pretrained denoising network estimates every pair-copula of a vine](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_overview.png)
+
+Vine copulas model high-dimensional dependence through a tree of bivariate
+**pair-copulas**, but classical fitting estimates every edge separately, which
+becomes the bottleneck as dimension grows. **VDC** trains one bivariate
+denoising network on simulated copulas and reuses it for every edge: it maps the
+empirical histogram of an edge to a density grid in a single forward pass, and
+an IPFP (Sinkhorn) projection restores uniform copula marginals. The fitted
+pair-copulas and their cached h-functions plug into standard vine recursion, so
+the model keeps an explicit, interpretable dependence structure while replacing
+repeated per-edge fitting with reusable neural inference.
+
+**What you can do with it**
+
+- Estimate a **bivariate copula density** from samples in milliseconds.
+- Fit **D-, C- and regular vines** in high dimensions, with batched GPU inference.
+- Evaluate **likelihoods**, draw **samples** (inverse Rosenblatt), and compute
+  conditional transforms.
+- Estimate **mutual information** and **total correlation**, decomposed by edge
+  and by tree of the fitted vine.
+- Train your own estimator on the included synthetic copula generators.
+
+## Results at a glance
+
+![Density accuracy, vine likelihood, fitting time and S&P100 likelihood](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_results_density_speed.png)
+
+From the NeurIPS 2026 paper (all numbers use the released `vdc-denoiser-m64-v1`):
+
+| | |
+|---|---|
+| Bivariate density (9 in-library cases) | lower ISE than histogram, KDE and pyvine-TLL at **~6 ms per edge** on a GPU; parametric family selection is more accurate on its own families at ~100x the cost |
+| Families never seen in training | matches per-case TLL refits in held-out likelihood and **roughly halves MI error** |
+| High-dimensional vines (d = 100–500) | **3.3–4.0x faster** than 16-thread pyvine-TLL on one node (749 s vs 2,489 s at d = 500) |
+| S&P100 daily returns (d = 100) | **best held-out likelihood** of the compared methods on random and chronological splits |
+| Information estimation | fewer data-processing-inequality violations and lower additivity error than KSG; TC at d = 50 in **0.71 s** |
+
+Limits are reported alongside: the 64x64 grid bounds accuracy for near-deterministic
+pairs, and chained conditional prediction (VaR, imputation) is not yet competitive.
+See the paper and [the reproduction guide](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md) for every protocol.
+
+![Mutual-information error, total-correlation runtime and self-consistency](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_results_information.png)
+
+## Installation
+
+```bash
+python -m pip install vine-denoising-copula
+```
+
+Python 3.11 or later with PyTorch 2 is required. A GPU is optional. The base
+install supports pretrained pair densities, vine fitting, likelihoods and
+sampling without pyvinecopulib or plotting/training packages. Optional features:
+
+```bash
+python -m pip install 'vine-denoising-copula[train]'      # synthetic data and training
+python -m pip install 'vine-denoising-copula[baselines]'  # qualified pyvinecopulib 0.7.x
+python -m pip install 'vine-denoising-copula[viz,data]'    # plotting and dataset downloads
+```
+
+Install `vine-denoising-copula`, not the unrelated PyPI project `vdc`. Both
+provide an `import vdc` namespace, so use separate virtual environments.
+Checkpoints remain on Hugging Face and are downloaded and hash-verified on first
+use. For a source installation:
+
+```bash
+git clone https://github.com/KempnerInstitute/vine-denoising-copula.git
+cd vine-denoising-copula
+python -m pip install -e '.[dev,train,data,viz]'
+```
+
+See [getting started](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/GETTING_STARTED.md) for CPU/GPU PyTorch installation.
+The paper reproduction environment retains its recorded dependency versions.
+
+## Quick start
+
+```python
+import numpy as np
+from vdc import load_pretrained_model, estimate_pair_density_from_samples, VineCopulaModel
+
+bundle = load_pretrained_model("vdc-denoiser-m64-v1", device="cpu")   # downloads and hash-checks
+
+# 1) a bivariate copula density from pseudo-observations in [0, 1]^2
+u = np.random.default_rng(0).uniform(size=(2000, 2))
+density = estimate_pair_density_from_samples(bundle, u)              # (64, 64) grid
+
+# 2) a vine on d-dimensional pseudo-observations
+x = np.random.default_rng(1).uniform(size=(2000, 8))
+vine = VineCopulaModel(vine_type="dvine", m=64, device="cpu", batch_edges=True)
+vine.fit(x, bundle.model, diffusion=bundle.diffusion)
+loglik = vine.logpdf(x)                      # per-row log copula density
+samples = vine.simulate(n=1000)              # inverse-Rosenblatt sampling
+```
+
+Pseudo-observations are ranks scaled to (0, 1). Fit marginal transforms on
+training rows and apply them to held-out rows. More: [examples/](https://github.com/KempnerInstitute/vine-denoising-copula/tree/main/examples/) and
+the [user guide](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/USER_GUIDE.md).
+
+## Pretrained models
+
+| Model | Grid | Use | Status |
+|---|---|---|---|
+| [`vdc-denoiser-m64-v1`](https://huggingface.co/hsafaai/vdc-denoiser-m64-v1) | 64x64 | the estimator of all main paper results | released |
+| [`vdc-denoiser-m64-v2`](https://huggingface.co/hsafaai/vdc-denoiser-m64-v2) | 64x64 | retrained linear-grid estimator VDC-64 (paper, Appendix G) | released |
+| [`vdc-denoiser-m128-v2`](https://huggingface.co/hsafaai/vdc-denoiser-m128-v2) | 128x128 | retrained linear-grid estimator VDC-128 (paper, Appendix G) | released |
+
+Every checkpoint is verified by SHA-256 on load. The v2 estimators were trained after the paper's
+main experiments on corrected synthetic data; they use a continuous bilinear density with exact
+h-functions and are selected with `VineCopulaModel.from_pretrained(bundle)`. Their training
+initialization is published as [`vdc-linear-grid-pilot`](https://huggingface.co/hsafaai/vdc-linear-grid-pilot).
+See [docs/MODEL_RELEASES.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/MODEL_RELEASES.md) and [docs/IMPROVED_ESTIMATORS.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/IMPROVED_ESTIMATORS.md).
+
+## Train an estimator
+
+```bash
+# the released estimator (vdc-denoiser-m64-v1)
+python scripts/train_unified.py --config configs/train/denoiser_cond_enhanced.yaml --model-type denoiser
+
+# the retrained linear-grid estimators: pilot, data cache, then each fine-tune
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_pilot.yaml
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_cache.yaml
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_vdc128_v2.yaml
+```
+
+Configurations and the synthetic training generators are documented in
+[docs/CONFIGURATION.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/CONFIGURATION.md) and [docs/TRAINING_DATA.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/TRAINING_DATA.md);
+the linear-grid recipes, their resources and verification are in [docs/IMPROVED_ESTIMATORS.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/IMPROVED_ESTIMATORS.md).
+
+## Reproduce the paper
+
+[`paper/`](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md) contains everything needed to reproduce the NeurIPS 2026
+results: experiment runners with fixed protocols, the scripts and saved outputs that
+regenerate every figure and table, and reference results. Figures and tables
+rebuild from saved outputs on a laptop in minutes:
+
+```bash
+bash paper/figures/make_figures.sh output/figures
+bash paper/tables/make_tables.sh output/tables
+```
+
+## Repository layout
+
+```
+vdc/        library: models, projection (IPFP), vine fitting, sampling, information, training, data
+configs/    training configurations
+scripts/    command-line entry points (training, model and dataset downloads, packaging)
+examples/   runnable examples
+tests/      test suite (run with python -m pytest tests)
+docs/       documentation (also served at kempnerinstitute.github.io/vine-denoising-copula)
+paper/      NeurIPS 2026 reproduction: runners, figure and table generators, saved results
+```
+
+## Citation
+
+```bibtex
+@inproceedings{safaai2026vdc,
+  title     = {Amortized Vine Copulas for High-Dimensional Density and Information Estimation},
+  author    = {Safaai, Houman},
+  booktitle = {Advances in Neural Information Processing Systems},
+  year      = {2026},
+  note      = {arXiv:2604.20568}
+}
+```
+
+## License
+
+MIT; see [LICENSE](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/LICENSE). This work was supported in part by a gift from the Chan
+Zuckerberg Initiative Foundation to establish the Kempner Institute for the Study of
+Natural and Artificial Intelligence at Harvard University.

vine_denoising_copula-0.4.0/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+
+# Vine Denoising Copula (VDC)
+
+**Amortized vine copulas for high-dimensional density and information estimation**
+
+[![CI](https://github.com/KempnerInstitute/vine-denoising-copula/actions/workflows/ci.yml/badge.svg)](https://github.com/KempnerInstitute/vine-denoising-copula/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://kempnerinstitute.github.io/vine-denoising-copula/)
+[![Paper](https://img.shields.io/badge/NeurIPS-2026-8c1515)](https://arxiv.org/abs/2604.20568)
+[![Model](https://img.shields.io/badge/%F0%9F%A4%97%20model-vdc--denoiser--m64--v1-yellow)](https://huggingface.co/hsafaai/vdc-denoiser-m64-v1)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[Paper](https://arxiv.org/abs/2604.20568) · [Documentation](https://kempnerinstitute.github.io/vine-denoising-copula/) · [Quick start](#quick-start) · [Pretrained models](#pretrained-models) · [Reproduce the paper](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md)
+
+</div>
+
+![VDC overview: one pretrained denoising network estimates every pair-copula of a vine](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_overview.png)
+
+Vine copulas model high-dimensional dependence through a tree of bivariate
+**pair-copulas**, but classical fitting estimates every edge separately, which
+becomes the bottleneck as dimension grows. **VDC** trains one bivariate
+denoising network on simulated copulas and reuses it for every edge: it maps the
+empirical histogram of an edge to a density grid in a single forward pass, and
+an IPFP (Sinkhorn) projection restores uniform copula marginals. The fitted
+pair-copulas and their cached h-functions plug into standard vine recursion, so
+the model keeps an explicit, interpretable dependence structure while replacing
+repeated per-edge fitting with reusable neural inference.
+
+**What you can do with it**
+
+- Estimate a **bivariate copula density** from samples in milliseconds.
+- Fit **D-, C- and regular vines** in high dimensions, with batched GPU inference.
+- Evaluate **likelihoods**, draw **samples** (inverse Rosenblatt), and compute
+  conditional transforms.
+- Estimate **mutual information** and **total correlation**, decomposed by edge
+  and by tree of the fitted vine.
+- Train your own estimator on the included synthetic copula generators.
+
+## Results at a glance
+
+![Density accuracy, vine likelihood, fitting time and S&P100 likelihood](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_results_density_speed.png)
+
+From the NeurIPS 2026 paper (all numbers use the released `vdc-denoiser-m64-v1`):
+
+| | |
+|---|---|
+| Bivariate density (9 in-library cases) | lower ISE than histogram, KDE and pyvine-TLL at **~6 ms per edge** on a GPU; parametric family selection is more accurate on its own families at ~100x the cost |
+| Families never seen in training | matches per-case TLL refits in held-out likelihood and **roughly halves MI error** |
+| High-dimensional vines (d = 100–500) | **3.3–4.0x faster** than 16-thread pyvine-TLL on one node (749 s vs 2,489 s at d = 500) |
+| S&P100 daily returns (d = 100) | **best held-out likelihood** of the compared methods on random and chronological splits |
+| Information estimation | fewer data-processing-inequality violations and lower additivity error than KSG; TC at d = 50 in **0.71 s** |
+
+Limits are reported alongside: the 64x64 grid bounds accuracy for near-deterministic
+pairs, and chained conditional prediction (VaR, imputation) is not yet competitive.
+See the paper and [the reproduction guide](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md) for every protocol.
+
+![Mutual-information error, total-correlation runtime and self-consistency](https://raw.githubusercontent.com/KempnerInstitute/vine-denoising-copula/main/docs/assets/vdc_results_information.png)
+
+## Installation
+
+```bash
+python -m pip install vine-denoising-copula
+```
+
+Python 3.11 or later with PyTorch 2 is required. A GPU is optional. The base
+install supports pretrained pair densities, vine fitting, likelihoods and
+sampling without pyvinecopulib or plotting/training packages. Optional features:
+
+```bash
+python -m pip install 'vine-denoising-copula[train]'      # synthetic data and training
+python -m pip install 'vine-denoising-copula[baselines]'  # qualified pyvinecopulib 0.7.x
+python -m pip install 'vine-denoising-copula[viz,data]'    # plotting and dataset downloads
+```
+
+Install `vine-denoising-copula`, not the unrelated PyPI project `vdc`. Both
+provide an `import vdc` namespace, so use separate virtual environments.
+Checkpoints remain on Hugging Face and are downloaded and hash-verified on first
+use. For a source installation:
+
+```bash
+git clone https://github.com/KempnerInstitute/vine-denoising-copula.git
+cd vine-denoising-copula
+python -m pip install -e '.[dev,train,data,viz]'
+```
+
+See [getting started](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/GETTING_STARTED.md) for CPU/GPU PyTorch installation.
+The paper reproduction environment retains its recorded dependency versions.
+
+## Quick start
+
+```python
+import numpy as np
+from vdc import load_pretrained_model, estimate_pair_density_from_samples, VineCopulaModel
+
+bundle = load_pretrained_model("vdc-denoiser-m64-v1", device="cpu")   # downloads and hash-checks
+
+# 1) a bivariate copula density from pseudo-observations in [0, 1]^2
+u = np.random.default_rng(0).uniform(size=(2000, 2))
+density = estimate_pair_density_from_samples(bundle, u)              # (64, 64) grid
+
+# 2) a vine on d-dimensional pseudo-observations
+x = np.random.default_rng(1).uniform(size=(2000, 8))
+vine = VineCopulaModel(vine_type="dvine", m=64, device="cpu", batch_edges=True)
+vine.fit(x, bundle.model, diffusion=bundle.diffusion)
+loglik = vine.logpdf(x)                      # per-row log copula density
+samples = vine.simulate(n=1000)              # inverse-Rosenblatt sampling
+```
+
+Pseudo-observations are ranks scaled to (0, 1). Fit marginal transforms on
+training rows and apply them to held-out rows. More: [examples/](https://github.com/KempnerInstitute/vine-denoising-copula/tree/main/examples/) and
+the [user guide](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/USER_GUIDE.md).
+
+## Pretrained models
+
+| Model | Grid | Use | Status |
+|---|---|---|---|
+| [`vdc-denoiser-m64-v1`](https://huggingface.co/hsafaai/vdc-denoiser-m64-v1) | 64x64 | the estimator of all main paper results | released |
+| [`vdc-denoiser-m64-v2`](https://huggingface.co/hsafaai/vdc-denoiser-m64-v2) | 64x64 | retrained linear-grid estimator VDC-64 (paper, Appendix G) | released |
+| [`vdc-denoiser-m128-v2`](https://huggingface.co/hsafaai/vdc-denoiser-m128-v2) | 128x128 | retrained linear-grid estimator VDC-128 (paper, Appendix G) | released |
+
+Every checkpoint is verified by SHA-256 on load. The v2 estimators were trained after the paper's
+main experiments on corrected synthetic data; they use a continuous bilinear density with exact
+h-functions and are selected with `VineCopulaModel.from_pretrained(bundle)`. Their training
+initialization is published as [`vdc-linear-grid-pilot`](https://huggingface.co/hsafaai/vdc-linear-grid-pilot).
+See [docs/MODEL_RELEASES.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/MODEL_RELEASES.md) and [docs/IMPROVED_ESTIMATORS.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/IMPROVED_ESTIMATORS.md).
+
+## Train an estimator
+
+```bash
+# the released estimator (vdc-denoiser-m64-v1)
+python scripts/train_unified.py --config configs/train/denoiser_cond_enhanced.yaml --model-type denoiser
+
+# the retrained linear-grid estimators: pilot, data cache, then each fine-tune
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_pilot.yaml
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_cache.yaml
+python scripts/train_linear_grid_estimator.py configs/train/linear_grid_vdc128_v2.yaml
+```
+
+Configurations and the synthetic training generators are documented in
+[docs/CONFIGURATION.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/CONFIGURATION.md) and [docs/TRAINING_DATA.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/TRAINING_DATA.md);
+the linear-grid recipes, their resources and verification are in [docs/IMPROVED_ESTIMATORS.md](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/docs/IMPROVED_ESTIMATORS.md).
+
+## Reproduce the paper
+
+[`paper/`](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/paper/README.md) contains everything needed to reproduce the NeurIPS 2026
+results: experiment runners with fixed protocols, the scripts and saved outputs that
+regenerate every figure and table, and reference results. Figures and tables
+rebuild from saved outputs on a laptop in minutes:
+
+```bash
+bash paper/figures/make_figures.sh output/figures
+bash paper/tables/make_tables.sh output/tables
+```
+
+## Repository layout
+
+```
+vdc/        library: models, projection (IPFP), vine fitting, sampling, information, training, data
+configs/    training configurations
+scripts/    command-line entry points (training, model and dataset downloads, packaging)
+examples/   runnable examples
+tests/      test suite (run with python -m pytest tests)
+docs/       documentation (also served at kempnerinstitute.github.io/vine-denoising-copula)
+paper/      NeurIPS 2026 reproduction: runners, figure and table generators, saved results
+```
+
+## Citation
+
+```bibtex
+@inproceedings{safaai2026vdc,
+  title     = {Amortized Vine Copulas for High-Dimensional Density and Information Estimation},
+  author    = {Safaai, Houman},
+  booktitle = {Advances in Neural Information Processing Systems},
+  year      = {2026},
+  note      = {arXiv:2604.20568}
+}
+```
+
+## License
+
+MIT; see [LICENSE](https://github.com/KempnerInstitute/vine-denoising-copula/blob/main/LICENSE). This work was supported in part by a gift from the Chan
+Zuckerberg Initiative Foundation to establish the Kempner Institute for the Study of
+Natural and Artificial Intelligence at Harvard University.

vine_denoising_copula-0.4.0/configs/README.md

@@ -0,0 +1,20 @@
+# Configurations
+
+For a new run, start with `examples/train_custom_copula.py` and
+[the configuration guide](../docs/CONFIGURATION.md). That example uses the
+maintained unified trainer and a small model suitable for checking the workflow.
+
+The existing YAML files retain earlier training and inference configurations.
+They are source records, not a list of recommended recipes. In particular, the
+`*_enhanced*` and `enhanced_cnn_cond.yaml` recipes contain `conditional_*` examples
+that the corrected generator rejects. Remove those entries and explicitly choose
+a new family mixture for a new study; do not describe it as exact historical
+retraining. The `data/`, `model/` and `inference/` fragments also serve older
+configuration frontends and cannot all be passed directly to the unified trainer.
+
+Paper reproduction uses the source pins and protocol-specific settings in
+[`paper/`](../paper/), not whichever configuration happens to be present on
+`main`. The training configurations of the paper's corruption and probit
+ablations are kept with it in [`paper/configs/`](../paper/configs/). Pretrained
+inference restores the model's embedded configuration and does not require
+these YAML files.