diff --git a/docs/index.md b/docs/index.md index 65f0dec..eb1cddf 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 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. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..8e5ac18 --- /dev/null +++ b/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 \ No newline at end of file