Release 1.1.0: TVAE KL weight, bounded spawner history, RiteWeight reweighting - #12
Open
namus wants to merge 1 commit into
Open
Release 1.1.0: TVAE KL weight, bounded spawner history, RiteWeight reweighting#12namus wants to merge 1 commit into
namus wants to merge 1 commit into
Conversation
…RiteWeight Three additions and one fix, all default-compatible: every new setting defaults to what the code already did, so existing configuration files are unaffected. spawning.history_window controls how much of the campaign a spawner scores against. The default (null) is unchanged -- the whole history -- while an integer gives PaCS-MD-style cycle-local selection and 0 scores only the current iteration. A coverage objective is only definable over cumulative history, and this makes that claim testable under an otherwise identical loop. adaptive_model.tvae_beta exposes the KL weight in the TVAE objective, loss = mse + beta * kld / n_features. The estimator was previously constructed without this argument, so every run silently used deeptime's default of 1.0 and no user could change it; answering "which beta did you use?" meant reading a dependency's source. The default stays 1.0, and checkpoints written before this release restore to 1.0 rather than to a new default. trails_md.analysis.riteweight implements randomized iterative trajectory reweighting (Kania et al., PNAS 123, e2529246123, 2026), recovering a stationary distribution from adaptively-sampled data without a lag time and without assuming cluster-level Markovianity. It is an independent implementation from the published algorithm; the authors' reference code carries no licence statement and was deliberately not copied. Fixed: the shipped template advertised encoder_hidden_dims [64, 32] and decoder_hidden_dims [32, 64] while the built-in defaults are [256, 128] and [128, 256], so copying the template trained a different network from omitting the block. The template now states the real defaults. trails_md.analysis also exported only `data`, leaving riteweight importable by full module path alone. Docs: new reweighting page (MSM vs RiteWeight, how to build segment pairs without crossing a respawn, and the mis-coverage limitation both share); the TVAE loss written out in full with beta and its per-feature normalisation; an explicit note that lagtime is counted in frames and that time-lagged pairs never span a respawn; a section on cumulative vs cycle-local selection. .zenodo.json added so the archived release carries proper metadata. Tests: 260 passing, including 27 new ones covering the window semantics, beta reaching the estimator and surviving a checkpoint round trip, and RiteWeight's cluster-count independence and recovery of structure finer than its own clustering.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three additions and one fix, all default-compatible. Every new setting defaults to
what the code already did, so existing configuration files and published results are
unaffected.
Added
spawning.history_window— how much of the campaign a spawner scores against.Default (
null) is unchanged: the whole history. An integer gives PaCS-MD-stylecycle-local selection;
0scores only the current iteration. A coverage objectiveis only definable over cumulative history, and this makes that claim testable under
an otherwise identical loop.
adaptive_model.tvae_beta— the KL weight inloss = mse + beta * kld / n_features.The estimator was previously built without this argument, so every run silently used
deeptime's default of
1.0and no user could change it; answering "which beta did youuse?" meant reading a dependency's source. Default stays
1.0; checkpoints writtenbefore this release restore to
1.0rather than to a new default.trails_md.analysis.riteweight— randomized iterative trajectory reweighting(Kania et al., PNAS 123, e2529246123, 2026): a stationary distribution from
adaptively-sampled data without a lag time and without assuming cluster-level
Markovianity, complementing the MSM route. Independent implementation from the
published algorithm; the authors' reference code carries no licence statement and was
deliberately not copied or vendored.
Fixed
encoder_hidden_dims: [64, 32]/decoder_hidden_dims: [32, 64]while the built-in defaults are
[256, 128]/[128, 256], so copying the templatetrained a different network from omitting the block. The template now states the
real defaults.
trails_md.analysisexported onlydata, leavingriteweightimportable by fullmodule path alone.
Documentation
docs/reweighting.md: MSM vs RiteWeight and how each fails, how to build segmentpairs without crossing a respawn, and the limitation both share — neither fixes
mis-coverage.
docs/cv_methods.md: the TVAE loss in full,betaand its per-featurenormalisation,
lagtimecounted in frames (physical lag =lagtime × stride × dt),and an explicit statement that time-lagged pairs never span a respawn.
docs/configuration.md:history_window,tvae_beta,dropout_rate, decoder widths,SPIB hyperparameters, and a section on cumulative vs cycle-local selection — including
that the comparison must be made against aggregate simulation time, not wall clock.
.zenodo.jsonso the archived release carries proper metadata.Tests
260 passing. 27 new: window semantics (including that a window of 0 must not slice to
the whole list), beta reaching the estimator and surviving a checkpoint round trip,
and RiteWeight's cluster-count independence plus recovery of structure finer than its
own clustering.