topo.optimize package

Submodules

topo.optimize.optimize module

Nscale (nscale) optimizer for TOPO coarse-grained models.

Automatically chooses the per-domain and per-interface nscale in domain.yaml — the smallest value on a discrete per-class ladder that keeps every domain and interface folded across ntraj independent trajectories.

This is the canonical optimizer for the package. Use it as a CLI:

topo-optimize -f optimize.ini -o opt_out
python -m topo.optimize -f optimize.ini -o opt_out

or call run_optimizer() from your own script.

The optimizer owns the search logic and drives the package tools as sub-steps, one round at a time:

round loop:
  1. write round_N/domain.yaml with the current nscales
  2. topo.mdrun                 (one multi-copy run -> ntraj chains)
  3. topo.split_chains          (split into per-copy DCDs, in-process)
  4. score Q per domain / per interface  (topo.analysis.native_contacts)
  5. decide: stable units freeze; unstable units climb the ladder
  until all units are stable, or unstable units reach the median fallback.

optimize.ini is a MINIMAL config: a single [OPTIONS] section. The optimizer takes the keys it needs (ntraj, q_threshold, frame_fraction, max_rounds, min_contacts — see CONTROL_TYPES); every other key is a simulation parameter (pdb_file, domain_def, md_steps, sampling, ref_t, …) passed through to each round’s md.ini. Anything unset uses the optimizer’s implicit protocol defaults (IMPLICIT_DEFAULTS / OPT_DEFAULTS). Each round the driver expands optimize.ini into a full round_N/md.ini and writes round_N/domain.yaml with the current nscales.

Per round it also writes one Q time series per trajectory next to its DCD: round_N/traj/Q_<k>.csv (paired with traj_<k>.dcd; columns frame, Q_<domain>..., Q_<d1>-<d2>...) for inspection of the Q values behind each stability decision.

Limitations: the optimization is not resumable — each invocation starts fresh (decide how to checkpoint level[] and completed rounds to add this).

class topo.optimize.optimize.Scorer(pdb, domain_yaml, cutoff=4.5, local_separation=3, tolerance=1.2)

Bases: object

Per-domain / per-interface native contacts, and per-trajectory folding.

static folded_fraction(series, q_threshold)

Fraction of frames folded per unit, from a q_per_frame() result. NaN (no native contacts) is treated as folded (not applicable).

static label(key)

Column label for a scoring unit, e.g. Q_D1 or Q_D1-D2.

Parameters:

key (tuple) – A ("domain", name) or ("interface", (a, b)) unit key.

Returns:

"Q_<name>" for a domain, "Q_<a>-<b>" for an interface.

Return type:

str

n_contacts(key)

Number of native contacts detected for a unit (domain or interface).

q_per_frame(psf, dcd)

Return {unit_key: np.array of Q per frame} for one trajectory.

unit_keys()

Return all scoring-unit keys (domain and interface) as a list.

Returns:

The ("domain", name) and ("interface", (a, b)) keys.

Return type:

list

topo.optimize.optimize._optimize_loop(log, pdb, domain_path, raw_cfg, sim_options, out_root, ntraj, q_threshold, frame_fraction, max_rounds, min_contacts, device, md_steps, python_exe)

Core round loop. Separated from resource setup so the log file is always closed (see run_optimizer()).

topo.optimize.optimize.normalize_class(raw)

Map a user-written structural class to a LADDER key.

topo.optimize.optimize.nscale_for(class_key, level)

Nscale for a given class and ladder level index (>=5 -> fallback).

topo.optimize.optimize.optimize(argv=None)

Console entry point (topo-optimize / python -m topo.optimize).

topo.optimize.optimize.parse_args(argv=None)

Parse command-line arguments for the topo-optimize entry point.

A bare invocation (no arguments) prints help and exits.

Parameters:

argv (list of str, optional) – Argument list to parse; defaults to sys.argv[1:].

Returns:

Parsed arguments: config, outdir, device, md_steps and python.

Return type:

argparse.Namespace

topo.optimize.optimize.read_optimize_config(path)

Read a minimal optimize.ini.

Returns:

• pdb (str absolute path to the reference PDB)

• domain (str absolute path to the initial domain.yaml)

• sim_options (dict simulation parameters for the per-round md.ini) – (file overrides IMPLICIT_DEFAULTS; controls removed)

• controls (dict optimizer controls (ntraj, thresholds, max_rounds, …))

topo.optimize.optimize.run_md(round_dir, md_ini, python_exe)

Run one multi-copy MD (topo.mdrun) as a subprocess.

Runs with cwd=round_dir so that, when no stride_output_file is configured, the STRIDE file the model build caches (“{pdb_stem}_stride.dat”) lands predictably inside round_dir, where the caller can pick it up to reuse in later rounds. All paths in the md.ini are absolute, so the working directory is otherwise irrelevant. A fresh subprocess per round also isolates each OpenMM/GPU context.

topo.optimize.optimize.run_optimizer(config, outdir='opt_out', device=None, md_steps=None, python_exe=None)

Run the nscale optimization end to end.

Parameters:

• config (str or Path) – Path to the minimal optimize.ini.

• outdir (str or Path, optional) – Optimization root directory (created if missing). Default opt_out.

• device (str, optional) – Override the simulation device (CPU/GPU) for every round.

• md_steps (int, optional) – Override md_steps for every round (useful for quick test runs).

• python_exe (str, optional) – Python interpreter used to launch topo.mdrun subprocesses. Defaults to the current interpreter (sys.executable).

Returns:

• final_yaml (Path) – Path to the written domain_optimized.yaml.

• converged (bool) – True if every (non-frozen) unit reached stability within max_rounds.

topo.optimize.optimize.run_subprocess(cmd, log_path, label, cwd=None)

Run cmd, streaming combined stdout/stderr to log_path; raise on failure.

topo.optimize.optimize.write_domain_yaml(path, raw_cfg, interfaces, nscale_dom, nscale_int)

Write a domain.yaml that keeps residues/class from the input and sets the current per-domain and per-interface nscales.

topo.optimize.optimize.write_round_ini(path, base_options, overrides)

Write a per-round md.ini = base [OPTIONS] with overrides applied.

Module contents

TOPO nscale optimizer.

Exposes optimize(), the console entry point, available from the shell as topo-optimize -f optimize.ini or python -m topo.optimize -f optimize.ini, and run_optimizer(), the importable core. The reusable building blocks (Scorer, read_optimize_config(), the nscale LADDER, …) are re-exported for programmatic use.