ASE driver¶

The ASE driver embeds MaxwellLink in the Atomic Simulation Environment, enabling Born–Oppenheimer molecular dynamics with any ASE-compatible calculator. The implementation is provided by maxwelllink.mxl_drivers.python.models.ASEModel.

Note

During the simulation, the ASE driver receives the electric field, applies

\[\mathbf{F}_i = Q_i \widetilde{\mathbf{E}},\]

and returns

\[\mathrm{d}\boldsymbol{\mu}/\mathrm{d}t = \sum_i Q_i \mathbf{v}_i,\]

where \(Q_i\) and \(\mathbf{v}_i\) are the partial charge (defined in charges in Parameters) and velocity of atom \(i\).

Requirements¶

ase (install via conda install -c conda-forge ase) for the Atomic Simulation Environment.
The desired calculator backends (Psi4, ORCA, DFTB+, …) must be installed and discoverable by ASE.

Usage¶

Socket mode¶

mxl_driver --model ase --port 31415 \
  --param "atoms=${PWD}/tests/data/hcn.xyz, calculator=psi4, \
           calc_kwargs=method=b3lyp,basis=sto-3g, \
           charges=[1.0 -1.0 0.0], temperature_K=300, \
           recompute_charges=false"

Non-socket mode¶

mxl.Molecule(
    driver="ase",
    driver_kwargs={
        "atoms": "tests/data/hcn.xyz",
        "calculator": "psi4",
        "calc_kwargs": "method=b3lyp,basis=sto-3g",
        "charges": "[1.0 -1.0 0.0]",
        "temperature_K": 300.0,
    },
    # ...
)

Parameters¶

Name	Description
`atoms`	ASE `Atoms` instance or path to a structure file readable by `ase.io.read` (`.xyz`, `.pdb` …). Required.
`calculator`	Name of the ASE calculator to wrap (`psi4`, `orca`, `dftb` …). Default: `psi4`.
`calc_kwargs`	Comma-separated `key=value` pairs (or a dict) forwarded to the calculator constructor. Default: `""`.
`charges`	Optional per-atom charges specified as a space-separated list in square brackets, e.g. `"[0.3 -0.3 0.0]"`. Default: `None`.
`recompute_charges`	When `True` the driver queries the wrapped calculator for charges at every step instead of using `charges`. Default: `False`.
`temperature_K`	Initial temperature passed to `MaxwellBoltzmannDistribution` before propagation. Default: `0.0`.
`verbose`	When `True` print calculator setup and integration diagnostics. Default: `False`.
`checkpoint`	When `True` write positions/velocities to `ase_checkpoint_id_<n>.npz`. Default: `False`.
`restart`	When `True` try to restore the most recent checkpoint on start-up. Default: `False`.

Returned data¶

time_au – Simulation time in atomic units.
energy_au – Electronic energy returned by the wrapped ASE calculator.
mux_au, muy_au, muz_au – Molecular dipole components in atomic units half a time step after the force evaluation time.
mux_m_au, muy_m_au, muz_m_au – Molecular dipole components in atomic units at the force evaluation time.
temperature_K – Instantaneous temperature reported by ASE.

Notes¶

Provide either charges or set recompute_charges=true; the driver raises an error if no charges are available.
Calculator-specific options can be supplied via calc_kwargs=... or as additional key=value pairs in --param; unrecognised tokens are forwarded to the calculator constructor.