User’s Manual

Introduction

Welcome to Molecular Dynamics Simulation Environment (MDSE)! This software parses, runs and evaluates ASE simulations with the help of ASAP3.

This software is developed towards solving problems regarding defect materials using existing data from a database at Linköping University, parsed via The High-Throughput Toolkit (httk). It is used to explore the possibility of running MD simulations with the help of MLIPs such as the MACE calculator instead of density functional theory (DFT) to calculate the defect formation energy. This was interesting because DFT calcuations are heavy and takes a lot of time and so doing it with MACE could be a lot faster. The question investigated was whether MACE is accurate enough.

Physical properties:

The following material properties can be calculated with mdse:

  • Mean square displacement

  • Lindemann index

  • Density of states

  • Debye temperature

  • Self diffusion coefficient

  • Isobaric specific heat

  • Isochoric heat capacity per atom

  • Elastic moduli and constants

    • Shear modulus

    • Bulk modulus

    • Young’s modulus

  • Coheseive energy (in the form of Atomization energy)

  • Formation energy

  • Defect formation energy

Installation

Requirements

Dependencies:

  • Python >=3.9.21, <3.12

Optional (Highly recommended):

  • Message Passing Interface (MPI), e.g. Open MPI

Installation from source

Using a conda environment is highly recommended:

conda create -n mdseenv python=3
conda activate mdseenv

git clone https://github.com/TFYA99ProjGroup/MDSE
cd MDSE
pip install -e .

Quick Start

Run your first simulation:

mdse simulate --filepath examples/test_result_sim.yaml

For a detailed example of the yaml-file, see mdse.parser

If you want to see the ASE GUI for the trajectory:

mdse view

If you want to clean up your directory from *.traj files:

mdse clean

Some interesting results are saved in the results/ directory in *.json files.

Set up your own server

This program is able to save the result data to a MongoDB server. In order to Set up the server docker is highly recommended and a docker-compose file is available in the project:

cd database
docker compose up -d --build
cd ..

In order to shut down the database:

cd database
docker compose down

Write your first simulation results to the database!

mdse write_db -f results/ -a mongodb://admin:secret@localhost:27017/

You can view the database in a web browser on the address http://localhost:8081/ with the default username webadmin and the default password websecret.

OPTIMADE rest api

You can query the database through the OPTIMADE rest api using the defualt port 8000.

Example:

To get all entries when nsites is 15.

curl http://localhost:8000/v1/structures?filter=nsites=15

Run simulations from a sqlite database

MDSE can use atomic position from a sqlite database in order to begin simulations.

Example of yaml

# challange.yaml
Simulation:
    CRYSTAL:
    TYPE: DATABASE
    Name: diamondsqliterunde
    Filepath: ../../defects.sqlite
    Structure_folder: "./defect"
    Query:
      charge: 0
      hulldistance: 1e-5
...

mdse simulate -f challange.yaml

Here we use the defects.sqlite database and query all materials with charge \(=0\) and hull distance \(< 10^{-5}\).

Visualize results

It may be interesting to visualize the results from the database. This is an example how to do it.

# visualize.yaml
data:
  data_source: "mongo" #mongo when using mongoDB
  uri: "mongodb://admin:secret@localhost:27017/"
plots:
  plot_1_defect:
    type: "single"
    average: False
    fix_y: False
  plot_2_defect:
    type: "heatmap"
    x: "interstitial"
    y: "substitution"
  plot_3_defect: #To get sub-sub. Dont think we have int-int
    type: "sub-sub"
    average: False
  plot_scatt:
    type: scatter
    x: lindemann
    y: self_diffusion
    z: debye

mdse visualize -f visualize.yaml

CLI Usage

Basic usage

mdse --help

Commands

Commands

Description

 
mdse [-h] [--debug] {subcommand} ...

The main CLI command

Command

Description

 
simulate [-h] -f FILEPATH [-e ENSAMBLE] [--mpi]

Runs the main simulation from config-file.

 
view [-h] [-f FILEPATH [FILEPATH ...]]

Triggers the ASE GUI from traj-files.

 
clean [-h] [-f FILEPATH] [-r]

Removes all the traj-files.

 
write_db [-h] -f FILEPATH [FILEPATH ...] -a ADDRESS

Writes data from json-file to MongoDB database.

 
visualize [-h] -f FILEPATH

Visualizes data from database. Uses config file too.

 
calc_defect_formation_energy [-h] -a ADDRESS

Calculates the defect formation energy from a database.

 
outliers [-h] -a ADDRESS [-p PROPERTY [PROPERTY ...]] [--db-client DB_CLIENT] [--db-collection DB_COLLECTION] [--std-dev STD_DEV_THRESHOLD]

Detects outliers in the database.

Library Usage

MDSE can also be used as a Python library:

import mdse

Example

from mdse.parser import main_read
from mdse.rm.runmanager import RunManager
from mdse.rm.dbmanager import DBManager

# Parse the yaml-file from your first simulation
sim_list = main_read("examples/test_result_sim.yaml")

# Simulate your first simulation again
rm = RunManager(sim_list)
rm.run_simulations()

# Write the data to the database
dbm = DBManager("mongodb://admin:secret@localhost:27017/")
dbm.write_jsonfiles_to_db("results")

Workflows

Description of recommended workflows or common tasks.

  1. Write config files or a directory with config files (the parser takes both).

  2. Run simulation, this software is made to be run on a supercomputer, so that is recommended.

  3. Write results to the database.

  4. Evaluate the results locally.

Troubleshooting

Common Issues

Problem: NPT simulation doesn’t work

Solution: Ensure your config contains:

  • Temp

  • Pressure

  • ThermoTime

  • BaroTime

Logging / Debug Mode

Add the –debug flag to after the mdse cli command:

mdse --debug simulate ...

If using MDSE as a library:

from mdse.parser import main_read
from mdse.rm.runmanager import RunManager
from mdse.rm.dbmanager import DBManager

from mdse.logging import setup_logging
import logging

logger = logging.getLogger(__name__)
# Use debug=False if you want less information
setup_logging(debug=True)

# ...

FAQ

Q: What does calc stand for? A: Calc is slang for calculator.

Version Compatibility

This software is based around working with Python 3.10 (3.10.12 to be precise)

Changelog

Full changelog is available in Changelog.

License

Full license is available in Licensing

Credits:

This program used the high-throughput toolkit

httk v1.2.0 (2020-09-25), (c) 2012 - 2020

Credits for httk modules used in this run:

  • (httk) Rickard Armiento

  • (imported spacegroup data) Computational Crystallography Toolbox, http://cctbx.sourceforge.net/

  • (imported code from cif2cell) Torbjörn Björkman

  • (httk_db) Rickard Armiento

Credits for MDSE:

  • Emil Alakulju

  • Oskar Bollner

  • Petter Johansson

  • Axel Kemppe

  • Patrik Modorato

  • Lukas Smith

Contact / Support

It is possible to open an issue in GitHub: https://github.com/TFYA99ProjGroup/MDSE/issues.

Note however that this software will not be supported continually after the 16th January 2026.

Until then, you can contact our Product owner: