tessl/pypi-pymatgen

Comprehensive materials science analysis library for crystal structures, molecules, and materials data with extensive computational chemistry integration.

—

Pending

Overview

Eval results

Files

Crystallographic Transformations

Name: tessl/pypi-pymatgen
Author: tessl

Systematic structure modifications including supercells, substitutions, defect creation, surface generation, and magnetic ordering enumeration. These transformations enable the systematic exploration of materials space and the generation of derivative structures for computational studies.

Capabilities

Base Transformation Framework

Abstract base class and transformation infrastructure for systematic structure modifications.

class AbstractTransformation:
    """
    Abstract base class for all structure transformations.
    """
    
    def apply_transformation(self, structure):
        """
        Apply transformation to a structure.
        
        Parameters:
        structure: Structure object to transform
        
        Returns:
        Structure or list: Transformed structure(s)
        """
        raise NotImplementedError
    
    def __call__(self, structure):
        """Allow transformation to be called as function."""
        return self.apply_transformation(structure)
    
    @property
    def inverse(self):
        """Inverse transformation (if applicable)."""
        return None
    
    @property
    def is_one_to_many(self):
        """Whether transformation returns multiple structures."""
        return False
    
    def __str__(self):
        """String representation of transformation."""
        return self.__class__.__name__

Structure-Level Transformations

Transformations that modify the overall structure, lattice, or unit cell.

class SupercellTransformation:
    """
    Create supercells using scaling matrices.
    
    Parameters:
    - scaling_matrix: 3x3 scaling matrix or list of 3 integers
    """
    def __init__(self, scaling_matrix): ...
    
    def apply_transformation(self, structure):
        """
        Apply supercell transformation.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        Structure: Supercell structure
        """
    
    @property
    def scaling_matrix(self):
        """3x3 scaling matrix."""
    
    @property
    def inverse(self):
        """Returns None - supercell transformation is not generally invertible."""
        return None

class PrimitiveCellTransformation:
    """
    Transform structure to primitive cell.
    
    Parameters:
    - tolerance: Tolerance for primitive cell detection
    - use_site_props: Whether to average site properties
    """
    def __init__(self, tolerance=0.5, use_site_props=False): ...
    
    def apply_transformation(self, structure):
        """
        Get primitive cell of structure.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        Structure: Primitive cell structure
        """
    
    @property
    def tolerance(self):
        """Tolerance for primitive cell detection."""

class ConventionalCellTransformation:
    """
    Transform structure to conventional unit cell.
    
    Parameters:
    - international_monoclinic: Whether to use international monoclinic setting
    - symprec: Symmetry precision
    - angle_tolerance: Angle tolerance for symmetry detection
    """
    def __init__(self, international_monoclinic=True, symprec=0.01, 
                 angle_tolerance=5): ...
    
    def apply_transformation(self, structure):
        """
        Get conventional cell of structure.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        Structure: Conventional cell structure
        """

class PerturbStructureTransformation:
    """
    Apply random perturbations to atomic positions.
    
    Parameters:
    - distance: Maximum perturbation distance in Angstroms
    - min_distance: Minimum allowed interatomic distance
    """
    def __init__(self, distance=0.1, min_distance=None): ...
    
    def apply_transformation(self, structure):
        """
        Apply random perturbations to structure.
        
        Parameters:
        structure: Structure to perturb
        
        Returns:
        Structure: Perturbed structure
        """
    
    @property
    def distance(self):
        """Maximum perturbation distance."""
    
    @property  
    def min_distance(self):
        """Minimum allowed interatomic distance."""

class DeformStructureTransformation:
    """
    Apply deformation to structure lattice.
    
    Parameters:
    - deformation: 3x3 deformation matrix
    """
    def __init__(self, deformation): ...
    
    def apply_transformation(self, structure):
        """
        Apply deformation to structure.
        
        Parameters:
        structure: Structure to deform
        
        Returns:
        Structure: Deformed structure
        """
    
    @property
    def deformation(self):
        """3x3 deformation matrix."""

class ScaleToRelaxedTransformation:
    """
    Scale structure to match relaxed structure dimensions.
    
    Parameters:
    - relaxed_struct: Relaxed structure to match
    """
    def __init__(self, relaxed_struct): ...
    
    def apply_transformation(self, structure):
        """
        Scale structure to match relaxed dimensions.
        
        Parameters:
        structure: Structure to scale
        
        Returns:
        Structure: Scaled structure
        """

Species and Substitution Transformations

Transformations that modify chemical species and perform substitutions.

class SubstitutionTransformation:
    """
    Substitute species in structure.
    
    Parameters:
    - species_map: Dict mapping old species to new species
    """
    def __init__(self, species_map): ...
    
    def apply_transformation(self, structure):
        """
        Apply species substitution.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with substituted species
        """
    
    @property
    def species_map(self):
        """Species substitution mapping."""
    
    @property
    def inverse(self):
        """Inverse substitution transformation."""
        return SubstitutionTransformation({v: k for k, v in self.species_map.items()})

class RemoveSpeciesTransformation:
    """
    Remove all sites of specified species.
    
    Parameters:
    - species_to_remove: List of species to remove
    """
    def __init__(self, species_to_remove): ...
    
    def apply_transformation(self, structure):
        """
        Remove specified species from structure.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with species removed
        """
    
    @property
    def species_to_remove(self):
        """Species to remove."""

class PartialRemoveSpecieTransformation:
    """
    Partially remove species to create vacancies.
    
    Parameters:
    - specie_to_remove: Species to partially remove
    - fraction_to_remove: Fraction of species to remove (0-1)
    - algo: Algorithm for selecting sites to remove
    """
    def __init__(self, specie_to_remove, fraction_to_remove, algo=0): ...
    
    def apply_transformation(self, structure):
        """
        Partially remove species from structure.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with partial species removal
        """
    
    @property
    def specie_to_remove(self):
        """Species to partially remove."""
    
    @property
    def fraction_to_remove(self):
        """Fraction to remove."""

class OxidationStateDecorationTransformation:
    """
    Add oxidation states to structure species.
    
    Parameters:
    - oxidation_states: Dict mapping elements to oxidation states
    """
    def __init__(self, oxidation_states): ...
    
    def apply_transformation(self, structure):
        """
        Decorate structure with oxidation states.
        
        Parameters:
        structure: Structure to decorate
        
        Returns:
        Structure: Structure with oxidation state information
        """
    
    @property
    def oxidation_states(self):
        """Oxidation state mapping."""

class AutoOxiStateDecorationTransformation:
    """
    Automatically determine and add oxidation states.
    
    Parameters:
    - symm_tol: Symmetry tolerance for bond valence analysis
    - max_radius: Maximum radius for neighbor detection
    """
    def __init__(self, symm_tol=0.1, max_radius=4): ...
    
    def apply_transformation(self, structure):
        """
        Automatically determine oxidation states.
        
        Parameters:
        structure: Structure to analyze
        
        Returns:
        Structure: Structure with automatically determined oxidation states
        """

class OxidationStateRemovalTransformation:
    """
    Remove oxidation state information from species.
    """
    def apply_transformation(self, structure):
        """
        Remove oxidation states from structure.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure without oxidation state information
        """

Site-Level Transformations

Transformations that operate on individual atomic sites.

class InsertSitesTransformation:
    """
    Insert new sites into structure.
    
    Parameters:
    - species: List of species to insert
    - coords: List of coordinates for new sites
    - coords_are_cartesian: Whether coordinates are Cartesian
    - validate_proximity: Whether to validate atomic distances
    """
    def __init__(self, species, coords, coords_are_cartesian=False,
                 validate_proximity=True): ...
    
    def apply_transformation(self, structure):
        """
        Insert sites into structure.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with inserted sites
        """
    
    @property
    def species(self):
        """Species to insert."""
    
    @property
    def coords(self):
        """Coordinates for new sites."""

class RemoveSitesTransformation:
    """
    Remove specific sites from structure.
    
    Parameters:
    - indices_to_remove: List of site indices to remove
    """
    def __init__(self, indices_to_remove): ...
    
    def apply_transformation(self, structure):
        """
        Remove sites from structure.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with sites removed
        """
    
    @property
    def indices_to_remove(self):
        """Site indices to remove."""

class ReplaceSiteSpeciesTransformation:
    """
    Replace species at specific sites.
    
    Parameters:
    - indices_species_map: Dict mapping site indices to new species
    """
    def __init__(self, indices_species_map): ...
    
    def apply_transformation(self, structure):
        """
        Replace species at specified sites.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with replaced species
        """
    
    @property
    def indices_species_map(self):
        """Site index to species mapping."""

class TranslateSitesTransformation:
    """
    Translate specific sites in structure.
    
    Parameters:
    - indices_to_move: List of site indices to translate
    - translation_vector: Translation vector
    - vector_in_frac_coords: Whether vector is in fractional coordinates
    """
    def __init__(self, indices_to_move, translation_vector, 
                 vector_in_frac_coords=True): ...
    
    def apply_transformation(self, structure):
        """
        Translate specified sites.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        Structure: Structure with translated sites
        """
    
    @property
    def indices_to_move(self):
        """Site indices to translate."""
    
    @property
    def translation_vector(self):
        """Translation vector."""

class RotationTransformation:
    """
    Rotate structure or specific sites.
    
    Parameters:
    - axis: Rotation axis
    - angle: Rotation angle in degrees
    - angle_in_radians: Whether angle is in radians
    """
    def __init__(self, axis, angle, angle_in_radians=False): ...
    
    def apply_transformation(self, structure):
        """
        Apply rotation to structure.
        
        Parameters:
        structure: Structure to rotate
        
        Returns:
        Structure: Rotated structure
        """
    
    @property
    def axis(self):
        """Rotation axis."""
    
    @property
    def angle(self):
        """Rotation angle."""

Ordering and Enumeration Transformations

Transformations for creating ordered structures from disordered ones and enumerating possible configurations.

class OrderDisorderedStructureTransformation:
    """
    Order disordered structure using enumeration algorithms.
    
    Parameters:
    - algo: Algorithm for ordering (ewald, best_first, fast)
    - symmetrized: Whether to return symmetrized structures
    - no_oxi_states: Whether to ignore oxidation states
    """
    def __init__(self, algo=0, symmetrized=False, no_oxi_states=False): ...
    
    def apply_transformation(self, structure):
        """
        Order disordered structure.
        
        Parameters:
        structure: Disordered structure to order
        
        Returns:
        list: List of ordered structures
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple ordered structures."""
        return True
    
    @property
    def algo(self):
        """Ordering algorithm."""

class EnumerateStructureTransformation:
    """
    Enumerate derivative structures using substitution.
    
    Parameters:
    - species: Dict of species substitutions {original: [substitutes]}
    - min_cell_size: Minimum supercell size for enumeration
    - max_cell_size: Maximum supercell size for enumeration
    - symm_prec: Symmetry precision
    - refine_structure: Whether to refine input structure
    - enum_precision_parameter: Enumeration precision parameter
    - check_ordered_symmetry: Whether to check ordered symmetry
    - max_disordered_sites: Maximum disordered sites
    """
    def __init__(self, species, min_cell_size=1, max_cell_size=1, 
                 symm_prec=0.1, refine_structure=False,
                 enum_precision_parameter=0.01, check_ordered_symmetry=True,
                 max_disordered_sites=None): ...
    
    def apply_transformation(self, structure):
        """
        Enumerate structures with substitutions.
        
        Parameters:
        structure: Structure to enumerate
        
        Returns:
        list: List of enumerated structures
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple structures."""
        return True

class SubstitutionPredictorTransformation:
    """
    ML-guided species substitution based on data-driven predictions.
    
    Parameters:
    - threshold: Probability threshold for substitution
    - scale_volumes: Whether to scale volumes after substitution
    - **kwargs: Additional arguments for SubstitutionPredictor
    """
    def __init__(self, threshold=1e-2, scale_volumes=True, **kwargs): ...
    
    def apply_transformation(self, structure):
        """
        Apply ML-guided substitutions.
        
        Parameters:
        structure: Structure to modify
        
        Returns:
        list: List of structures with predicted substitutions
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple structures."""
        return True

Surface and Interface Transformations

Transformations for creating surfaces, slabs, and interfaces.

class SlabTransformation:
    """
    Create surface slabs from bulk structures.
    
    Parameters:
    - miller_index: Miller index of surface plane
    - min_slab_size: Minimum slab thickness in Angstroms
    - min_vacuum_size: Minimum vacuum thickness in Angstroms
    - lll_reduce: Whether to LLL reduce slab
    - center_slab: Whether to center slab in cell
    - primitive: Whether to use primitive slab
    - max_normal_search: Maximum normal search depth
    """
    def __init__(self, miller_index, min_slab_size, min_vacuum_size=10,
                 lll_reduce=False, center_slab=False, primitive=True,
                 max_normal_search=None): ...
    
    def apply_transformation(self, structure):
        """
        Generate surface slab from bulk structure.
        
        Parameters:
        structure: Bulk structure to cut
        
        Returns:
        list: List of possible slab terminations
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple slab terminations."""
        return True
    
    @property
    def miller_index(self):
        """Surface Miller index."""
    
    @property
    def min_slab_size(self):
        """Minimum slab thickness."""
    
    @property
    def min_vacuum_size(self):
        """Minimum vacuum thickness."""

class AddAdsorbateTransformation:
    """
    Add adsorbate molecules to surface slabs.
    
    Parameters:
    - adsorbate: Molecule object for adsorbate
    - selective_dynamics: Whether to use selective dynamics
    - height: Height above surface for adsorbate
    - mi_vec: Miller index vector
    """
    def __init__(self, adsorbate, selective_dynamics=False, height=0.9,
                 mi_vec=None): ...
    
    def apply_transformation(self, structure):
        """
        Add adsorbate to slab structure.
        
        Parameters:
        structure: Slab structure
        
        Returns:
        list: List of structures with adsorbates at different sites
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates structures with adsorbates at different sites."""
        return True
    
    @property
    def adsorbate(self):
        """Adsorbate molecule."""

class GrainBoundaryTransformation:
    """
    Create grain boundary structures.
    
    Parameters:
    - rotation_axis: Rotation axis for grain boundary
    - rotation_angle: Rotation angle in degrees
    - expand_times: Number of times to expand interface
    - vacuum_thickness: Vacuum thickness between grains
    - ab_shift: Shift vector in ab plane
    - normal: Whether rotation axis is normal to interface
    - ratio: Ratio for interface construction
    """
    def __init__(self, rotation_axis, rotation_angle, expand_times=4, 
                 vacuum_thickness=0.0, ab_shift=None, normal=False,
                 ratio=None): ...
    
    def apply_transformation(self, structure):
        """
        Create grain boundary structure.
        
        Parameters:
        structure: Structure to create grain boundary from
        
        Returns:
        Structure: Grain boundary structure
        """
    
    @property
    def rotation_axis(self):
        """Grain boundary rotation axis."""
    
    @property
    def rotation_angle(self):
        """Grain boundary rotation angle."""

Magnetic Ordering Transformations

Transformations for generating magnetic ordering configurations.

class MagOrderingTransformation:
    """
    Enumerate magnetic ordering configurations.
    
    Parameters:
    - mag_species_spin: Dict mapping magnetic species to spin values
    - order_parameter: Magnetic order parameter constraint
    - energy_model: Energy model for magnetic interactions
    - **kwargs: Additional enumeration parameters
    """
    def __init__(self, mag_species_spin, order_parameter=0.5,
                 energy_model=None, **kwargs): ...
    
    def apply_transformation(self, structure):
        """
        Generate magnetic ordering configurations.
        
        Parameters:
        structure: Structure to add magnetic ordering to
        
        Returns:
        list: List of magnetically ordered structures
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple magnetic configurations."""
        return True
    
    @property
    def mag_species_spin(self):
        """Magnetic species and their spin values."""

Advanced Transformations

Specialized transformations for complex structure modifications.

class CubicSupercellTransformation:
    """
    Create cubic supercell with specified minimum length.
    
    Parameters:
    - min_length: Minimum supercell length in Angstroms
    - max_length: Maximum supercell length in Angstroms
    - min_atoms: Minimum number of atoms in supercell
    - prefer_90_degrees: Whether to prefer 90-degree angles
    - allow_rotation: Whether to allow lattice rotations
    """
    def __init__(self, min_length=10, max_length=15, min_atoms=None,
                 prefer_90_degrees=True, allow_rotation=False): ...
    
    def apply_transformation(self, structure):
        """
        Create cubic supercell.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        Structure: Cubic supercell
        """
    
    @property
    def min_length(self):
        """Minimum supercell length."""

class SQSTransformation:
    """
    Generate Special Quasi-random Structures (SQS).
    
    Parameters:
    - scaling: Supercell scaling matrix
    - search_time: Time limit for SQS search in seconds
    - directory: Working directory for mcsqs
    - instances: Number of SQS instances to generate
    - wd: Alternative working directory specification
    - objective: Objective function for SQS optimization
    """
    def __init__(self, scaling=None, search_time=60, directory=None,
                 instances=None, wd=None, objective=None): ...
    
    def apply_transformation(self, structure):
        """
        Generate SQS structures.
        
        Parameters:
        structure: Disordered structure to create SQS from
        
        Returns:
        list: List of SQS structures
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple SQS structures."""
        return True

class MonteCarloRattleTransformation:
    """
    Apply Monte Carlo rattling to atomic positions.
    
    Parameters:
    - rattle_std: Standard deviation for rattling
    - min_distance: Minimum allowed interatomic distance
    - seed: Random seed for reproducibility
    """
    def __init__(self, rattle_std=0.01, min_distance=1.0, seed=None): ...
    
    def apply_transformation(self, structure):
        """
        Apply Monte Carlo rattling.
        
        Parameters:
        structure: Structure to rattle
        
        Returns:
        Structure: Rattled structure
        """
    
    @property
    def rattle_std(self):
        """Rattling standard deviation."""

Multi-Step Transformations

Transformations that combine multiple operations.

class SuperTransformation:
    """
    Apply multiple transformations in sequence.
    
    Parameters:
    - transformations: List of transformation objects to apply
    - nprocs: Number of processes for parallel execution
    """
    def __init__(self, transformations, nprocs=None): ...
    
    def apply_transformation(self, structure):
        """
        Apply multiple transformations in sequence.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        Structure or list: Final transformed structure(s)
        """
    
    @property
    def transformations(self):
        """List of transformations to apply."""
    
    @property
    def is_one_to_many(self):
        """Whether any transformation in sequence is one-to-many."""
        return any(getattr(t, "is_one_to_many", False) for t in self.transformations)

class MultipleSubstitutionTransformation:
    """
    Perform multiple species substitutions.
    
    Parameters:
    - substitutions: List of substitution dictionaries
    """
    def __init__(self, substitutions): ...
    
    def apply_transformation(self, structure):
        """
        Apply multiple substitutions.
        
        Parameters:
        structure: Structure to transform
        
        Returns:
        list: List of structures with different substitutions
        """
    
    @property
    def is_one_to_many(self):
        """Returns True - generates multiple substitution variants."""
        return True
    
    @property
    def substitutions(self):
        """List of substitution mappings."""

Utility Functions

Helper functions for transformation operations and structure manipulation.

def standardize_transformation(transformation, structure):
    """
    Standardize transformation output format.
    
    Parameters:
    transformation: Transformation object
    structure: Input structure
    
    Returns:
    list: Standardized list of transformed structures
    """

def batch_write_vasp_input(transformed_structures, vasp_input_set=None,
                          output_dir=".", make_dir_if_not_present=True,
                          subfolder=None, include_cif=False, **kwargs):
    """
    Batch write VASP input files for transformed structures.
    
    Parameters:
    transformed_structures: List of transformed structures
    vasp_input_set: VASP input set to use
    output_dir: Output directory
    make_dir_if_not_present: Whether to create directories
    subfolder: Subfolder naming scheme
    include_cif: Whether to include CIF files
    """

def apply_transformation_to_structures(transformations, structures, 
                                     extend_collection=True):
    """
    Apply transformations to multiple structures.
    
    Parameters:
    transformations: List of transformations
    structures: List of input structures
    extend_collection: Whether to extend or replace collection
    
    Returns:
    list: List of all transformed structures
    """

Install with Tessl CLI