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. Set cache_engine to 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 with from_spec_dict(), model= supplies that dependency and extra_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. None requires an override.

  • engine_kwargs (dict of str to Any, optional) – Additional engine constructor arguments. model, hooks, and n_steps are supplied by the strategy.

  • n_steps (int or None, optional) – Default number of dynamics steps. None delegates 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 to False. Cached runtime state is excluded from strategy specs.

build_engine()[source]#

Construct a fresh dynamics engine.

The default builds one engine from engine and build_hooks(). Override for multi-engine or multi-stage strategies.

Returns:

Newly constructed engine configured by this strategy.

Return type:

BaseDynamics

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:

DynamicsStrategy

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. With cache_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. Use cache_engine=False for independent simulations.

Parameters:
  • batch (Batch) – Atomic systems to update in place.

  • n_steps (int or None, optional) – Per-run step-limit override. None uses n_steps.

Returns:

The input batch after dynamics updates.

Return type:

Batch

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]