Feature/SOF-7456 adjustments for Twisted Interface Builder

src/py/mat3ra/made/tools/build/interface/builders.py

@@ -15,6 +15,7 @@
     rotate,
     translate_by_vector,
     add_vacuum_sides,
+    add_vacuum,
 )
 from ...analyze import get_chemical_formula
 from ...convert import to_ase, from_ase, to_pymatgen, PymatgenInterface, ASEAtoms
@@ -243,7 +244,7 @@ def _generate(self, configuration: _ConfigurationType) -> List[Material]:
     def _update_material_name(
         self, material: Material, configuration: NanoRibbonTwistedInterfaceConfiguration
     ) -> Material:
-        material.name = f"Twisted Nanoribbon Interface ({configuration.twist_angle:.2f}°)"
+        material.name = f"Twisted Nanoribbon Interface ({configuration.twist_angle:.2f} degrees)"
         return material
 
 
@@ -252,13 +253,14 @@ class CommensurateLatticeTwistedInterfaceBuilderParameters(BaseModel):
     Parameters for the commensurate lattice interface builder.
 
     Args:
-        max_repetition_int (int): The maximum search range for commensurate lattices.
+        max_repetition_int (Optional[int]): The maximum integer for the transformation matrices. If not provided, it
+            will be determined based on the target angle and the lattice vectors automatically.
         angle_tolerance (float): The tolerance for the angle between the commensurate lattices
             and the target angle, in degrees.
         return_first_match (bool): Whether to return the first match or all matches.
     """
 
-    max_repetition_int: int = 10
+    max_repetition_int: Optional[int] = None
     angle_tolerance: float = 0.1
     return_first_match: bool = False
 
@@ -270,36 +272,74 @@ class CommensurateLatticeTwistedInterfaceBuilder(BaseBuilder):
     def _generate(self, configuration: _ConfigurationType) -> List[_GeneratedItemType]:
         film = configuration.film
         # substrate = configuration.substrate
-        max_search = self.build_parameters.max_repetition_int
         a = film.lattice.vector_arrays[0][:2]
         b = film.lattice.vector_arrays[1][:2]
-        commensurate_lattice_pairs = self.__generate_commensurate_lattices(
-            configuration, a, b, max_search, configuration.twist_angle
+        max_int = self.build_parameters.max_repetition_int or self.__get_initial_guess_for_max_int(
+            film, configuration.twist_angle
         )
+        commensurate_lattice_pairs: List[CommensurateLatticePair] = []
+        while not commensurate_lattice_pairs and max_int < 42:
+            commensurate_lattice_pairs = self.__generate_commensurate_lattices(
+                configuration, a, b, max_int, configuration.twist_angle
+            )
+            max_int += 1
+
         return commensurate_lattice_pairs
 
+    def __get_initial_guess_for_max_int(self, film, target_angle: float) -> int:
+        """
+        Determine the maximum integer for the transformation matrices based on the target angle.
+
+        Args:
+            a (List[float]): The a lattice vector.
+            b (List[float]): The b lattice vector.
+            target_angle (float): The target twist angle, in degrees.
+
+        Returns:
+            int: The maximum integer for the transformation matrices.
+        """
+        a = film.lattice.vector_arrays[0][:2]
+        b = film.lattice.vector_arrays[1][:2]
+        length_a = np.linalg.norm(a)
+        length_b = np.linalg.norm(b)
+        average_length = (length_a + length_b) / 2
+        theta_rad = np.radians(target_angle)
+
+        # Factor in both the lattice length and twist angle, ensuring a minimum of 1 for very small angles
+        if theta_rad == 0:
+            max_int = 1
+        if film.lattice.type == "HEX":
+            from .enums import angle_to_lmpq_hex
+
+            closest_match = min(angle_to_lmpq_hex, key=lambda x: abs(x[0] - target_angle))
+            max_int = max(closest_match[1])
+        else:
+            max_int = int(np.ceil(average_length / theta_rad))
+        return max_int
+
     def __generate_commensurate_lattices(
         self,
         configuration: TwistedInterfaceConfiguration,
         a: List[float],
         b: List[float],
-        max_search: int = 10,
+        max_int: int,
         target_angle: float = 0.0,
     ) -> List[CommensurateLatticePair]:
         """
-        Generate all commensurate lattices for a given search range and filter by closeness to target angle.
+        Generate all commensurate lattices for a given target angle and filter by closeness to target angle.
 
         Args:
             configuration (TwistedInterfaceConfiguration): The configuration for the twisted interface.
             a (List[float]): The a lattice vector.
             b (List[float]): The b lattice vector.
-            max_search (int): The maximum search range.
-            target_angle (float): The target angle, in degrees.
+            max_int (int): The maximum integer for the transformation matrices.
+            target_angle (float): The target twist angle, in degrees.
 
         Returns:
             List[CommensurateLatticePair]: The list of commensurate lattice pairs
         """
-        matrices = create_2d_supercell_matrices(max_search)
+        # Generate the supercell matrices using the calculated max_int
+        matrices = create_2d_supercell_matrices(max_int)
         matrix_ab = np.array([a, b])
         matrix_ab_inverse = np.linalg.inv(matrix_ab)
 
@@ -342,8 +382,10 @@ def _post_process(
             new_film = translate_by_vector(
                 new_film, [0, 0, item.configuration.distance_z], use_cartesian_coordinates=True
             )
-            interface = merge_materials([new_substrate, new_film])
+            interface = merge_materials([new_substrate, new_film], merge_dangerously=True)
             interface.metadata["actual_twist_angle"] = item.angle
+            if item.configuration.vacuum != 0:
+                interface = add_vacuum(interface, item.configuration.vacuum)
             interfaces.append(interface)
         return interfaces
 
@@ -354,3 +396,9 @@ def _update_material_metadata(self, material, configuration) -> Material:
                 "actual_twist_angle"
             ]
         return updated_material
+
+    def _update_material_name(
+        self, material: Material, configuration: NanoRibbonTwistedInterfaceConfiguration
+    ) -> Material:
+        material.name = f"Twisted Bilayer Interface ({material.metadata['actual_twist_angle']:.2f} degrees)"
+        return material

src/py/mat3ra/made/tools/build/interface/configuration.py

@@ -40,6 +40,7 @@ class TwistedInterfaceConfiguration(BaseConfiguration):
     substrate: Optional[Material] = None
     twist_angle: float = 0.0
     distance_z: float = 3.0
+    vacuum: float = 0.0
 
     @property
     def _json(self):

src/py/mat3ra/made/tools/build/interface/enums.py

@@ -10,3 +10,49 @@ class StrainModes(str, Enum):
 class SupercellTypes(str, Enum):
     hexagonal = "hexagonal"
     orthogonal = "orthogonal"
+
+
+# Tabulation from https://github.com/qtm-iisc/Twister/blob/474156a2a59f2b9d59350b32de56864a9496f848/examples/Homobilayer_hex/hex.table
+angle_to_lmpq_hex = [
+    (60.0, [0, 1, -1, 1]),
+    (21.7867892983, [1, 2, -2, 3]),
+    (13.1735511073, [2, 3, -3, 5]),
+    (9.4300079079, [3, 4, -4, 7]),
+    (7.34099301663, [4, 5, -5, 9]),
+    (6.00898319777, [5, 6, -6, 11]),
+    (5.08584780812, [6, 7, -7, 13]),
+    (4.40845500794, [7, 8, -8, 15]),
+    (3.89023816901, [8, 9, -9, 17]),
+    (3.48100608947, [9, 10, -10, 19]),
+    (3.14965742639, [10, 11, -11, 21]),
+    (2.87589463363, [11, 12, -12, 23]),
+    (2.64590838119, [12, 13, -13, 25]),
+    (2.44997727662, [13, 14, -14, 27]),
+    (2.28105960973, [14, 15, -15, 29]),
+    (2.1339296666, [15, 16, -16, 31]),
+    (2.00462783069, [16, 17, -17, 33]),
+    (1.89009907347, [17, 18, -18, 35]),
+    (1.78794861038, [18, 19, -19, 37]),
+    (1.69627269352, [19, 20, -20, 39]),
+    (1.61353890116, [20, 21, -21, 41]),
+    (1.53849981837, [21, 22, -22, 43]),
+    (1.47012972578, [22, 23, -23, 45]),
+    (1.40757744635, [23, 24, -24, 47]),
+    (1.35013073557, [24, 25, -25, 49]),
+    (1.29718904759, [25, 26, -26, 51]),
+    (1.24824246553, [26, 27, -27, 53]),
+    (1.20285522748, [27, 28, -28, 55]),
+    (1.16065271985, [28, 29, -29, 57]),
+    (1.12131111538, [29, 30, -30, 59]),
+    (1.08454904916, [30, 31, -31, 61]),
+    (1.05012087979, [31, 32, -32, 63]),
+    (1.01781119445, [32, 33, -33, 65]),
+    (0.987430297814, [33, 34, -34, 67]),
+    (0.958810485525, [34, 35, -35, 69]),
+    (0.931802947264, [35, 36, -36, 71]),
+    (0.906275178895, [36, 37, -37, 73]),
+    (0.882108808579, [37, 38, -38, 75]),
+    (0.859197761631, [38, 39, -39, 77]),
+    (0.8374467041, [39, 40, -40, 79]),
+    (0.816769716893, [40, 41, -41, 81]),
+]