@mat3ra/made 2026.7.8-0 → 2026.7.13-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2026.7.8-0",
+    "version": "2026.7.13-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/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/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/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/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_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"]