==============================
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:
.. code-block:: bash
conda create -n mdseenv python=3
conda activate mdseenv
.. code-block:: bash
git clone https://github.com/TFYA99ProjGroup/MDSE
cd MDSE
pip install -e .
Quick Start
===========
Run your first simulation:
.. code-block:: bash
mdse simulate --filepath examples/test_result_sim.yaml
For a detailed example of the yaml-file, see :py:mod:`mdse.parser`
If you want to see the ASE GUI for the trajectory:
.. code-block:: bash
mdse view
If you want to clean up your directory from ``*.traj`` files:
.. code-block:: bash
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:
.. code-block:: bash
cd database
docker compose up -d --build
cd ..
In order to shut down the database:
.. code-block:: bash
cd database
docker compose down
Write your first simulation results to the database!
.. code-block:: bash
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.
.. code-block:: bash
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
---------------
.. code-block:: yaml
# challange.yaml
Simulation:
CRYSTAL:
TYPE: DATABASE
Name: diamondsqliterunde
Filepath: ../../defects.sqlite
Structure_folder: "./defect"
Query:
charge: 0
hulldistance: 1e-5
...
.. code-block:: bash
mdse simulate -f challange.yaml
Here we use the defects.sqlite database and query all materials with charge :math:`=0` and hull distance :math:`< 10^{-5}`.
Visualize results
=================
It may be interesting to visualize the results from the database.
This is an example how to do it.
.. code-block:: yaml
# 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
.. code-block:: bash
mdse visualize -f visualize.yaml
CLI Usage
=========================
Basic usage
-----------
.. code-block:: bash
mdse --help
Commands
--------
.. list-table::
:header-rows: 1
* - Commands
- Description
* - ::
mdse [-h] [--debug] {subcommand} ...
- The main CLI command
.. list-table::
:header-rows: 1
:widths: 35 65
* - 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:
.. code-block:: python
import mdse
Example
-------
.. code-block:: python
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
-------------
.. admonition:: 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:
.. code-block:: bash
mdse --debug simulate ...
If using MDSE as a library:
.. code-block:: python
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 :doc:`changelog`.
License
=======
Full license is available in :doc:`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: ``_.
Note however that this software will not be supported continually after the 16th January 2026.
Until then, you can contact our Product owner:
- oskbo133@student.liu.se
- H305b, Hertz, F-house, Linköping University