nvalchemi.dynamics.DynamicsStrategy#
- class nvalchemi.dynamics.DynamicsStrategy(*, model, engine=None, engine_kwargs=<factory>, n_steps=None, extra_hooks=<factory>, cache_engine=False)[source]#
Base class for declarative, serializable dynamics strategies.
A strategy stores the configuration needed to construct a dynamics engine. By default, each
run()constructs a fresh engine. Setcache_engineto continue the same simulation with its engine state preserved across runs.to_spec_dict()represents hooks as reconstructible constructor specs while the live model remains a runtime dependency. When restoring withfrom_spec_dict(),model=supplies that dependency andextra_hooks=appends runtime hooks.- Parameters:
model (BaseModelMixin) – Potential model used by the dynamics engine.
engine (type of BaseDynamics or None, optional) – Engine class for the default
build_engine()implementation. Serialized as an importable dotted path.Nonerequires an override.engine_kwargs (dict of str to Any, optional) – Additional engine constructor arguments.
model,hooks, andn_stepsare supplied by the strategy.n_steps (int or None, optional) – Default number of dynamics steps.
Nonedelegates termination to the constructed engine.extra_hooks (sequence of Hook or None, optional) – Ordered runtime hooks added to the constructed engine.
cache_engine (bool, optional) – Reuse the first engine built by
run()to continue the same simulation, preserving optimizer or thermostat state and step counts. Defaults toFalse. Cached runtime state is excluded from strategy specs.
- build_engine()[source]#
Construct a fresh dynamics engine.
The default builds one engine from
engineandbuild_hooks(). Override for multi-engine or multi-stage strategies.- Returns:
Newly constructed engine configured by this strategy.
- Return type:
- Raises:
NotImplementedError – If no engine class is configured and this method is not overridden.
- build_hooks()[source]#
Build the ordered hook list for the default engine builder.
- Returns:
A new list containing the configured extra hooks. Override to add strategy-specific hooks.
- Return type:
list of Hook
- classmethod from_spec_dict(spec, *, model, extra_hooks=None)[source]#
Rebuild a strategy from
to_spec_dict()output.- Parameters:
spec (mapping of str to Any) – JSON-decoded strategy configuration.
model (BaseModelMixin) – Weighted potential model to attach to the restored strategy.
extra_hooks (sequence of Hook or None, optional) – Runtime hooks appended after hooks rebuilt from serialized specs.
- Returns:
Freshly validated strategy instance.
- Return type:
- model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'revalidate_instances': 'never', 'validate_assignment': False}#
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- model_post_init(context, /)#
This function is meant to behave like a BaseModel method to initialise private attributes.
It takes context as an argument since that’s what pydantic-core passes when calling it.
- Parameters:
self (BaseModel) – The BaseModel instance.
context (Any) – The context.
- Return type:
None
- run(batch, n_steps=None)[source]#
Run an engine on
batch, reusing it when caching is enabled.With
cache_engine=False, every call builds a fresh engine. Withcache_engine=True, only the first call builds an engine, and later calls reuse its state and original configuration to continue the same simulation. Optimizer or thermostat state and step counts are retained. The caller must keep the batch’s system/group membership and ordering, device, and dtype aligned with the cached engine’s state. Compatibility is not validated automatically, and changing the batch does not reset engine state. Usecache_engine=Falsefor independent simulations.
- to_spec_dict()[source]#
Serialize declarative strategy fields to a JSON-ready dictionary.
Hooks are represented by constructor specs. The live model, cached engine, and mutable hook state are not included. Subclasses with arbitrary configuration objects must provide Pydantic serializers or override this method.
- Returns:
JSON-ready strategy configuration.
- Return type:
dict[str, Any]