Python API¶
import minelastic
from minelastic import ElasticSetup, ElasticResult, calculate, generate, collect
All quantities follow the conventions: GPa, Voigt order xx yy zz yz xz xy, engineering shear strain, stress positive in tension.
| name | what it does |
|---|---|
calculate |
the whole calculation with an ASE calculator, in memory |
ElasticSetup |
the strain set of a structure, its strained cells, and the tensor from their stresses |
ElasticResult |
the constants, tensors, moduli and checks |
generate, collect |
the minelastic generate and minelastic collect commands, for DFT codes |
calculate ¶
calculate(atoms, calc, relax_ions=False, method='uncoupled', fmax=0.0001, steps=500, optimizer=None, dipole=None, **setup_kwargs)
Elastic tensor of atoms from the stresses of every strained cell, computed with an ASE calculator.
Builds ElasticSetup(atoms, **setup_kwargs), computes the stress (eV/A^3 from calc, converted to GPa, tension positive) and the forces (eV/A) of every state with calc, and returns ElasticSetup.compute of them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
atoms
|
Atoms
|
Reference structure, relaxed and stress-free for the textbook constants. |
required |
calc
|
ase calculator
|
Calculator that returns the stress; it is attached to every strained cell. |
required |
relax_ions
|
bool
|
Relax the atoms of each strained cell at fixed cell (optimizer, default BFGS, to fmax eV/A within steps steps); the constants are then the relaxed-ion constants and no forces are passed on. Otherwise the cells are clamped and their forces give the internal-strain tensor. |
False
|
method
|
str
|
Extraction method of ElasticSetup.compute: 'uncoupled', 'designated' or 'lstsq'. |
'uncoupled'
|
fmax
|
Convergence (eV/A), step limit and ASE optimizer class of the relaxations. |
0.0001
|
|
steps
|
Convergence (eV/A), step limit and ASE optimizer class of the relaxations. |
0.0001
|
|
optimizer
|
Convergence (eV/A), step limit and ASE optimizer class of the relaxations. |
0.0001
|
|
dipole
|
callable
|
Function of an Atoms object (calculator attached, after any relaxation) that returns the dipole moment of the cell in e*Angstrom, physical sign. It gives the piezoelectric tensor e = dP/de (clamped-ion for clamped cells, relaxed-ion with relax_ions) and, with ionic=True, the Born charges, the total e and d. |
None
|
**setup_kwargs
|
Options of ElasticSetup: scheme, delta, stencil, symprec, frame, ionic, displacement. |
{}
|
Returns:
| Type | Description |
|---|---|
ElasticResult
|
With ionic=True, result.C_relaxed is the relaxed-ion stiffness from the clamped cells and the displacements. |
ElasticSetup ¶
Strain set of one crystal and the extraction of its elastic constants.
The point group of atoms restricts the stiffness to C = sum_p c_p B_p with n independent constants c_p. Each strain pattern u_k (a 6-vector, engineering Voigt) is applied at the strains m delta u_k for the multipliers m of the finite-difference formula.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
atoms
|
Atoms
|
Reference structure, relaxed and stress-free for the textbook constants. Initial magnetic moments enter the symmetry analysis. |
required |
scheme
|
str or list
|
'minimal' (the minimal uncoupled set), 'asess' (the six single-component strains), or a list of 6-vectors (patterns per unit step, engineering Voigt). |
'minimal'
|
delta
|
float
|
Strain step. |
0.01
|
stencil
|
str or tuple
|
'four-point' (multipliers -2, -1, 1, 2; error O(delta^4); the default), 'central' (-1, 1; error O(delta^2), half the cells, the choice for noisy MD averages), 'forward' (1, with the unstrained reference) or a tuple of multipliers of delta. |
'four-point'
|
symprec
|
float
|
spglib tolerance (Angstrom). |
1e-05
|
frame
|
str
|
'auto', 'input' or 'standard': orientation in which the strains are applied (see _choose). |
'auto'
|
ionic
|
bool
|
Also displace the symmetry-irreducible atoms, for the relaxed-ion and piezoelectric response from clamped calculations (see ionic.py). |
False
|
displacement
|
float
|
Atomic step (Angstrom), with the same multipliers as the strains. |
0.01
|
Attributes:
| Name | Type | Description |
|---|---|---|
states |
list of dict
|
One dict per calculation, with id, pattern, amplitude and strain (engineering Voigt): 's{k}_p{m}' / 's{k}_m{m}' for pattern k at +m delta / -m delta, 'd{k}_p{m}' / 'd{k}_m{m}' for displacement k (with atom and the Cartesian vector in Angstrom), and 'ref' (zero strain) when the formula has no negative multiplier. |
patterns |
(K, 6) array
|
The strain patterns u_k. |
displacements |
list
|
The symmetry-irreducible (atom index, Cartesian unit vector) pairs, with ionic. |
atoms, input_atoms, rotation |
The reference structure in the working frame and as given, and the rotation R with x_work = R x_input. |
|
symmetry |
Space-group number, international symbol, point group, Cartesian rotations and atom permutations. |
|
form |
TensorForm
|
The symmetry-adapted form of C: labels of the independent constants, matrix(c), project(C) and expression(i, j). |
n_min |
int
|
Lower bound on the number of strain patterns: the dimension of the invariant strain subspace. |
compute ¶
compute(stresses, forces=None, method='uncoupled', kinetic_temperature=None, stress_measure='cauchy', polarization=None, pol_quantum=1.0, born=None, clamped_piezo=None, internal_strain_from='displacements')
Elastic tensor from the stresses (and optionally forces and dipoles) of the states.
r_k = (1/delta) sum_m g_m sigma(m delta u_k) is the response of pattern k (of J sigma for 'kirchhoff', J = det F), and r_ki = sum_p a_kip c_p with a_kip = (B_p u_k)_i. 'uncoupled': c_p is the mean of r_ki / a_kip over all single-constant relations of p, with its standard error from Cov(r_k) (correlations within a pattern included); 'designated': the first such relation; 'lstsq': weighted least squares over all relations, weight w_i^2 / |u_k|_M^2 (Mandel stress metric, per unit Mandel strain of the pattern), or, with samples, generalized least squares with Cov(r_k). Then C = sum_p c_p B_p, plus n kB T in C_ij (i, j <= 3) for kinetic_temperature (Cauchy stress only: the Kirchhoff kinetic stress -N kB T / V0 does not depend on the strain). checks compares every r_ki with (C u_k)_i.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stresses
|
dict
|
{state_id: (6,) or (n_samples, 6)} Cauchy stress in GPa, physical sign (tension > 0), Voigt order xx yy zz yz xz xy, in the working frame (as computed for the generated cells). Several samples (e.g. MD configurations) are averaged and give standard errors. |
required |
forces
|
dict
|
{state_id: (N, 3)} forces (eV/A) of clamped-ion calculations, giving the internal-strain tensor. |
None
|
method
|
str
|
'uncoupled' (every constant from the stress components that contain it alone, averaged over all such components), 'designated' (the first such component only, as in the paper's tables) or 'lstsq' (least squares over all stress components of all patterns). |
'uncoupled'
|
kinetic_temperature
|
float
|
T (K): add the ideal-gas term n kB T to C_ij (i, j <= 3), for MD stresses that contain only the virial (e.g. VASP). |
None
|
stress_measure
|
str
|
'cauchy' (default) differentiates the Cauchy stress; 'kirchhoff' differentiates J sigma (J = V/V0), as VASP does for IBRION=6 (SIF/Omega0). Both give the same constants for a stress-free reference; they differ at O(delta^2) in the finite differences. |
'cauchy'
|
polarization
|
dict
|
{state_id: (3,)} dipole moment of the cell in e*Angstrom, physical sign (positive charge), e.g. from a Berry-phase calculation. Gives the proper piezoelectric tensor (clamped-ion for clamped cells, total for relaxed ions), completed by symmetry, and with ionic=True the Born charges. |
None
|
pol_quantum
|
float
|
Berry-phase quantum in reduced units used for the branch alignment (1 is safe for spin-polarized and non-spin-polarized cases alike). |
1.0
|
born
|
array
|
With ionic=True: (N, 3, 3) Born charges (|e|, Z[n, alpha, j] = dp_alpha/du_nj, working frame), e.g. from DFPT; replaces those from the dipoles of the displaced atoms. |
None
|
clamped_piezo
|
array
|
With ionic=True: (3, 6) clamped-ion piezoelectric tensor (C/m^2, working frame), e.g. from DFPT; used when the strained cells have no dipoles. |
None
|
internal_strain_from
|
str
|
With ionic=True: 'displacements' (stresses of the displaced cells, as VASP, for the ionic terms) or 'strains' (forces in the strained cells). |
'displacements'
|
Returns:
| Type | Description |
|---|---|
ElasticResult
|
|
strained_atoms ¶
strained_atoms(state)
Atoms of a state (dict or id) in the working frame: lattice vectors a_i' = F a_i, F = I + eps(strain), fractional coordinates kept; in a displaced-atom state, atom n moved by the Cartesian vector.
describe ¶
describe()
Text summary as printed by minelastic info: symmetry, n_min, frame, tensor form, patterns and the single-constant relation of each stress component.
relation_table ¶
relation_table()
algorithm.relations of every pattern: r_ki = sum_p a_kip c_p per unit step, classified.
to_dict ¶
to_dict()
JSON-ready record: program name, version and URL, input structure (with initial magnetic moments and species labels when set), frame rotation, delta, stencil, symprec, scheme, patterns, states, displacements and the symmetry found.
from_dict
classmethod
¶
from_dict(d)
Setup from to_dict() output, with the stored frame and patterns; symmetry and tensor form are recomputed from the stored structure. ValueError if the rebuilt states (ids, strains, displaced atoms and vectors) differ from the stored ones.
ElasticResult ¶
Result of ElasticSetup.compute. All tensors are in the working frame.
Attributes:
| Name | Type | Description |
|---|---|---|
constants, labels, errors |
Independent constants c_p (GPa), their names (c11, c12, ...) and standard errors (None without samples). |
|
C |
(6, 6) array
|
Stiffness C = sum_p c_p B_p (GPa), Voigt order xx yy zz yz xz xy, engineering shear strain. |
checks |
list
|
Every stress relation r_ki with its computed and fitted value. |
internal_strain |
(N, 3, 6) array or None
|
Lambda = dF/d eps (eV/A per unit strain), from the forces of clamped cells. |
piezo |
(3, 6) array or None
|
e = dP/d eps (C/m^2) from the dipoles of the strained cells; the clamped-ion e0 for clamped cells. |
force_constants, internal_strain_displaced, born, C_ionic, piezo_ionic, piezo_total, piezo_d, ionic_relaxation |
With ionic=True: Phi (N, 3, N, 3, eV/A^2), Lambda from the displaced atoms, Z* (N, 3, 3, |e|), -Lambda^T Phi^+ Lambda / Omega (GPa), Z* Phi^+ Lambda / Omega (C/m^2), e = e0 + piezo_ionic, d = e C^-1 (pC/N) and u = Phi^+ Lambda (N, 3, 6, A per unit strain). |
C_input_frame
property
¶
C_input_frame
C in the input orientation: rotate_stiffness(C, R^T), with x_work = R x_input.
C_relaxed
property
¶
C_relaxed
C + C_ionic: the relaxed-ion stiffness (GPa); None without the ionic route.
to_dict ¶
to_dict()
JSON-ready dict of all results, as written to elastic.json, headed by the program name, version and URL.
generate ¶
generate(code, template, out_dir, scheme='minimal', delta=0.01, stencil=None, symprec=1e-05, frame='auto', relax_ions=False, fmt=None, filename=None, extra_files=(), ionic=False, displacement=0.01, md=False, **code_kwargs)
Writes the inputs of every strained (and displaced-atom) cell from a template, as minelastic generate.
One directory per state of ElasticSetup(reference structure of the template, ...) is written into out_dir, plus minelastic.json (the setup record that collect needs) and STATES (the state names, one per line).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
code
|
str
|
'vasp', 'qe', 'abinit', 'aims' or 'generic'. |
required |
template
|
str
|
vasp, abinit, aims: directory with the inputs of the relaxed reference structure; qe: pw.x input; generic: structure file. |
required |
out_dir
|
str
|
Output directory. |
required |
scheme
|
As for ElasticSetup. |
'minimal'
|
|
delta
|
As for ElasticSetup. |
'minimal'
|
|
symprec
|
As for ElasticSetup. |
'minimal'
|
|
frame
|
As for ElasticSetup. |
'minimal'
|
|
displacement
|
As for ElasticSetup. |
'minimal'
|
|
stencil
|
str
|
As for ElasticSetup; by default 'four-point', and 'central' with md. |
None
|
relax_ions
|
bool
|
Relax the atoms in each strained cell (relaxed-ion constants). |
False
|
ionic
|
bool
|
Also the symmetry-irreducible atomic displacements; the clamped single points then give the relaxed-ion tensors, the Born charges and the piezoelectric response. |
False
|
md
|
bool
|
Fixed-cell molecular dynamics in every strained cell as set up in the template (VASP: IBRION = 0 with NSW, POTIM and the thermostat; QE: calculation = 'md'); collect with md=True. |
False
|
fmt
|
generic interface: ASE format, structure file name, files copied into every directory. |
None
|
|
filename
|
generic interface: ASE format, structure file name, files copied into every directory. |
None
|
|
extra_files
|
generic interface: ASE format, structure file name, files copied into every directory. |
None
|
|
**code_kwargs
|
Options of the code's prepare (vasp: potcar='copy' or 'link', nsw, fix_incar). |
{}
|
Returns:
| Type | Description |
|---|---|
(ElasticSetup, list of str)
|
The setup and the notes: the changes made to the template and the recommended settings it misses. |
collect ¶
collect(out_dir, method='uncoupled', output=None, fmt=None, md=False, skip=0, kinetic_temperature=None, samples=None, stress_measure='cauchy', polarization=False, born_file=None, save=True)
Elastic tensor from the finished calculations in out_dir (as written by generate), as minelastic collect.
Reads the stress (and forces, and dipoles) of every state and returns ElasticSetup.compute of them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
out_dir
|
str
|
Directory written by generate. |
required |
method
|
str
|
'uncoupled', 'designated' or 'lstsq' (see ElasticSetup.compute). |
'uncoupled'
|
output
|
Output file name in each directory (default per code) and, for generic, its ASE format. |
None
|
|
fmt
|
Output file name in each directory (default per code) and, for generic, its ASE format. |
None
|
|
md
|
bool
|
The stress of each state is the set of all MD steps after the first skip (VASP, QE); the standard errors assume uncorrelated steps, so thin or block-average long trajectories. |
False
|
skip
|
int
|
Number of initial MD steps discarded. |
0
|
kinetic_temperature
|
Passed to ElasticSetup.compute. |
None
|
|
stress_measure
|
Passed to ElasticSetup.compute. |
None
|
|
samples
|
str
|
Glob of sub-directories of each state (e.g. 'conf-*'), whose stresses are the samples. |
None
|
polarization
|
bool
|
Read the Berry-phase dipoles (VASP LCALCPOL) of all cells: e0 from the strained cells and, with displaced atoms, the Born charges. |
False
|
born_file
|
str
|
OUTCAR of a VASP LEPSILON or LCALCEPS run of the reference structure; its Born charges and e0, rotated to the working frame, are used for the ionic terms. |
None
|
save
|
bool
|
Also write the result to out_dir/elastic.json. |
True
|
Returns:
| Type | Description |
|---|---|
ElasticResult
|
|
Code interfaces and utilities¶
| module | contents |
|---|---|
minelastic.io.vasp |
read_vasprun, read_outcar, read_result, read_elastic_tensor, read_dipole, read_born_charges, read_clamped_piezo, read_incar, kspacing_grid |
minelastic.io.qe |
read_structure (any ibrav), read_output, qe_lattice |
minelastic.io.abinit, minelastic.io.aims, minelastic.io.generic |
read_structure, prepare, read_result |
minelastic.properties |
vrh(C), born_stable(C) |
minelastic.voigt |
rotate_stiffness(C, R), mandel_rotation(R), conversions between strain and stress vectors and tensors |
minelastic.symmetry |
analyze(atoms, symprec), elastic_type(spacegroup_number), rotate_atoms(atoms, R) |
minelastic.tensor_form |
TensorForm(rotations), invariant_strain_dimension(rotations) |
minelastic.algorithm |
paper_greedy(form), exact_minimum(form), relations(form, pattern), choose_amplitudes |
minelastic.ionic |
irreducible_displacements, force_constants, born_charges, ionic_contributions, strain_coefficients, rotate_born, rotate_piezo |
minelastic.internal_strain, minelastic.piezo |
symmetry completion of the internal-strain and piezoelectric tensors |