SCGO Documentation

SCGO finds low-energy atomic structures with global optimization. It uses Basin Hopping, Genetic Algorithms, NEB transition-state search, and machine learning potentials (MACE, UMA, UPET) through ASE and TorchSim.

What SCGO works with

Three building blocks cover every workflow:

• Cluster (also called the core when molecules are present): the metal nanoparticle whose shape you are searching.

• Adsorbate: a small molecule or fragment (for example OH or CO) attached to the cluster or the surface.

• Slab: a periodic surface the cluster or adsorbate sits on. You can also search the top layers of the slab itself, with the bottom layers held still.

The six system types combine these pieces (see Quick Start for the full table): gas_cluster, surface_cluster, gas_cluster_adsorbate, surface_cluster_adsorbate, bare-slab surface, and surface_adsorbate.

See Quick Start to get started.

Contents

Getting Started

• Installation
  • Prerequisites
  • PyPI
  • From source
  • Parallel jobs and HPC
• Quick Start
  • System Types
  • Gas Cluster
  • On a Surface
  • With Adsorbates
  • Surface + Adsorbates
  • Slab as search target
  • Transition States
  • Campaigns
  • Output
  • Parameters
  • Examples
• Surface slabs for global optimization
  • Choosing a substrate
  • Pristine slabs (no defects)
  • Defective slabs
  • Defect-biased nanoparticle placement
  • Using a slab as the GO target
  • Tuning deposition
  • Low-level builders
• Uniqueness (de-duplication)
  • What is compared
  • When it runs
  • How to change it
  • Transition states
• Validation and Constraints
  • What constraints and validation do
  • What counts as connected
  • Outcome toggles
  • How validation runs during global optimization
  • Minima pair selection
  • Surface NEB path preparation
  • NEB pre-screen gates
  • Constraint model
  • Tunables and floors
  • MIC semantics
• Output Layout
  • Path Keys
  • Output directories
  • On-disk layout
  • Reading Results
• All Parameters
  • Parameter resolution
  • GO Parameters
  • TS Parameters
  • Surface Config
  • Adsorbate Config
  • See Also
• Benchmarks
  • Dependencies
  • Output layout
  • Entry points
  • Pytest

API Reference

• API Reference
  • Main Functions
  • Output directories
  • Complete Examples
  • Utility Functions
  • Timing and Profiling
  • Module Reference
• Runner internals
  • CompositionInput
  • parse_composition_arg()
  • build_one_element_compositions()
  • build_two_element_compositions()
  • RunGOContext
  • RunGOCampaignContext
  • RunGOTSContext
  • RunTSContext
  • format_completion_details()
  • resolve_workflow_seed()
  • run_go_ts()
  • run_go_ts_campaign()
  • run_ts_search()
  • run_ts_campaign()
  • log_go_ts_summary()
  • run_transition_state_search()
  • run_transition_state_campaign()
  • ParallelNEBBatch
  • add_ts_to_database()
  • save_ts_network_metadata()
  • tag_unique_ts_in_databases()
• Top-level API
  • Surface and adsorption
  • Database
  • Surface configuration builders
  • Parameter resolution
  • Logging
  • GO + TS pipeline
  • Version
• Calculators
  • UMA
  • UPET
  • TorchSimBatchRelaxer
• Database access
  • DatabaseSetupError
  • get_global_cache()
  • close_data_connection()
  • get_connection()
  • setup_database()
  • extract_minima_from_database_file()
  • load_previous_run_results()
  • load_reference_structures()
  • list_discovered_db_paths_with_run()
  • clear_discovery_cache()
  • SCGODatabaseManager
  • database_transaction()
  • RetryConfig
  • database_retry()
  • retry_transaction()
  • DatabaseDiscovery
  • SCGODataConnection
  • setup_database()
  • extract_minima_from_database_file()
  • load_previous_run_results()
  • load_reference_structures()
  • database_transaction()
  • get_connection()
  • DatabaseRegistry
  • get_registry()
  • clear_registry()
  • UnifiedCache
  • get_global_cache()
  • reset_global_cache()
• Metadata
  • Structure tags (ASE Atoms)
  • Final-minima SQL tagging
  • Output-JSON provenance header
  • Run-directory records
  • SQLite DB stamp
• Exceptions
  • SCGOError
  • SCGOValidationError
  • SCGOConfigurationError
  • SCGORuntimeError
  • SCGODatabaseError
  • SCGONotImplementedError
  • SCGOFileError
• Cluster initialization
  • Initialization modes
  • Atom ordering (multi-element GA)
  • Placement order and diversity
  • Reproducibility
  • Connectivity and steric checks
  • Module reference
• Surface workflows
  • Deposition and adsorbate initialization
  • Slab search partitioning
  • Deposition
  • Presets
• Cluster adsorbate placement
  • Configuration
  • Surface site discovery
  • Placement and hierarchical builds
  • Pre-GO feasibility checks
  • GA repositioning and rigid geometry
  • Radii and steric scoring
  • Submodule reference
• Parameter Presets
  • Preset Functions
  • Parameter reference
  • Available Models
  • Usage Examples
  • Module Reference
• Validation and constraints API
  • validate_surface_config_slab_prefix()
  • validate_stored_slab_adsorbate_metadata()
  • validate_stored_mobile_partition_metadata()
  • layer_stacking_cutoff_from_template()
  • validate_supported_cluster_deposit()
  • attach_slab_constraints()
  • attach_slab_constraints_from_surface_config()
  • surface_slab_constraint_summary()
  • resolve_run_uniqueness_comparator()
  • slab_ga_metadata_extras()
  • adsorbate_partition_metadata()
  • ga_run_metadata_extras()
  • extract_constraint_index_lists()
  • reconstruct_constraints_from_index_lists()
  • validate_structure_for_ga_storage()
  • core_adsorbate_partition_counts()
  • core_adsorbate_partition_details()
  • resolve_neb_mobile_dims()
  • apply_mobile_core_ads_tags()
  • maybe_apply_mobile_core_ads_tags()
  • validate_ga_common_params()
  • ClusterStartGenerator
  • SurfaceClusterStartGenerator
  • SurfaceSlabStartGenerator
  • create_ga_pairing()
  • unmatched_operator_weight_keys()
  • create_mutation_operators()
  • reseed_mutation_operator_rngs()
  • update_mutation_weights()
  • create_structure_comparator()
  • update_early_stopping_state_unified()
  • setup_diversity_scorer()
  • select_population_class()
  • log_early_stopping_info()
  • sort_minima_by_fitness()
  • scgo()
  • run_trials()
  • neb_max_atom_force()
  • attach_singlepoint_from_relax_output()
  • calculate_structure_similarity()
  • TorchSimNEB
  • interpolate_path()
  • neb_uses_two_stage_climb()
  • validate_initial_neb_path()
  • validate_initial_neb_energy_profile()
  • evaluate_neb_image_energies()
  • evaluate_neb_image_energies_ase()
  • idpp_band_optimization_priority()
  • make_ts_result()
  • minima_provenance_dict()
  • attach_minima_traceability()
  • find_transition_state()
  • load_completed_neb_result()
  • save_neb_result()
  • half_inplane_cell_length()
  • unwrap_breaks_mic()
  • consistent_product_positions()
  • inplane_symmetry_matrices()
  • apply_inplane_symmetry()
  • symmetry_anchor_center()
  • symmetry_product_rejected()
  • ensure_symmetry_copy_energy()
  • variable_spring_constants()
  • refresh_surface_neb_springs()
  • bond_set()
  • classify_band()
  • displaced_mobile_images()
  • count_imaginary_frequencies()
  • mass_weighted_hessian_omega2()
  • finite_difference_hessian()
  • count_imaginary_modes_from_forces()
  • adsorbate_pair_select_cap()
  • resolve_ts_pair_select_cap()
  • load_minima_by_composition()
  • select_structure_pairs()
  • save_transition_state_results()
  • write_final_unique_ts()
  • pair_selection_param_defaults()
  • GA internals
• System Types Guide
  • Available system types
  • Surface mobile connectivity
  • Adsorbate subgraph integrity
  • Adsorbate placement tuning
  • Defaults you rarely change
• System Types Reference
  • AdsorbateDefinition
  • CalculatorKwargs
  • GLOptimizerParams
  • NormalizedConnectivityFactor
  • OptimizerSlotParams
  • SystemPolicy
  • as_adsorbate_definition()
  • build_adsorbate_definition_from_inputs()
  • extract_adsorbate_definition_from_params()
  • flatten_adsorbate_symbols()
  • get_system_policy()
  • normalize_adsorbates_input()
  • normalize_connectivity_factor()
  • resolve_adsorbate_fragments()
  • resolve_adsorbate_run_composition()
  • resolve_connectivity_factor()
  • resolve_mobile_composition()
  • resolve_neb_mic()
  • resolve_search_mobile_composition()
  • resolve_structure_mic()
  • select_scgo_minima_algorithm()
  • slab_is_search_target()
  • uses_surface()
  • validate_adsorbate_definition()
  • validate_composition_against_adsorbate()
  • validate_connectivity_policy()
  • validate_minimum_structure()
  • validate_mobile_symbols_match_adsorbate_definition()
  • validate_structure_for_system_type()
  • validate_system_type_settings()
  • Connectivity factor
• Utilities
  • Parameter resolution
  • Combine atoms
  • Logging
  • Phase logging
  • Timing JSON
  • Output path helpers
  • Path keys
  • Helpers
  • Comparators
  • Parallel workers
  • TS runner kwargs
  • Fitness strategies

Indices and tables

• Index

• Module Index

• Search Page