From 94b05c9c831b9110cfb0946d266af9216161dfe2 Mon Sep 17 00:00:00 2001 From: ymzhang0 Date: Tue, 26 May 2026 16:33:10 +0200 Subject: [PATCH 1/3] docs: expand index to document SFE and dislocation features --- docs/index.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 65f0dec..e9dfb5a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,43 @@ -# Introduction +# Welcome to `aiida-mechanical` -This is the documentation of the `aiida-mechanical` Python package. +`aiida-mechanical` is a comprehensive AiiDA plugin designed for managing, running, and analyzing mechanical and thermodynamic properties of materials. It integrates high-throughput workflow engines for crystal elasticity, structural shear, and defect modeling. -AiiDA plugin for mechanical properties +--- + +## 🚀 Key Features + +### 1. Thermodynamic & Elasticity Properties (`thermo_pw` module) +Derived and extended from Quantum ESPRESSO's `thermo_pw` project, this module automates high-throughput calculations of: +* Elastic constants and shear/bulk moduli. +* Phonon-driven thermodynamic properties. +* Automatic spacegroup analysis and Bravais lattice generation. + +### 2. Defect & Dislocation Workflows (`dislocation` module) +Integrated to evaluate planar defects and generalized stacking fault energy (GSFE) surfaces: +* **GSFE & USFE WorkChains**: Computes stable and unstable stacking fault energy curves along customizable gliding planes. +* **Relaxation & Rigid Layer Shear**: Integrates rigid-layer shear sliding and full k-point adaptive relaxation. +* **Twinning & Surface Energy**: Automation of crystal twinning energies and surface cleavage energies. + +--- + +## 🏗️ Registered Entry Points + +Here are the primary entry points registered under the `mechanical` namespace: + +### Workflows +* `mechanical.thermo_pw.base` — Base workflows for elastic/phonon engines. +* `mechanical.dislocation.gsfe` — Generalized Stacking Fault Energy WorkChain. +* `mechanical.dislocation.gsfe_relax` — Relaxed Generalized Stacking Fault Energy WorkChain. +* `mechanical.dislocation.isfe` — Inherent Stacking Fault Energy WorkChain. +* `mechanical.dislocation.esfe` — Empirical Stacking Fault Energy WorkChain. +* `mechanical.dislocation.usfe` — Unstable Stacking Fault Energy WorkChain. +* `mechanical.dislocation.twinning` — Twinning energy calculation WorkChain. + +### Custom Stacking Fault Data Models +* `mechanical.dislocation.cleavaged_structure` — Managed slab structure with customized vacuum padding. +* `mechanical.dislocation.faulted_structure` — Shear-faulted crystal system containing glide-plane definitions. + +--- + +## 📖 Quick Links +* [Developer Guide](developer.md) — Setup local editable installations, pre-commit styling, and testing. From 563d2275d92a82a1b5009f9f8b808cd7f6ea2bf5 Mon Sep 17 00:00:00 2001 From: ymzhang0 Date: Tue, 26 May 2026 16:44:47 +0200 Subject: [PATCH 2/3] docs: add Quick Start guides for thermo_pw and SFE/GSFE workflows --- docs/index.md | 18 +++--- docs/quickstart.md | 135 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+), 9 deletions(-) create mode 100644 docs/quickstart.md diff --git a/docs/index.md b/docs/index.md index e9dfb5a..eb1cddf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,21 @@ # Welcome to `aiida-mechanical` -`aiida-mechanical` is a comprehensive AiiDA plugin designed for managing, running, and analyzing mechanical and thermodynamic properties of materials. It integrates high-throughput workflow engines for crystal elasticity, structural shear, and defect modeling. +`aiida-mechanical` is an AiiDA plugin for managing elastic calculations using thermo_pw and stacking fault energy calculations using Quantum ESPRESSO. --- ## 🚀 Key Features -### 1. Thermodynamic & Elasticity Properties (`thermo_pw` module) -Derived and extended from Quantum ESPRESSO's `thermo_pw` project, this module automates high-throughput calculations of: +### 1. Elastic Constants (`thermo_pw` module) +This module automates calculations of: * Elastic constants and shear/bulk moduli. -* Phonon-driven thermodynamic properties. -* Automatic spacegroup analysis and Bravais lattice generation. -### 2. Defect & Dislocation Workflows (`dislocation` module) + +### 2. Dislocation Workflows (`dislocation` module) Integrated to evaluate planar defects and generalized stacking fault energy (GSFE) surfaces: -* **GSFE & USFE WorkChains**: Computes stable and unstable stacking fault energy curves along customizable gliding planes. -* **Relaxation & Rigid Layer Shear**: Integrates rigid-layer shear sliding and full k-point adaptive relaxation. -* **Twinning & Surface Energy**: Automation of crystal twinning energies and surface cleavage energies. +* **GSFE**: Computes generalized stacking fault energy curves along customizable gliding planes. +* **Surface Energy**: Computes surface energy. + --- @@ -40,4 +39,5 @@ Here are the primary entry points registered under the `mechanical` namespace: --- ## 📖 Quick Links +* [Quick Start Guide](quickstart.md) — Get up and running with example scripts for `thermo_pw` and `gsfe` workflows. * [Developer Guide](developer.md) — Setup local editable installations, pre-commit styling, and testing. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..490a22f --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,135 @@ +# Quick Start Guide + +This guide provides simple, ready-to-run Python examples for the two core submodules of `aiida-mechanical`: +1. **`thermo_pw`**: Calculating crystal elastic constants. +2. **`dislocation`**: Evaluating Generalized Stacking Fault Energy curves (GSFE). + +--- + +## 1. Elastic Constants (`thermo_pw`) + +The `mechanical.thermo_pw.base` workflow calculates elastic constants. + +### Python Example: Running a Thermo_pw SCF Workflow + +Save this script as `run_thermopw.py` and run it with `python run_thermopw.py`: + +```python +from aiida import engine, orm +from aiida.plugins import WorkflowFactory +from ase.build import bulk + +# 1. Load the Thermo_pw base workflow +Thermo_pwBaseWorkChain = WorkflowFactory("mechanical.thermo_pw.base") + +# 2. Setup your structure (e.g., Silicon primitive cell) using ASE +silicon_ase = bulk("Si", "diamond", a=5.43) +structure = orm.StructureData(ase=silicon_ase) + +# 3. Define the Quantum ESPRESSO pw.x code (replace with your code label) +code = orm.load_code("pw-7.2@localhost") + +# You can use manually defined overrides to specify the resource and calculation parameters. +overrides = { + "metadata": { + "options": { + "account": "XXX", + "append_text": "", + "max_wallclock_seconds": 36000, + "parser_name": "thermo_pw", + "prepend_text": '', + "qos": 'XXX', + "queue_name": 'XXX', + "resources": { + "num_machines": 1, + "num_mpiprocs_per_machine": 32 + }, + "withmpi": true + } + }, + "thermo_control": { + "what": "scf_elastic_constants", + "frozen_ions": false, + }, + "parameters": { + "CONTROL": { + "calculation": "scf", + "tstress": true, + "tprnfor": true, + "disk_io": "nowf" + }, + "SYSTEM": { + "occupations": "smearing", + "smearing": "cold", + "degauss": 0.02 + }, + "ELECTRONS": { + "conv_thr": 1.0e-10, + "diagonalization": "david", + "electron_maxstep": 80, + "mixing_beta": 0.4 + }, + } +} +# 4. Generate the workchain builder using the default 'moderate' protocol +builder = Thermo_pwBaseWorkChain.get_builder_from_protocol( + code=code, + structure=structure, + protocol="moderate", + overrides={} +) + +# 5. Submit the calculation to the AiiDA daemon +node = engine.submit(builder) +print(f"Submitted mechanical.thermo_pw.base<{node.pk}> to calculate elastic properties.") +``` + +--- + +## 2. Generalized Stacking Fault Energy (`gsfe`) + +The `mechanical.dislocation.gsfe` workflow automates the evaluation of crystal slip and planar shear faults. It shears a conventional cell along a gliding plane (e.g., `(111)`) to compute the energy barrier. + +### Python Example: Running a GSFE Workflow + +Firstly, we need to setup the code, unit-cell structure and parameters. Here we use FCC Aluminum as an example. + +```python +from aiida import engine, orm +from aiida.plugins import WorkflowFactory +from ase.build import bulk + +# 1. Load the GSFE workflow and custom data structures +GSFEWorkChain = WorkflowFactory("mechanical.dislocation.gsfe") + +# 2. Setup a bulk material structure (e.g., FCC Aluminum) +al_ase = bulk("Al", "fcc", a=4.05) +structure = orm.StructureData(ase=al_ase) + +# 3. Define the Quantum ESPRESSO pw.x code (replace with your code label) +code = orm.load_code("pw-7.2@localhost") +``` + +Then we can define the calculation parameters and generate the workchain builder: + +```python +# 4. Generate the SFE builder using the default protocol API +# We specify a (111) gliding plane and repeat the unit cell 4 times +builder = GSFEWorkChain.get_builder_from_protocol( + code=code, + structure=structure, + protocol="moderate", + n_repeats=orm.Int(4), + gliding_plane=orm.Str("1 1 1") +) + +# 5. Define resource limits +builder.relax.base_relax.metadata.options.resources = { + "num_machines": 1, + "num_mpiprocs_per_machine": 4 +} + +# 6. Submit the workflow to the AiiDA daemon +node = engine.submit(builder) +print(f"Submitted GSFEWorkChain<{node.pk}> along plane (111).") +``` From beea2af68856d4e38628cdb115155ed0b343b250 Mon Sep 17 00:00:00 2001 From: ymzhang0 Date: Tue, 26 May 2026 16:59:51 +0200 Subject: [PATCH 3/3] docs: expand SFE/GSFE Quick Start guide with custom overrides and references --- docs/quickstart.md | 47 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 490a22f..8e5ac18 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -110,7 +110,38 @@ structure = orm.StructureData(ase=al_ase) code = orm.load_code("pw-7.2@localhost") ``` -Then we can define the calculation parameters and generate the workchain builder: +Then we can define the calculation parameters and generate the workchain builder. Since the GSFEWorkChain is composed of a PwRelaxWorkChain and a PwBaseWorkChain, you can check the [relaxation example][1] and [SCF example][2] in the aiida-quantumespresso documentation. + +Then, GSFEWorkChain will execute the PwBaseWorkChain to calculate a series of faulted structures generated by `aiida_mechanical.tools.structure_builder:build_atoms_from_burger_vector_general`. + +```python +overrides = { + "clean_workdir": True, + "kpoints_distance": 0.3, + "pseudo_family": "PseudoDojo/0.5/PBE/SR/standard/upf" + # The GSFEWorkChain will firstly run a vc-relaxation for the unit cell, you should define the input parameters for a PwRelaxWorkChain in the relax. + "relax": { + ## You should define the resource and parameters you would like to use for a PwRelaxWorkChain. + }, + + # Then, the GSFEWorkChain will run SCF calculations the conventional cell, you should define the input parameters for a PwBaseWorkChain in the scf. + "scf":{ + ## You should define the parameters for a PwBaseWorkChain. + }, + + "sfe":{ + ## You should define the parameters for the GSFE calculation. + }, +} +``` + +After defining the parameters and resources that are used in the workflows, we can generate the workchain builder. + +We should provide the size of the supercell (n_repeats) and the gliding plane that we want to study. + +Currently, only limited gliding systems for limited structure types are supported. + +You can check the supported configurations in `aiida_mechanical.data.gliding_systems`. ```python # 4. Generate the SFE builder using the default protocol API @@ -120,16 +151,14 @@ builder = GSFEWorkChain.get_builder_from_protocol( structure=structure, protocol="moderate", n_repeats=orm.Int(4), - gliding_plane=orm.Str("1 1 1") + gliding_plane=orm.Str("111") ) -# 5. Define resource limits -builder.relax.base_relax.metadata.options.resources = { - "num_machines": 1, - "num_mpiprocs_per_machine": 4 -} - -# 6. Submit the workflow to the AiiDA daemon +# 5. Submit the workflow to the AiiDA daemon node = engine.submit(builder) print(f"Submitted GSFEWorkChain<{node.pk}> along plane (111).") ``` + + +[1]: https://aiida-quantumespresso.readthedocs.io/en/stable/howto/relax_structure.html +[2]: https://aiida-quantumespresso.readthedocs.io/en/stable/howto/run_pw.html \ No newline at end of file