mdse.md.simulationmanager

Manages the setup and execution of molecular dynamics simulations.

This module provides the SimulationManager class, which is responsible for interpreting a configuration dictionary, setting up an ASE (Atomic Simulation Environment) Atoms object, initializing a calculator, and running the simulation according to the specified ensemble (NVE, NVT, or NPT).

It acts as a high-level interface to ASE’s dynamics and calculator functionalities, streamlining the process of running simulations from a structured configuration.

Classes

SimulationManager(config)

Manages the setup and execution of a single molecular dynamics simulation.
class mdse.md.simulationmanager.SimulationManager(config)

Bases: object

Manages the setup and execution of a single molecular dynamics simulation.

This class interprets a configuration dictionary to set up and run a simulation using ASE. It handles crystal creation (from bulk, file, or list), calculator initialization (EMT, LennardJones, MACE), and execution of dynamics in NVE, NVT, or NPT ensembles.

Parameters:

config (dict) – A dictionary containing the complete configuration for the simulation, typically parsed from a YAML file. It should include sections for ‘CRYSTAL’, ‘SIMULATION’, and ‘ENSAMBLE’.

crystal

The ASE Atoms object representing the constructed system.

Type:

ase.Atoms

Examples

>>> sim_list = main_read("examples/test_file.yaml")

sim_list[0] is the first simulation sim equals the dictionary of the first simulation

>>> sim_item = next(iter(sim_list[0].values()))

sim_item.get() picks the values from the simulation

>>> sim = SimulationManager(sim_item)
>>> sim.simulate_nve()
print_energy()

Print the current energy and temperature of the system.

Displays potential energy, kinetic energy, instantaneous temperature, and total energy per atom.

simulate(distribution=<function MaxwellBoltzmannDistribution>, print_output=False)

Run a molecular dynamics simulation for the selected ensemble.

This method acts as a high-level dispatcher that selects and executes the appropriate simulation routine based on self.ensamble. Supported ensembles are:

  • NVE: microcanonical (constant energy)

  • NVT: canonical (constant temperature)

  • NPT: isothermal-isobaric (constant pressure and temperature)

Parameters:

  • distribution (callable, optional) – Function used to initialize particle velocities. Defaults to MaxwellBoltzmannDistribution.

  • print_output (bool, optional) – If True, prints simulation output at runtime. Defaults to False.

Returns:

Object containing the trajectory and simulation data.

Return type:

ResultMD

Raises:

  • ValueError – If self.ensamble is not one of NVE, NVT, or NPT.

  • Exception – Propagates other unexpected errors from lower-level methods.

Note

The ensemble type is read from the instance attribute self.ensamble. This attribute must be one of 'NVE', 'NVT', or 'NPT'.

The simulation is carried out using one of:

simulate_npt(distribution=<function MaxwellBoltzmannDistribution>, print_output=False)

Run a molecular dynamics simulation in the NPT ensemble using IsotropicMTKNPT integration.

Parameters:

  • distribution (callable, optional) – Function used to initialize velocities (default: MaxwellBoltzmannDistribution).

  • print_output (bool, optional) – If True, prints simulation output at runtime.

Returns:

An object containing the simulation data.

Return type:

ResultMD

Notes

If create_trajectory is True Trajectory snapshots are written to a .traj file with the chemical symbols of the system as the filename. Otherwise the snapshots will be written to a ResultMD

simulate_nve(distribution=<function MaxwellBoltzmannDistribution>, print_output=False)

Run a molecular dynamics simulation in the NVE ensemble using VelocityVerlet integration.

Parameters:

  • distribution (callable, optional) – Function used to initialize velocities (default: MaxwellBoltzmannDistribution).

  • print_output (bool, optional) – If True, prints simulation output at runtime.

Returns:

An object containing the simulation data.

Return type:

ResultMD

Notes

If create_trajectory is True Trajectory snapshots are written to a .traj file with the chemical symbols of the system as the filename. Otherwise the snapshots will be written to a ResultMD

simulate_nvt(distribution=<function MaxwellBoltzmannDistribution>, print_output=False)

Run a molecular dynamics simulation in the NVT ensemble using NoseHooverChainNVT integration.

Parameters:

  • distribution (callable, optional) – Function used to initialize velocities (default: MaxwellBoltzmannDistribution).

  • print_output (bool, optional) – If True, prints simulation output at runtime.

Returns:

An object containing the simulation data.

Return type:

ResultMD

Notes

If create_trajectory is True Trajectory snapshots are written to a .traj file with the chemical symbols of the system as the filename. Otherwise the snapshots will be written to a ResultMD

view_super_crystal()

Visualize the constructed crystal structure.

If the crystal was created as a supercell, this will visualize the entire supercell.

Notes

Requires ASE’s view function to be available.