Ab-initio MD

Perform ab initio molecular dynamics (MD) simulations using machine learning force fields to study atomic motion, thermodynamic properties, and phase transitions in materials at finite temperature.

Atomic Tessellator offers the following models:

The Atomic Tessellator MD module provides:

• Single Temperature Simulations - Run MD at constant temperature
• Annealing Simulations - Cool structures through temperature ranges
• Multiple Ensembles - NPT (constant pressure) and NVT (constant volume)
• Advanced Thermostats - Langevin, Berendsen, Bussi-Donadio-Parrinello, Nosé-Hoover
• Flexible Output Formats - XYZ, Extended XYZ, NetCDF trajectory formats

1. Anatomy of an MD Simulation

from atomict.simulation.md import create_md_simulation
from atomict.simulation.models import MODEL_ORB_V3_CONSERVATIVE, MODEL_ESEN_30M_OAM

result = create_md_simulation({
    "project": "your-project-id",
    "source_geometry_id": "your-structure-id",
    "name": "Basic MD Simulation",
    "description": "description",
    "mode": 0,
    "temperature": 300.0,
    "num_steps": 10000,
    "timestep_fs": 1.0,
    "calculator": MODEL_ORB_V3_CONSERVATIVE,
    "ensemble_type": 0,
    "thermostat_type": 0,
    "barostat_type": 0,
    "barostat_time_fs": 100.0,
    "thermostat_time_fs": 100.0,
    "output_format": 1,
})

2. Parameters

2.1 Simulation Modes

The mode parameter determines the type of temperature profile used during the MD simulation. Choose between constant temperature equilibrium dynamics or temperature annealing protocols.

Annealing Configuration

When using annealing mode (mode = 1), you must specify temperature parameters instead of the single temperature used in equilibrium simulations:

• high_temperature - Starting temperature in Kelvin
• low_temperature - Final temperature in Kelvin
• num_intervals - Number of cooling intervals
• high_temperature_steps - Steps at initial temperature
• annealing_steps - Total steps for annealing process

# Annealing simulation from 800K to 300K
result = create_md_simulation({
    "project": "your-project-id",
    "source_geometry_id": "your-structure-id",
    "name": "Annealing Simulation",
    "description": "Cool from 800K to 300K over 5 intervals",
    "mode": 1,                        # Annealing mode
    "high_temperature": 800.0,        # Starting temperature
    "low_temperature": 300.0,         # Final temperature
    "num_intervals": 5,               # Number of cooling steps
    "high_temperature_steps": 2000,   # Steps at high temperature
    "annealing_steps": 8000,          # Total annealing steps
    "calculator": MODEL_ORB_V3_CONSERVATIVE,
})

2.2 Ensemble Configuration

NPT Ensemble (ensemble_type = 0, default):

• Uses thermostat + barostat for temperature and pressure control
• Good for bulk materials and thermal expansion studies

NVT Ensemble (ensemble_type = 1):

• Uses only thermostat for temperature control (no barostat needed)
• Good for fixed density studies and surface systems

2.3 Thermostat Configuration

Thermostat parameters apply to both NPT and NVT ensembles for temperature control. The thermostat maintains the target temperature by coupling to the atomic velocities:

Additional parameters:

• thermostat_time_fs - Time constant for temperature coupling
• friction - Friction coefficient for Langevin thermostat (default: 0.002)

# Single temperature simulation with Bussi thermostat
result = create_md_simulation({
    "project": "your-project-id",
    "source_geometry_id": "your-structure-id",
    "name": "Equilibrium MD",
    "description": "Single temperature with Bussi thermostat",
    "mode": 0,                        # Single temperature
    "temperature": 400.0,             # Simulation temperature
    "num_steps": 15000,               # Simulation steps
    "calculator": MODEL_ORB_V3_CONSERVATIVE,
    "thermostat_type": 2,             # Bussi-Donadio-Parrinello
    "thermostat_time_fs": 150.0,      # Thermostat time constant
})

2.4 Barostat Configuration

Barostat parameters only apply to NPT ensemble simulations (ensemble_type = 0). The barostat controls pressure by adjusting the simulation cell volume:

Additional parameters:

• barostat_time_fs - Time constant for pressure coupling (default varies)
• external_stress_gpa - Applied external stress in GPa (default: 0.0)

# NPT simulation with barostat configuration
result = create_md_simulation({
    "project": "your-project-id",
    "source_geometry_id": "your-structure-id",
    "name": "NPT Equilibration",
    "description": "Constant pressure simulation with Parrinello-Rahman barostat",
    "mode": 0,                        # Single temperature
    "temperature": 300.0,             # Room temperature
    "num_steps": 20000,               # Simulation steps
    "calculator": MODEL_ORB_V3_CONSERVATIVE,
    "ensemble_type": 0,               # NPT ensemble
    "barostat_type": 1,               # Parrinello-Rahman barostat
    "barostat_time_fs": 200.0,        # Barostat time constant
    "external_stress_gpa": 0.1,       # Small applied pressure
})

3. Advanced Parameters

3.1 Cell Shape Control

Modify unit cell behavior and transformations during simulation. The cell_handling parameter controls how the simulation cell is maintained, while auto_convert_cell enables automatic conversion to preferred cell shapes for computational efficiency:

result = create_md_simulation({
    # ... other parameters ...
    "cell_handling": 1,           # Force upper triangular cell
    "auto_convert_cell": True,    # Automatic cell conversion
})

3.2 Velocity Initialization

Control initial velocity distribution and random number generation for reproducible simulations. The velocity_init parameter determines how atomic velocities are assigned at startup, while random_seed ensures reproducible results across multiple runs:

result = create_md_simulation({
    # ... other parameters ...
    "velocity_init": 0,           # Maxwell-Boltzmann (default)
    "random_seed": 42,            # Reproducible random numbers
    "velocity_scaling_factor": 1.0, # Velocity scaling
})

3.3 Trajectory Output

Configure simulation output frequency and data formats for analysis needs. The dump_interval controls how often trajectory snapshots are saved, while output_format determines the file format and save_stress includes stress tensor data:

result = create_md_simulation({
    # ... other parameters ...
    "dump_interval": 50,          # Save every 50 steps
    "output_format": 1,           # Extended XYZ format
    "save_stress": True,          # Include stress tensor
})

3.4 Constraints and Restraints

Apply position constraints and regional temperature control for specialized simulation scenarios. The fixed_atoms parameter allows you to constrain specific atoms to their initial positions, while region_based_thermostat enables different temperature control for different regions of the system:

result = create_md_simulation({
    # ... other parameters ...
    "fixed_atoms": "1,2,5-10",    # Fix specific atoms
    "region_based_thermostat": True, # Regional temperature control
})

4. Output Formats

4.1. Analysis Data

MD simulations provide comprehensive output data:

• Atomic trajectories and velocities
• Temperature and pressure evolution
• Energy conservation monitoring
• Stress tensor components (if enabled)

4.2. Trajectory Formats

The output_format parameter determines the file format of trajectory data generated during the simulation. Once your MD simulation completes, you can download trajectory files in the specified format through the file operations.

5. Simulation Management

5.1. Retrieving MD Simulations

Get comprehensive information about an MD simulation:

from atomict.simulation.md import get_md_simulation

response = get_md_simulation("your-md-simulation-id")

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Basic MD Simulation",
  "description": "Single temperature equilibrium MD",
  "mode": 0,
  "temperature": 300.0,
  "num_steps": 10000,
  "timestep_fs": 1.0,
  "calculator": 2,
  "ensemble_type": 0,
  "thermostat_type": 0,
  "barostat_type": 0,
  "source_geometry_id": "structure-uuid",
  "source_geometry": {
    "id": "structure-uuid",
    "filename": "crystal_structure.cif",
    "file_type": "cif"
  },
  "project": "project-uuid",
  "created_at": "2025-01-15T10:30:00Z",
  "edited_at": "2025-01-15T10:35:00Z",
  "task": {
    "id": "task-uuid",
    "status": 0,
    "progress": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z",
    "owner": "user-uuid",
    "k8s_cluster": null,
    "running_on": null
  }
}

5.2. File Operations

Link user-uploaded files to MD simulations:

from atomict.simulation.md import associate_user_upload_with_md_simulation

# Associate a file with the simulation
association = associate_user_upload_with_md_simulation(
    user_upload_id="your-upload-id",
    simulation_id="md-simulation-id"
)

print(f"Associated file: {association}")

Retrieve all files linked to a simulation:

files = get_md_simulation_files("simulation-id")

for file_assoc in files['results']:
    filename = file_assoc['user_upload']['filename']
    print(f"  - {filename}")

5.3. Deleting Simulations

Remove simulations from your project:

from atomict.simulation.md import delete_md_simulation

result = delete_md_simulation("simulation-id")