# mech2d

**Repository Path**: haidi-hfut/mech2d

## Basic Information

- **Project Name**: mech2d
- **Description**: A usefull tool to to calculate the mechanics properties of two dimenional material.
- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-09-04
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mech2d

mech2d is a Python package for calculating mechanical properties of two-dimensional materials, including elastic constant tensors, stress-strain curves, and related orientation-dependent properties. It generates deformed structures, prepares and submits DFT tasks, and post-processes the results.

For more information, see the [documentation](https://mech2d.readthedocs.io/en/latest/) or the [paper](https://doi.org/10.3390/molecules28114337).

## Installation

Clone the source code from Gitee:
```bash
git clone https://gitee.com/haidi-hfut/mech2d.git
```

or from GitHub:
```bash
git clone git@github.com:haidi-ustc/mech2d.git
```

Before installing mech2d, create a virtual Python environment with conda. Current releases require Python 3.11 or newer because mech2d tracks recent pymatgen and custodian releases.

```bash
conda create -n mech2d python=3.11
```

After creating the environment, activate it and install mech2d:

```bash
conda activate mech2d
cd mech2d 
pip install .
```

You can also download the source archive and install it:
```bash
wget https://gitee.com/haidi-hfut/mech2d/repository/archive/master.zip
unzip master.zip
cd mech2d
pip install .
```

For development and tests, install the optional test dependencies:

```bash
pip install -e ".[test]"
pytest -q
```

## Method

Please refer to the [mech2d paper](https://doi.org/10.3390/molecules28114337) for method details.

The polar plot of Young's modulus and Poisson's ratio is obtained by the following equations:

$$
\begin{align*}
v_{zz} & = \frac{C_{12}}{C_{22}} \\
d_1 & = \frac{C_{11}}{C_{22}} + 1 - \frac{C_{11} C_{22} - C_{12}^2}{C_{22} C_{66}} \\
d_2 & = -\left(2 \frac{C_{12}}{C_{22}} - \frac{C_{11} C_{22} - C_{12}^2}{C_{22} C_{66}}\right) \\
d_3 & = \frac{C_{11}}{C_{22}} \\
Y_{zz} & = \frac{C_{11} C_{22} - C_{12}^2}{C_{22}} \\
\theta & \in [0, 2\pi] \text{ with 360 points} \\
E(\theta) & = \frac{Y_{zz}}{\cos(\theta)^4 + d_2 \cos(\theta)^2 \sin(\theta)^2 + d_3 \sin(\theta)^4} \\
V(\theta) & = \frac{v_{zz} \cos(\theta)^4 - d_1 \cos(\theta)^2 \sin(\theta)^2 + v_{zz} \sin(\theta)^4}{\cos(\theta)^4 + d_2 \cos(\theta)^2 \sin(\theta)^2 + d_3 \sin(\theta)^4}
\end{align*} 
$$

## Usage

The calculation workflow has three stages: **init**, **run**, and **post**.

All operations are available from the `m2d` command line interface. Show the top-level help with:

```bash
m2d -h
```

```
usage: m2d [-h] [-v] {init,run,post} ...

Description:
------------
mech2d prepares, submits, and post-processes mechanical-property calculations
for two-dimensional materials. It supports elastic constants and stress-strain
curves using energy- or stress-based workflows. Use "m2d <sub-command> -h" to
inspect options for init, run, and post.

positional arguments:
  {init,run,post}
    init           Generate deformed structures and Mech2D metadata.
    run            Generate DFT inputs and submit deformed-structure tasks.
    post           Parse results, fit tensors or curves, and optionally plot.

options:
  -h, --help       show this help message and exit
  -v, --version    Display version
```

### 1. Generate deformed structures with `init`

Use this stage to generate deformed structures and `Mech2D.json` metadata.

```bash
m2d init -h
```

```
usage: m2d init [-h] [-c CONFIG] [-a {stress,energy}] [-m MAXS] [-n NUMBER] [-d {xx,yy,bi,xy} [{xx,yy,bi,xy} ...]] [-r RANGES [RANGES ...]]
                [-p {elc,ssc}] [-v] [-b]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Input structure file. Supported formats include POSCAR, .vasp, .cif, and .xsf.
  -a {stress,energy}, --approach {stress,energy}
                        Fitting approach: energy or stress.
  -m MAXS, --maxs MAXS  Maximum Lagrangian strain. Suggested values: 0.030-0.150 for energy,
                        0.0010-0.0050 for stress elastic constants.
  -n NUMBER, --number NUMBER
                        Number of deformed structures. Odd values greater than 4 are recommended.
  -d {xx,yy,bi,xy} [{xx,yy,bi,xy} ...], --direction {xx,yy,bi,xy} [{xx,yy,bi,xy} ...]
                        Stress-strain directions: xx, yy, bi, or xy. Default: xx.
  -r RANGES [RANGES ...], --ranges RANGES [RANGES ...]
                        Stress-strain Lagrangian strain range, for example: 0.0 0.2.
  -p {elc,ssc}, --properties {elc,ssc}
                        Target property: elc for elastic constants or ssc for stress-strain curve.
  -v, --verbose         Print verbose diagnostic information.
  -b, --back            Back up an existing output folder before writing new files.
```

To obtain deformed structures according to the detected 2D Bravais lattice, start from a relaxed structure. Suppose you have a `POSCAR` file in the current folder. Generate the deformed structures for a stress fitting workflow with:
```bash
m2d init -c POSCAR -n 9 -m 0.02 -a stress
```
After running this command, mech2d builds an `elc_stress` folder with subfolders.

```bash
elc_stress/
├── Def_1
│   ├── Def_1_001
│   ├── Def_1_002
│   ├── Def_1_003
│   ├── Def_1_004
│   ├── Def_1_005
│   ├── Def_1_006
│   ├── Def_1_007
│   ├── Def_1_008
│   └── Def_1_009
└── Def_2
    ├── Def_2_001
    ├── Def_2_002
    ├── Def_2_003
    ├── Def_2_004
    ├── Def_2_005
    ├── Def_2_006
    ├── Def_2_007
    ├── Def_2_008
    └── Def_2_009

```
Likewise, generate deformed structures for an energy fitting workflow with:
```bash
m2d init -c POSCAR -n 9 -m 0.05 -a energy
```

The deformed structures used for stress-strain curve calculation can be obtained by:
```bash
m2d init -c POSCAR -n 21 -r 0.0 0.2 -a stress -d 'xx' 'yy' -p ssc 
```
If `-r` is used, the Lagrangian strain is sampled from that range, for example `0.0 0.2`. If `-m` is used, the strain range is `[-max, +max]`.

> Tip: `.vasp`, `.xsf`, `.cif`, and `POSCAR` structure files are supported.

### 2. Prepare and submit DFT tasks with `run`

Use this stage to generate VASP inputs for the deformed structures and submit them through `dpdispatcher`, or use manual mode to only prepare the folders.

```bash
m2d run -h
```

```
usage: m2d run [-h] [-a {stress,energy}] [-p {elc,ssc}] [--manual] [-v] input

positional arguments:
  input                 YAML or JSON input file containing machine, resources,
                        tasks, and code sections.

options:
  -h, --help            show this help message and exit
  -a {stress,energy}, --approach {stress,energy}
                        Fitting approach: energy or stress.
  -p {elc,ssc}, --properties {elc,ssc}
                        Target property: elc for elastic constants or ssc for
                        stress-strain curve.
  --manual              Only generate calculation input files; do not submit tasks.
  -v, --verbose         Print verbose diagnostic information.
```

Example:

```bash
m2d run -a stress input.yaml
```

The `input.yaml` file includes four required sections:

1. **machine**: execution context, scheduler type, and local or remote work paths.
2. **resources**: queue, CPU/GPU resources, task grouping, modules, and environment settings.
3. **tasks**: executable command, forwarded input files, returned output files, and log names.
4. **code**: DFT engine name and input-generation settings.

An example for `input.yaml` is shown below:

```yaml
---
machine:
  batch_type: Slurm
  context_type: LocalContext
  local_root: "./work"
  remote_root: "./work"
  remote_profile:
    hostname: localhost
    username: wang
    port: 22
    timeout: 10
resources:
  number_node: 1
  cpu_per_node: 48
  gpu_per_node: 0
  queue_name: batch
  task_max: 10
  group_size: 1
  custom_flags: 
   - "ulimit -s unlimited"
  module_list: 
   - "vasp/5.4.1"
  
  #source_list:
  # - "/opt/intel/parallel_studio_xe_2020.2.108/psxevars.sh intel64"
  #envs:
  #  PATH: "/opt/soft/vasp541:$PATH"
tasks:
  command: "mpirun -np 48 vasp_std"
  task_work_path:
  forward_files:
  - INCAR
  - KPOINTS
  - POTCAR
  - POSCAR
  backward_files:
  - runlog
  - errlog
  - OUTCAR
  - OSZICAR
  - vasprun.xml
  - CONTCAR
  outlog: runlog
  errlog: errlog
code:
  name: vasp
  input:
    INCAR: "./INCAR"
    #KPOINTS: "./KPOINTS"
    KPOINTS:
      kspacing: 5000
      kgamma: false
    POTCAR: "./POTCAR"
    #vdw_kernel: vdw_kernel.bindat
```

> `input.yaml` can also be written in JSON format, but YAML is usually easier to read.

To generate VASP inputs without submitting jobs, use:

```bash
m2d run -a stress --manual input.yaml
```

### 3. Post-process results with `post`

Use this stage to parse results, fit elastic tensors or stress-strain curves, and optionally write plots.

```bash
m2d post -h
```

```
usage: m2d post [-h] [-a {stress,energy}] [-i INPUTFILE] [-p {elc,ssc}]
                [--skip] [-o ORDER] [-f FMT] [-d DPI] [--plot] [-v]

options:
  -h, --help            show this help message and exit
  -a {stress,energy}, --approach {stress,energy}
                        Fitting approach: energy or stress.
  -i INPUTFILE, --inputfile INPUTFILE
                        Parse an elastic tensor directly from an input file such as OUTCAR.
  -p {elc,ssc}, --properties {elc,ssc}
                        Target property: elc for elastic constants or ssc for stress-strain curve.
  --skip                Skip parsing raw DFT outputs and use existing Def_* data files.
  -o ORDER, --order ORDER
                        Polynomial fitting order. Defaults are selected from the calculation approach.
  -f FMT, --fmt FMT     Output figure format. Default: png.
  -d DPI, --dpi DPI     Output figure resolution. Default: 100.
  --plot                Write plot files during post-processing.
  -v, --verbose         Print verbose diagnostic information.
```

For elastic constants:

```bash
m2d post -a stress --plot
```

A figure such as `stress-EV.png` will be generated when `--plot` is used.

![EV](https://note.youdao.com/yws/api/personal/file/A22D69ECC94C45138EBBB385DC4AAB95?method=download&shareKey=eebde950bb2defb3f61c1ec285a50b2f)

For stress-strain calculations:

```bash
m2d post -a stress -p ssc --plot
```

## How to Cite

Wang, H.; Li, T.; Liu, X.; Zhu, W.; Chen, Z.; Li, Z.; Yang, J. mech2d: An Efficient Tool for High-Throughput Calculation of Mechanical Properties for Two-Dimensional Materials. [Link](https://doi.org/10.3390/molecules28114337)