Rigorous.ComparePaths

Rigorous.ComparePaths#

Rigorous.ComparePaths.py

Side-by-side validation of optimize_rigorously() execution paths (subprocess vs in-process), introduced as Phase 2.5 of the split-architecture plan. See molass-library/Copilot/DESIGN_split_optimizer_architecture.md.

Single-cell entry point for the 13h_split_architecture_validation workflow:

from molass.Rigorous import compare_optimization_paths

result = compare_optimization_paths(

decomp, rgcurve, method=’NS’, niter=20, paths=(‘subprocess’, ‘in_process’), trimmed_ssd=trimmed,

) result.summary_table() result.plot_convergence() result.plot_components() result.assert_parity(fv_rtol=1e-2)

Copyright (c) 2026, SAXS Team, KEK-PF

class PathResult(label, in_process, analysis_folder, run_info, conv, best, rgs, elapsed, completed)#

Bases: object

Result of a single optimize_rigorously call inside a comparison.

label#

Path label ('subprocess' or 'in_process').

Type:

str

in_process#

Resolved in_process flag passed to optimize_rigorously.

Type:

bool

analysis_folder#

Absolute path to the analysis folder used by this run.

Type:

str

run_info#

The RunInfo returned by optimize_rigorously.

Type:

RunInfo

conv#

Convergence info returned by Decomposition.plot_convergence; None if results never materialised within timeout.

Type:

object or None

best#

Best-result decomposition from load_best_rigorous_result; None if no result.

Type:

Decomposition or None

rgs#

Component Rg values from best.get_rgs(); None if no result.

Type:

list[float] or None

elapsed#

Wall-clock seconds for the optimize_rigorously call.

Type:

float

completed#

True iff conv and best are both populated.

Type:

bool

label#
in_process#
analysis_folder#
run_info#
conv#
best#
rgs#
elapsed#
completed#
property best_fv#
property best_sv#
class ComparisonResult(results, niter, method, rgcurve)#

Bases: object

Result of running optimize_rigorously along multiple paths.

Returned by compare_optimization_paths().

results#

One entry per path, in the order requested.

Type:

list[PathResult]

niter#

niter value used for both runs.

Type:

int

method#

Solver method used for both runs.

Type:

str

rgcurve#

Rg curve passed to the runs (kept for plot_components).

Type:

object

by_label(label)#
live_status(label=None)#

Return RunInfo.live_status() snapshots for the comparison.

Convenience wrapper so callers don’t have to spell out result.by_label('subprocess').run_info.live_status().

Parameters:

label (str, optional) – If given, return the single dict for that path (e.g. 'subprocess' or 'in_process'). If None (default), return {label: status_dict, ...} for every path that has a run_info available.

Returns:

Either a single live_status dict (when label is given) or a mapping of label → live_status dict.

Return type:

dict

Examples

result = compare_optimization_paths(decomp, rgcurve, niter=20)
result.live_status()                      # both paths
result.live_status('subprocess')          # one path
aicKernelEval(expression="result.live_status()")
summary_table(file=None)#

Print a side-by-side summary table.

The format matches the hand-rolled table in 13h_split_architecture_validation cell [8] so existing readers see the same shape.

Parameters:

file (file-like, optional) – Destination for the printed table; defaults to sys.stdout.

plot_convergence(figsize=None)#

Side-by-side convergence plot, one panel per path.

plot_components()#

Plot best-result components for each completed path.

assert_parity(fv_rtol=0.01, sv_atol=1.0, rg_atol=0.5)#

Assert that all path results agree within tolerances.

Intended for the validation workflow: a passing assertion means the in-process path reproduces the subprocess path’s result on the given problem (within stochastic tolerance).

Parameters:

  • fv_rtol (float, optional) – Relative tolerance on best_fv between paths. Default 1e-2.

  • sv_atol (float, optional) – Absolute tolerance on best_sv. Default 1.0 SV point.

  • rg_atol (float, optional) – Absolute tolerance on per-component Rg in ångström. Default 0.5 Å.

Raises:

AssertionError – If any path is incomplete or any pairwise comparison exceeds tolerance.

compare_optimization_paths(decomposition, rgcurve, *, method='NS', niter=20, paths=('subprocess', 'in_process'), trimmed_ssd=None, analysis_folder_prefix=None, timeout=600, clear_jobs=True, frozen_components=None, function_code=None, monitor=False, debug=False, **kwargs)#

Run optimize_rigorously along each requested path and compare.

Single-cell entry point for split-architecture validation. Each path runs the same optimization problem, results are gathered into a ComparisonResult, and the summary table / convergence plot / parity assertion are available as one-line method calls.

Parameters:

  • decomposition (Decomposition) – Initial decomposition (from corrected.quick_decomposition).

  • rgcurve (Curve) – Rg component curve.

  • method (str, optional) – Solver method passed to optimize_rigorously. Default 'NS'.

  • niter (int, optional) – Iteration count for both runs. Default 20.

  • paths (sequence of str, optional) – Paths to run. Each entry must be one of 'subprocess', 'in_process' (or aliases 'sub' / 'inp'). Default ('subprocess', 'in_process').

  • trimmed_ssd (SecSaxsData, optional) – Trimmed SSD (passed through to optimize_rigorously).

  • analysis_folder_prefix (str, optional) – If given, each path’s analysis folder is f"{analysis_folder_prefix}_{label}_{HHMMSS}". If None, a temp-style analysis_split_{label}_{HHMMSS} is used in the current working directory.

  • timeout (float, optional) – Per-path timeout passed to wait_for_rigorous_results. Default 600 s.

  • monitor (bool, optional) – Forwarded to optimize_rigorously for the subprocess leg. Default False — the comparison does not need the live MplMonitor dashboard, and skipping it avoids the matplotlib / ipywidgets fragility that has crashed the kernel on accept events (Python 3.14 + degraded widget CDN). Set True only if you also want the dashboard while the comparison runs.

  • clear_jobs – Passed through to optimize_rigorously.

  • frozen_components – Passed through to optimize_rigorously.

  • function_code – Passed through to optimize_rigorously.

  • debug – Passed through to optimize_rigorously.

  • **kwargs – Passed through to optimize_rigorously.

Return type:

ComparisonResult