eon.amsel_superbasin_gate

amsel discover_decide for a superbasin graph and for one state’s table.

discover_decide_for_superbasin is the only gate. It calls amsel.discover_decide_status and returns one status from DISCOVER_DECIDE_STATUSES.

• accepted / retightened — the candidate is one basin.

• split_required — use the primary transient set anchored at the entry.

• rejected_no_metastable_basin — ordinary single-state KMC.

• fallback_single — a failed amsel call (available is true).

• unavailable — amsel is not importable, or on_error is unavailable_mcamc (available is false).

[amsel] discover_decide does not require use_mcamc. amsel_discover_exit reads the current state’s process table. A barrier strictly below e_min_init is in-basin. A higher barrier is an exit. A table with no in-basin edge still exits: the transient set is the entry state and the products are absorbing. A product column of -1 is that exit too: the absorbing label is a 32-bit id, and the hop creates the product state from the process id. The exit time and channel come from MRM (mean time) or FPTA (one sample). The kernels are the amsel package. A missing package logs unavailable and returns no exit.

Module Contents

Classes

AmselExit

One basin exit chosen by MRM or FPTA.

Functions

build_graph_from_superbasin	Return (candidate_states, rate_triples, ts_energies) for amsel.
discover_decide_for_superbasin	Run amsel.discover_decide_status; return a structured result dict.
load_persisted_split
persist_split
apply_gate_to_superbasin	Mutate superbasin in-place for split_required; raise on reject.
status_pair	Return true when (status, available) is in the one vocabulary.
basin_view_from_state	States reached by barriers below e_min_init, plus exit products.
amsel_discover_exit	Log amsel discover_decide status and maybe return an MRM or FPTA exit.

Data

logger
DISCOVER_DECIDE_STATUSES

API

eon.amsel_superbasin_gate.logger

‘getLogger(…)’

eon.amsel_superbasin_gate.DISCOVER_DECIDE_STATUSES

(‘unavailable’, ‘fallback_single’, ‘accepted’, ‘retightened’, ‘split_required’, ‘rejected_no_metasta…

exception eon.amsel_superbasin_gate.AmselSuperbasinReject(status: str, detail: str = '')

Bases: RuntimeError

Raised when discover_decide rejects the candidate superbasin.

Initialization

Initialize self. See help(type(self)) for accurate signature.

eon.amsel_superbasin_gate.build_graph_from_superbasin(superbasin: Any, entry_number: int) → tuple[list[int], list[tuple[int, int, float]], list[float]]

Return (candidate_states, rate_triples, ts_energies) for amsel.

eon.amsel_superbasin_gate.discover_decide_for_superbasin(superbasin: Any, entry_state: Any, *, e_min_init: float = 0.5, e_min_step: float = 0.05, e_min_floor: float = 0.05, cv_threshold: float = 10.0, on_error: str = 'fallback_single') → dict[str, Any]

Run amsel.discover_decide_status; return a structured result dict.

Keys: status (str), primary_transient (list[int]|None), raw (tuple|None), available (bool). If amsel is not importable, available=False and status is unavailable (caller should proceed with legacy MCAMC).

on_error decides what a failing amsel call returns: raise re-raises, unavailable_mcamc reports amsel as unavailable so MCAMC runs as before, and fallback_single (the default) reports fallback_single so the caller takes an ordinary single-state step.

eon.amsel_superbasin_gate.load_persisted_split(superbasin: Any) → list[int] | None

eon.amsel_superbasin_gate.persist_split(superbasin: Any, keep: list[int]) → None

eon.amsel_superbasin_gate.apply_gate_to_superbasin(superbasin: Any, entry_state: Any, decision: Mapping[str, Any]) → str

Mutate superbasin in-place for split_required; raise on reject.

Returns the status string for logging.

eon.amsel_superbasin_gate.status_pair(status: str, available: bool) → bool

Return true when (status, available) is in the one vocabulary.

class eon.amsel_superbasin_gate.AmselExit(exit_number: int, proc_id: int, product_number: int, mean_time: float, time_is_sample: bool, barrier: float, rate: float, kernel: str)

One basin exit chosen by MRM or FPTA.

Initialization

eon.amsel_superbasin_gate.basin_view_from_state(entry_state: Any, resolve_state: Callable[[int], Any] | None, e_min_init: float) → Any

States reached by barriers below e_min_init, plus exit products.

Exit products are candidate ids with an empty process table, so their own edges are not fed to discover_decide. A barrier strictly below e_min_init enqueues the product when the state list can resolve it.

eon.amsel_superbasin_gate.amsel_discover_exit(entry_state: Any, resolve_state: Callable[[int], Any] | None, config: Any, uniform: Callable[[], float] | None = None) → eon.amsel_superbasin_gate.AmselExit | None

Log amsel discover_decide status and maybe return an MRM or FPTA exit.

The log line is written for every call, including a table with one state and a missing amsel package. An in-basin edge is a barrier strictly below e_min_init. With such an edge, an exit is returned when discover accepts the basin, retightens it, or splits it. With no such edge, a barrier at or above the cutoff is a direct exit. The transient set is the entry state, the products are absorbing, and the logged status is accepted. A product column of -1 uses a 32-bit absorbing label. The process id is unchanged.

debug_use_mean_time selects MRM. Otherwise the clock is one FPTA sample. The other kernel is used when the selected one is missing. A missing package logs unavailable and returns no exit.