@mat3ra/made 2024.6.29-0 → 2024.7.2-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2024.6.29-0",
+    "version": "2024.7.2-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,4 +1,4 @@
-from typing import List, Optional
+from typing import Callable, List, Optional
 
 import numpy as np
 
@@ -198,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/modify.py

@@ -1,11 +1,18 @@
-from typing import List, Union
+from typing import Callable, List, Optional, Union
 
+import numpy as np
 from mat3ra.made.material import Material
 
-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 .third_party import PymatgenSpacegroupAnalyzer, PymatgenStructure
-from .utils import translate_to_bottom_pymatgen_structure
+from .utils import (
+    is_coordinate_in_box,
+    is_coordinate_in_cylinder,
+    is_coordinate_in_triangular_prism,
+    is_coordinate_within_layer,
+    translate_to_bottom_pymatgen_structure,
+)
 
 
 def filter_by_label(material: Material, label: Union[int, str]) -> Material:
@@ -81,30 +88,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.
 
@@ -120,6 +170,156 @@ 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,
+    min_coordinate: List[float] = [0, 0],
+    max_coordinate: List[float] = [1, 1],
+    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.
+        min_coordinate (List[float]): The minimum coordinate of the rectangle.
+        max_coordinate (List[float]): The maximum 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.
+    """
+    min_coordinate = min_coordinate[:2] + [0]
+    max_coordinate = max_coordinate[:2] + [1]
+
+    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
+    )
+
+
+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
+    )
+
+
+def filter_by_triangle_projection(
+    material: Material,
+    coordinate_1: List[float] = [0, 0],
+    coordinate_2: List[float] = [0, 1],
+    coordinate_3: List[float] = [1, 0],
+    min_z: float = 0,
+    max_z: float = 1,
+    use_cartesian_coordinates: bool = False,
+    invert_selection: bool = False,
+) -> Material:
+    """
+    Get material with atoms that are within or outside a prism formed by triangle projection.
+
+    Args:
+        material (Material): The material object to filter.
+        coordinate_1 (List[float]): The coordinate of the first vertex.
+        coordinate_2 (List[float]): The coordinate of the second vertex.
+        coordinate_3 (List[float]): The coordinate of the third vertex.
+        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_triangular_prism(coordinate, coordinate_1, coordinate_2, coordinate_3, min_z, max_z)
+
+    return filter_by_condition_on_coordinates(
+        material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
+    )

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

@@ -96,3 +96,120 @@ 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 coordinate 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 coordinate 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 coordinate 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 coordinate 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 coordinate'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 coordinate 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
+
+
+def is_coordinate_in_triangular_prism(
+    coordinate: List[float],
+    coordinate_1: List[float],
+    coordinate_2: List[float],
+    coordinate_3: List[float],
+    min_z: float = 0,
+    max_z: float = 1,
+) -> bool:
+    """
+    Check if a coordinate is inside a triangular prism.
+    Args:
+        coordinate (List[float]): The coordinate to check.
+        coordinate_1 (List[float]): The first coordinate of the triangle.
+        coordinate_2 (List[float]): The second coordinate of the triangle.
+        coordinate_3 (List[float]): The third coordinate of the triangle.
+        min_z (float): Lower limit of z-coordinate.
+        max_z (float): Upper limit of z-coordinate.
+
+    Returns:
+        bool: True if the coordinate is inside the triangular prism, False otherwise.
+    """
+    # convert to 3D coordinates at the origin XY plane
+    coordinate_1.extend([0] * (3 - len(coordinate_1)))
+    coordinate_2.extend([0] * (3 - len(coordinate_2)))
+    coordinate_3.extend([0] * (3 - len(coordinate_3)))
+
+    coordinate = np.array(coordinate)
+    v1 = np.array(coordinate_1)
+    v2 = np.array(coordinate_2)
+    v3 = np.array(coordinate_3)
+
+    v2_v1 = v2 - v1
+    v3_v1 = v3 - v1
+    coordinate_v1 = coordinate - v1
+
+    # Compute dot products for the barycentric coordinates
+    d00 = np.dot(v2_v1, v2_v1)
+    d01 = np.dot(v2_v1, v3_v1)
+    d11 = np.dot(v3_v1, v3_v1)
+    d20 = np.dot(coordinate_v1, v2_v1)
+    d21 = np.dot(coordinate_v1, v3_v1)
+
+    # Calculate barycentric coordinates
+    denom = d00 * d11 - d01 * d01
+    v = (d11 * d20 - d01 * d21) / denom
+    w = (d00 * d21 - d01 * d20) / denom
+    u = 1.0 - v - w
+
+    return (u >= 0) and (v >= 0) and (w >= 0) and (u + v + w <= 1) and (min_z <= coordinate[2] <= max_z)

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,14 @@
 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,
+    filter_by_triangle_projection,
+)
 from mat3ra.utils import assertion as assertion_utils
 
 from .fixtures import SI_CONVENTIONAL_CELL
@@ -46,15 +53,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 +69,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 +80,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 +99,40 @@ 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())
+
+
+def test_filter_by_triangle_projection():
+    # Small prism in the middle of the cell containing the central atom will be removed -- the same as with sphere
+    material = Material(SI_CONVENTIONAL_CELL)
+    section = filter_by_triangle_projection(material, [0.4, 0.4], [0.4, 0.5], [0.5, 0.5])
+    cavity = filter_by_triangle_projection(material, [0.4, 0.4], [0.4, 0.5], [0.5, 0.5], 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())