single atom alloy surface builder (#137)

* added functionality for building SAAs

* fixed var name typo in example

* fixed typo in description

* fixed typo in description

carmm/build/alloy.py

@@ -1,3 +1,5 @@
+from ase import Atoms
+
 def binary_alloy(model, second_element, n_second_element, random_level=1):
     '''
     Setup a random alloy
@@ -129,3 +131,33 @@ def ternary_alloy(model, second_element, third_element, n_second_element, n_thir
 
     return new_model
 
+
+def get_SAA_surfaces(surface_slab: Atoms, SAA_elements: list, substitution_indices: list, include_pristine: bool):
+    '''Generate a list of single atom alloy (SAA) surfaces as Atoms objects. SAA surfaces contain substitutions
+    as combinations of chemical symbols without replacement based on the list of chemical species listed in
+    SAA_elements
+
+    Args:
+        surface: Atoms object
+        substitution_indices: list of int
+        include_pristine: bool
+
+    Returns:
+        list of Atoms objects
+    '''
+    from itertools import combinations
+
+    element_combinations = [combo for combo in combinations(SAA_elements, len(substitution_indices))]
+    list_of_SAAs = [surface_slab.copy() for element_pair in range(len(element_combinations))]
+
+    for _, elements in enumerate(element_combinations):
+        symbols = list_of_SAAs[_].symbols
+        for __, sub_index in enumerate(substitution_indices):
+            symbols[sub_index] = elements[__]
+
+        list_of_SAAs[_].symbols = symbols
+
+    if include_pristine:
+        list_of_SAAs.append(surface_slab.copy())
+
+    return list_of_SAAs

examples/build_alloy.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 
 '''
-This example shows how to build an alloy surface, both binary and ternary
+This example shows how to build an alloy surface, both binary and ternary,
+and substituted single atom alloy surfaces.
 
 This is useful when wanting a randomly distributed set of elements through a model
 '''
@@ -28,4 +29,12 @@ def test_build_alloy():
     # assert(ternary_slab.get_chemical_symbols().count('Pd') == 4)
     assert(ternary_slab.get_chemical_symbols().count('Zn') == 5)
 
+    #### Single Atom Alloy surfaces test ####
+    from carmm.build.alloy import get_SAA_surfaces
+    SAA_elements = ['Ag', 'Au', 'Cu', 'Pd', 'Ni', 'Ti']
+    substitution_indices = [13, 16]
+    SAA_surfaces = get_SAA_surfaces(slab, SAA_elements, substitution_indices, include_pristine=True)
+
+    assert len(SAA_surfaces) == 16
+
 test_build_alloy()