pymatgen.analysis.substrate_analyzer module

class SubstrateAnalyzer(zslgen=<pymatgen.analysis.substrate_analyzer.ZSLGenerator object>)[source]

Bases: object

This class applies a set of search criteria to identify suitable substrates for film growth. It first uses a topoplogical search by Zur and McGill to identify matching super-lattices on various faces of the two materials. Additional criteria can then be used to identify the most suitable substrate. Currently, the only additional criteria is the elastic strain energy of the super-lattices

Initializes the substrate analyzer :param zslgen: Defaults to a ZSLGenerator with standard

tolerances, but can be fed one with custom tolerances
calculate(film, substrate, elasticity_tensor=None, film_millers=None, substrate_millers=None, ground_state_energy=0, lowest=False)[source]

Finds all topological matches for the substrate and calculates elastic strain energy and total energy for the film if elasticity tensor and ground state energy are provided:

  • film (Structure) – conventional standard structure for the film
  • substrate (Structure) – conventional standard structure for the substrate
  • elasticity_tensor (ElasticTensor) – elasticity tensor for the film
  • film_millers (array) – film facets to consider in search as defined by miller indicies
  • substrate_millers (array) – substrate facets to consider in search as defined by miller indicies
  • ground_state_energy (float) – ground state energy for the film
  • lowest (bool) – only consider lowest matching area for each surface
calculate_3D_elastic_energy(film, match, elasticity_tensor=None, include_strain=False)[source]

Calculates the multi-plane elastic energy. Returns 999 if no elastic tensor was given on init

  • film (Structure) – conventional standard structure for the film
  • match (dictionary) – match dictionary from substrate analyzer
  • elasticity_tensor (ElasticTensor) – elasticity tensor for the film
  • include_strain (bool) – include strain in the output or not; changes return from just the energy to a tuple with the energy and strain in voigt notation
class ZSLGenerator(max_area_ratio_tol=0.09, max_area=400, film_max_miller=1, substrate_max_miller=1, max_length_tol=0.03, max_angle_tol=0.01)[source]

Bases: object

This class generate interface super lattices based on the methodology of lattice vector matching for heterostructural interfaces proposed by Zur and McGill: Journal of Applied Physics 55 (1984), 378 ; doi: 10.1063/1.333084

The process of generating all possible interaces is as such:

1.) Generate all slabs for the film and substrate for different orientations
given by maximum miller limitations
2.) For each film/substrate orientation pair:

1.) Reduce lattice vectors and calculate area 2.) Generate all super lattice transformations within a maximum area

limit that give nearly equal area super-lattices for the two surfaces
3.) For each superlattice set:

1.) Reduce super lattice vectors 2.) Check length and angle between film and substrate super lattice

vectors to determine if the super lattices are the nearly same and therefore coincident
Intialize a Zur Super Lattice Generator for a specific film and
  • max_area_ratio_tol (float) – Max tolerance on ratio of super-lattices to consider equal
  • max_area (float) – max super lattice area to generate in search
  • film_max_miller (int) – maximum miller index to generate for film surfaces
  • substrate_max_miller (int) – maximum miller index to generate for substrate surfaces
  • max_length_tol – maximum length tolerance in checking if two vectors are of nearly the same length
  • max_angle_tol – maximum angle tolerance in checking of two sets of vectors have nearly the same angle between them
check_transformations(transformation_sets, film_vectors, substrate_vectors)[source]

Applies the transformation_sets to the film and substrate vectors to generate super-lattices and checks if they matches. Returns all matching vectors sets.

  • transformation_sets (array) – an array of transformation sets: each transformation set is an array with the (i,j) indicating the area multipes of the film and subtrate it corresponds to, an array with all possible transformations for the film area multiple i and another array for the substrate area multiple j.
  • film_vectors (array) – film vectors to generate super lattices
  • substrate_vectors (array) – substrate vectors to generate super lattices
generate(film, substrate, film_millers=None, substrate_millers=None, lowest=False)[source]

Generates the film/substrate combinations for either set miller indicies or all possible miller indices up to a max miller index

  • film (Structure) – Conventional standard pymatgen structure for the film
  • substrate (Struture) – Conventional standard pymatgen Structure for the substrate
  • film_millers (array) – array of film miller indicies to consider in the matching algorithm
  • substrate_millers (array) – array of substrate miller indicies to consider in the matching algorithm

Generates the transformation matricies that convert a set of 2D vectors into a super lattice of integer area multiple as proven in Cassels:

Cassels, John William Scott. An introduction to the geometry of numbers. Springer Science & Business Media, 2012.

  • area_multiple (int) – integer multiple of unit cell area for super
  • area (lattice) –

transformation matricies to covert unit vectors to super lattice vectors

Return type:


generate_sl_transformations(film_area, substrate_area)[source]

Generates transformation sets for film/substrate pair given the area of the unit cell area for the film and substrate. The transformation sets map the film and substrate unit cells to super lattices with a maximum area

  • film_area (int) – the unit cell area for the film
  • substrate_area (int) – the unit cell area for the substrate

a set of transformation_sets defined as:

1.) the (i,j) pair corresponding to the integer multiple of the film area (i) and substrate area (j) that makes the two equal within tolerance 2.) the transformation matricies for the film to create a super lattice of area i*film area 3.) the tranformation matricies for the substrate to create a super lattice of area j*film area

Return type:


generate_slabs(film_millers, substrate_millers)[source]

Generates the film/substrate slab combinations for a set of given miller indicies

  • film_millers (array) – all miller indices to generate slabs for film
  • substrate_millers (array) – all miller indicies to generate slabs for substrate
is_same_vectors(vec_set1, vec_set2)[source]

Determine if two sets of vectors are the same within length and angle tolerances

  • vec_set1 (array[array]) – an array of two vectors
  • vec_set2 (array[array]) – second array of two vectors
match_as_dict(film_miller, substrate_miller, film_sl_vectors, substrate_sl_vectors, film_vectors, substrate_vectors, match_area)[source]

Returns dict which contains ZSL match

  • film_miller (array) –
  • substrate_miller (array) –
rel_angle(vec_set1, vec_set2)[source]

Calculate the relative angle between two vector sets

  • vec_set1 (array[array]) – an array of two vectors
  • vec_set2 (array[array]) – second array of two vectors
rel_strain(vec1, vec2)[source]

Calculate relative strain between two vectors


Much faster variant of numpy linalg norm


Generate all factors of n

reduce_vectors(a, b)[source]

Generate independent and unique basis vectors based on the methodology of Zur and McGill

vec_angle(a, b)[source]

Calculate angle between two vectors

vec_area(a, b)[source]

Area of lattice plane defined by two vectors