First-principles calculations or experiments hand you a $6 \times 6$ stiffness matrix — and then what? Extracting directional Young’s modulus, checking mechanical stability, computing polycrystalline averages, and exporting material cards for ABAQUS or COMSOL usually means writing one-off scripts every time. Mat Model Lab packages all of that into a single, open-source desktop application so you can go from raw $C_{ij}$ to publication-ready 3D anisotropy plots in seconds.

GitHub: github.com/seekzzh/mat-model-lab

Why Build This Tool?

In computational materials science, the elastic constant matrix ($C_{ij}$) is fundamental to describing the mechanical behavior of materials. First-principles calculations (e.g., VASP, Quantum ESPRESSO) or experimental measurements can provide a $6 \times 6$ stiffness matrix, but there is a significant gap between a raw matrix and engineering intuition:

• How do you intuitively visualize the directional dependence of Young’s modulus in anisotropic materials?
• What are the Voigt, Reuss, and Hill polycrystalline average values?
• Does a given set of elastic constants satisfy the Born stability criteria?
• How do you export elastic parameters as an ABAQUS UMAT or COMSOL material card?

Mat Model Lab was created to bridge this gap.

Core Features

Directional Elastic Property Visualization

Mat Model Lab supports 2D (polar) and 3D (spherical) directional visualization of the following elastic properties:

All directional properties are computed from the compliance matrix $\mathbf{S} = \mathbf{C}^{-1}$ via rotation transformations. For 4D properties (e.g., shear modulus depends on an additional angle $\chi$), the software averages over $\chi$ on a specified cross-section.

Crystal Symmetry Types

A material’s crystal symmetry determines how many independent elastic constants it has — from 21 for Triclinic (no symmetry) down to just 3 for Cubic. Choosing the correct symmetry class is the first step in any elastic analysis, as it dictates which $C_{ij}$ entries are independent, which are related by symmetry, and which are zero.

The software includes built-in definitions for the complete set of 3D crystal symmetry types:

1
2

Triclinic (21) → Monoclinic (13) → Orthorhombic (9) → Tetragonal (6-7)
    → Trigonal (6-7) → Hexagonal (5) → Cubic (3)

The numbers in parentheses indicate the count of independent elastic constants. After selecting a crystal type, the input panel automatically disables non-independent entries and fills the matrix based on symmetry relations during computation.

Additionally, 2D materials (Hexagonal, Square, Rectangular, Oblique) are supported, suitable for elastic analysis of two-dimensional materials such as graphene and $\text{MoS}_2$.

Voigt-Reuss-Hill Polycrystalline Averaging

For polycrystalline materials, the software automatically computes:

• Voigt upper bound (equal strain assumption)
• Reuss lower bound (equal stress assumption)
• Hill average: $X_{\text{Hill}} = (X_{\text{Voigt}} + X_{\text{Reuss}}) / 2$

Output includes: Bulk modulus $K$, Shear modulus $G$, Young’s modulus $E$, and Poisson’s ratio $\nu$.

Born Stability Check

After entering elastic constants, the software automatically verifies that all eigenvalues of the stiffness matrix are positive. If the material is mechanically unstable, the interface clearly marks it as “The Structure is UNSTABLE”.

Finite Element Code Export

Elastic constants can be exported with one click to:

• ABAQUS UMAT (Fortran .f file)
• COMSOL Parameters (.txt file)

Report Generation

Analysis reports can be exported in three formats:

Reports include: material information, $C_{ij}/S_{ij}$ matrices, VRH results, stability analysis, and visualization charts for all elastic properties.

Technical Architecture

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

mat-model-lab/
├── main.py               # Entry point
├── core/                  # Core computation engine
│   ├── young.py           # Young's Modulus E(θ,φ)
│   ├── shear.py           # Shear Modulus G(θ,φ,χ)
│   ├── poisson.py         # Poisson's Ratio ν(θ,φ,χ)
│   ├── bulk.py            # Bulk Modulus B(θ,φ)
│   ├── hardness.py        # Hardness H(θ,φ)
│   ├── elastic_vrh.py     # 3D VRH polycrystalline averaging
│   ├── elastic_vrh_2d.py  # 2D VRH polycrystalline averaging
│   ├── stability.py       # Born stability criteria
│   ├── crystal_type.py    # Crystal type and symmetry constraints
│   └── conversions.py     # Coordinate/matrix transformations
├── gui/                   # Graphical interface (PyQt6)
│   ├── main_window.py     # Main window
│   ├── modules/           # Feature modules (Elasticity, Plasticity, ...)
│   └── widgets/           # UI components
├── visualization/         # Matplotlib visualization
│   ├── plot_2d.py         # Polar coordinate plotting
│   ├── plot_3d.py         # 3D surface plotting
│   └── plot_slice.py      # Arbitrary cross-section plotting
└── mml_utils/             # Utility functions
    ├── data_io.py          # Data I/O (txt/xlsx/mat)
    ├── material_db.py      # Material database
    ├── report_generator.py # Report generation
    ├── code_export.py      # FEA code export
    └── paths.py            # Resource path resolution

Technology Stack

Design Highlights

1. Separation of computation and GUI: The core/ modules are pure NumPy functions with no GUI dependencies, usable as a standalone Python library.
2. Modular architecture: Elasticity, Plasticity, and Hyperelasticity are independent modules plugged into the main window.
3. Dark/Light theme: One-click toggle with all controls and charts adapting automatically.
4. Cross-platform: Built on PyQt6, runs on Windows, macOS, and Linux.

Getting Started

Option A: Download the Executable

Download MatModelLab.exe from the Releases page. Double-click to run — no Python installation required.

Option B: Run from Source

1
2
3
4

git clone https://github.com/seekzzh/mat-model-lab.git
cd mat-model-lab
pip install -r requirements.txt
python main.py

Option C: Use as a Python Library

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import numpy as np
from core import Young_3D, ElasticVRH3D, StableofMechanical
from mml_utils import Elastic_Read

# Read elastic constants
Cij, names, status = Elastic_Read('data.txt')

# VRH polycrystalline averaging
vrh = ElasticVRH3D(Cij[:,:,0])
print(f"E = {vrh['E']:.2f} GPa, G = {vrh['G_VRH']:.2f} GPa")

# Stability check
print(f"Stable: {StableofMechanical(Cij[:,:,0])}")

Worked Example: Analyzing Elastic Anisotropy of Copper

1. Launch the program → Select Data Mode: “From Database”
2. Load material → Database → Browse Materials → Select Copper (Pure)
3. Choose visualization → 3D mode, check Young’s Modulus
4. Click Calculate

The results show that the anisotropy ratio of Cu is $A = 2C_{44}/(C_{11}-C_{12}) \approx 3.21$, making it a strongly anisotropic FCC metal. The 3D plot clearly shows that Young’s modulus is maximum along the $[111]$ direction and minimum along the $[100]$ direction.

2D Material Support

Mat Model Lab includes dedicated support for elastic analysis of two-dimensional materials. Taking graphene as an example:

Graphene belongs to the 2D Hexagonal symmetry type, with isotropic in-plane elastic properties — the polar plot forms a perfect circle.

Future Roadmap

• 🚧 Plasticity module: von Mises, Hill, and Drucker-Prager yield criteria with stress-strain curve fitting
• 🚧 Hyperelasticity module: Parameter calibration and UMAT generation for Neo-Hookean, Mooney-Rivlin, Ogden, and other models
• 📋 GitHub Actions CI for automated testing
• 📋 Comprehensive pytest unit test suite

Contributing

Contributions are welcome through:

• 🐛 File a Bug Report
• 💡 Submit a Feature Request
• 🔧 Open a Pull Request

See CONTRIBUTING.md for details.

License: GPL-3.0 | GitHub: seekzzh/mat-model-lab