Skip to content

Modularize - #4

Merged
carlocamilloni merged 5 commits into
mainfrom
modularize
Sep 19, 2026
Merged

carlocamilloni merged 5 commits into
mainfrom
modularize

Conversation

@carlocamilloni

Copy link
Copy Markdown
Member

No description provided.

The single maxcal_poisson.py mixed three separate analyses.  Split into a
package whose modules share maxcal/core.py (trajectory parsing, attempt
counting, the tilt, survival/KS statistics, status codes, common CLI args):

  maxcal-stitch     (maxcal/stitching.py) thinning: lambda_min, attempt
                    statistics, the (Q‡, lambda) decision map
  maxcal-reweight   (maxcal/reweight.py)  MaxCal weights on whole
                    trajectories: lambda*, N_eff, per-trajectory weights
  maxcal-committor  (maxcal/committor.py) model/corrected committor, TS
                    location, committor-based TSE frames
  maxcal-joint      (maxcal/joint.py)     unchanged behaviour
  maxcal-target     (maxcal/target.py)    unchanged behaviour

Each module has a main() and runs as python -m maxcal.<module>; the package
re-exports the shared functions, so 'import maxcal as m' gives m.attempts,
m.stitch, m.cv_curve, m.ts_location as before.  Per-trajectory weights are now
written by maxcal-reweight (weights_qts*.csv) next to the TSE frames.

- tests updated to the package; regtest runs the three executables and keeps
  one reference per tool (reference_stitching.csv, reference_reweight.csv)
- notebook, example script, README (tool table, per-tool options and outputs)
  and pyproject (packages + five console scripts, version 0.2.0)
tests/synthetic.py gains write_rate_dataset(): twelve PDZ2-like systems built
from the experimental kon/koff and the model rates of the paper's Table 1
(the unbinding tau of EQVTAV/L18A is taken from Table 1, the SI figure caption
being inconsistent with it), with seeded exponential times.

tests/test_target_regtest.py runs maxcal-target on that dataset and compares
summary.csv with tests/regtest/reference_target.csv, plus sanity checks: every
weighted mean equals its target, needed factors lie in a reachable range,
N_eff > 20 of 50, and the spread of the log factors (the model's own
per-system error) is bounded.
…est data

Interactive walkthrough of maxcal-target on the twelve PDZ2-like systems built
by tests/synthetic.py (the same dataset as its regression test):

- experimental vs model rates as the tool reads them (systems.csv)
- clock calibration: one global factor, the three --clock modes compared, and
  the per-system residual factors against the f = 2 hard limit
- weights per system and direction (slider): model, reweighted and target CDFs,
  the weights themselves, N_eff / max weight / tail gap, target vs mean mode
- the cost of the correction: the 24 points against N_eff/N = 2f - f^2
- using the weights on a (synthetic) structural observable, with bootstrap
  errors and a colour map of which trajectories gain weight
- K_D before and after: matching both directions puts the affinities on the
  diagonal, with mild weights

tests/test_notebook.py now parametrises over both notebooks; README documents
the new notebook.
The corrected-committor formula in section 2.10 used \left( ... \right), which
GitHub's math rendering reports as a missing parenthesis.  Plain parentheses
render identically, so they are used everywhere now (sections 2.4, 2.10, 6.2,
6.4), together with \! removal; all 18 display equations parse in KaTeX strict
mode.  The two cases of the formula are also split into separate blocks, which
reads better on narrow screens.  Section 2.10 still referred to --tse-lams,
which modularisation replaced by --lams / --from-stitch.
Derivation (minimum relative entropy onto a fully specified target: the weights
are the importance ratio, conditional structure is preserved), the time-scale
calibration and why only the residual factors are physical, the closed-form
cost N_eff/N = 2f - f^2 with the f = 2 hard limit, the diagnostics, what the
method can and cannot do, usage and outputs, a worked example on the twelve
PDZ2-like systems (clock factor, per-system factors and N_eff, how to join the
weights to a structural analysis), the tests, and references.

README section 7 now points at it as the detailed version.
@carlocamilloni
carlocamilloni merged commit 1b42e00 into main Sep 19, 2026
3 checks passed
@carlocamilloni
carlocamilloni deleted the modularize branch September 19, 2026 08:54
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.

2 participants