minelastic 0.1.0__tar.gz

minelastic-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0 (2026-10-28)
+
+First public release, accompanying S. I. Simak and U. Singh, arXiv:2610.11733.
+
+* Minimal uncoupled strain sets for all nine elastic symmetry types, in any orientation; extraction
+  methods `uncoupled`, `designated` and `lstsq`; consistency checks; VRH moduli and Born stability.
+* Four-point finite differences by default (central differences for MD inputs).
+* `generate`/`collect` from the command line or from Python (`minelastic.generate`, `minelastic.collect`).
+  For VASP, every INCAR change is listed and the settings that matter for small stress differences are
+  checked; `--fix-incar` applies them.
+* `calculate(..., dipole=f)`: Born charges and piezoelectric tensors with any ASE calculator.
+* Interfaces: VASP, Quantum ESPRESSO (pw.x, any `ibrav`), ABINIT, FHI-aims, any ASE format, any ASE
+  calculator.
+* Clamped- and relaxed-ion constants; internal-strain tensor completed by symmetry.
+* `--ionic`: Gamma-point force constants, Born charges, relaxed-ion stiffness and the piezoelectric e and
+  d tensors from clamped single points.
+* Berry-phase piezoelectric tensor from the strained cells (VASP `LCALCPOL`).
+* Finite temperature: MD averages (`generate --md`, `collect --md`) and snapshot averages (`--samples`),
+  with standard errors and the kinetic term.
+* Symmetry with magnetic order (magnetic space group, including time-reversed operations) from VASP
+  `MAGMOM`, ABINIT `spinat`, pw.x species labels and noncollinear directions, and ASE initial moments; VASP
+  species blocks and pw.x species labels.
+* Documentation with tutorials for ASE, VASP, Quantum ESPRESSO, ABINIT and CP2K (outputs of real runs),
+  how-to guides per quantity and per code, the theory, and the API reference generated from the
+  docstrings. The tests run every code block of the documentation and compare the printed output.
+* An agent skill for agentic workflows (`skills/minelastic/`), installable as a Claude Code plugin.

minelastic-0.1.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use minelastic, please cite the paper below."
+title: "minelastic: elastic constants from minimal uncoupled stress-strain calculations"
+type: software
+version: 0.1.0
+date-released: "2026-10-28"
+license: MIT
+repository-code: "https://github.com/utksi/minelastic"
+url: "https://utksi.github.io/minelastic/"
+keywords:
+  - elastic constants
+  - stress-strain
+  - density functional theory
+  - piezoelectricity
+  - VASP
+  - Quantum ESPRESSO
+  - ASE
+authors:
+  - family-names: Singh
+    given-names: Utkarsh
+    affiliation: "Department of Physics, Chemistry and Biology (IFM), Linköping University, Sweden"
+  - family-names: Simak
+    given-names: Sergei I.
+    affiliation: "Department of Physics, Chemistry and Biology (IFM), Linköping University, Sweden"
+preferred-citation:
+  type: article
+  title: "A General Algorithm for Minimal Uncoupled Stress--Strain Calculations of Elastic Constants"
+  authors:
+    - family-names: Simak
+      given-names: Sergei I.
+    - family-names: Singh
+      given-names: Utkarsh
+  journal: "arXiv preprint arXiv:2610.11733"
+  year: 2026
+  doi: "10.48550/arXiv.2610.11733"
+  url: "https://arxiv.org/abs/2610.11733"

minelastic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utkarsh Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

minelastic-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include CITATION.cff CHANGELOG.md mkdocs.yml
+recursive-include tests *.py *.json *.sh *.abo
+recursive-include examples *
+recursive-include docs *.md *.js
+recursive-include skills *.md
+prune **/__pycache__

minelastic-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: minelastic
+Version: 0.1.0
+Summary: Elastic constants from minimal uncoupled stress-strain calculations (VASP, Quantum ESPRESSO, ABINIT, FHI-aims, any ASE calculator)
+Author: Utkarsh Singh, Sergei I. Simak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/utksi/minelastic
+Project-URL: Documentation, https://utksi.github.io/minelastic/
+Project-URL: Source, https://github.com/utksi/minelastic
+Project-URL: Issues, https://github.com/utksi/minelastic/issues
+Project-URL: Paper, https://arxiv.org/abs/2610.11733
+Keywords: elastic constants,stress-strain,density functional theory,VASP,Quantum ESPRESSO,ABINIT,ASE,piezoelectric,materials science
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: spglib>=2.0
+Requires-Dist: ase>=3.22
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
+Dynamic: license-file
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://utksi.github.io/minelastic/assets/wordmark-dark.svg">
+  <img src="https://utksi.github.io/minelastic/assets/wordmark-light.svg" alt="minelastic" height="72">
+</picture>
+
+[![arXiv](https://img.shields.io/badge/arXiv-2610.11733-b31b1b.svg)](https://arxiv.org/abs/2610.11733)
+[![tests](https://github.com/utksi/minelastic/actions/workflows/tests.yml/badge.svg)](https://github.com/utksi/minelastic/actions/workflows/tests.yml)
+[![docs](https://img.shields.io/badge/docs-online-blue.svg)](https://utksi.github.io/minelastic/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/utksi/minelastic/blob/main/LICENSE)
+
+Elastic, internal-strain and piezoelectric tensors from the fewest possible stress calculations, for every
+crystal symmetry and with any electronic-structure code.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://utksi.github.io/minelastic/assets/hero-dark.svg">
+  <img src="https://utksi.github.io/minelastic/assets/hero-light.svg" alt="The usual approach applies six strain patterns; minelastic applies one to a cubic crystal and reads c11, c12 and c44 from the stress components of the strained cell. Below, the number of strain patterns for each crystal system.">
+</picture>
+
+**minelastic** implements the minimal and uncoupled strain sets scheme of
+
+> S. I. Simak and U. Singh, *A general algorithm for minimal uncoupled stress-strain calculations of
+> elastic constants*, [arXiv:2610.11733](https://arxiv.org/abs/2610.11733) (2026).
+
+Each independent elastic constant is read off one stress component of one strained cell, and the number of
+strain patterns is the smallest that any stress-strain method can use: one for a cubic crystal and two for
+tetragonal, trigonal and hexagonal crystals, where the usual approach (VASP's `IBRION = 6` and most
+workflows) applies six. The same strained cells also give the internal-strain tensor and, with Berry-phase
+dipoles, the clamped-ion piezoelectric tensor; a few single points with displaced atoms add the relaxed-ion constants,
+the Born charges and the total piezoelectric tensors; and molecular dynamics in the strained cells gives the
+constants at finite temperature.
+
+## Installation
+
+<!-- skip: installs the package -->
+```bash
+pip install minelastic
+```
+
+minelastic requires Python 3.9 or newer; numpy, spglib and ASE are installed with it.
+
+## Usage
+
+With any ASE calculator, in memory:
+
+<!-- run -->
+```python
+from ase.build import bulk
+from ase.calculators.emt import EMT
+import minelastic
+
+result = minelastic.calculate(bulk("Cu", "fcc", a=3.59, cubic=True), EMT())
+print(result.summary())
+```
+
+<!-- output -->
+```text
+minelastic 0.1.0: Fm-3m (225), cubic, 1 strain pattern(s), method 'uncoupled'
+  c11 =     172.50 GPa
+  c12 =     115.35 GPa
+  c44 =      89.84 GPa
+...
+Born stable: True (eigenvalues 57.2, 57.2, 89.8, 89.8, 89.8, 403.2)
+K_VRH = 134.40  G_VRH = 56.85  E = 149.48 GPa  nu = 0.315  A_U = 1.755
+...
+```
+
+With a DFT code, minelastic writes the inputs of the strained cells from the input of the relaxed structure
+and reads the finished calculations:
+
+<!-- skip: needs a VASP template and the VASP runs -->
+```bash
+# ref/ holds POSCAR, INCAR, POTCAR and KPOINTS of the relaxed structure
+minelastic generate vasp ref/ -o el
+# run VASP in every directory listed in el/STATES
+minelastic collect el     # prints the constants, writes el/elastic.json
+```
+
+VASP, Quantum ESPRESSO, ABINIT, FHI-aims and every structure format that ASE writes are supported, and any
+ASE calculator (EMT, MACE, CP2K, ...) can be used directly.
+
+## Documentation
+
+The documentation at https://utksi.github.io/minelastic/ contains tutorials for VASP, Quantum ESPRESSO,
+ABINIT and CP2K, how-to guides for every quantity, the theory with all formulas, and the validation against
+the codes' own elastic, internal-strain, Born-charge and piezoelectric tensors. Runnable scripts are in
+[`examples/`](https://github.com/utksi/minelastic/tree/main/examples).
+
+## Usage with agentic workflows
+
+An AI coding agent can run minelastic for you. [`skills/minelastic`](https://github.com/utksi/minelastic/tree/main/skills/minelastic) is an agent skill
+with the commands and the checks that a correct calculation needs. In Claude Code:
+
+<!-- skip: Claude Code commands -->
+```text
+/plugin marketplace add utksi/minelastic
+/plugin install minelastic@minelastic
+```
+
+Other agents can read [`skills/minelastic/SKILL.md`](https://github.com/utksi/minelastic/blob/main/skills/minelastic/SKILL.md) directly. Examples are in
+the [documentation](https://utksi.github.io/minelastic/how-to/agentic-workflows/).
+
+## Citing
+
+If you use minelastic in published work, please cite the paper:
+
+```bibtex
+@misc{simak2026minimal,
+  title         = {A General Algorithm for Minimal Uncoupled Stress--Strain
+                   Calculations of Elastic Constants},
+  author        = {Simak, Sergei I. and Singh, Utkarsh},
+  year          = {2026},
+  eprint        = {2610.11733},
+  archivePrefix = {arXiv},
+  primaryClass  = {cond-mat.mtrl-sci},
+  doi           = {10.48550/arXiv.2610.11733}
+}
+```
+
+## Tests and license
+
+`pip install -e ".[test]" && pytest tests` runs the tests. They use stored stresses of real calculations,
+among them the paper's benchmark runs for all nine elastic types, and they run every code example of the
+documentation, so no DFT code is needed.
+
+minelastic is distributed under the MIT license ([LICENSE](https://github.com/utksi/minelastic/blob/main/LICENSE)). It was developed at the Department of
+Physics, Chemistry and Biology (IFM), Linköping University. Questions and bug reports are welcome as GitHub
+issues.

minelastic-0.1.0/README.md

@@ -0,0 +1,127 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://utksi.github.io/minelastic/assets/wordmark-dark.svg">
+  <img src="https://utksi.github.io/minelastic/assets/wordmark-light.svg" alt="minelastic" height="72">
+</picture>
+
+[![arXiv](https://img.shields.io/badge/arXiv-2610.11733-b31b1b.svg)](https://arxiv.org/abs/2610.11733)
+[![tests](https://github.com/utksi/minelastic/actions/workflows/tests.yml/badge.svg)](https://github.com/utksi/minelastic/actions/workflows/tests.yml)
+[![docs](https://img.shields.io/badge/docs-online-blue.svg)](https://utksi.github.io/minelastic/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/utksi/minelastic/blob/main/LICENSE)
+
+Elastic, internal-strain and piezoelectric tensors from the fewest possible stress calculations, for every
+crystal symmetry and with any electronic-structure code.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://utksi.github.io/minelastic/assets/hero-dark.svg">
+  <img src="https://utksi.github.io/minelastic/assets/hero-light.svg" alt="The usual approach applies six strain patterns; minelastic applies one to a cubic crystal and reads c11, c12 and c44 from the stress components of the strained cell. Below, the number of strain patterns for each crystal system.">
+</picture>
+
+**minelastic** implements the minimal and uncoupled strain sets scheme of
+
+> S. I. Simak and U. Singh, *A general algorithm for minimal uncoupled stress-strain calculations of
+> elastic constants*, [arXiv:2610.11733](https://arxiv.org/abs/2610.11733) (2026).
+
+Each independent elastic constant is read off one stress component of one strained cell, and the number of
+strain patterns is the smallest that any stress-strain method can use: one for a cubic crystal and two for
+tetragonal, trigonal and hexagonal crystals, where the usual approach (VASP's `IBRION = 6` and most
+workflows) applies six. The same strained cells also give the internal-strain tensor and, with Berry-phase
+dipoles, the clamped-ion piezoelectric tensor; a few single points with displaced atoms add the relaxed-ion constants,
+the Born charges and the total piezoelectric tensors; and molecular dynamics in the strained cells gives the
+constants at finite temperature.
+
+## Installation
+
+<!-- skip: installs the package -->
+```bash
+pip install minelastic
+```
+
+minelastic requires Python 3.9 or newer; numpy, spglib and ASE are installed with it.
+
+## Usage
+
+With any ASE calculator, in memory:
+
+<!-- run -->
+```python
+from ase.build import bulk
+from ase.calculators.emt import EMT
+import minelastic
+
+result = minelastic.calculate(bulk("Cu", "fcc", a=3.59, cubic=True), EMT())
+print(result.summary())
+```
+
+<!-- output -->
+```text
+minelastic 0.1.0: Fm-3m (225), cubic, 1 strain pattern(s), method 'uncoupled'
+  c11 =     172.50 GPa
+  c12 =     115.35 GPa
+  c44 =      89.84 GPa
+...
+Born stable: True (eigenvalues 57.2, 57.2, 89.8, 89.8, 89.8, 403.2)
+K_VRH = 134.40  G_VRH = 56.85  E = 149.48 GPa  nu = 0.315  A_U = 1.755
+...
+```
+
+With a DFT code, minelastic writes the inputs of the strained cells from the input of the relaxed structure
+and reads the finished calculations:
+
+<!-- skip: needs a VASP template and the VASP runs -->
+```bash
+# ref/ holds POSCAR, INCAR, POTCAR and KPOINTS of the relaxed structure
+minelastic generate vasp ref/ -o el
+# run VASP in every directory listed in el/STATES
+minelastic collect el     # prints the constants, writes el/elastic.json
+```
+
+VASP, Quantum ESPRESSO, ABINIT, FHI-aims and every structure format that ASE writes are supported, and any
+ASE calculator (EMT, MACE, CP2K, ...) can be used directly.
+
+## Documentation
+
+The documentation at https://utksi.github.io/minelastic/ contains tutorials for VASP, Quantum ESPRESSO,
+ABINIT and CP2K, how-to guides for every quantity, the theory with all formulas, and the validation against
+the codes' own elastic, internal-strain, Born-charge and piezoelectric tensors. Runnable scripts are in
+[`examples/`](https://github.com/utksi/minelastic/tree/main/examples).
+
+## Usage with agentic workflows
+
+An AI coding agent can run minelastic for you. [`skills/minelastic`](https://github.com/utksi/minelastic/tree/main/skills/minelastic) is an agent skill
+with the commands and the checks that a correct calculation needs. In Claude Code:
+
+<!-- skip: Claude Code commands -->
+```text
+/plugin marketplace add utksi/minelastic
+/plugin install minelastic@minelastic
+```
+
+Other agents can read [`skills/minelastic/SKILL.md`](https://github.com/utksi/minelastic/blob/main/skills/minelastic/SKILL.md) directly. Examples are in
+the [documentation](https://utksi.github.io/minelastic/how-to/agentic-workflows/).
+
+## Citing
+
+If you use minelastic in published work, please cite the paper:
+
+```bibtex
+@misc{simak2026minimal,
+  title         = {A General Algorithm for Minimal Uncoupled Stress--Strain
+                   Calculations of Elastic Constants},
+  author        = {Simak, Sergei I. and Singh, Utkarsh},
+  year          = {2026},
+  eprint        = {2610.11733},
+  archivePrefix = {arXiv},
+  primaryClass  = {cond-mat.mtrl-sci},
+  doi           = {10.48550/arXiv.2610.11733}
+}
+```
+
+## Tests and license
+
+`pip install -e ".[test]" && pytest tests` runs the tests. They use stored stresses of real calculations,
+among them the paper's benchmark runs for all nine elastic types, and they run every code example of the
+documentation, so no DFT code is needed.
+
+minelastic is distributed under the MIT license ([LICENSE](https://github.com/utksi/minelastic/blob/main/LICENSE)). It was developed at the Department of
+Physics, Chemistry and Biology (IFM), Linköping University. Questions and bug reports are welcome as GitHub
+issues.

minelastic-0.1.0/docs/codes/ase.md

@@ -0,0 +1,69 @@
+# ASE calculators
+
+Any ASE calculator that returns the stress can be used directly from Python: EMT and other interatomic
+potentials, machine-learned potentials such as MACE, and DFT codes driven through ASE such as CP2K. The
+[first tutorial](../get-started/first-tensor.md) uses EMT, and the [CP2K tutorial](../get-started/cp2k.md) a
+DFT code.
+
+## `calculate`
+
+<!-- input -->
+```python
+result = minelastic.calculate(atoms, calc, relax_ions=False, method="uncoupled", fmax=1e-4, steps=500,
+                              optimizer=None, dipole=None, **setup_kwargs)
+```
+
+builds the strain set of `atoms` (`ElasticSetup(atoms, **setup_kwargs)`), computes every strained and
+displaced cell with the ASE calculator `calc` and returns the `ElasticResult`. For each cell it takes
+
+* the stress, `calc.get_stress()` in eV/Å$^3$, converted to GPa (tension positive, as in ASE);
+* the forces, for the internal-strain tensor and, with `ionic=True`, the force constants;
+* the dipole `dipole(atoms)` in e Å, if a function is given, for the Born charges and the piezoelectric
+  tensors.
+
+With `relax_ions=True` the atoms of each strained cell are first relaxed at fixed cell with `optimizer`
+(default BFGS) to `fmax` (eV/Å). `setup_kwargs` are the options of `ElasticSetup`: `scheme`, `delta`,
+`stencil`, `symprec`, `frame`, `ionic` and `displacement` ([Python API](../reference/api.md)).
+
+The how-to pages show each quantity with an ASE calculator:
+
+| quantity | example | page |
+|---|---|---|
+| clamped- and relaxed-ion constants | fcc and hcp Cu, EMT | [Your first elastic tensor](../get-started/first-tensor.md) |
+| relaxed-ion constants, two routes | hcp Cu, EMT (`examples/emt_ionic.py`) | [Relaxed-ion constants](../how-to/relaxed-ions.md#with-an-ase-calculator) |
+| internal-strain tensor, force constants | hcp Cu, EMT (`examples/emt_internal_strain.py`) | [Internal strain](../how-to/internal-strain.md#with-an-ase-calculator) |
+| Born charges, piezoelectric e and d | alpha-quartz, BKS rigid-ion model (`examples/bks_quartz_piezo.py`) | [Piezoelectricity](../how-to/piezoelectricity.md#with-an-ase-calculator) |
+| finite temperature | fcc Al, EMT molecular dynamics (`examples/emt_finite_temperature.py`) | [Finite temperature](../how-to/finite-temperature.md#with-an-ase-calculator) |
+
+!!! tip
+
+    Relax the reference cell with the same calculator first: the textbook constants refer to a stress-free
+    reference.
+
+## Machine-learned potentials
+
+Any ASE calculator works.
+
+!!! tip "Double precision"
+
+    Run machine-learned potentials in double precision: the stresses of the strained cells differ by only
+    about 1 GPa.
+
+<!-- skip: needs MACE -->
+```python
+from ase.io import read
+from ase.filters import FrechetCellFilter
+from ase.optimize import BFGS
+from mace.calculators import mace_mp
+import minelastic
+
+atoms = read("POSCAR")
+calc = mace_mp(model="medium", default_dtype="float64")
+atoms.calc = calc
+BFGS(FrechetCellFilter(atoms)).run(fmax=1e-4)           # stress-free reference
+result = minelastic.calculate(atoms, calc, relax_ions=True)
+print(result.summary())
+```
+
+For wurtzite AlN with MACE-MPA-0, the minimal set and the six single strains agree to 0.1 GPa, and the two
+routes to the relaxed-ion constants to 0.3 GPa ([Validation](../reference/validation.md)).

minelastic-0.1.0/docs/codes/other.md

@@ -0,0 +1,54 @@
+# ABINIT, FHI-aims and other codes
+
+## ABINIT
+
+A complete example is the [ABINIT tutorial](../get-started/abinit.md). The template
+directory holds the reference structure as `POSCAR` and one ABINIT input file (`*.abi`) that reads it with
+`structure "poscar:POSCAR"`. The input sets everything else: pseudopotentials in the order of the POSCAR
+species, cutoff, k-point mesh and convergence.
+
+ABINIT's POSCAR reader takes the element of each atom from the end of its coordinate line, so minelastic
+writes the strained POSCARs in that form; for the same reason two species of one element cannot be used.
+Magnetic sublattices are set with `spinat`, which minelastic also reads for the symmetry
+([Magnetic materials](../how-to/magnetic.md)). `collect` reads the stress and forces from the newest
+`*.abo` file of each directory. With `--relax-ions`, `ionmov 2`, `ntime 100` and `tolmxf 1.0d-6` are
+appended unless the input sets `ionmov`. The cell must stay fixed (`optcell 0`), the ions must stay fixed for
+clamped-ion runs (no `ionmov`), and dataset-specific values of `ionmov` and `optcell` are not accepted.
+
+## FHI-aims
+
+The template directory holds `geometry.in` (the reference structure) and `control.in`:
+
+<!-- skip: needs an FHI-aims template and the FHI-aims runs -->
+```bash
+minelastic generate aims ref/ -o el          # geometry.in per strain state, control.in copied
+# run aims in every directory, output in aims.out
+minelastic collect el
+```
+
+`control.in` must request the stress (`compute_analytical_stress .true.`) and must not relax the cell
+(`relax_unit_cell`); otherwise `generate` stops with an error. For clamped ions it must not relax the atoms
+either. With `--relax-ions`, `relax_geometry bfgs 1E-3` is added unless it is present. The FHI-aims reader
+is tested on an output distributed with ASE; minelastic has not been run with FHI-aims itself.
+
+## Any format ASE can write (CASTEP, SIESTA, ...)
+
+The `generic` interface writes only the strained structure in each directory and copies further input
+files. The results are read back with ASE:
+
+<!-- skip: needs CASTEP inputs and the CASTEP runs -->
+```bash
+minelastic generate generic crystal.cell -o el --format castep-cell --filename crystal.cell \
+    --extra crystal.param
+# run the code in every directory
+minelastic collect el --output crystal.castep --format castep-castep
+```
+
+The reference structure (`crystal.cell` here) is read with the same `--format` as the files that are
+written. Make sure the inputs request the stress and keep the cell fixed. Keep the ions fixed too, unless
+you want relaxed ions. `minelastic info crystal.cell --format castep-cell` shows the strain set first.
+
+## Anything else
+
+The Python API separates the strain set from how the calculations are run, so stresses from any source can
+be used ([Your own workflow](../how-to/own-workflow.md)).

minelastic-0.1.0/docs/codes/qe.md

@@ -0,0 +1,41 @@
+# Quantum ESPRESSO
+
+A complete example is the [Quantum ESPRESSO tutorial](../get-started/qe.md). Below we describe how
+minelastic handles the pw.x inputs and outputs.
+
+## Template and commands
+
+The template is the pw.x input of the relaxed reference structure. pw.x runs in one sub-directory per
+state, so set `pseudo_dir` to an absolute path.
+
+<!-- skip: needs a pw.x template and the pw.x runs -->
+```bash
+minelastic generate qe pw.in -o el                  # clamped ions
+minelastic generate qe pw.in -o el_relaxed --relax-ions
+for d in $(cat el/STATES); do (cd el/$d && mpirun pw.x -in pw.in > pw.out); done
+minelastic collect el
+```
+
+## The inputs
+
+Every strained input is written with
+
+* `ibrav = 0`, the strained `CELL_PARAMETERS` in Å and `ATOMIC_POSITIONS crystal`;
+* the species labels and `if_pos` flags of the template;
+* `tstress` and `tprnfor` switched on.
+
+Any `ibrav` is accepted, with `celldm` or with `A, B, C, cosAB, ...`, and the positions may be given in
+`alat`, `bohr`, `angstrom` or `crystal`. All other namelists and cards are copied unchanged. For relaxed
+ions, `calculation = 'relax'` is set, with tight `forc_conv_thr` and `etot_conv_thr` unless the template
+sets them: the defaults of pw.x stop the relaxation before the internal strain is relaxed. `collect` reads
+`pw.out` in each directory (`--output` for another name). pw.x prints the stress in Ry/bohr$^3$, positive in
+compression; minelastic converts it to GPa, positive in tension.
+
+## Magnetic order and molecular dynamics
+
+pw.x needs a separate species label for every magnetic sublattice (starting magnetization per species), and
+minelastic treats the labels as distinct species in the symmetry analysis. With `noncolin = .true.` it also
+reads the moment directions from `starting_magnetization`, `angle1` and `angle2`
+([Magnetic materials](../how-to/magnetic.md)). For finite temperature, the template has `calculation = 'md'`
+with a thermostat in `&IONS` and a fixed cell; `generate --md` keeps it and `collect --md` averages the
+stresses of all steps ([Finite temperature](../how-to/finite-temperature.md#with-vasp-or-quantum-espresso)).

minelastic-0.1.0/docs/codes/vasp.md

@@ -0,0 +1,92 @@
+# VASP
+
+A complete example is the [VASP tutorial](../get-started/vasp.md). Below we describe how minelastic
+handles the VASP inputs and outputs.
+
+## Template and commands
+
+The template directory holds the input of the relaxed reference structure: `POSCAR`, `INCAR`, `POTCAR`, and
+`KPOINTS` or `KSPACING` in the INCAR.
+
+<!-- skip: needs a template directory ref/ and the VASP runs -->
+```bash
+minelastic info --code vasp ref/             # symmetry, tensor form and strain set; no files written
+minelastic generate vasp ref/ -o el          # one directory per state, listed in el/STATES
+minelastic collect el                        # after the runs; writes el/elastic.json
+```
+
+Each `el/<state>/` holds `POSCAR` (the strained or displaced cell, with the species lines and the
+selective-dynamics flags of the template), `INCAR`, `KPOINTS` and `POTCAR` (`--potcar link` symlinks it).
+`el/minelastic.json` records the setup; `collect` needs it.
+
+## The INCAR
+
+`generate` copies the template's INCAR and changes only what the type of calculation requires:
+
+* `IBRION = -1`, `NSW = 0`, `ISIF = 2` for clamped ions (`ISIF = 2` computes the stress);
+* `IBRION = 2`, `NSW = 99`, `ISIF = 2` and, unless set, `EDIFFG = -5E-4` with `--relax-ions`;
+* with `--md`, the template's `IBRION = 0`, `NSW` and `POTIM` are kept and `ISIF = 2` is set;
+* `NFREE`, `POTIM`, `LEPSILON` and `LCALCEPS` are removed, so that an `IBRION = 6` input can be used as it
+  is (relaxations then use VASP's default `POTIM`);
+* `KSPACING` is replaced by the explicit k-point mesh of the reference cell, so that all cells use the same
+  mesh.
+
+Every change is listed. The settings that matter for stress differences of a few GPa are checked, but left as
+they are: `EDIFF` at most 1E-6 (1E-8 suggested; 1E-6 for MD), `ENCUT` at least 1.3 times the largest
+`ENMAX` of the POTCAR, `PREC = Accurate` (or `High`) and `LREAL = .FALSE.`. The template of the tutorial
+meets all of them. The INCAR of an `IBRION = 6` run with VASP's defaults gives:
+
+<!-- shell -->
+```console
+$ cat ibrion6/INCAR
+IBRION = 6
+ISIF = 3
+NFREE = 2
+POTIM = 0.015
+$ minelastic generate vasp ibrion6 -o el
+...
+NOTE: INCAR: set IBRION = -1 (template: 6), NSW = 0, ISIF = 2 (template: 3); removed NFREE, POTIM
+NOTE: INCAR: recommended for small stress differences: EDIFF default 1E-4 -> 1E-8, ENCUT default ENMAX = 400 -> 520, PREC default Normal -> Accurate. The template values are kept; --fix-incar (fix_incar=True) applies all of these
+```
+
+`--fix-incar` applies all of the recommended values. There is no partial fix: the INCAR is either the
+template's or follows all the recommendations.
+
+## Running
+
+Any scheduler works. For example, a Slurm job array over the lines of `STATES`:
+
+<!-- skip: submits a Slurm job -->
+```bash
+#!/bin/bash
+#SBATCH --array=1-8              # one task per line of el/STATES
+d=el/$(sed -n "${SLURM_ARRAY_TASK_ID}p" el/STATES)
+cd "$d" && srun vasp_std > out
+```
+
+## Reading the results
+
+`collect` reads the stress and the forces of each directory from `vasprun.xml`, or from `OUTCAR` if there is
+no readable `vasprun.xml`. VASP prints the stress in kB, positive in compression, in the order XX YY ZZ XY YZ
+ZX; minelastic converts it to GPa, positive in tension, in Voigt order. With `--md` the stress of every ionic
+step is read; with `--piezo` the Berry-phase dipole of each cell (`LCALCPOL`); with `--born OUTCAR` the Born
+charges and the clamped-ion piezoelectric tensor of a DFPT (`LEPSILON`) or `LCALCEPS` run.
+
+`minelastic vasp-tensor OUTCAR` reads the tensor that VASP prints for `IBRION = 6` with `ISIF = 3` or more,
+converts it to GPa and Voigt order, and adds the Voigt-Reuss-Hill moduli and the Born stability test
+([Elastic constants in practice](../how-to/elastic.md#compare-with-vasps-ibrion-6)).
+
+## Notes
+
+* Use the same `ENCUT`, `PREC`, k-point mesh and `EDIFF` for the reference and all strained cells. The
+  plane-wave basis changes with the volume of the strained cell, and a raised cutoff (1.3 to 1.4 times
+  ENMAX) keeps the resulting Pulay stress small.
+* `MAGMOM`, `LDAU*`, `ISPIN` and all other tags are copied unchanged, and `MAGMOM` enters the symmetry
+  analysis ([Magnetic materials](../how-to/magnetic.md)). If the cell has to be rotated to its standard
+  orientation, direction-dependent inputs (`LNONCOLLINEAR`, `LSORBIT`, `SAXIS`, `EFIELD`, Cartesian k points)
+  are refused; use `--frame input`.
+* The elastic constants, the internal-strain tensor, the relaxed-ion constants and the piezoelectric tensors
+  of the tutorial structure are on the how-to pages:
+  [elastic constants](../how-to/elastic.md), [relaxed ions](../how-to/relaxed-ions.md#with-vasp),
+  [internal strain](../how-to/internal-strain.md#with-vasp) and
+  [piezoelectricity](../how-to/piezoelectricity.md#with-vasp).