@mat3ra/made 2026.7.8-0 → 2026.7.18-0

package/package.json

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

package/pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
 ]
 dependencies = [
     "mat3ra-code",
-    "mat3ra-esse>=2026.6.30.post0",
+    "mat3ra-esse",
     "mat3ra-utils>=2026.7.3.post0",
     # new verison of numpy==2.0.0 is not handled by pymatgen yet
     "numpy<=1.26.4",

package/src/py/mat3ra/made/basis/__init__.py

@@ -175,9 +175,12 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
             other_basis (Basis): The other basis to add atoms from.
         """
 
-        self.elements.add_items(other_basis.elements.values)
-        self.coordinates.add_items(other_basis.coordinates.values)
-        self.labels.add_items(other_basis.labels.values)
+        for el in other_basis.elements.values:
+            self.elements.add_item(el)
+        for coord in other_basis.coordinates.values:
+            self.coordinates.add_item(coord)
+        for label in other_basis.labels.values:
+            self.labels.add_item(label)
 
     def remove_atom_by_id(self, id: int):
         self.elements.remove_item(id)

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

@@ -16,6 +16,8 @@ class BuildMetadataAnalyzer(BaseMaterialAnalyzer, Generic[TypeConfiguration, Typ
 
     @property
     def build_metadata(self) -> BuildMetadata:
+        if not self.material.metadata.build:
+            raise ValueError("No metadata.build on the material.")
         metadata = self.material.metadata.get_build_metadata_of_type(self.configuration_cls.__name__)
         if not metadata:
             raise ValueError(f"Build metadata for {self.configuration_cls.__name__} not found.")

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

@@ -0,0 +1,31 @@
+from typing import Dict, Type
+
+from ..build_components.metadata import MaterialWithBuildMetadata
+from .build_metadata_analyzer import BuildMetadataAnalyzer
+from .interface_material import (
+    InterfaceMaterialAnalyzer,
+)
+from .slab import SlabMaterialAnalyzer
+
+BUILD_METADATA_ANALYZER_REGISTRY: Dict[str, Type[BuildMetadataAnalyzer]] = {
+    "SlabConfiguration": SlabMaterialAnalyzer,
+    "InterfaceConfiguration": InterfaceMaterialAnalyzer,
+}
+
+
+def create_build_metadata_analyzer(
+    material: MaterialWithBuildMetadata,
+    **analyzer_kwargs,
+) -> BuildMetadataAnalyzer:
+    build_metadata = material.metadata.get_latest_build_metadata()
+    configuration_type = build_metadata.configuration.get("type")
+    if not configuration_type:
+        raise ValueError("Latest build step has no configuration type.")
+    analyzer_cls = BUILD_METADATA_ANALYZER_REGISTRY.get(configuration_type)
+    if analyzer_cls is None:
+        registered_types = ", ".join(sorted(BUILD_METADATA_ANALYZER_REGISTRY))
+        raise ValueError(
+            f"No build metadata analyzer registered for '{configuration_type}'. "
+            f"Registered types: {registered_types}."
+        )
+    return analyzer_cls(material=material, **analyzer_kwargs)

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

@@ -0,0 +1,45 @@
+from typing import Type, Union
+
+from ..build.compound_pristine_structures.two_dimensional.interface.base.build_parameters import (
+    InterfaceBuilderParameters,
+)
+from ..build.compound_pristine_structures.two_dimensional.interface.base.configuration import InterfaceConfiguration
+from ..build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
+from ..build.pristine_structures.two_dimensional.slab_strained_supercell.configuration import (
+    SlabStrainedSupercellConfiguration,
+)
+from ..build_components.metadata import MaterialWithBuildMetadata
+from ..convert.interface_parts_enum import INTERFACE_LABELS_MAP
+from .build_metadata_analyzer import BuildMetadataAnalyzer
+
+
+class InterfaceMaterialAnalyzer(
+    BuildMetadataAnalyzer[InterfaceConfiguration, InterfaceBuilderParameters],
+):
+    configuration_cls: Type[InterfaceConfiguration] = InterfaceConfiguration
+    build_parameters_cls: Type[InterfaceBuilderParameters] = InterfaceBuilderParameters
+
+    @property
+    def substrate_slab_configuration(self) -> Union[SlabStrainedSupercellConfiguration, SlabConfiguration]:
+        return self.build_configuration.substrate_configuration
+
+    @property
+    def film_slab_configuration(self) -> Union[SlabStrainedSupercellConfiguration, SlabConfiguration]:
+        return self.build_configuration.film_configuration
+
+    def get_bulk_crystal(self, part: str = "substrate") -> dict:
+        if part not in INTERFACE_LABELS_MAP:
+            raise ValueError(f"Unknown interface part '{part}'. Use 'substrate' or 'film'.")
+        slab_configuration = self.substrate_slab_configuration if part == "substrate" else self.film_slab_configuration
+        crystal = slab_configuration.atomic_layers.crystal
+        if crystal is None:
+            raise ValueError(f"No bulk crystal for {part} in interface build metadata.")
+        return crystal if isinstance(crystal, dict) else crystal.to_dict()
+
+
+def get_interface_configuration(interface: MaterialWithBuildMetadata) -> InterfaceConfiguration:
+    return InterfaceMaterialAnalyzer(material=interface).build_configuration
+
+
+def get_interface_bulk_crystal(interface: MaterialWithBuildMetadata, part: str = "substrate") -> dict:
+    return InterfaceMaterialAnalyzer(material=interface).get_bulk_crystal(part=part)

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

@@ -0,0 +1,171 @@
+import random
+from typing import List, Optional, Union
+
+import numpy as np
+from mat3ra.made.material import Material
+
+from ..analyze import BaseMaterialAnalyzer
+from ..analyze.utils import minimum_image_distances
+from ..build.defective_structures.three_dimensional.solid_solution.enums import SiteSelectionMethodEnum
+from ..build_components import MaterialWithBuildMetadata
+from ..build_components.entities.reusable.three_dimensional.supercell.helpers import create_supercell
+
+
+def _most_isotropic_dimensions(total_cells: int) -> List[int]:
+    """
+    Find [a, b, c] repeat factors whose product equals total_cells with minimum aspect ratio.
+
+    Enumerates factor triples with a <= b <= c and returns the triple with the
+    smallest spread (c - a).
+
+    Args:
+        total_cells (int): Target number of unit cells in the supercell.
+
+    Returns:
+        List[int]: Repeat factors [a, b, c] along the three lattice directions.
+    """
+    best_dimensions = [1, 1, total_cells]
+    best_spread = total_cells - 1
+    for a in range(1, total_cells + 1):
+        if total_cells % a:
+            continue
+        for b in range(a, total_cells // a + 1):
+            if (total_cells // a) % b:
+                continue
+            c = total_cells // (a * b)
+            if c < b:
+                continue
+            spread = c - a
+            if spread < best_spread:
+                best_dimensions = [a, b, c]
+                best_spread = spread
+    return best_dimensions
+
+
+def _select_sites_uniform(
+    material: Union[Material, MaterialWithBuildMetadata],
+    source_indices: List[int],
+    number_to_select: int,
+    seed: int = None,
+) -> List[int]:
+    """
+    Select number_to_select sites from source_indices using Farthest Point Sampling.
+
+    Iteratively picks the site whose minimum distance to all already-selected
+    sites is largest, producing a maximally dispersed subset under PBC.
+
+    Args:
+        material (Union[Material, MaterialWithBuildMetadata]): Material with lattice and coordinates.
+        source_indices (List[int]): Indices of candidate sites in the material basis.
+        number_to_select (int): Number of sites to select.
+        seed (int, optional): Random seed for the initial site choice.
+
+    Returns:
+        List[int]: Sorted list of selected site indices.
+    """
+    if number_to_select <= 0:
+        return []
+    if number_to_select >= len(source_indices):
+        return sorted(source_indices)
+
+    material.to_crystal()
+    fractional_coordinates = np.array(material.basis.coordinates.values)
+    lattice_vectors = np.array(material.lattice.vector_arrays)
+    pairwise_distances = minimum_image_distances(fractional_coordinates[source_indices], lattice_vectors)
+
+    random_generator = random.Random(seed)
+    first_pick = random_generator.randrange(len(source_indices))
+    selected = [first_pick]
+    distance_to_selected = pairwise_distances[first_pick].copy()
+    is_candidate = np.ones(len(source_indices), dtype=bool)
+    is_candidate[first_pick] = False
+
+    for _ in range(number_to_select - 1):
+        farthest_distance = np.max(distance_to_selected[is_candidate])
+        tied_candidates = np.where(is_candidate & np.isclose(distance_to_selected, farthest_distance))[0]
+        next_pick = int(random_generator.choice(tied_candidates))
+        selected.append(next_pick)
+        is_candidate[next_pick] = False
+        np.minimum(distance_to_selected, pairwise_distances[next_pick], out=distance_to_selected)
+
+    return sorted(source_indices[i] for i in selected)
+
+
+class SolidSolutionAnalyzer(BaseMaterialAnalyzer):
+    """
+    Analyzes a unit cell to plan supercell dimensions and select substitution sites.
+
+    Given a unit cell material and a desired substitution ratio, finds the
+    most isotropic supercell matching the target concentration within tolerance,
+    then selects specific sites for substitution.
+    """
+
+    source_element: str
+    target_element: str
+    target_concentration: float
+    tolerance: float = 0.01
+    max_supercell_cells: int = 128
+    seed: Optional[int] = None
+    site_selection_method: SiteSelectionMethodEnum = SiteSelectionMethodEnum.UNIFORM
+
+    @property
+    def source_element_count_per_cell(self) -> int:
+        return sum(1 for element in self.material.basis.elements.values if element == self.source_element)
+
+    @property
+    def optimal_supercell_dimensions(self) -> List[int]:
+        source_count_per_cell = self.source_element_count_per_cell
+        if source_count_per_cell == 0:
+            raise ValueError(f"No {self.source_element} atoms found in the unit cell.")
+
+        best_dimensions = None
+        best_shape_spread = self.max_supercell_cells
+        for cell_count in range(1, self.max_supercell_cells + 1):
+            source_atoms = source_count_per_cell * cell_count
+            replacement_atoms = min(max(round(self.target_concentration * source_atoms), 0), source_atoms)
+            achieved_concentration = replacement_atoms / source_atoms
+            if abs(achieved_concentration - self.target_concentration) > self.tolerance:
+                continue
+
+            dimensions = _most_isotropic_dimensions(cell_count)
+            shape_spread = dimensions[2] - dimensions[0]
+            if shape_spread < best_shape_spread:
+                best_dimensions = dimensions
+                best_shape_spread = shape_spread
+            if shape_spread == 0:
+                break
+
+        if best_dimensions is None:
+            raise ValueError(
+                f"Cannot achieve concentration {self.target_concentration} "
+                f"within tolerance {self.tolerance} for up to {self.max_supercell_cells} cells."
+            )
+        return best_dimensions
+
+    @property
+    def actual_concentration(self) -> float:
+        a, b, c = self.optimal_supercell_dimensions
+        source_atoms = self.source_element_count_per_cell * a * b * c
+        replacement_atoms = min(max(round(self.target_concentration * source_atoms), 0), source_atoms)
+        return replacement_atoms / source_atoms
+
+    @property
+    def selected_site_indices(self) -> List[int]:
+        supercell = create_supercell(material=self.material, scaling_factor=self.optimal_supercell_dimensions)
+        supercell_material = MaterialWithBuildMetadata.create(supercell.to_dict())
+        elements = supercell_material.basis.elements.values
+        source_indices = [index for index, element in enumerate(elements) if element == self.source_element]
+        replacement_atoms = min(
+            max(round(self.actual_concentration * len(source_indices)), 0),
+            len(source_indices),
+        )
+
+        if self.site_selection_method == SiteSelectionMethodEnum.UNIFORM:
+            keep_atoms = len(source_indices) - replacement_atoms
+            if keep_atoms < replacement_atoms:
+                kept_indices = _select_sites_uniform(supercell_material, source_indices, keep_atoms, self.seed)
+                return sorted(set(source_indices) - set(kept_indices))
+            return _select_sites_uniform(supercell_material, source_indices, replacement_atoms, self.seed)
+
+        random_generator = random.Random(self.seed)
+        return sorted(random_generator.sample(source_indices, replacement_atoms))

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

@@ -135,3 +135,28 @@ def calculate_von_mises_strain(strain_matrix: np.ndarray) -> float:
     e_von_mises = np.sqrt(exx**2 - exx * eyy + eyy**2 + 3 * exy**2)
 
     return abs(e_von_mises) * 100.0
+
+
+def minimum_image_distances(frac_coords: np.ndarray, lattice_vectors: np.ndarray) -> np.ndarray:
+    """
+    Compute pairwise distances between fractional coordinates under periodic boundary conditions.
+
+    Applies the minimum image convention: for each pair, the shortest distance
+    across all periodic images is returned.
+
+    Args:
+        frac_coords (np.ndarray): Fractional coordinates, shape (N, 3).
+        lattice_vectors (np.ndarray): Lattice vectors, shape (3, 3), rows are vectors.
+
+    Returns:
+        np.ndarray: Symmetric distance matrix, shape (N, N), in the same units as lattice_vectors.
+    """
+    n = len(frac_coords)
+    distances = np.zeros((n, n))
+    for i in range(n):
+        delta = frac_coords[i] - frac_coords[i + 1 :]
+        delta -= np.round(delta)
+        dists = np.linalg.norm(delta @ lattice_vectors, axis=1)
+        distances[i, i + 1 :] = dists
+        distances[i + 1 :, i] = dists
+    return distances

package/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/__init__.py

@@ -13,7 +13,11 @@ from .twisted import (
     TwistedNanoribbonsInterfaceConfiguration,
     create_interface_twisted,
 )
-from .utils import get_optimal_film_displacement, get_slab, remove_duplicate_interfaces
+from .utils import (
+    get_optimal_film_displacement,
+    get_slab,
+    remove_duplicate_interfaces,
+)
 from .zsl import (
     create_interface_zsl,
     create_interface_zsl_between_slabs,

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/__init__.py

@@ -0,0 +1 @@
+

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/solid_solution/__init__.py

@@ -0,0 +1,9 @@
+from .builder import SolidSolutionBuilder
+from .configuration import SolidSolutionConfiguration
+from .enums import SiteSelectionMethodEnum
+
+__all__ = [
+    "SiteSelectionMethodEnum",
+    "SolidSolutionBuilder",
+    "SolidSolutionConfiguration",
+]

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/solid_solution/builder.py

@@ -0,0 +1,37 @@
+from typing import Dict, Type, Union
+
+from mat3ra.made.material import Material
+
+from .....analyze.other import get_chemical_formula_empirical
+from .....build_components import MaterialWithBuildMetadata, TypeConfiguration
+from .....build_components.entities.auxiliary.zero_dimensional.point_defect_site.builder import PointDefectSiteBuilder
+from .....build_components.entities.auxiliary.zero_dimensional.point_defect_site.configuration import (
+    PointDefectSiteConfiguration,
+)
+from .....build_components.operations.core.combinations.merge.builder import MergeBuilder
+from .configuration import SolidSolutionConfiguration
+
+
+class SolidSolutionBuilder(MergeBuilder):
+    """Builds a solid solution by merging substitution sites into a supercell."""
+
+    _ConfigurationType: Type[SolidSolutionConfiguration] = SolidSolutionConfiguration
+
+    @property
+    def merge_component_types_conversion_map(self) -> Dict[Type, Type]:
+        return {
+            PointDefectSiteConfiguration: PointDefectSiteBuilder,
+        }
+
+    def _update_material_name(
+        self, material: Union[Material, MaterialWithBuildMetadata], configuration: TypeConfiguration
+    ) -> MaterialWithBuildMetadata:
+        formula = get_chemical_formula_empirical(material)
+        concentration_percentage = configuration.actual_concentration * 100
+        source_element = configuration.source_element
+        target_element = configuration.target_element
+        material.name = (
+            f"{formula} - Solid Solution ({source_element}\u2192{target_element} "
+            f"{concentration_percentage:.4g}%)"
+        )
+        return material

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/solid_solution/configuration.py

@@ -0,0 +1,30 @@
+from typing import List, Union
+
+from mat3ra.esse.models.materials_category.defective_structures.three_dimensional.solid_solution.configuration import (
+    SolidSolutionConfigurationSchema,
+)
+from mat3ra.esse.models.materials_category_components.operations.core.combinations.merge import MergeMethodsEnum
+from mat3ra.made.material import Material
+
+from .....build_components import MaterialWithBuildMetadata
+from .....build_components.entities.auxiliary.zero_dimensional.point_defect_site.configuration import (
+    PointDefectSiteConfiguration,
+)
+from .....build_components.operations.core.combinations.merge.configuration import MergeConfiguration
+
+
+class SolidSolutionConfiguration(MergeConfiguration, SolidSolutionConfigurationSchema):
+    """Configuration for building a solid solution by merging substitution sites.
+
+    Physical specification: crystal, source_element, target_element, concentrations.
+    The merge_components hold the resolved substitution sites.
+    """
+
+    type: str = "SolidSolutionConfiguration"
+    crystal: Union[Material, MaterialWithBuildMetadata]
+    source_element: str
+    target_element: str
+    target_concentration: float
+    actual_concentration: float
+    merge_components: List[Union[Material, MaterialWithBuildMetadata, PointDefectSiteConfiguration]]
+    merge_method: MergeMethodsEnum = MergeMethodsEnum.REPLACE

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/solid_solution/enums.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class SiteSelectionMethodEnum(str, Enum):
+    # Selects sites purely at random (seeded for reproducibility).
+    RANDOM = "random"
+    # Selects sites using Farthest Point Sampling for maximal dispersion under PBC.
+    UNIFORM = "uniform"

package/src/py/mat3ra/made/tools/build/defective_structures/three_dimensional/solid_solution/helpers.py

@@ -0,0 +1,76 @@
+from typing import Optional, Union
+
+from mat3ra.esse.models.materials_category_components.entities.core.zero_dimensional.atom import AtomSchema
+from mat3ra.esse.models.materials_category_components.operations.core.combinations.merge import MergeMethodsEnum
+from mat3ra.made.material import Material
+
+from .....analyze.solid_solution_analyzer import SolidSolutionAnalyzer
+from .....build_components import MaterialWithBuildMetadata
+from .....build_components.entities.auxiliary.zero_dimensional.point_defect_site.configuration import (
+    PointDefectSiteConfiguration,
+)
+from .....build_components.entities.reusable.three_dimensional.supercell.helpers import create_supercell
+from .builder import SolidSolutionBuilder
+from .configuration import SolidSolutionConfiguration
+from .enums import SiteSelectionMethodEnum
+
+
+def create_solid_solution(
+    material: Union[Material, MaterialWithBuildMetadata],
+    source_element: str,
+    target_element: str,
+    concentration: float,
+    seed: Optional[int] = None,
+    tolerance: float = 0.01,
+    max_supercell_cells: int = 128,
+    site_selection_method: SiteSelectionMethodEnum = SiteSelectionMethodEnum.UNIFORM,
+) -> MaterialWithBuildMetadata:
+    """
+    Create a solid solution by partially substituting one element for another.
+
+    Automatically determines the optimal supercell size to achieve the target
+    concentration, builds the supercell, and performs substitution.
+
+    Args:
+        material (Union[Material, MaterialWithBuildMetadata]): Unit cell crystal.
+        source_element (str): Element to partially replace (e.g. "Hf").
+        target_element (str): Replacement element (e.g. "Zr").
+        concentration (float): Fraction of source_element to replace (0.0-1.0).
+        seed (Optional[int]): Random seed for reproducible site selection.
+        tolerance (float): Acceptable deviation from target concentration.
+        max_supercell_cells (int): Maximum supercell size to search.
+        site_selection_method (SiteSelectionMethodEnum): RANDOM or UNIFORM (Farthest Point Sampling).
+
+    Returns:
+        MaterialWithBuildMetadata: Solid solution with full build metadata.
+    """
+    analyzer = SolidSolutionAnalyzer(
+        material=material,
+        source_element=source_element,
+        target_element=target_element,
+        target_concentration=concentration,
+        tolerance=tolerance,
+        max_supercell_cells=max_supercell_cells,
+        seed=seed,
+        site_selection_method=site_selection_method,
+    )
+    supercell = create_supercell(material, scaling_factor=analyzer.optimal_supercell_dimensions)
+    coordinates = supercell.basis.coordinates.values
+    site_configurations = [
+        PointDefectSiteConfiguration(
+            crystal=supercell,
+            coordinate=coordinates[site_index],
+            element=AtomSchema(chemical_element=target_element),
+        )
+        for site_index in analyzer.selected_site_indices
+    ]
+    configuration = SolidSolutionConfiguration(
+        crystal=material,
+        source_element=source_element,
+        target_element=target_element,
+        target_concentration=concentration,
+        actual_concentration=analyzer.actual_concentration,
+        merge_components=[supercell] + site_configurations,
+        merge_method=MergeMethodsEnum.REPLACE,
+    )
+    return SolidSolutionBuilder().get_material(configuration)

package/src/py/mat3ra/made/tools/build_components/entities/auxiliary/zero_dimensional/crystal_site/crystal_site.py

@@ -6,13 +6,14 @@ from mat3ra.esse.models.materials_category_components.entities.auxiliary.zero_di
     CrystalSiteSchema,
 )
 from mat3ra.made.material import Material
+from pydantic import Field
 
 
 class CrystalSite(CrystalSiteSchema, InMemoryEntityPydantic):
-    crystal: Optional[Material] = None
+    crystal: Optional[Material] = Field(None, exclude=True)
     # element: str
     coordinate: Optional[List[float]] = None
-    nearest_neighbor_vectors: List[np.ndarray] = []
+    nearest_neighbor_vectors: List[np.ndarray] = Field([], exclude=True)
     # coordination_number: int = 0
     # see https://www.cryst.ehu.es/cgi-bin/cryst/programs/nph-wp-list for an example
 

package/src/py/mat3ra/made/tools/build_components/entities/auxiliary/zero_dimensional/point_defect_site/builder.py

@@ -1,3 +1,6 @@
+from mat3ra.code.array_with_ids import ArrayWithIds
+from mat3ra.made.basis import Basis, Coordinates
+
 from ......build_components import MaterialWithBuildMetadata
 from ..... import BaseSingleBuilder
 from .configuration import PointDefectSiteConfiguration
@@ -14,18 +17,16 @@ class PointDefectSiteBuilder(BaseSingleBuilder):
         if configuration.crystal is None:
             raise ValueError("Crystal configuration is required for PointDefectSiteBuilder")
 
-        new_material = MaterialWithBuildMetadata.create(
-            {
-                "name": configuration.crystal.name,
-                "lattice": configuration.crystal.lattice.to_dict(),
-                "basis": configuration.crystal.basis.to_dict(),
-            }
+        crystal = configuration.crystal
+        basis = Basis(
+            elements=ArrayWithIds(values=[], ids=[]),
+            coordinates=Coordinates(values=[], ids=[]),
+            units=crystal.basis.units,
+            cell=crystal.basis.cell,
         )
-        elements = configuration.crystal.basis.elements.values
-        new_material.basis.remove_atoms_by_elements(elements)
-        new_material.basis.add_atom(
+        basis.add_atom(
             element=configuration.element.chemical_element,
             coordinate=configuration.coordinate,
             label=configuration.host_atom_label,
         )
-        return new_material
+        return MaterialWithBuildMetadata(name=crystal.name, lattice=crystal.lattice, basis=basis)

package/src/py/mat3ra/made/tools/build_components/metadata/material_build_metadata.py

@@ -10,6 +10,11 @@ class MaterialBuildMetadata(BaseMetadata):
     # Other metadata fields can be added as needed
     build: List[BuildMetadata] = Field([])
 
+    def get_latest_build_metadata(self) -> BuildMetadata:
+        if not self.build:
+            raise ValueError("No metadata.build on the material.")
+        return self.build[-1]
+
     def get_build_metadata_of_type(self, configuration_type: str) -> Optional[BuildMetadata]:
         """
         Returns the first build configuration of the specified type.

package/src/py/mat3ra/made/tools/build_components/operations/core/combinations/merge/builder.py

@@ -79,6 +79,15 @@ class MergeBuilder(BaseSingleBuilder):
         if len(materials) == 1:
             return materials[0]
 
+        # Optimization: when there are many materials to merge, combine all non-first
+        # materials into one before merging with the base to avoid N sequential merges.
+        if len(materials) > 2:
+            base = materials[0]
+            combined = materials[1]
+            for m in materials[2:]:
+                combined.basis.add_atoms_from_another_basis(m.basis)
+            materials = [base, combined]
+
         parameters = self.build_parameters or self._DefaultBuildParameters
         merge_method = getattr(configuration, "merge_method", None)
         return self._merge_by_method(materials, parameters, merge_method)

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

@@ -2,8 +2,9 @@ from typing import Optional
 
 from ...material import Material
 from ..analyze.other import get_surface_area
-from ..build.compound_pristine_structures.two_dimensional.interface import InterfaceConfiguration, get_slab
-from ..build_components import MaterialBuildMetadata, MaterialWithBuildMetadata
+from ..analyze.interface_material import get_interface_bulk_crystal
+from ..build.compound_pristine_structures.two_dimensional.interface import get_slab
+from ..build_components.metadata import MaterialWithBuildMetadata
 from ..convert import decorator_convert_material_args_kwargs_to_atoms
 from ..third_party import ASEAtoms, ASECalculator, ASECalculatorEMT
 from .calculators import InterfaceMaterialCalculatorParameters
@@ -114,19 +115,14 @@ def calculate_interfacial_energy(
     substrate_slab = get_slab(interface, part="substrate") if substrate_slab is None else substrate_slab
     film_slab = get_slab(interface, part="film") if film_slab is None else film_slab
 
-    metadata = (
-        interface.metadata
-        if isinstance(interface, MaterialWithBuildMetadata)
-        else MaterialBuildMetadata(**interface.metadata)
-    )
-    build_configuration = metadata.build[-1].configuration if metadata.build else {}
-    config = InterfaceConfiguration(**build_configuration)
-
     try:
-        substrate_bulk = config.substrate_configuration.atomic_layers.crystal
-        film_bulk = config.film_configuration.atomic_layers.crystal
-    except KeyError:
-        raise ValueError("The substrate and film bulk materials must be provided or defined in the interface metadata.")
+        interface_with_metadata = MaterialWithBuildMetadata.create(interface.to_dict())
+        substrate_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="substrate"))
+        film_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="film"))
+    except ValueError as exc:
+        raise ValueError(
+            "The substrate and film bulk materials must be provided or defined in the interface metadata."
+        ) from exc
     surface_energy_substrate = calculate_surface_energy(substrate_slab, substrate_bulk, calculator)
     surface_energy_film = calculate_surface_energy(film_slab, film_bulk, calculator)
     adhesion_energy = calculate_adhesion_energy(interface, substrate_slab, film_slab, calculator)

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

@@ -42,6 +42,7 @@ from .build.defective_structures.zero_dimensional.point_defect.substitutional.he
 )
 from .build.defective_structures.zero_dimensional.point_defect.types import PointDefectDict
 from .build.defective_structures.zero_dimensional.point_defect.vacancy.helpers import create_defect_point_vacancy
+from .build.defective_structures.three_dimensional.solid_solution.helpers import create_solid_solution
 
 # Pristine Structures
 from .build.pristine_structures.three_dimensional.ideal_crystal.helpers import create_monolayer
@@ -117,6 +118,7 @@ __all__ = [
     "create_defect_point_substitution",
     "create_defect_point_interstitial",
     "create_multiple_defects",
+    "create_solid_solution",
     # Surface Defect Functions
     "create_defect_adatom",
     "create_multiple_adatom_defects",

package/tests/py/unit/test_primitive_cell.py

@@ -3,7 +3,7 @@ import pytest
 
 from mat3ra.made.cell.primitive_cell import get_primitive_lattice_vectors_from_config
 from mat3ra.made.lattice import Lattice, LatticeTypeEnum
-from tests.py.unit.utils import assert_two_entities_deep_almost_equal
+from unit.utils import assert_two_entities_deep_almost_equal
 
 EXPECTED_PRIMITIVE_CELL_NA4CL4 = [
     [5.691694, 0.0, 0.0],

package/tests/py/unit/test_tools_analyze_interface_material.py

@@ -0,0 +1,63 @@
+from typing import Final, Type
+
+import pytest
+from mat3ra.made.tools.analyze.build_metadata_analyzer import BuildMetadataAnalyzer
+from mat3ra.made.tools.analyze.build_metadata_analyzer_factory import create_build_metadata_analyzer
+from mat3ra.made.tools.analyze.interface_material import (
+    InterfaceMaterialAnalyzer,
+    get_interface_bulk_crystal,
+    get_interface_configuration,
+)
+from mat3ra.made.tools.analyze.slab import SlabMaterialAnalyzer
+from mat3ra.made.tools.build import MaterialWithBuildMetadata
+from mat3ra.made.tools.build.compound_pristine_structures.two_dimensional.interface import InterfaceConfiguration
+from unit.fixtures.interface.zsl import GRAPHENE_NICKEL_INTERFACE
+from unit.fixtures.slab import SI_CONVENTIONAL_SLAB_001
+
+INTERFACE_MATERIAL: Final = MaterialWithBuildMetadata.create(GRAPHENE_NICKEL_INTERFACE)
+SLAB_MATERIAL: Final = MaterialWithBuildMetadata.create(SI_CONVENTIONAL_SLAB_001)
+SUBSTRATE_CRYSTAL_NAME: Final = "Ni, Nickel, FCC (Fm-3m) 3D (Bulk), mp-23"
+FILM_CRYSTAL_NAME: Final = "Graphene"
+
+GET_BULK_CRYSTAL_CASES = [
+    ("substrate", SUBSTRATE_CRYSTAL_NAME),
+    ("film", FILM_CRYSTAL_NAME),
+]
+
+CREATE_BUILD_METADATA_ANALYZER_CASES = [
+    (INTERFACE_MATERIAL, InterfaceMaterialAnalyzer),
+    (SLAB_MATERIAL, SlabMaterialAnalyzer),
+]
+
+
+def test_build_configuration():
+    configuration = InterfaceMaterialAnalyzer(material=INTERFACE_MATERIAL).build_configuration
+    assert isinstance(configuration, InterfaceConfiguration)
+    assert configuration.type == "InterfaceConfiguration"
+
+
+@pytest.mark.parametrize("part,expected_name", GET_BULK_CRYSTAL_CASES)
+def test_get_bulk_crystal(part, expected_name):
+    crystal = InterfaceMaterialAnalyzer(material=INTERFACE_MATERIAL).get_bulk_crystal(part=part)
+    assert crystal["name"] == expected_name
+
+
+def test_get_interface_configuration():
+    configuration = get_interface_configuration(INTERFACE_MATERIAL)
+    assert isinstance(configuration, InterfaceConfiguration)
+    assert configuration.type == "InterfaceConfiguration"
+
+
+@pytest.mark.parametrize("part,expected_name", GET_BULK_CRYSTAL_CASES)
+def test_get_interface_bulk_crystal(part, expected_name):
+    crystal = get_interface_bulk_crystal(INTERFACE_MATERIAL, part=part)
+    assert crystal["name"] == expected_name
+
+
+@pytest.mark.parametrize("material,expected_analyzer_cls", CREATE_BUILD_METADATA_ANALYZER_CASES)
+def test_create_build_metadata_analyzer(
+    material: MaterialWithBuildMetadata,
+    expected_analyzer_cls: Type[BuildMetadataAnalyzer],
+):
+    analyzer = create_build_metadata_analyzer(material)
+    assert isinstance(analyzer, expected_analyzer_cls)

package/tests/py/unit/test_tools_build_defect/test_solid_solution.py

@@ -0,0 +1,90 @@
+import numpy as np
+import pytest
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build.defective_structures.three_dimensional.solid_solution.helpers import (
+    create_solid_solution,
+)
+from mat3ra.standata.materials import Materials
+
+BULK_HfO2 = Materials.get_by_name_first_match("HfO2")
+
+
+def _min_nearest_neighbor_distance(material, element):
+    material.to_crystal()
+    coords = np.array(material.basis.coordinates.values)
+    lv = np.array(material.lattice.vector_arrays)
+    idx = [i for i, e in enumerate(material.basis.elements.values) if e == element]
+    sub = coords[idx]
+    min_d = np.inf
+    for i in range(len(sub)):
+        for j in range(i + 1, len(sub)):
+            delta = sub[i] - sub[j]
+            delta -= np.round(delta)
+            min_d = min(min_d, np.linalg.norm(delta @ lv))
+    return min_d
+
+
+def test_create_solid_solution_uniform_element_counts():
+    material = Material.create(BULK_HfO2)
+    result = create_solid_solution(material, "Hf", "Zr", 0.5, seed=42, site_selection_method="uniform")
+    elements = result.basis.elements.values
+    assert elements == ["Hf", "Hf", "O", "O", "O", "O", "O", "O", "O", "O", "Zr", "Zr"]
+
+
+@pytest.mark.parametrize(
+    "concentration, expected_zr, expected_hf",
+    [
+        (0.0, 0, 4),
+        (0.25, 1, 3),
+        (0.5, 2, 2),
+        (1.0, 4, 0),
+    ],
+)
+def test_create_solid_solution_concentration(concentration, expected_zr, expected_hf):
+    material = Material.create(BULK_HfO2)
+    result = create_solid_solution(material, "Hf", "Zr", concentration, seed=42, site_selection_method="uniform")
+    elements = result.basis.elements.values
+    assert elements.count("Zr") == expected_zr
+    assert elements.count("Hf") == expected_hf
+
+
+@pytest.mark.parametrize(
+    "concentration, expected_min_distance",
+    [
+        (0.1, 4.5),
+        (0.2, 3.5),
+        (0.33, 3.4),
+    ],
+)
+def test_create_solid_solution_uniform(concentration, expected_min_distance):
+    material = Material.create(BULK_HfO2)
+    result = create_solid_solution(
+        material,
+        "Hf",
+        "Zr",
+        concentration,
+        seed=42,
+        site_selection_method="uniform",
+        tolerance=0.001,
+    )
+    assert _min_nearest_neighbor_distance(result, "Zr") > expected_min_distance
+
+
+def test_create_solid_solution_records_target_and_actual_concentration():
+    material = Material.create(BULK_HfO2)
+    target_concentration = 0.37
+    result = create_solid_solution(
+        material,
+        "Hf",
+        "Zr",
+        target_concentration,
+        seed=42,
+        tolerance=0.01,
+        site_selection_method="uniform",
+    )
+    build_step = result.metadata.get_build_metadata_of_type("SolidSolutionConfiguration")
+    assert build_step is not None
+    configuration = build_step.configuration
+    assert configuration["target_concentration"] == target_concentration
+    assert configuration["actual_concentration"] == pytest.approx(0.375)
+    assert configuration["target_concentration"] != configuration["actual_concentration"]

package/tests/py/unit/test_tools_build_metadata.py

@@ -28,6 +28,16 @@ def test_metadata_empty_initialization():
     assert metadata.model_dump(exclude_none=True) == {"build": []}
 
 
+def test_get_latest_build_metadata():
+    metadata = MaterialBuildMetadata(build=[BuildMetadata(configuration={"type": "SlabConfiguration"})])
+    assert metadata.get_latest_build_metadata().configuration["type"] == "SlabConfiguration"
+
+
+def test_get_latest_build_metadata_raises_when_empty():
+    with pytest.raises(ValueError, match="No metadata.build"):
+        MaterialBuildMetadata().get_latest_build_metadata()
+
+
 @pytest.mark.parametrize(
     "config_object, expected_dict",
     [