docs: add Thermo_pw and GSFE Quick Start guides and expand index homepage

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 an AiiDA plugin for managing elastic calculations using thermo_pw and stacking fault energy calculations using Quantum ESPRESSO.
 
-AiiDA plugin for mechanical properties
+---
+
+## 🚀 Key Features
+
+### 1. Elastic Constants (`thermo_pw` module)
+This module automates calculations of:
+* Elastic constants and shear/bulk moduli.
+
+
+### 2. Dislocation Workflows (`dislocation` module)
+Integrated to evaluate planar defects and generalized stacking fault energy (GSFE) surfaces:
+* **GSFE**: Computes generalized stacking fault energy curves along customizable gliding planes.
+* **Surface Energy**: Computes surface energy.
+
+
+---
+
+## 🏗️ 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
+* [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.

docs/quickstart.md

@@ -0,0 +1,164 @@
+# 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. 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
+# 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("111")
+)
+
+# 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