tessl/pypi-pymatgen
Comprehensive materials science analysis library for crystal structures, molecules, and materials data with extensive computational chemistry integration.
—
Pending
structure-analysis.mddocs/
Structure Analysis & Manipulation
Comprehensive tools for structure comparison, local environment analysis, Voronoi tessellation, bond analysis, and advanced structural characterization methods. These capabilities enable detailed analysis of crystal structures, defect identification, surface analysis, and molecular recognition.
Capabilities
Structure Comparison and Matching
Advanced algorithms for comparing and matching crystal structures with tolerance for symmetry operations and lattice transformations.
class StructureMatcher:
"""
Class for matching structures using various algorithms and tolerances.
Parameters:
- ltol: Fractional length tolerance for lattice matching
- stol: Site tolerance for matching sites
- angle_tol: Angle tolerance in degrees for lattice matching
- primitive_cell: Whether to reduce to primitive cells first
- scale: Whether to scale volumes to match
- attempt_supercell: Whether to attempt supercell matching
- allow_subset: Whether to allow subset matching
- comparator: Comparison method for sites
- supercell_size: Supercell size limit for matching
- ignored_species: Species to ignore during matching
"""
def __init__(self, ltol=0.2, stol=0.3, angle_tol=5, primitive_cell=True,
scale=True, attempt_supercell=False, allow_subset=False,
comparator=ElementComparator(), supercell_size="num_sites",
ignored_species=None): ...
def fit(self, struct1, struct2):
"""
Check if two structures match.
Returns:
bool: True if structures match within tolerances
"""
def fit_anonymous(self, struct1, struct2):
"""
Check if structures match using anonymous species comparison.
Returns:
bool: True if structures match anonymously
"""
def get_rms_dist(self, struct1, struct2):
"""
Get RMS distance between matched structures.
Returns:
list: RMS distances for each matching configuration
"""
def get_supercells(self, struct1, struct2, max_supercell=1, include_primitive=True):
"""
Get supercells that can be used for matching.
Returns:
list: Possible supercells for matching
"""
def get_transformation(self, struct1, struct2):
"""
Get transformation matrix between matched structures.
Returns:
numpy.ndarray: Transformation matrix
"""
def group_structures(self, s_list, anonymous=False):
"""
Group structures by similarity.
Parameters:
s_list: List of Structure objects
anonymous: Whether to use anonymous matching
Returns:
list: Grouped structures
"""class StructureAnalyzer:
"""
General structure analysis tools.
"""
@staticmethod
def get_oxide_type(structure, relative_cutoff=1.1, return_nbonds=False):
"""
Determine oxide type (ionic, covalent, etc.).
Parameters:
structure: Structure to analyze
relative_cutoff: Relative cutoff for bond determination
return_nbonds: Whether to return bond counts
Returns:
str: Oxide type classification
"""
@staticmethod
def get_dimensionality_larsen(structure, tolerance=0.45):
"""
Get structural dimensionality using Larsen algorithm.
Returns:
int: Dimensionality (0D, 1D, 2D, or 3D)
"""
@staticmethod
def get_dimensionality_cheon(structure, tolerance=0.45, ldict=None):
"""
Get structural dimensionality using Cheon algorithm.
Returns:
int: Dimensionality classification
"""Local Environment Analysis
Comprehensive neighbor-finding algorithms for analyzing local coordination environments and bonding patterns.
class VoronoiNN:
"""
Voronoi tessellation-based neighbor detection.
Parameters:
- tol: Tolerance parameter for neighbor detection
- targets: Target species to consider
- cutoff: Distance cutoff for neighbors
- allow_pathological: Whether to allow pathological cases
- weight: Weighting scheme ('solid_angle', 'volume', 'area')
- extra_nn_info: Whether to return extra neighbor information
"""
def __init__(self, tol=0, targets=None, cutoff=13.0,
allow_pathological=False, weight="solid_angle",
extra_nn_info=True): ...
def get_nn_info(self, structure, n):
"""
Get neighbor information for a site.
Parameters:
structure: Structure object
n: Site index
Returns:
list: List of neighbor dictionaries with site info and weights
"""
def get_cn(self, structure, n, use_weights=False):
"""
Get coordination number for a site.
Parameters:
structure: Structure object
n: Site index
use_weights: Whether to use weighted coordination number
Returns:
float: Coordination number
"""
def get_nn(self, structure, n):
"""
Get neighbor sites for a given site.
Returns:
list: List of neighboring PeriodicSite objects
"""class JmolNN:
"""
Jmol-based neighbor detection using covalent radii.
Parameters:
- tol: Tolerance factor for covalent radius cutoffs
- min_bond_distance: Minimum bond distance
- el_radius_updates: Custom element radius updates
"""
def __init__(self, tol=0.45, min_bond_distance=0.4, el_radius_updates=None): ...
def get_nn_info(self, structure, n): ...
def get_cn(self, structure, n, use_weights=False): ...class CrystalNN:
"""
Neural network-based neighbor detection optimized for crystals.
Parameters:
- weighted_cn: Whether to return weighted coordination numbers
- cation_anion: Whether to consider only cation-anion bonds
- distance_cutoffs: Custom distance cutoffs
- x_diff_weight: Weight for electronegativity differences
- porous_adjustment: Adjustment for porous materials
"""
def __init__(self, weighted_cn=False, cation_anion=False,
distance_cutoffs=None, x_diff_weight=3.0,
porous_adjustment=True): ...
def get_nn_info(self, structure, n): ...
def get_cn(self, structure, n, use_weights=False): ...
def get_cn_dict(self, structure, n, use_weights=False):
"""
Get coordination number dictionary with species breakdown.
Returns:
dict: Coordination numbers by species
"""class MinimumDistanceNN:
"""
Simple distance-based neighbor detection.
Parameters:
- tol: Distance tolerance
- cutoff: Maximum neighbor distance
"""
def __init__(self, tol=0.1, cutoff=10.0): ...
def get_nn_info(self, structure, n): ...
def get_cn(self, structure, n, use_weights=False): ...Bond Analysis
Tools for analyzing chemical bonds, bond valences, and bonding patterns in structures.
class BVAnalyzer:
"""
Bond valence analysis for determining oxidation states and bond strengths.
Parameters:
- symm_tol: Symmetry tolerance
- max_radius: Maximum ionic radius for analysis
- max_permutations: Maximum oxidation state permutations to try
- distance_scale_factor: Scaling factor for bond distances
- charge_neutrality_tolerance: Tolerance for charge neutrality
- forbidden_species: Species not allowed in analysis
"""
def __init__(self, symm_tol=0.1, max_radius=4, max_permutations=100000,
distance_scale_factor=1.015, charge_neutrality_tolerance=1e-4,
forbidden_species=None): ...
def get_oxi_state_decorated_structure(self, structure):
"""
Get structure decorated with oxidation states.
Parameters:
structure: Structure to analyze
Returns:
Structure: Structure with oxidation states assigned
"""
def get_valences(self, structure):
"""
Get bond valences for all sites in structure.
Returns:
list: Bond valences for each site
"""
def get_oxi_state_guesses(self, structure, max_sites=-1):
"""
Get possible oxidation state assignments.
Returns:
list: List of possible oxidation state dictionaries
"""class BondDissociationEnergies:
"""
Analysis of bond dissociation energies in molecular systems.
"""
def __init__(self, molecule_entry, fragments=None,
fragment_entries=None, allow_additional_mvs=True): ...
def build_new_entry(self, name, molecule, additional_charge=0,
additional_spin_multiplicity=0, level_of_theory=None,
return_ia_data=False, nbo_data=None): ...
def fragment_and_process(self, molecule_entry, edges,
depth=1, open_rings=True, opt_steps=10000): ...Voronoi Analysis
Advanced Voronoi tessellation analysis for coordination environments and pore analysis.
class VoronoiAnalyzer:
"""
Voronoi tessellation analysis of crystal structures.
Parameters:
- cutoff: Cutoff distance for Voronoi analysis
- qhull_options: Options for Qhull Voronoi computation
"""
def __init__(self, cutoff=5.0, qhull_options="Qbb Qc Qz"): ...
def analyze(self, structure, n=0):
"""
Perform Voronoi analysis on a structure.
Parameters:
structure: Structure to analyze
n: Site index to focus analysis on (0 for all sites)
Returns:
dict: Voronoi analysis results
"""
def analyze_structures(self, structures, step_freq=10, most_frequent_polyhedra=15):
"""
Analyze multiple structures for Voronoi polyhedra statistics.
Parameters:
structures: List of structures to analyze
step_freq: Frequency of analysis steps
most_frequent_polyhedra: Number of most frequent polyhedra to track
Returns:
dict: Statistical analysis of polyhedra across structures
"""class VoronoiConnectivity:
"""
Connectivity analysis using Voronoi tessellation.
Parameters:
- structure: Structure to analyze
- cutoff: Distance cutoff for connectivity
"""
def __init__(self, structure, cutoff=10): ...
@property
def connectivity_array(self):
"""
Get connectivity matrix between sites.
Returns:
numpy.ndarray: Connectivity matrix
"""
@property
def max_connectivity(self):
"""
Get maximum connectivity in structure.
Returns:
float: Maximum connectivity value
"""
def get_connections(self):
"""
Get all connections in the structure.
Returns:
list: List of connected site pairs
"""Graph-Based Structure Analysis
Structure and molecule graphs for topological analysis and similarity comparison.
class StructureGraph:
"""
Graph representation of crystal structures.
Parameters:
- structure: Structure object
- graph_data: Optional pre-computed graph data
"""
def __init__(self, structure, graph_data=None): ...
@classmethod
def with_empty_graph(cls, structure, name="bonds",
edge_weight_name=None, edge_weight_units=None):
"""
Create StructureGraph with empty graph.
Returns:
StructureGraph: Empty graph for the structure
"""
@classmethod
def with_local_env_strategy(cls, structure, strategy):
"""
Create StructureGraph using local environment strategy.
Parameters:
structure: Structure object
strategy: Local environment strategy (e.g., VoronoiNN)
Returns:
StructureGraph: Graph built using the strategy
"""
def add_edge(self, from_index, to_index, from_jimage=(0, 0, 0),
to_jimage=(0, 0, 0), weight=None, warn_duplicates=True): ...
def remove_edge(self, from_index, to_index, from_jimage=(0, 0, 0),
to_jimage=(0, 0, 0)): ...
def get_connected_sites(self, n, jimage=(0, 0, 0)):
"""
Get sites connected to site n.
Parameters:
n: Site index
jimage: Periodic image
Returns:
list: Connected sites
"""
def get_coordination_of_site(self, n):
"""
Get coordination number of site.
Returns:
int: Coordination number
"""
def draw_graph_to_file(self, filename="graph", diff=None,
hide_unconnected_nodes=False, hide_image_edges=True,
edge_colors=False, node_labels=False, weight_labels=False,
image_labels=False, color_scheme="VESTA",
keep_dot=False, algo="fdp"): ...
def get_subgraphs_as_molecules(self, use_weights=False):
"""
Get disconnected subgraphs as Molecule objects.
Returns:
list: List of Molecule objects for each subgraph
"""
def types_and_weights_of_connections(self):
"""
Get types and weights of all connections in graph.
Returns:
dict: Connection types and their weights
"""class MoleculeGraph:
"""
Graph representation of molecular structures.
Parameters:
- molecule: Molecule object
- graph_data: Optional pre-computed graph data
"""
def __init__(self, molecule, graph_data=None): ...
@classmethod
def with_empty_graph(cls, molecule, name="bonds",
edge_weight_name="weight", edge_weight_units=""): ...
@classmethod
def with_local_env_strategy(cls, molecule, strategy): ...
@classmethod
def from_edges(cls, molecule, edges): ...
def add_edge(self, from_index, to_index, weight=1, warn_duplicates=True): ...
def remove_edge(self, from_index, to_index): ...
def get_connected_sites(self, n):
"""
Get sites connected to site n.
Returns:
list: Connected sites
"""
def get_coordination_of_site(self, n): ...
def find_rings(self, including=None):
"""
Find rings in the molecular graph.
Parameters:
including: Sites that must be included in rings
Returns:
list: List of rings (cycles) in the graph
"""
def get_disconnected_fragments(self):
"""
Get disconnected molecular fragments.
Returns:
list: List of MoleculeGraph objects for each fragment
"""
def split_molecule_subgraphs(self, bonds_to_break, allow_reverse=False):
"""
Split molecule by breaking specified bonds.
Parameters:
bonds_to_break: List of bonds to break
allow_reverse: Whether to allow reverse bond breaking
Returns:
list: Resulting molecular fragments
"""Molecular Analysis
Tools for molecular structure analysis, comparison, and property calculation.
class MoleculeMatcher:
"""
Class for matching and comparing molecular structures.
Parameters:
- tolerance: Distance tolerance for matching
- mapper: Atom mapping algorithm
"""
def __init__(self, tolerance=0.3, mapper=None): ...
def fit(self, mol1, mol2):
"""
Check if two molecules match.
Parameters:
mol1, mol2: Molecule objects to compare
Returns:
bool: True if molecules match
"""
def get_rmsd(self, mol1, mol2):
"""
Get RMSD between matched molecules.
Returns:
float: RMSD value
"""
def group_molecules(self, mol_list):
"""
Group molecules by similarity.
Parameters:
mol_list: List of Molecule objects
Returns:
list: Grouped molecules
"""class FunctionalGroupExtractor:
"""
Extract functional groups from molecular structures.
"""
def __init__(self, molecule): ...
def get_functional_groups(self, func_groups=None, catch_basic=True):
"""
Identify functional groups in molecule.
Parameters:
func_groups: List of functional groups to look for
catch_basic: Whether to catch basic functional groups
Returns:
list: Identified functional groups
"""
def categorize_functional_groups(self, func_groups):
"""
Categorize functional groups by type.
Returns:
dict: Categorized functional groups
"""Surface and Interface Analysis
Specialized tools for analyzing surfaces, slabs, and interfaces.
class AdsorbateSiteFinder:
"""
Find adsorption sites on surfaces.
Parameters:
- slab: Slab structure for adsorption analysis
- selective_dynamics: Whether to use selective dynamics
- height: Height above surface to place adsorbates
- mi_vec: Miller index vector
"""
def __init__(self, slab, selective_dynamics=False, height=0.9, mi_vec=None): ...
def find_adsorption_sites(self, distance=1.0, put_inside=True,
symm_reduce=1e-2, near_reduce=1e-2,
positions=("ontop", "bridge", "hollow"),
no_obtuse_hollow=True):
"""
Find adsorption sites on the surface.
Parameters:
distance: Distance from surface atoms for site generation
put_inside: Whether to put sites inside unit cell
symm_reduce: Symmetry reduction tolerance
near_reduce: Distance reduction tolerance
positions: Types of adsorption sites to find
no_obtuse_hollow: Whether to exclude obtuse hollow sites
Returns:
dict: Adsorption sites by type
"""
def add_adsorbate(self, molecule, ads_sites_dict, repeat=None,
min_lw=5.0, translate=True, reorient=True):
"""
Add adsorbate molecules to adsorption sites.
Parameters:
molecule: Adsorbate molecule
ads_sites_dict: Dictionary of adsorption sites
repeat: Repeat pattern for adsorbate placement
min_lw: Minimum layer width
translate: Whether to translate adsorbate
reorient: Whether to reorient adsorbate
Returns:
list: Structures with adsorbates added
"""Utility Functions
Helper functions for structure analysis and manipulation.
def obtain_all_bond_lengths(structure, max_bond_length=3.0):
"""
Obtain all bond lengths in a structure.
Parameters:
structure: Structure to analyze
max_bond_length: Maximum bond length to consider
Returns:
dict: Bond lengths by species pairs
"""
def get_bond_length(sp1, sp2, bond_order=1):
"""
Get expected bond length between two species.
Parameters:
sp1, sp2: Species objects or symbols
bond_order: Bond order (1, 2, 3, etc.)
Returns:
float: Expected bond length in Angstroms
"""
def get_bond_order(sp1, sp2, dist, check_exists=False):
"""
Get bond order from bond distance.
Parameters:
sp1, sp2: Species objects or symbols
dist: Bond distance in Angstroms
check_exists: Whether to check if bond type exists
Returns:
float: Estimated bond order
"""
def solid_angle(center, coords):
"""
Calculate solid angle subtended by points at center.
Parameters:
center: Center point coordinates
coords: Array of coordinates
Returns:
float: Solid angle in steradians
"""
def contains_peroxide(structure, relative_cutoff=1.1):
"""
Check if structure contains peroxide anions.
Parameters:
structure: Structure to check
relative_cutoff: Relative cutoff for peroxide detection
Returns:
bool: True if peroxide is present
"""
def oxide_type(structure, relative_cutoff=1.1, return_nbonds=False):
"""
Determine oxide type (ionic, covalent, etc.).
Parameters:
structure: Structure to classify
relative_cutoff: Relative cutoff for bond classification
return_nbonds: Whether to return bond counts
Returns:
str: Oxide type classification
"""Install with Tessl CLI
npx tessl i tessl/pypi-pymatgen