@mat3ra/made 2024.6.25-0 → 2024.7.1-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2024.6.25-0",
+    "version": "2024.7.1-0",
     "description": "MAterials DEsign library",
     "scripts": {
         "lint": "eslint --cache src/js tests/js && prettier --write src/js tests/js",

package/src/py/mat3ra/made/tools/analyze.py

@@ -1,24 +1,21 @@
-from typing import List, Optional
+from typing import Callable, List, Optional
 
 import numpy as np
-from ase import Atoms
-from pymatgen.core import IStructure as PymatgenIStructure
 
 from ..material import Material
 from .convert import decorator_convert_material_args_kwargs_to_atoms, to_pymatgen
-
-PymatgenIStructure = PymatgenIStructure
+from .third_party import ASEAtoms, PymatgenIStructure
 
 
 @decorator_convert_material_args_kwargs_to_atoms
 def get_average_interlayer_distance(
-    interface_atoms: Atoms, tag_substrate: str, tag_film: str, threshold: float = 0.5
+    interface_atoms: ASEAtoms, tag_substrate: str, tag_film: str, threshold: float = 0.5
 ) -> float:
     """
     Calculate the average distance between the top layer of substrate atoms and the bottom layer of film atoms.
 
     Args:
-        interface_atoms (ase.Atoms): The ASE Atoms object containing both sets of atoms.
+        interface_atoms (ase.ASEAtoms): The ASE ASEAtoms object containing both sets of atoms.
         tag_substrate (int): The tag representing the substrate atoms.
         tag_film (int): The tag representing the film atoms.
         threshold (float): The threshold for identifying the top and bottom layers of atoms.
@@ -48,12 +45,12 @@ def get_average_interlayer_distance(
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def get_surface_area(atoms: Atoms):
+def get_surface_area(atoms: ASEAtoms):
     """
     Calculate the area of the surface perpendicular to the z-axis of the atoms structure.
 
     Args:
-        atoms (ase.Atoms): The Atoms object to calculate the surface area of.
+        atoms (ase.ASEAtoms): The ASEAtoms object to calculate the surface area of.
 
     Returns:
         float: The surface area of the atoms.
@@ -64,12 +61,12 @@ def get_surface_area(atoms: Atoms):
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def get_chemical_formula(atoms: Atoms):
+def get_chemical_formula(atoms: ASEAtoms):
     """
     Calculate the formula of the atoms structure.
 
     Args:
-        atoms (ase.Atoms): The Atoms object to calculate the formula of.
+        atoms (ase.ASEAtoms): The ASEAtoms object to calculate the formula of.
 
     Returns:
         str: The formula of the atoms.
@@ -201,3 +198,34 @@ def get_atom_indices_within_radius_pbc(
 
     selected_indices = [site.index for site in sites_within_radius]
     return selected_indices
+
+
+def get_atom_indices_with_condition_on_coordinates(
+    material: Material,
+    condition: Callable[[List[float]], bool],
+    use_cartesian_coordinates: bool = False,
+) -> List[int]:
+    """
+    Select atoms whose coordinates satisfy the given condition.
+
+    Args:
+        material (Material): Material object
+        condition (Callable[List[float], bool]): Function that checks if coordinates satisfy the condition.
+        use_cartesian (bool): Whether to use Cartesian coordinates for the condition evaluation.
+
+    Returns:
+        List[int]: List of indices of atoms whose coordinates satisfy the condition.
+    """
+    new_material = material.clone()
+    if use_cartesian_coordinates:
+        new_basis = new_material.basis
+        new_basis.to_cartesian()
+        new_material.basis = new_basis
+    coordinates = new_material.basis.coordinates.to_array_of_values_with_ids()
+
+    selected_indices = []
+    for coord in coordinates:
+        if condition(coord.value):
+            selected_indices.append(coord.id)
+
+    return selected_indices

package/src/py/mat3ra/made/tools/build/defect/builders.py

@@ -2,15 +2,16 @@ from typing import List, Callable
 
 from mat3ra.made.material import Material
 from pydantic import BaseModel
-from pymatgen.analysis.defects.core import (
-    Substitution as PymatgenSubstitution,
-    Vacancy as PymatgenVacancy,
-    Interstitial as PymatgenInterstitial,
-)
-from pymatgen.core import PeriodicSite as PymatgenPeriodicSite
 
+from ...third_party import (
+    PymatgenStructure,
+    PymatgenPeriodicSite,
+    PymatgenVacancy,
+    PymatgenSubstitution,
+    PymatgenInterstitial,
+)
 from ...build import BaseBuilder
-from ...convert import PymatgenStructure, to_pymatgen
+from ...convert import to_pymatgen
 from ..mixins import ConvertGeneratedItemsPymatgenStructureMixin
 from .configuration import PointDefectConfiguration
 

package/src/py/mat3ra/made/tools/build/mixins.py

@@ -1,4 +1,5 @@
-from ..convert import from_ase, from_pymatgen, ASEAtoms, PymatgenStructure
+from ..convert import from_ase, from_pymatgen
+from ..third_party import ASEAtoms, PymatgenStructure
 
 
 class ConvertGeneratedItemsASEAtomsMixin:

package/src/py/mat3ra/made/tools/build/slab/builders.py

@@ -1,18 +1,16 @@
-from pymatgen.core.surface import SlabGenerator as PymatgenSlabGenerator
-from ...convert import label_pymatgen_slab_termination
 from typing import List
 from pydantic import BaseModel
 
-
 from mat3ra.made.material import Material
 
-from .termination import Termination
+from ...third_party import PymatgenSlab, PymatgenSlabGenerator, label_pymatgen_slab_termination
 from ...analyze import get_chemical_formula
-from ...convert import to_pymatgen, PymatgenSlab
+from ...convert import to_pymatgen
 from ...build import BaseBuilder
 from ...build.mixins import ConvertGeneratedItemsPymatgenStructureMixin
 from ..supercell import create_supercell
 from .configuration import SlabConfiguration
+from .termination import Termination
 
 
 class SlabSelectorParameters(BaseModel):

package/src/py/mat3ra/made/tools/build/slab/configuration.py

@@ -1,10 +1,10 @@
 from typing import List, Tuple, Any
+from pydantic import BaseModel
 
 from mat3ra.code.entity import InMemoryEntity
-from pymatgen.symmetry.analyzer import SpacegroupAnalyzer as PymatgenSpacegroupAnalyzer
-from pydantic import BaseModel
 
 from mat3ra.made.material import Material
+from ...third_party import PymatgenSpacegroupAnalyzer
 from ...convert import to_pymatgen, from_pymatgen
 
 

package/src/py/mat3ra/made/tools/build/supercell.py

@@ -1,15 +1,14 @@
 from typing import List
-from ase import Atoms
-from ase.build.supercells import make_supercell
 
 from mat3ra.made.material import Material
+from ..third_party import ASEAtoms, ase_make_supercell
 from ..utils import decorator_convert_2x2_to_3x3
 from ..convert import from_ase, decorator_convert_material_args_kwargs_to_atoms
 
 
 @decorator_convert_2x2_to_3x3
 @decorator_convert_material_args_kwargs_to_atoms
-def create_supercell(atoms: Atoms, supercell_matrix: List[List[int]]) -> Material:
+def create_supercell(atoms: ASEAtoms, supercell_matrix: List[List[int]]) -> Material:
     """
     Create a supercell of the atoms.
 
@@ -21,5 +20,5 @@ def create_supercell(atoms: Atoms, supercell_matrix: List[List[int]]) -> Materia
         Material: The supercell of the atoms.
     """
 
-    supercell_atoms = make_supercell(atoms, supercell_matrix)
+    supercell_atoms = ase_make_supercell(atoms, supercell_matrix)
     return Material(from_ase(supercell_atoms))

package/src/py/mat3ra/made/tools/calculate.py

@@ -1,22 +1,19 @@
 from typing import Optional
 
-from ase import Atoms
-from ase.calculators.calculator import Calculator
-from ase.calculators.emt import EMT
-
 from ..material import Material
 from .analyze import get_surface_area
 from .build.interface.utils import get_slab
 from .convert import decorator_convert_material_args_kwargs_to_atoms
+from .third_party import ASEAtoms, ASECalculator, ASECalculatorEMT
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def calculate_total_energy(atoms: Atoms, calculator: Calculator):
+def calculate_total_energy(atoms: ASEAtoms, calculator: ASECalculator):
     """
     Set calculator for ASE Atoms and calculate the total energy.
 
     Args:
-        atoms (ase.Atoms): The Atoms object to calculate the energy of.
+        atoms (ASEAtoms): The Atoms object to calculate the energy of.
         calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
 
     Returns:
@@ -27,12 +24,12 @@ def calculate_total_energy(atoms: Atoms, calculator: Calculator):
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def calculate_total_energy_per_atom(atoms: Atoms, calculator: Calculator):
+def calculate_total_energy_per_atom(atoms: ASEAtoms, calculator: ASECalculator):
     """
     Set calculator for ASE Atoms and calculate the total energy per atom.
 
     Args:
-            atoms (ase.Atoms): The Atoms object to calculate the energy of.
+            atoms (ASEAtoms): The Atoms object to calculate the energy of.
             calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
 
     Returns:
@@ -42,13 +39,13 @@ def calculate_total_energy_per_atom(atoms: Atoms, calculator: Calculator):
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def calculate_surface_energy(slab: Atoms, bulk: Atoms, calculator: Calculator):
+def calculate_surface_energy(slab: ASEAtoms, bulk: ASEAtoms, calculator: ASECalculator):
     """
     Calculate the surface energy by subtracting the weighted bulk energy from the slab energy.
 
     Args:
-        slab (ase.Atoms): The slab Atoms object to calculate the surface energy of.
-        bulk (ase.Atoms): The bulk Atoms object to calculate the surface energy of.
+        slab (ASEAtoms): The slab Atoms object to calculate the surface energy of.
+        bulk (ASEAtoms): The bulk Atoms object to calculate the surface energy of.
         calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
 
     Returns:
@@ -62,7 +59,9 @@ def calculate_surface_energy(slab: Atoms, bulk: Atoms, calculator: Calculator):
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def calculate_adhesion_energy(interface: Atoms, substrate_slab: Atoms, film_slab: Atoms, calculator: Calculator):
+def calculate_adhesion_energy(
+    interface: ASEAtoms, substrate_slab: ASEAtoms, film_slab: ASEAtoms, calculator: ASECalculator
+):
     """
     Calculate the adhesion energy.
     The adhesion energy is the difference between the energy of the interface and
@@ -70,9 +69,9 @@ def calculate_adhesion_energy(interface: Atoms, substrate_slab: Atoms, film_slab
     According to: 10.1088/0953-8984/27/30/305004
 
     Args:
-        interface (ase.Atoms): The interface Atoms object to calculate the adhesion energy of.
-        substrate_slab (ase.Atoms): The substrate slab Atoms object to calculate the adhesion energy of.
-        film_slab (ase.Atoms): The film slab Atoms object to calculate the adhesion energy of.
+        interface (ASEAtoms): The interface ASEAtoms object to calculate the adhesion energy of.
+        substrate_slab (ASEAtoms): The substrate slab ASEAtoms object to calculate the adhesion energy of.
+        film_slab (ASEAtoms): The film slab ASEAtoms object to calculate the adhesion energy of.
         calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
 
     Returns:
@@ -91,7 +90,7 @@ def calculate_interfacial_energy(
     substrate_bulk: Optional[Material] = None,
     film_slab: Optional[Material] = None,
     film_bulk: Optional[Material] = None,
-    calculator: Calculator = EMT(),
+    calculator: ASECalculator = ASECalculatorEMT(),
 ):
     """
     Calculate the interfacial energy.

package/src/py/mat3ra/made/tools/convert/__init__.py

@@ -5,20 +5,22 @@ from typing import Any, Callable, Dict, Union
 from mat3ra.made.material import Material
 from mat3ra.made.utils import map_array_with_id_value_to_array
 from mat3ra.utils.mixins import RoundNumericValuesMixin
-from pymatgen.io.ase import AseAtomsAdaptor
-from pymatgen.io.vasp.inputs import Poscar
 
-from .utils import (
-    INTERFACE_LABELS_MAP,
+from ..third_party import (
     ASEAtoms,
+    PymatgenAseAtomsAdaptor,
     PymatgenInterface,
     PymatgenLattice,
+    PymatgenPoscar,
     PymatgenSlab,
     PymatgenStructure,
+    label_pymatgen_slab_termination,
+)
+from .utils import (
+    INTERFACE_LABELS_MAP,
     extract_labels_from_pymatgen_structure,
     extract_metadata_from_pymatgen_structure,
     extract_tags_from_ase_atoms,
-    label_pymatgen_slab_termination,
     map_array_to_array_with_id_value,
 )
 
@@ -138,7 +140,7 @@ def to_poscar(material_or_material_data: Union[Material, Dict[str, Any]]) -> str
         str: A POSCAR string.
     """
     structure = to_pymatgen(material_or_material_data)
-    poscar = Poscar(structure)
+    poscar = PymatgenPoscar(structure)
     # For pymatgen `2023.6.23` supporting py3.8 the method name is "get_string"
     # TODO: cleanup the if statement when dropping support for py3.8
     if hasattr(poscar, "get_string"):
@@ -175,7 +177,7 @@ def to_ase(material_or_material_data: Union[Material, Dict[str, Any]]) -> ASEAto
     else:
         material_config = material_or_material_data
     structure = to_pymatgen(material_config)
-    atoms = AseAtomsAdaptor.get_atoms(structure)
+    atoms = PymatgenAseAtomsAdaptor.get_atoms(structure)
 
     atomic_labels = material_config["basis"].get("labels", [])
     if atomic_labels:
@@ -196,7 +198,7 @@ def from_ase(ase_atoms: ASEAtoms) -> Dict[str, Any]:
         dict: A dictionary containing the material information in ESSE format.
     """
     # TODO: check that atomic labels/tags are properly handled
-    structure = AseAtomsAdaptor.get_structure(ase_atoms)
+    structure = PymatgenAseAtomsAdaptor.get_structure(ase_atoms)
     material = from_pymatgen(structure)
     ase_tags = extract_tags_from_ase_atoms(ase_atoms)
     material["basis"]["labels"] = ase_tags

package/src/py/mat3ra/made/tools/convert/utils.py

@@ -1,22 +1,10 @@
 import json
 from typing import Any, Dict, List, Union
 
-from ase import Atoms as ASEAtoms
 from mat3ra.made.utils import map_array_to_array_with_id_value
 from mat3ra.utils.object import NumpyNDArrayRoundEncoder
-from pymatgen.core.interface import Interface as PymatgenInterface
-from pymatgen.core.interface import label_termination
-from pymatgen.core.structure import Lattice as PymatgenLattice
-from pymatgen.core.structure import Structure as PymatgenStructure
-from pymatgen.core.surface import Slab as PymatgenSlab
-
-# Re-exported imports to allow for both use in type hints and instantiation
-PymatgenLattice = PymatgenLattice
-PymatgenStructure = PymatgenStructure
-PymatgenSlab = PymatgenSlab
-PymatgenInterface = PymatgenInterface
-ASEAtoms = ASEAtoms
-label_pymatgen_slab_termination = label_termination
+
+from ..third_party import ASEAtoms, PymatgenInterface, PymatgenStructure
 
 INTERFACE_LABELS_MAP = {"substrate": 0, "film": 1}
 

package/src/py/mat3ra/made/tools/modify.py

@@ -1,12 +1,17 @@
-from typing import List, Union
+from typing import Callable, List, Optional, Union
 
+import numpy as np
 from mat3ra.made.material import Material
-from pymatgen.analysis.structure_analyzer import SpacegroupAnalyzer
-from pymatgen.core.structure import Structure
 
-from .analyze import get_atom_indices_within_layer_by_atom_index, get_atom_indices_within_radius_pbc
+from .analyze import get_atom_indices_with_condition_on_coordinates, get_atom_indices_within_radius_pbc
 from .convert import decorator_convert_material_args_kwargs_to_structure
-from .utils import translate_to_bottom_pymatgen_structure
+from .third_party import PymatgenSpacegroupAnalyzer, PymatgenStructure
+from .utils import (
+    is_coordinate_in_box,
+    is_coordinate_in_cylinder,
+    is_coordinate_within_layer,
+    translate_to_bottom_pymatgen_structure,
+)
 
 
 def filter_by_label(material: Material, label: Union[int, str]) -> Material:
@@ -30,7 +35,7 @@ def filter_by_label(material: Material, label: Union[int, str]) -> Material:
 
 
 @decorator_convert_material_args_kwargs_to_structure
-def translate_to_bottom(structure: Structure, use_conventional_cell: bool = True):
+def translate_to_bottom(structure: PymatgenStructure, use_conventional_cell: bool = True):
     """
     Translate atoms to the bottom of the cell (vacuum on top) to allow for the correct consecutive interface generation.
     If use_conventional_cell is passed, conventional cell is used.
@@ -42,20 +47,20 @@ def translate_to_bottom(structure: Structure, use_conventional_cell: bool = True
         Structure: The normalized pymatgen Structure object.
     """
     if use_conventional_cell:
-        structure = SpacegroupAnalyzer(structure).get_conventional_standard_structure()
+        structure = PymatgenSpacegroupAnalyzer(structure).get_conventional_standard_structure()
     structure = translate_to_bottom_pymatgen_structure(structure)
     return structure
 
 
 @decorator_convert_material_args_kwargs_to_structure
-def wrap_to_unit_cell(structure: Structure):
+def wrap_to_unit_cell(structure: PymatgenStructure):
     """
     Wrap atoms to the cell
 
     Args:
-        structure (Structure): The pymatgen Structure object to normalize.
+        structure (PymatgenStructure): The pymatgen PymatgenStructure object to normalize.
     Returns:
-        Structure: The wrapped pymatgen Structure object.
+        PymatgenStructure: The wrapped pymatgen PymatgenStructure object.
     """
     structure.make_supercell((1, 1, 1), to_unit_cell=True)
     return structure
@@ -82,30 +87,73 @@ def filter_material_by_ids(material: Material, ids: List[int], invert: bool = Fa
     return new_material
 
 
+def filter_by_condition_on_coordinates(
+    material: Material,
+    condition: Callable[[List[float]], bool],
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Filter atoms based on a condition on their coordinates.
+
+    Args:
+        material (Material): The material object to filter.
+        condition (Callable): The condition on coordinate function.
+        use_cartesian_coordinates (bool): Whether to use cartesian coordinates.
+        invert_selection (bool): Whether to invert the selection.
+
+    Returns:
+        Material: The filtered material object.
+    """
+    new_material = material.clone()
+    ids = get_atom_indices_with_condition_on_coordinates(
+        material,
+        condition,
+        use_cartesian_coordinates=use_cartesian_coordinates,
+    )
+
+    new_material = filter_material_by_ids(new_material, ids, invert=invert_selection)
+    return new_material
+
+
 def filter_by_layers(
-    material: Material, central_atom_id: int, layer_thickness: float, invert: bool = False
+    material: Material,
+    center_coordinate: List[float] = [0, 0, 0],
+    central_atom_id: Optional[int] = None,
+    layer_thickness: float = 1.0,
+    invert_selection: bool = False,
 ) -> Material:
     """
     Filter out atoms within a specified layer thickness of a central atom along c-vector direction.
 
     Args:
         material (Material): The material object to filter.
+        center_coordinate (List[float]): Index of the central atom.
         central_atom_id (int): Index of the central atom.
         layer_thickness (float): Thickness of the layer in angstroms.
-        invert (bool): Whether to invert the selection.
+        invert_selection (bool): Whether to invert the selection.
 
     Returns:
         Material: The filtered material object.
     """
-    ids = get_atom_indices_within_layer_by_atom_index(
-        material,
-        central_atom_id,
-        layer_thickness,
-    )
-    return filter_material_by_ids(material, ids, invert=invert)
+    if central_atom_id is not None:
+        center_coordinate = material.basis.coordinates.get_element_value_by_index(central_atom_id)
+    vectors = material.lattice.vectors
+    direction_vector = np.array(vectors[2])
+
+    def condition(coordinate):
+        return is_coordinate_within_layer(coordinate, center_coordinate, direction_vector, layer_thickness)
 
+    return filter_by_condition_on_coordinates(material, condition, invert_selection=invert_selection)
 
-def filter_by_sphere(material: Material, central_atom_id: int, radius: float, invert: bool = False) -> Material:
+
+def filter_by_sphere(
+    material: Material,
+    center_coordinate: List[float] = [0, 0, 0],
+    central_atom_id: Optional[int] = None,
+    radius: float = 1,
+    invert: bool = False,
+) -> Material:
     """
     Filter out atoms within a specified radius of a central atom considering periodic boundary conditions.
 
@@ -121,6 +169,124 @@ def filter_by_sphere(material: Material, central_atom_id: int, radius: float, in
     ids = get_atom_indices_within_radius_pbc(
         material=material,
         atom_index=central_atom_id,
+        position=center_coordinate,
         radius=radius,
     )
     return filter_material_by_ids(material, ids, invert=invert)
+
+
+def filter_by_circle_projection(
+    material: Material,
+    x: float = 0.5,
+    y: float = 0.5,
+    r: float = 0.25,
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Get material with atoms that are within or outside an XY circle projection.
+
+    Args:
+        material (Material): The material object to filter.
+        x (float): The x-coordinate of the circle center.
+        y (float): The y-coordinate of the circle center.
+        r (float): The radius of the circle.
+        use_cartesian_coordinates (bool): Whether to use cartesian coordinates
+        invert_selection (bool): Whether to invert the selection.
+
+    Returns:
+        Material: The filtered material object.
+    """
+
+    def condition(coordinate):
+        return is_coordinate_in_cylinder(coordinate, [x, y, 0], r, min_z=0, max_z=1)
+
+    return filter_by_condition_on_coordinates(
+        material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
+    )
+
+
+def filter_by_cylinder(
+    material: Material,
+    center_position: List[float] = [0.5, 0.5],
+    min_z: float = 0,
+    max_z: float = 1,
+    radius: float = 0.25,
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Get material with atoms that are within or outside a cylinder.
+
+    Args:
+        material (Material): The material object to filter.
+        center_position (List[float]): The coordinates of the center position.
+        radius (float): The radius of the cylinder.
+        min_z (float): Lower limit of z-coordinate.
+        max_z (float): Upper limit of z-coordinate.
+        use_cartesian_coordinates (bool): Whether to use cartesian coordinates
+        invert_selection (bool): Whether to invert the selection.
+
+    Returns:
+        Material: The filtered material object.
+    """
+
+    def condition(coordinate):
+        return is_coordinate_in_cylinder(coordinate, center_position, radius, min_z, max_z)
+
+    return filter_by_condition_on_coordinates(
+        material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
+    )
+
+
+def filter_by_rectangle_projection(
+    material: Material,
+    x_min: float = 0.0,
+    y_min: float = 0.0,
+    x_max: float = 1.0,
+    y_max: float = 1.0,
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Get material with atoms that are within or outside an XY rectangle projection.
+
+    Args:
+
+        material (Material): The material object to filter.
+        x_min (float): The minimum x-coordinate of the rectangle.
+        y_min (float): The minimum y-coordinate of the rectangle.
+        x_max (float): The maximum x-coordinate of the rectangle.
+        y_max (float): The maximum y-coordinate of the rectangle.
+        use_cartesian_coordinates (bool): Whether to use cartesian coordinates
+        invert_selection (bool): Whether to invert the selection.
+
+    Returns:
+        Material: The filtered material object.
+    """
+
+    def condition(coordinate):
+        return is_coordinate_in_box(coordinate, [x_min, y_min, 0], [x_max, y_max, 1])
+
+    return filter_by_condition_on_coordinates(
+        material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
+    )
+
+
+def filter_by_box(
+    material: Material,
+    min_coordinate: List[float] = [0.0, 0.0, 0.0],
+    max_coordinate: List[float] = [1.0, 1.0, 1.0],
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Get material with atoms that are within or outside an XYZ box.
+    """
+
+    def condition(coordinate):
+        return is_coordinate_in_box(coordinate, min_coordinate, max_coordinate)
+
+    return filter_by_condition_on_coordinates(
+        material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
+    )

package/src/py/mat3ra/made/tools/third_party.py

@@ -0,0 +1,41 @@
+from ase import Atoms as ASEAtoms
+from ase.build.supercells import make_supercell as ase_make_supercell
+from ase.calculators.calculator import Calculator as ASECalculator
+from ase.calculators.emt import EMT as ASECalculatorEMT
+from pymatgen.analysis.defects.core import Interstitial as PymatgenInterstitial
+from pymatgen.analysis.defects.core import Substitution as PymatgenSubstitution
+from pymatgen.analysis.defects.core import Vacancy as PymatgenVacancy
+from pymatgen.core import IStructure as PymatgenIStructure
+from pymatgen.core import PeriodicSite as PymatgenPeriodicSite
+from pymatgen.core.interface import Interface as PymatgenInterface
+from pymatgen.core.interface import label_termination as label_pymatgen_slab_termination
+from pymatgen.core.structure import Lattice as PymatgenLattice
+from pymatgen.core.structure import Structure as PymatgenStructure
+from pymatgen.core.surface import Slab as PymatgenSlab
+from pymatgen.core.surface import SlabGenerator as PymatgenSlabGenerator
+from pymatgen.io.ase import AseAtomsAdaptor as PymatgenAseAtomsAdaptor
+from pymatgen.io.vasp.inputs import Poscar as PymatgenPoscar
+from pymatgen.symmetry.analyzer import SpacegroupAnalyzer as PymatgenSpacegroupAnalyzer
+
+# Re-exported imports to allow for both use in type hints and instantiation
+
+__all__ = [
+    "ASEAtoms",
+    "ASECalculator",
+    "ASECalculatorEMT",
+    "PymatgenLattice",
+    "PymatgenStructure",
+    "PymatgenIStructure",
+    "PymatgenSlab",
+    "PymatgenSlabGenerator",
+    "PymatgenInterface",
+    "PymatgenPeriodicSite",
+    "PymatgenSpacegroupAnalyzer",
+    "PymatgenVacancy",
+    "PymatgenSubstitution",
+    "PymatgenInterstitial",
+    "label_pymatgen_slab_termination",
+    "ase_make_supercell",
+    "PymatgenAseAtomsAdaptor",
+    "PymatgenPoscar",
+]

package/src/py/mat3ra/made/tools/utils.py

@@ -4,18 +4,19 @@ from typing import Callable, List
 import numpy as np
 from mat3ra.made.basis import Basis
 from mat3ra.utils.matrix import convert_2x2_to_3x3
-from pymatgen.core.structure import Structure
+
+from .third_party import PymatgenStructure
 
 
 # TODO: convert to accept ASE Atoms object
-def translate_to_bottom_pymatgen_structure(structure: Structure):
+def translate_to_bottom_pymatgen_structure(structure: PymatgenStructure):
     """
     Translate the structure to the bottom of the cell.
     Args:
-        structure (Structure): The pymatgen Structure object to translate.
+        structure (PymatgenStructure): The pymatgen Structure object to translate.
 
     Returns:
-        Structure: The translated pymatgen Structure object.
+        PymatgenStructure: The translated pymatgen Structure object.
     """
     min_c = min(site.c for site in structure)
     translation_vector = [0, 0, -min_c]
@@ -95,3 +96,69 @@ def get_norm(vector: List[float]) -> float:
         float: The norm of the vector.
     """
     return float(np.linalg.norm(vector))
+
+
+# Condition functions:
+
+
+def is_coordinate_in_cylinder(
+    coordinate: List[float], center_position: List[float], radius: float = 0.25, min_z: float = 0, max_z: float = 1
+) -> bool:
+    """
+    Check if a point is inside a cylinder.
+    Args:
+        coordinate (List[float]): The coordinate to check.
+        center_position (List[float]): The coordinates of the center position.
+        min_z (float): Lower limit of z-coordinate.
+        max_z (float): Upper limit of z-coordinate.
+        radius (float): The radius of the cylinder.
+
+    Returns:
+        bool: True if the point is inside the cylinder, False otherwise.
+    """
+    return (coordinate[0] - center_position[0]) ** 2 + (coordinate[1] - center_position[1]) ** 2 <= radius**2 and (
+        min_z <= coordinate[2] <= max_z
+    )
+
+
+def is_coordinate_in_box(
+    coordinate: List[float], min_coordinate: List[float] = [0, 0, 0], max_coordinate: List[float] = [1, 1, 1]
+) -> bool:
+    """
+    Check if a point is inside a box.
+    Args:
+        coordinate (List[float]): The coordinate to check.
+        min_coordinate (List[float]): The minimum coordinate of the box.
+        max_coordinate (List[float]): The maximum coordinate of the box.
+    Returns:
+        bool: True if the point is inside the box, False otherwise.
+    """
+    x_min, y_min, z_min = min_coordinate
+    x_max, y_max, z_max = max_coordinate
+    return x_min <= coordinate[0] <= x_max and y_min <= coordinate[1] <= y_max and z_min <= coordinate[2] <= z_max
+
+
+def is_coordinate_within_layer(
+    coordinate: List[float], center_position: List[float], direction_vector: List[float], layer_thickness: float
+) -> bool:
+    """
+    Checks if a point's projection along a specified direction vector
+    is within a certain layer thickness centered around a given position.
+
+    Args:
+        coordinate (List[float]): The coordinate to check.
+        center_position (List[float]): The coordinates of the center position.
+        direction_vector (List[float]): The direction vector along which the layer thickness is defined.
+        layer_thickness (float): The thickness of the layer along the direction vector.
+
+    Returns:
+        bool: True if the point is within the layer thickness, False otherwise.
+    """
+    direction_norm = np.array(direction_vector) / np.linalg.norm(direction_vector)
+    central_projection = np.dot(center_position, direction_norm)
+    layer_thickness_frac = layer_thickness / np.linalg.norm(direction_vector)
+
+    lower_bound = central_projection - layer_thickness_frac / 2
+    upper_bound = central_projection + layer_thickness_frac / 2
+
+    return lower_bound <= np.dot(coordinate, direction_norm) <= upper_bound

package/tests/py/unit/test_tools_build.py

@@ -7,8 +7,8 @@ from mat3ra.utils import assertion as assertion_utils
 
 ase_ni = bulk("Ni", "fcc", a=3.52, cubic=True)
 material = Material(from_ase(ase_ni))
-section = filter_by_layers(material, 0, 1.0)
-cavity = filter_by_layers(material, 0, 1.0, invert=True)
+section = filter_by_layers(material, central_atom_id=0, layer_thickness=1.0)
+cavity = filter_by_layers(material, central_atom_id=0, layer_thickness=1.0, invert_selection=True)
 
 # Change 0th element
 section.basis.elements.values[0] = "Ge"

package/tests/py/unit/test_tools_modify.py

@@ -1,7 +1,13 @@
 from ase.build import bulk
 from mat3ra.made.material import Material
 from mat3ra.made.tools.convert import from_ase
-from mat3ra.made.tools.modify import filter_by_label, filter_by_layers, filter_by_sphere
+from mat3ra.made.tools.modify import (
+    filter_by_circle_projection,
+    filter_by_label,
+    filter_by_layers,
+    filter_by_rectangle_projection,
+    filter_by_sphere,
+)
 from mat3ra.utils import assertion as assertion_utils
 
 from .fixtures import SI_CONVENTIONAL_CELL
@@ -46,15 +52,15 @@ expected_basis_layers_cavity = {
 
 
 expected_basis_sphere_cluster = {
-    "elements": [{"id": 0, "value": "Si"}],
-    "coordinates": [{"id": 0, "value": [0.5, 0.0, 0.0]}],
+    "elements": [{"id": 2, "value": "Si"}],
+    "coordinates": [{"id": 2, "value": [0.5, 0.5, 0.5]}],
     **COMMON_PART,
 }
 
 expected_basis_sphere_cavity = {
     "elements": [
+        {"id": 0, "value": "Si"},
         {"id": 1, "value": "Si"},
-        {"id": 2, "value": "Si"},
         {"id": 3, "value": "Si"},
         {"id": 4, "value": "Si"},
         {"id": 5, "value": "Si"},
@@ -62,8 +68,8 @@ expected_basis_sphere_cavity = {
         {"id": 7, "value": "Si"},
     ],
     "coordinates": [
+        {"id": 0, "value": [0.5, 0.0, 0.0]},
         {"id": 1, "value": [0.25, 0.25, 0.75]},
-        {"id": 2, "value": [0.5, 0.5, 0.5]},
         {"id": 3, "value": [0.25, 0.75, 0.25]},
         {"id": 4, "value": [0.0, 0.0, 0.5]},
         {"id": 5, "value": [0.75, 0.25, 0.25]},
@@ -73,6 +79,9 @@ expected_basis_sphere_cavity = {
     **COMMON_PART,
 }
 
+CRYSTAL_RADIUS = 0.25  # in crystal coordinates
+CRYSTAL_CENTER_3D = [0.5, 0.5, 0.5]  # in crystal coordinates
+
 
 def test_filter_by_label():
     substrate = bulk("Si", cubic=True)
@@ -89,15 +98,31 @@ def test_filter_by_label():
 
 def test_filter_by_layers():
     material = Material(SI_CONVENTIONAL_CELL)
-    section = filter_by_layers(material, 0, 3.0)
-    cavity = filter_by_layers(material, 0, 3.0, invert=True)
+    section = filter_by_layers(material=material, central_atom_id=0, layer_thickness=3.0)
+    cavity = filter_by_layers(material=material, central_atom_id=0, layer_thickness=3.0, invert_selection=True)
     assertion_utils.assert_deep_almost_equal(expected_basis_layers_section, section.basis.to_json())
     assertion_utils.assert_deep_almost_equal(expected_basis_layers_cavity, cavity.basis.to_json())
 
 
 def test_filter_by_sphere():
     material = Material(SI_CONVENTIONAL_CELL)
-    cluster = filter_by_sphere(material, 0, 2.0)
-    cavity = filter_by_sphere(material, 0, 2.0, invert=True)
+    cluster = filter_by_sphere(material, center_coordinate=CRYSTAL_CENTER_3D, radius=CRYSTAL_RADIUS)
+    cavity = filter_by_sphere(material, center_coordinate=CRYSTAL_CENTER_3D, radius=CRYSTAL_RADIUS, invert=True)
     assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cluster, cluster.basis.to_json())
     assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cavity, cavity.basis.to_json())
+
+
+def test_filter_by_circle_projection():
+    material = Material(SI_CONVENTIONAL_CELL)
+    # Small cylinder in the middle of the cell containing the central atom will be removed -- the same as with sphere
+    section = filter_by_circle_projection(material, 0.5, 0.5, CRYSTAL_RADIUS)
+    cavity = filter_by_circle_projection(material, 0.5, 0.5, CRYSTAL_RADIUS, invert_selection=True)
+    assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cluster, section.basis.to_json())
+    assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cavity, cavity.basis.to_json())
+
+
+def test_filter_by_rectangle_projection():
+    material = Material(SI_CONVENTIONAL_CELL)
+    # Default will contain all the atoms
+    section = filter_by_rectangle_projection(material)
+    assertion_utils.assert_deep_almost_equal(material.basis.to_json(), section.basis.to_json())