Surface workflows

Slab configuration, deposition, and validation for supported-cluster runs.

Deposition and adsorbate initialization

create_deposited_cluster() builds initial structures for surface_cluster and surface_cluster_adsorbate:

• Plain cluster — gas-phase seed via scgo.initialization (init_mode on SurfaceSystemConfig), then rotate/translate above the slab with covalent-radius connectivity height heuristics.

• Cluster + adsorbate — hierarchical core + fragment placement (hull sites, ranked steric candidates), then deposit with surface-biased rotation.

• Adsorbate-only mobile region (empty core_symbols) — fragments placed directly on slab top-layer hull sites via place_fragment_on_cluster().

class scgo.surface.config.SurfaceSystemConfig(slab, adsorption_height_min=1.2, adsorption_height_max=3.0, surface_normal_axis=2, fix_all_slab_atoms=True, n_fix_bottom_slab_layers=None, n_relax_top_slab_layers=None, comparator_use_mic=False, cluster_init_vacuum=8.0, init_mode='smart', max_placement_attempts=200, structure_connectivity_factor=1.4)

Bases: object

Describe a fixed slab plus a movable adsorbate cluster for GA.

Atom ordering in combined systems must be slab atoms first, then the len(composition) adsorbate atoms (matching ASE GA patches: n_top trailing atoms are optimized). Pass the same instance to TS search (get_ts_search_params(..., surface_config=...) or run_ts_search(..., ts_params=..., system_type=..., surface_config=...)) so NEB uses the identical slab FixAtoms policy as local relaxation. At runtime, scgo.surface.validation.validate_surface_config_slab_prefix() checks that combined systems still begin with slab’s symbols in order.

Slab motion during local relaxation (three common modes; L is the number of distinct slab coordinate layers along surface_normal_axis):

Intent	Settings
Full slab frozen	fix_all_slab_atoms=True (default)
Frozen except top N slab layers	fix_all_slab_atoms=False and either n_relax_top_slab_layers=N, or n_fix_bottom_slab_layers=L - N
Nothing on the slab frozen	fix_all_slab_atoms=False, n_fix_bottom_slab_layers=None, n_relax_top_slab_layers=None

For a typical slab with vacuum along z, the adsorbate sits on the high-z side; fixing the bottom L - N distinct layers is the same as leaving only the top N layers free to relax.

Do not set n_relax_top_slab_layers together with n_fix_bottom_slab_layers, or together with fix_all_slab_atoms=True.

slab: Atoms

adsorption_height_min: float = 1.2

adsorption_height_max: float = 3.0

surface_normal_axis: int = 2

fix_all_slab_atoms: bool = True

n_fix_bottom_slab_layers: int | None = None

n_relax_top_slab_layers: int | None = None

comparator_use_mic: bool = False

cluster_init_vacuum: float = 8.0

init_mode: str = 'smart'

max_placement_attempts: int = 200

structure_connectivity_factor: float = 1.4

scgo.surface.make_surface_config(slab, *, adsorption_height_min=2.0, adsorption_height_max=3.5, fix_all_slab_atoms=True, comparator_use_mic=True, max_placement_attempts=500)

Build a SurfaceSystemConfig from an arbitrary ASE slab.

Return type:

SurfaceSystemConfig

scgo.surface.make_graphite_surface_config(*, slab_layers=5, slab_repeat_xy=4, vacuum=12.0, structure_connectivity_factor=1.4)

Graphite slab preset (top layer relaxes with adsorbate during GO/NEB).

Return type:

SurfaceSystemConfig

scgo.surface.describe_surface_config(cfg)

Summarize key surface/deposition fields for logging and provenance.

Return type:

str

Composition builders for campaigns live in scgo.runner_api (build_one_element_compositions, build_two_element_compositions); high-level runners are in API Reference.