schrodinger.application.matsci.interface module

Utilities for building interfaces using pymatgen.

Copyright Schrodinger, LLC. All rights reserved.

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

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)

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

Parameters:
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:

  1. 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)

  2. 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, 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

  • 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, 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, 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

  • 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, 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, 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

  • 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.