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=<object object>, adsorption_height_max=<object object>, height_min=<object object>, height_max=<object object>, surface_normal_axis=2, fix_all_slab_atoms=True, n_fix_bottom_slab_layers=None, n_relax_top_slab_layers=None, comparator_use_mic=True, 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.

Height may be set via adsorption_height_* or alias height_*.

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

adsorption_height_max: float

surface_normal_axis: int

fix_all_slab_atoms: bool

n_fix_bottom_slab_layers: int | None

n_relax_top_slab_layers: int | None

comparator_use_mic: bool

cluster_init_vacuum: float

init_mode: str

max_placement_attempts: int

structure_connectivity_factor: float

property height_min: float

Alias for adsorption_height_min.

property height_max: float

Alias for adsorption_height_max.

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

scgo.surface.create_deposited_cluster(composition, slab, blmin, rng, config, previous_search_glob='**/*.db', adsorbate_definition=None, adsorbate_fragment_template=None, cluster_adsorbate_config=None, batch_site_counts=None)

One adsorbate+slab structure, or None if placement fails.

For non-adsorbate runs: build one gas-phase cluster for composition, then place above slab. For adsorbate runs: build hierarchical core+fragment first.

Return type:

Atoms | None

scgo.surface.create_deposited_cluster_batch(composition, slab, blmin, n_structures, rng, config, *, previous_search_glob='**/*.db', n_jobs=1, adsorbate_definition=None, adsorbate_fragment_template=None, cluster_adsorbate_config=None, batch_site_counts=None)

Generate multiple deposited structures (sequential or threaded).

Return type:

list[Atoms]

scgo.surface.adsorption_energy(e_adsorbate_slab, e_slab, e_isolated_cluster)

Classical adsorption energy: E(ads+slab) - E(slab) - E(cluster).

Negative values usually indicate binding.

Parameters:

• e_adsorbate_slab (float) – Total energy of the relaxed adsorbate+slab system.

• e_slab (float) – Total energy of the bare relaxed slab (same cell/supercell).

• e_isolated_cluster (float) – Total energy of the isolated cluster.

Return type:

float

Returns:

Adsorption energy in the same units as inputs (typically eV).

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