schrodinger.application.matsci.interface module¶

Utilities for building interfaces using pymatgen.

class schrodinger.application.matsci.interface.SubstrateFilmMillers(substrate, film)¶

Bases: tuple

film¶: Alias for field number 1

substrate¶: Alias for field number 0

class schrodinger.application.matsci.interface.Slab(slab, st)¶

Bases: tuple

slab¶: Alias for field number 0

st¶: Alias for field number 1

class schrodinger.application.matsci.interface.SubstrateFilmTerminations(substrate, film)¶

Bases: tuple

film¶: Alias for field number 1

substrate¶: Alias for field number 0

class schrodinger.application.matsci.interface.SubstrateFilmShifts(substrate, film)¶

Bases: tuple

film¶: Alias for field number 1

substrate¶: Alias for field number 0

class schrodinger.application.matsci.interface.GetInterfacesKwargs(zslgen_kwargs, get_interfaces_kwargs)¶

Bases: tuple

get_interfaces_kwargs¶: Alias for field number 1

zslgen_kwargs¶: Alias for field number 0

class schrodinger.application.matsci.interface.SubstrateFilmInterface(interface, interface_st, substrate_st, film_st)¶

Bases: tuple

film_st¶: Alias for field number 3

interface¶: Alias for field number 0

interface_st¶: Alias for field number 1

substrate_st¶: Alias for field number 2

schrodinger.application.matsci.interface.get_pretty_float(num, percentage=False, n_decimal=3)¶

Return a pretty version of the given float.

Parameters:

num (float) – the float
percentage (bool) – if True make a percentage
n_decimal (int) – the number of decimals

Return type:

str

Returns:

pretty float

schrodinger.application.matsci.interface.get_max_area(match_area, max_area_buffer=50.0)¶

Return the max area from the given match area.

Parameters:

match_area (float) – the match area in Ang.^2
max_area_buffer (float) – the match area buffer in Ang.^2

Return type:

float

Returns:

the max area in Ang.^2

schrodinger.application.matsci.interface.get_pretty_structure(st)¶

Return a pretty copy of the given structure.

Parameters:: st (schrodinger.structure.Structure) – the structure
Return type:: schrodinger.structure.Structure
Returns:: the pretty structure

exception schrodinger.application.matsci.interface.InterfaceException¶: Bases: Exception

class schrodinger.application.matsci.interface.ConventionalSlabGenerator(*args, **kwargs)¶

Bases: SlabGenerator

SlabGenerator subclass that forces primitive=False. Used to monkey-patch pymatgen.analysis.interfaces.coherent_interfaces.SlabGenerator so that CoherentInterfaceBuilder’s hardcoded primitive=True is bypassed. See MATSCI-21585, where the primitive reduction of the Si(100) slab produces two half-coverage terminating layers instead of the expected uniform coverage.

__init__(*args, **kwargs)¶

Calculates the slab scale factor and uses it to generate a unit cell of the initial structure that has been oriented by its miller index. Also stores the initial information needed later on to generate a slab.

Args:

initial_structure (Structure): Initial input structure. Note that to: ensure that the miller indices correspond to usual crystallographic definitions, you should supply a conventional unit cell structure.
miller_index ([h, k, l]): Miller index of plane parallel to: surface. Note that this is referenced to the input structure. If you need this to be based on the conventional cell, you should supply the conventional structure.

min_slab_size (float): In Angstroms or number of hkl planes min_vacuum_size (float): In Angstroms or number of hkl planes lll_reduce (bool): Whether to perform an LLL reduction on the

eventual structure.

center_slab (bool): Whether to center the slab in the cell with: equal vacuum spacing from the top and bottom.
in_unit_planes (bool): Whether to set min_slab_size and min_vac_size: in units of hkl planes (True) or Angstrom (False/default). Setting in units of planes is useful for ensuring some slabs have a certain n_layer of atoms. e.g. for Cs (100), a 10 Ang slab will result in a slab with only 2 layer of atoms, whereas Fe (100) will have more layer of atoms. By using units of hkl planes instead, we ensure both slabs have the same number of atoms. The slab thickness will be in min_slab_size/math.ceil(self._proj_height/dhkl) multiples of oriented unit cells.
primitive (bool): Whether to reduce any generated slabs to a: primitive cell (this does not mean the slab is generated from a primitive cell, it simply means that after slab generation, we attempt to find shorter lattice vectors, which lead to less surface area and smaller cells).
max_normal_search (int): If set to a positive integer, the code will: conduct a search for a normal lattice vector that is as perpendicular to the surface as possible by considering multiples linear combinations of lattice vectors up to max_normal_search. This has no bearing on surface energies, but may be useful as a preliminary step to generating slabs for absorption and other sizes. It is typical that this will not be the smallest possible cell for simulation. Normality is not guaranteed, but the oriented cell will have the c vector as normal as possible (within the search range) to the surface. A value of up to the max absolute Miller index is usually sufficient.
reorient_lattice (bool): reorients the lattice parameters such that: the c direction is the third vector of the lattice matrix

schrodinger.application.matsci.interface.get_conventional_slab_patch(conventional_slabs)¶

Return a context manager that, when conventional_slabs is True, patches pymatgen.analysis.interfaces.coherent_interfaces.SlabGenerator with ConventionalSlabGenerator so CoherentInterfaceBuilder’s hardcoded primitive=True is bypassed. When conventional_slabs is False, return a null context.

Parameters:: conventional_slabs (bool) – whether to enable the patch
Return type:: contextlib.AbstractContextManager
Returns:: the context manager

schrodinger.application.matsci.interface.get_topo_matches(substrate_st, film_st, substrate_max_miller=1, film_max_miller=1, zslgen_kwargs=None, calculate_kwargs=None)¶

Return topological matches for the given substrate/film pair where the film can be strained.

Parameters:

substrate_st (schrodinger.structure.Structure) – the bulk substrate structure
film_st (schrodinger.structure.Structure) – the bulk film structure
substrate_max_miller (int) – maximum Miller index to generate for substrate surfaces
film_max_miller (int) – maximum Miller index to generate for film surfaces
zslgen_kwargs (dict or None) – options for pymatgen.analysis.interfaces.zsl.ZSLGenerator if there are any
calculate_kwargs (dict or None) – options for pymatgen.analysis.interfaces.substrate_analyzer.SubstrateAnalyzer.calculate if there are any

Raises:

InterfaceException – if there is an issue

Return type:

dict[SubstrateFilmMillers]= list[pymatgen.analysis.interfaces.substrate_analyzer.SubstrateMatch]

Returns:

keys are SubstrateFilmMillers, values are lists of pymatgen.analysis.interfaces.substrate_analyzer.SubstrateMatch

schrodinger.application.matsci.interface.get_slab_generator(pmg_st, millers, generator_kwargs=None)¶

Return an instance of SlabGenerator.

Parameters:

pmg_st (pymatgen.core.structure.Structure) – the bulk structure
millers (tuple[int]) – triple of Miller indices
generator_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator if there are any

Return type:

pymatgen.core.surface.SlabGenerator

Returns:

instance of SlabGenerator

schrodinger.application.matsci.interface.get_slabs(st, millers, generator_kwargs=None, get_slabs_kwargs=None)¶

Return slabs for the given structure, Miller indices, and other parameters.

Parameters:

st (schrodinger.structure.Structure) – the bulk structure
millers (tuple[int]) – triple of Miller indices
generator_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator if there are any
get_slabs_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator.get_slabs if there are any

Return type:

dict[str]=list[Slab]

Returns:

keys are termination strings, values are lists of Slab

schrodinger.application.matsci.interface.get_title(bulk, tag, millers, termination)¶

Return the structure title for the given information.

Parameters:

bulk (str) – bulk title read from input
tag (str) – one of module constants SUBSTRATE or FILM
millers (tuple[int]) – triple of Miller indices
termination (str) – the slab termination

Return type:

str

Returns:

the structure title

schrodinger.application.matsci.interface.get_interface_terminations(substrate_st, film_st, all_millers, zslgen_kwargs=None, conventional_slabs=False)¶

Return terminations for the given substrate/film pair and their Miller indices that can be made into interfaces.

Parameters:

substrate_st (schrodinger.structure.Structure) – the bulk substrate structure
film_st (schrodinger.structure.Structure) – the bulk film structure
all_millers (list[SubstrateFilmMillers]) – collection of substrate and film Miller indices
zslgen_kwargs (dict or None) – options for pymatgen.analysis.interfaces.zsl.ZSLGenerator if there are any
conventional_slabs (bool) – by default pymatgen reduces each slab to its primitive cell inside CoherentInterfaceBuilder. Use this flag to keep the conventional (unreduced) slab. See MATSCI-21585.

Raises:

InterfaceException – if there is an issue

Return type:

dict[SubstrateFilmMillers]=dict[SubstrateFilmTerminations ]=`SubstrateFilmShifts`

Returns:

outer keys are SubstrateFilmMillers, inner keys are SubstrateFilmTerminations, values are SubstrateFilmShifts

schrodinger.application.matsci.interface.mismatched_zeros_assert_allclose(actual, desired, **kwargs)¶

Wrapper for numpy.testing.assert_allclose that injects an atol for elements that are floating-point noise rather than meaningful quantities.

An element is treated as noise when both actual and desired are below NOISE_ATOL. This covers two cases that rtol alone cannot:

one is exactly 0. and the other is near-zero floating-point residue (e.g. 0. vs 7.105427e-15 from a sin(180) that didn’t fully cancel)

both sides are independent roundings of “should-be-zero” (e.g. 6.989905e-09 vs 6.989911e-09, differing by 6e-15)

See numpy.testing.assert_allclose for more documentation.

schrodinger.application.matsci.interface.predict_thickness(st, millers, thickness, termination=None, generator_kwargs=None, get_slabs_kwargs=None, get_slab_kwargs=None)¶

Return the predicted thickness of a slab in a given interface without actually building the interface. If termination is provided the thickness is an exact top-layer-atom-to-bottom-layer-atom thickness, otherwise it is an approximate thickness which is just the lattice vector length.

Parameters:

st (schrodinger.structure.Structure) – the bulk structure
millers (tuple[int]) – triple of Miller indices
thickness (int) – thickness in units of layers
termination (str or None) – the slab termination, if None signifies to return an approximate thickness that is inexpensive to calculate
generator_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator if there are any
get_slabs_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator.get_slabs if there are any
get_slab_kwargs (dict or None) – options for pymatgen.core.surface.SlabGenerator.get_slab if there are any

Raises:

InterfaceException – if there is an issue

Return type:

float

Returns:

the predicted thickness in Ang.

schrodinger.application.matsci.interface.get_ab_plane_area(st)¶

Return the area of the ab-plane in the given structure.

Parameters:: st (schrodinger.structure.Structure) – the structure
Return type:: float
Returns:: the area of the ab-plane in Ang.^2

schrodinger.application.matsci.interface.get_interfaces(substrate_st, film_st, all_terminations, zslgen_kwargs=None, get_interfaces_kwargs=None, no_reduce_to_primitive=False, conventional_slabs=False, logger=None)¶

Return interfaces for the given substrate/film pair, their Miller indices, and their terminations.

Parameters:

substrate_st (schrodinger.structure.Structure) – the bulk substrate structure
film_st (schrodinger.structure.Structure) – the bulk film structure
all_terminations (dict[SubstrateFilmMillers ]=list[SubstrateFilmTerminations]) – collection of substrate and film Miller indices and terminations
zslgen_kwargs (dict or None) – options for pymatgen.analysis.interfaces.zsl.ZSLGenerator if there are any
get_interfaces_kwargs (dict or None) – options for pymatgen.analysis.interfaces.coherent_interfaces.CoherentInterfaceBuilder. get_interfaces if there are any
no_reduce_to_primitive (bool) – by default interface, and if relevant slab, cells are reduced to their primitive form, use this flag to skip this reduction and instead potentially return conventional cells
conventional_slabs (bool) – by default pymatgen reduces each slab to its primitive cell inside CoherentInterfaceBuilder. Use this flag to keep the conventional (unreduced) slab. Can produce larger interface cells and more redundant matches. See MATSCI-21585.
logger (logging.Logger) – the logger

Raises:

InterfaceException – if there is an issue

Return type:

dict[SubstrateFilmMillers]=dict[SubstrateFilmTerminations ]=list[SubstrateFilmInterface]

Returns:

outer keys are SubstrateFilmMillers, inner keys are SubstrateFilmTerminations, values are lists of SubstrateFilmInterface

schrodinger.application.matsci.interface.get_unique_interfaces(interfaces, structure_matcher_kwargs=None, fit_kwargs=None)¶

Return unique interfaces.

Parameters:

interfaces (list[SubstrateFilmInterface]) – interfaces
structure_matcher_kwargs (dict or None) – kwargs for pymatgen.analysis.structure_matcher .StructureMatcher
fit_kwargs (dict or None) – kwargs for pymatgen.analysis.structure_matcher .StructureMatcher.fit

Return type:

list[SubstrateFilmInterface]

Returns:

unique interfaces

schrodinger.application.matsci.interface.isnan(value)¶

Wraps numpy.isnan to take a value of any type and not traceback.

Parameters:: value (any) – the value to check
Return type:: bool
Returns:: True if the value is not a number

schrodinger.application.matsci.interface.get_millers_tuple_from_str(millers_str)¶

Return a Millers tuple from a Millers string.

Parameters:: millers_str (str) – the Millers string
Raises:: InterfaceException – if there is an issue
Return type:: tuple(int)
Returns:: the Millers tuple

schrodinger.application.matsci.interface.get_millers_and_terminations(row_idx, row_dict, include_terminations=True)¶

Return a validated tuple of (substrate millers, film millers) or (substrate millers, film millers, substrate termination, film termination) from the given dictionary of row data.

Parameters:

row_idx (int) – the row index, 1-based
row_dict (dict[str]=any) – contains row data, keys are columns, values are data of any type
include_terminations (bool) – True if including terminations

Raises:

InterfaceException – if there is an issue

Return type:

tuple(tuple, tuple) or tuple(tuple, tuple, str, str)

Returns:

validated tuple of (substrate millers, film millers) or (substrate millers, film millers, substrate termination, film termination)

schrodinger.application.matsci.interface.get_match_area_from_match(match, use_film=False)¶

Return the match area from the given match.

Parameters:

match (pymatgen.analysis.interfaces.substrate_analyzer. SubstrateMatch) – the match
use_film (bool) – if True then use the film vectors which is pymatgen’s default

Return type:

float

Returns:

the match area in Ang.^2

class schrodinger.application.matsci.interface.TopologicalMatches(substrate_st, film_st, basename, substrate_max_miller=1, film_max_miller=1, zslgen_kwargs=None, calculate_kwargs=None, generate_terminations=False, conventional_slabs=False, logger=None)¶

Bases: object

__init__(substrate_st, film_st, basename, substrate_max_miller=1, film_max_miller=1, zslgen_kwargs=None, calculate_kwargs=None, generate_terminations=False, conventional_slabs=False, logger=None)¶

Parameters:

substrate_st (schrodinger.structure.Structure) – the bulk substrate structure
film_st (schrodinger.structure.Structure) – the bulk film structure
basename (str) – the base name to use for output file naming
substrate_max_miller (int) – maximum Miller index to generate for substrate surfaces
film_max_miller (int) – maximum Miller index to generate for film surfaces
zslgen_kwargs (dict or None) – options for pymatgen.analysis.interfaces.zsl.ZSLGenerator if there are any
calculate_kwargs (dict or None) – options for pymatgen.analysis.interfaces.substrate_analyzer.SubstrateAnalyzer.calculate if there are any
generate_terminations (bool) – for each topological match generate substrate and film terminations that are commensurate for interface building
conventional_slabs (bool) – by default pymatgen reduces each slab to its primitive cell when discovering terminations. Use this flag to keep the conventional (unreduced) slab. See MATSCI-21585.
logger (logging.Logger) – the logger

generateTerminations(millers, matches)¶

Generate terminations.

Parameters:

millers (SubstrateFilmMillers) – substrate and film Miller indices
matches (list[ pymatgen.analysis.interfaces.substrate_analyzer.SubstrateMatch]) – the match objects

setMatchDataFrame()¶: Set the match data frame.

writeOutputFiles()¶: Write the output files.

run()¶: Run it.

static getTopologicalMatchesDF(csv_fn, generate_terminations=False, lowest=True)¶

Return the topological matches dataframe.

Parameters:

csv_fn (str) – the topological matches output csv file name
generate_terminations (bool) – True if the topological matches was run with the generate terminations option
lowest (bool) – if True return only that of the lowest match area for a given pair of Miller indices

Raises:

InterfaceException – if there is an issue

Return type:

pandas.DataFrame

Returns:

the topological matches dataframe

class schrodinger.application.matsci.interface.BuildInterfaces(substrate_st, film_st, basename, get_interfaces_kwargs, allow_duplicates=False, no_slab_extraction=False, no_reduce_to_primitive=False, conventional_slabs=False, logger=None)¶

Bases: object

PT_HIERARCHY_MILLERS = 'Interface_Orientations_substrate={substrate}_film={film}'¶

PT_HIERARCHY_TERMINATIONS = 'Interface_Terminations_substrate={substrate}_film={film}'¶

PT_HIERARCHY_THICKNESSES = 'Thicknesses_substrate={substrate}{units}_film={film}{units}_vacuum={vacuum}Ang_gap={gap}Ang'¶

PT_HIERARCHY_AREA = 'Area={area}Ang^2'¶

PT_HIERARCHY_STRAIN = 'Film_Strain={strain}'¶

__init__(substrate_st, film_st, basename, get_interfaces_kwargs, allow_duplicates=False, no_slab_extraction=False, no_reduce_to_primitive=False, conventional_slabs=False, logger=None)¶

Parameters:

substrate_st (schrodinger.structure.Structure) – the bulk substrate structure
film_st (schrodinger.structure.Structure) – the bulk film structure
basename (str) – the base name to use for output file naming
get_interfaces_kwargs (dict[SubstrateFilmMillers]=dict[ SubstrateFilmTerminations]=list[GetInterfacesKwargs]) – outer keys are SubstrateFilmMillers, inner keys are SubstrateFilmTerminations, values are lists of GetInterfacesKwargs
allow_duplicates (bool) – by default only unique interfaces are returned, use this option to instead return all built interfaces (including duplicates)
no_slab_extraction (bool) – by default the individual substrate and film slab models are extracted from each built interface model and returned alongside the interface models, use this flag to instead only return the interface models
no_reduce_to_primitive (bool) – by default interface, and if relevant slab, cells are reduced to their primitive form, use this flag to skip this reduction and instead potentially return conventional cells
conventional_slabs (bool) – by default pymatgen reduces each slab to its primitive cell inside CoherentInterfaceBuilder. Use this flag to keep the conventional (unreduced) slab. Can produce larger interface cells and more redundant matches. See MATSCI-21585.
logger (logging.Logger) – the logger

static getGetInterfacesKwargs(csv_fn, global_zslgen_kwargs=None)¶

Return parameters for building interfaces.

Parameters:

csv_fn (str) – file name for the csv file containing parameters for building interfaces
global_zslgen_kwargs (dict or None) – global options for pymatgen.analysis.interfaces. zsl.ZSLGenerator if there are any

Raises:

InterfaceException – if there is an issue

Return type:

dict[SubstrateFilmMillers]=dict[SubstrateFilmTerminations]=list[dict], dict[SubstrateFilmMillers]=dict[SubstrateFilmTerminations]=list[ GetInterfacesKwargs]

Returns:

outer keys are SubstrateFilmMillers, inner keys are SubstrateFilmTerminations, values are lists of GetInterfacesKwargs

setInterfaceDataFrame()¶

Set the interface data frame.

Raises:: InterfaceException – if there is an issue

writeOutputFiles()¶: Write the output files.

run()¶: Run it.