[Alexander-Mitrofanov]

Refs #285.

This is a draft implementation checkpoint, following the issue's instruction to stop and ask in a PR when questions arise. --outNumberPerSeed is not implemented yet.

The source investigation found that shared ranking discards candidates before seed traceback, so filtering the final output would lose some seeds' best interactions. Model P also ranks site ensembles, which can disagree with both per-seed ensemble ranking and individual-conformation MFE ranking. Selecting an interpretation changes scientific results.

The new implementation plan records the relevant code paths, concrete examples, proposed scope, implementation steps and regression matrix. ChangeLog records this documentation checkpoint. Prediction behavior is unchanged.

Guidance needed

1. Seed membership: Should we rank extensions constrained to each generating seed, including conformations that are not the global MFE at their site, or only seeds present in each site's existing MFE traceback? I propose seed-constrained candidates. When different seeds select different conformations at identical boundaries, should we retain the lowest-energy eligible conformation and report that site once?
2. Model P: Should a seed's candidates be ranked by the full site's ensemble free energy, an ensemble conditioned on containing that seed, or individual-conformation MFE? If conditional ensembles are intended, should reported site energies also become conditional? Current first-seed ownership contributions are not containing-seed partitions. I propose preserving ensemble-based ranking and keeping Zall/probability outputs independent of this reporting limit.
3. Scope and restrictions: Is the proposed scope correct: all dispatched seeded modes, a positive value rejected with --noSeed, evaluation excluded, quotas shared across merged regions/windows and reset with --outPerRegion, then deduplication followed by final overlap/energy/count restrictions without refilling per-seed quotas?

After guidance, the plan is to add a default-zero CLI/OutputConstraint field, collect eligible candidates before global pruning with explicit seed identity and coherent traceback, merge at the agreed scope, then validate against independent short-sequence oracles and the full release/debug suites. Zero must retain the existing execution path and outputs.

Validation of this checkpoint

• git diff --check passed.
• Checked all nine local Markdown links/anchors, UTF-8/LF encoding and ChangeLog summary/date placement.
• Reviewed the referenced dispatch, ranking, seed annotation, ensemble and merge paths against current master (2c4d0ec).
• No C++ build or runtime tests: only documentation changed; implementation tests are specified in the plan.

Awaiting a review answer before implementation, as requested in #285.

[martin-raden]

@Alexander-Mitrofanov

answers

• concerning question 1:
  • outNumberPerSeed should constrain each seed's candidate list that is considered for the final output list. so it is kind of a intermediate energy ranking forwarding only the best to the overall output handler
  • if different seeds select different conformations at identical boundaries, retain the lowest-energy eligible conformation and report that site once
• concerning question 2:
  • energy ranking for ensembles should be done by the ensemble energy for all interactions (for the current left-right boundaries) that use the current seed as their anchor (left most) seed
• concering question 3:
  • Scope and restrictions are correct