用途:nvalchemi 的 Hooks 是回调机制,在每步工作流的特定阶段触发,用于观察或修改批次状态,而无需改动引擎本身。该协议框架通用,动力学引擎传入 DynamicsContext,自定义引擎可传入 HookContext 或其子类。
主要能力:任何具备 frequency、stage 属性和 call(ctx, stage) 的对象都满足 Hook 协议。钩子在 step_count % frequency == 0 时触发(第 0 步全部触发),ON_ADMISSION 例外,每次准入触发一次。DynamicsStage 提供 11 个生命周期阶段,包括 ON_ADMISSION、BEFORE_STEP、BEFORE/AFTER_PRE_UPDATE、BEFORE/AFTER_COMPUTE、BEFORE/AFTER_POST_UPDATE、AFTER_STEP、ON_CONVERGE、ON_GRADUATE。内置钩子涵盖安全(NaNDetectorHook、MaxForceClampHook)、偏置势(BiasedPotentialHook,已弃用,建议改用 nvalchemi.enhanced_sampling)、观察(LoggingHook、SnapshotHook、EnergyDriftMonitorHook)、周期边界(WrapPeriodicHook)与性能分析(StageTimingHook、TorchProfilerHook)。
使用方式:可在构造时通过 hooks=[...] 传入,或构造后调用 dynamics.register_hook(...);同阶段多个钩子按注册顺序执行。自定义钩子可直接实现协议,或用 _runs_on_stage 支持多阶段,或用 plum.dispatch 处理多种上下文/阶段类型。建议注册顺序为:偏置、安全钳制、NaN 检测、周期包裹、观察者、性能分析。
限制:ON_ADMISSION 忽略基于步数的频率门控;ON_GRADUATE 忽略 frequency,且 DomainParallel 不派发该阶段;ON_CONVERGE 仅限子阶段;FusedStage 中融合级钩子在各共享边界包裹子阶段钩子,修改型子阶段钩子须将写入限制在自身掩码内。BiasedPotentialHook 的 bias_fn 不产生应力,在 NPT/NPH 恒压器下会静默出错。具体平台与收费信息暂未提供。