Multiple adsorbate placement

docs/User_Guide/Structure_Generation/adsorption.md

@@ -4,9 +4,11 @@ Tools within
 are geared towards generating structures with adsorbates placed on
 a candidate catalyst surface.
 
+## Placing a single adsorbate
+
 The core function of this module is
 [`generate_adsorbed_structures`](../../API/Structure_Generation/adsorption.md#autocat.adsorption.generate_adsorbed_structures)
- for generating multiple adsorbed structures with a single function call.
+ for generating multiple structures with one adsorbate placed via a single function call.
 
 For the oxygen reduction (ORR) and nitrogen reduction (NRR) reactions,
 AutoCat has default starting geometries for all of these intermediates
@@ -177,4 +179,138 @@ inputs. The example below illustrates this capability, where can be used to spec
 ...     adsorption_sites=sites,
 ...     write_to_disk=True,
 ... )
-```
+```
+
+## Placing multiple adsorbates
+
+If we want to place multiple adsorbates (e.g. to explicitly model 
+high adsorbate coverage on a surface), the core function is 
+[`generate_high_coverage_adsorbed_structures`](../../API/Structure_Generation/adsorption.md#autocat.adsorption.generate_high_coverage_adsorbed_structures)
+
+This function behaves similarly as in the single adsorbate case, but with the
+key difference that adsorbate coverage must now also be specified. This can
+be given as either an integer maximum number of the adsorbate type to be placed,
+or as a fraction of all sites to be considered. If there should not be a 
+limit on the number of adsorbates to be placed, use `np.inf`.
+
+
+In the below example, hydrogens are placed at all identified hollow sites.
+
+```py
+>>> import numpy as np
+>>> from autocat.surface import generate_surface_structures
+>>> from autocat.adsorption import generate_high_coverage_adsorbed_structures
+>>> surface_dict = generate_surface_structures(
+...     species_list=["Pt"], 
+...     facets={"Pt": ["111"]}, 
+...     n_fixed_layers=2,
+...     supercell_dim=(2,2,3)
+... )
+>>> surface = surface_dict["Pt"]["fcc111"]["structure"]
+>>> multi_ads_dict = generate_high_coverage_adsorbed_structures(
+...     surface=surface,
+...     adsorbates=["H"],
+...     adsorbate_coverage={"H": np.inf},
+...     use_all_sites=True,
+...     site_types="hollow"
+... )
+```
+
+In the case where you don't want all of the sites covered, you can use
+"X" as a dummy species for adsorbate site vacancies. In the below example
+it will cover **up to** half of the top sites with `H`.
+
+```py
+>>> import numpy as np
+>>> from autocat.surface import generate_surface_structures
+>>> from autocat.adsorption import generate_high_coverage_adsorbed_structures
+>>> surface_dict = generate_surface_structures(
+...     species_list=["Pt"], 
+...     facets={"Pt": ["111"]}, 
+...     n_fixed_layers=2,
+...     supercell_dim=(2,2,3)
+... )
+>>> surface = surface_dict["Pt"]["fcc111"]["structure"]
+>>> multi_ads_dict = generate_high_coverage_adsorbed_structures(
+...     surface=surface,
+...     adsorbates=["H", "X"],
+...     adsorbate_coverage={"H": 0.5, "X": np.inf},
+...     use_all_sites=True,
+...     site_types="ontop"
+... )
+```
+
+To cover **exactly** half of the sites, instead we can set
+`adsorbate_coverate={"H": 0.5, "X": 0.5}` for example.
+
+If we want to specify the allowed sites for all adsorbates, manually,
+we can supply `adsorption_sites` as a `list` of these sites. For example:
+
+```py
+>>> import numpy as np
+>>> from autocat.surface import generate_surface_structures
+>>> from autocat.adsorption import generate_high_coverage_adsorbed_structures
+>>> surface_dict = generate_surface_structures(
+...     species_list=["Pt"], 
+...     facets={"Pt": ["111"]}, 
+...     n_fixed_layers=2,
+...     supercell_dim=(2,2,3)
+... )
+>>> surface = surface_dict["Pt"]["fcc111"]["structure"]
+>>> multi_ads_dict = generate_high_coverage_adsorbed_structures(
+...     surface=surface,
+...     adsorbates=["H", "X"],
+...     adsorbate_coverage={"H": 3, "X": np.inf},
+...     use_all_sites=False,
+...     adsorption_sites=[(0.0, 0.0), (2.77, 0.0), (1.39, 2.4)]
+... )
+```
+
+We can also specify exactly which sites each adsorbate is allowed to
+occupy by giving `adsorption_sites` as a `dict`. For example, if we wanted 
+to restrict `H` to only be able to occupy `(0.0, 0.0)`, but allow 
+`OH` to occupy either `(0.0, 0.0)` or `(2.77, 0.0)`, we can do as follows:
+
+```py
+>>> import numpy as np
+>>> from autocat.surface import generate_surface_structures
+>>> from autocat.adsorption import generate_high_coverage_adsorbed_structures
+>>> surface_dict = generate_surface_structures(
+...     species_list=["Pt"], 
+...     facets={"Pt": ["111"]}, 
+...     n_fixed_layers=2,
+...     supercell_dim=(2,2,3)
+... )
+>>> surface = surface_dict["Pt"]["fcc111"]["structure"]
+>>> multi_ads_dict = generate_high_coverage_adsorbed_structures(
+...     surface=surface,
+...     adsorbates=["H", "OH"],
+...     adsorbate_coverage={"H": 1, "OH": 2},
+...     use_all_sites=False,
+...     adsorption_sites={"H": [(0.0, 0.0)], "OH":[(0.0, 0.0), (2.77, 0.0)]}
+... )
+```
+
+This function enumerates all unique structures given the coverage and site
+occupation constraints. A dictionary is returned keyed by `int`s for each
+resulting structure.
+
+When writing to disk, this same format is maintained with each combination
+subdirectory assigned an arbitrary `int`.
+
+```
+.
+├── multiple_adsorbates
+│   │   
+│   ├── 0
+│   │   └── input.traj
+│   │   
+│   └── 1
+│   │   └── input.traj
+│   │   
+│   └── 2
+│       └── input.traj
+```
+
+**N.B.**: Depending on your surface and coverage constraints, the number
+of unique combinations can explode to a very large number of systems!