Mat Md Monitors

Molecular Dynamics

<!-- mcp-tools-note -->

[!NOTE] Steps written server.tool are MCP tool calls: mace.run_md is the run_md tool of the mace server (mcp__mace__run_md, or mcp__plugin_atomistic-skills_mace__run_md when installed as a plugin). Without a connected server, run the same tools from the shell. Tools named in one command share a process, so a model loaded by load_model stays loaded:

${CLAUDE_SKILL_DIR}/../../venv/run mlip python -m src.mcp_server.cli mace run_md key=value

Goal

To perform stable and accurate molecular dynamics simulations using MLIPs, ensuring physical correctness and avoiding common "explosions" associated with neural network potentials.

Instructions

1. Monitoring Stability

MD stability monitoring is integrated directly into the run_md tool via ASE callbacks. This ensures zero-latency response to instabilities and simplifies the simulation workflow.

• Enable Monitoring: Set monitor=True and specify monitor_type (single string or list).

  • explosion: Safety check. Stops if T > 10,000K or NaN. Recommended for all unstable simulations.
  • equilibration: Convergence check. Stops once temperature and potential energy stabilize (e.g., for production runs).
  • overshoot: Thermostat check. Stops if T deviates significantly from target (T-target > 200K).
  • volume: NPT stability check. Stops if volume expands by 2x or contracts to 0.2x of initial.
  • diffusion: Convergence check for transport properties. Stops once the relative error of diffusivity for a specific specie (default Li) falls below a threshold (default 0.1).
    • Parameters: specie, threshold, check_interval_ps (default 5.0), ignore_ps (initial equilibration to skip, default 5.0).
  • quenching: Linear temperature ramp. Updates the thermostat target every step to move from temperature to temperature_end over a specified number of steps.
    • Best Practice: Use dyn.set_temperature(temperature_K=T) inside the ramping callback. This is critical for thermostats like Langevin to update internal noise/coupling coefficients.
    • Advanced Thermostats: For NoseHooverChainNVT and MTKNPT, where set_temperature might be missing, manual updates to internal attributes (_kT, _Q, _W) are required to keep the damping frequency consistent.

• Example Usage:

  # MACE example with multiple monitors
  mace.run_md(structure, monitor=True, monitor_type=["explosion", "equilibration"])

• Quenching Template (MCP Tool Call):

  {
    "tool": "mace.run_md",
    "arguments": {
      "structure_data": "initial_structure.cif",
      "temperature": 3000.0,
      "steps": 5000,
      "timestep": 2.0,
      "ensemble": "nvt_langevin",
      "monitor": true,
      "monitor_type": "quenching",
      "monitor_params": {
        "temperature_end": 300.0,
        "steps": 5000
      },
      "output_dir": "research/quenching_output"
    }
  }

• Action: When a monitor triggers, the simulation stops immediately with a status: "stopped" and a clear stop_reason in the result dictionary.