seamm_mdi package

Submodules

seamm_mdi.mdi_engine module

Driver-side MDI engine facility for SEAMM.

MDIEngine launches an MDI engine once and drives it for many energy/force evaluations. The driver is the MDI listener: it binds a TCP port and the engine connects back to it (the direction that works both locally and, later, from a compute node dialing back to the JobServer). Unit conversions are handled here, in one place, via seamm_util.Q_.

Local mode only for now: the engine is launched as a subprocess on the same host (localhost). Remote/queue launching through the SEAMM executor is planned.

class seamm_mdi.mdi_engine.MDIEngine(build_argv, elements, *, name='SEAMM', hostname='localhost', timeout=60.0, logger=<Logger seamm_mdi.mdi_engine (WARNING)>)

Bases: object

Drive an MDI engine for repeated energy/force evaluations.

Parameters:

• build_argv (callable(hostname, port) -> list[str]) – Builds the argv that launches the engine wrapper, pointed at the driver’s hostname/port (e.g. from a program step’s get_mdi_engine_command). The engine must be -role ENGINE so it connects back to the driver.

• elements (sequence[int]) – Atomic numbers of the atoms, in coordinate order. Fixed for the session.

• name (str) – The MDI driver name.

• hostname (str) – The host the engine should dial (localhost in local mode).

• timeout (float) – Seconds to wait for the engine to connect before giving up.

• logger (logging.Logger)

Notes

One active engine per process (MDI keeps global state). Use as a context manager, or call start() / close() explicitly.

close()

Tell the engine to exit and reap the process.

energy(units='hartree')

Return the total energy in units (default MDI-native hartree).

forces(units='hartree/bohr')

Return the forces as an (n, 3) array in units (default hartree/bohr).

hessian(units='hartree/bohr**2')

Return the analytic Cartesian Hessian as a (3n, 3n) array in units (default hartree/bohr^2), via the engine’s custom <HESSIAN command.

Raises NotImplementedError if the engine does not support <HESSIAN – the caller should then finite-difference forces() instead.

set_cell(vectors, units='bohr')

Send the periodic cell (lattice) vectors to the engine (>CELL).

Parameters:

• vectors ((3, 3) array-like) – The three cell vectors as rows, in units.

• units (str) – The units of vectors (default MDI-native bohr).

Notes

Not every engine understands >CELL; check supports() first when a molecular-only engine is a possibility. The MDI convention is that the engine treats the system as fully periodic once a cell is set.

set_coordinates(xyz, units='bohr')

Send the atomic coordinates to the engine.

Parameters:

• xyz ((n, 3) or (3n,) array-like) – The coordinates, in units.

• units (str) – The units of xyz (default MDI-native bohr).

start()

Listen, launch the engine, accept its connection, send the topology.

stress(units='hartree/bohr**3')

Return the stress tensor as a (3, 3) array in units (default hartree/bohr^3), via <STRESS.

The engine returns the MDI pressure-sign convention; a non-periodic engine typically returns zeros.

supports(command, node='@DEFAULT')

Whether the engine supports an MDI command (e.g. "<HESSIAN").

Lets a driver discover an optional capability at runtime rather than being told in advance – e.g. use the analytic Hessian if the engine offers one, else finite-difference the forces.

Module contents

seamm_mdi – a reusable MDI driver facility for SEAMM.