Skip to content

Release 1.1.0: TVAE KL weight, bounded spawner history, RiteWeight reweighting - #12

Open
namus wants to merge 1 commit into
mainfrom
release-1.1.0
Open

Release 1.1.0: TVAE KL weight, bounded spawner history, RiteWeight reweighting#12
namus wants to merge 1 commit into
mainfrom
release-1.1.0

Conversation

@namus

@namus namus commented Aug 2, 2026

Copy link
Copy Markdown
Member

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-style
cycle-local selection; 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 — the KL weight in loss = mse + beta * kld / n_features.
The estimator was previously built 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. Default stays 1.0; checkpoints written
before this release restore to 1.0 rather 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

  • The shipped template advertised encoder_hidden_dims: [64, 32] / decoder_hidden_dims: [32, 64]
    while the built-in defaults are [256, 128] / [128, 256], so copying the template
    trained a different network from omitting the block. The template now states the
    real defaults.
  • trails_md.analysis exported only data, leaving riteweight importable by full
    module path alone.

Documentation

  • New docs/reweighting.md: MSM vs RiteWeight and how each fails, how to build segment
    pairs without crossing a respawn, and the limitation both share — neither fixes
    mis-coverage.
  • docs/cv_methods.md: the TVAE loss in full, beta and its per-feature
    normalisation, lagtime counted 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.json so 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.

…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant