matcalc._surface module

Surface Energy calculations.

class SurfaceCalc(calculator: Calculator | str, *, relax_bulk: bool = True, relax_slab: bool = True, fmax: float = 0.1, optimizer: str | Optimizer = 'BFGS', max_steps: int = 500, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

A class for performing surface energy calculations by generating and optionally relaxing bulk and slab structures. This facilitates materials science and computational chemistry workflows, enabling computations of surface properties for various crystal orientations and surface terminations.

Detailed description of the class, its purpose, and usage.

Variables:

  • calculator – ASE Calculator used for energy and force evaluations. Interface to computational backends like DFT or classical force fields.

  • relax_bulk – Indicates whether to relax the bulk structure, including its lattice parameters. Default is True.

  • relax_slab – Indicates whether to relax the slab structure, fixing its cell. Default is True.

  • fmax – Force tolerance (in eV/Å) used during relaxation, controlling convergence. Default is 0.1.

  • optimizer – Optimizer to be used for structure relaxation. Can be a string referring to the optimizer’s name (e.g., “BFGS”) or an instance of an optimizer class. Default is “BFGS”.

  • max_steps – Maximum allowed steps for optimization during relaxation. Default is 500.

  • relax_calc_kwargs – Additional parameters passed to the relaxation calculator for bulk and slab structures. Default is None.

  • final_bulk – Optimized bulk structure after relaxation. Initialized as None until relaxation is performed.

  • bulk_energy – Energy of the relaxed bulk structure. Initialized as None and updated after relaxation.

  • n_bulk_atoms – Number of atoms in the bulk structure. Set after the bulk relaxation step.

Constructor for initializing the SurfaceCalc with all parameters needed to generate and optionally relax bulk and slab structures.

Parameters:

  • calculator (Calculator | str) – An ASE calculator object used to perform energy and force calculations. If string is provided, the corresponding universal calculator is loaded.

  • relax_bulk (bool, optional) – Whether to relax the bulk structure, including its cell. Default is True.

  • relax_slab (bool, optional) – Whether to relax each slab structure (cell fixed). Default is True.

  • fmax (float, optional) – Force tolerance in eV/Å for relaxation. Default is 0.1.

  • optimizer (str | Optimizer, optional) – The ASE optimizer to use. Can be a string (e.g. “BFGS”) or an Optimizer instance. Default is “BFGS”.

  • max_steps (int, optional) – Maximum number of optimization steps for relaxation. Default is 500.

  • relax_calc_kwargs (dict | None, optional) – Additional keyword arguments passed to the RelaxCalc constructor for both bulk and slabs. Default is None.

_abc_impl = <_abc._abc_data object>[source]
calc(structure: Structure | dict[str, Any]) → dict[str, Any][source]

Performs surface energy calculation for a given structure dictionary. The function handles the relaxation of both bulk and slab structures when necessary and computes the surface energy using the slab’s relaxed energy, number of atoms, bulk energy per atom, and surface area.

Parameters:

structure (Structure | dict[str, Any]) – Dictionary containing information about the bulk and slab structures. It must have the format: {‘slab’: slab_structure, ‘bulk’: bulk_structure} or {‘slab’: slab_structure, ‘bulk_energy_per_atom’: energy}.

Returns:

A dictionary containing the updated structure data, including fields like ‘slab’, ‘final_slab’, ‘slab_energy’, ‘surface_energy’, and possibly updated ‘bulk_energy_per_atom’ and ‘final_bulk’.

Return type:

dict[str, Any]

calc_slabs(bulk: Structure, miller_index: tuple[int, int, int] = (1, 0, 0), min_slab_size: float = 10.0, min_vacuum_size: float = 20.0, symmetrize: bool = True, inplane_supercell: tuple[int, int] = (1, 1), slab_gen_kwargs: dict | None = None, get_slabs_kwargs: dict | None = None, **kwargs: dict[str, Any]) → list[dict[str, Any]][source]

Calculates slabs based on a given bulk structure and generates a set of slabs using specified parameters. The function leverages slab generation tools and defines the in-plane supercell, symmetry, and optimizes the bulk structure prior to slab generation. This is useful for surface calculations in materials science and computational chemistry.

Parameters:

  • bulk (Structure) – The bulk structure from which slabs are generated. Must be an instance of pymatgen’s Structure class.

  • miller_index (tuple[int, int, int]) – The Miller index used for generating the slabs. Defines the crystallographic orientation. Defaults to (1, 0, 0).

  • min_slab_size (float) – Minimum thickness of the slab in angstroms. Defines the slab’s physical size. Defaults to 10.0.

  • min_vacuum_size (float) – Minimum vacuum layer thickness in angstroms to ensure surface isolation. Defaults to 20.0.

  • symmetrize (bool) – A boolean indicating whether or not to symmetrize the slab structure based on the bulk symmetry. Defaults to True.

  • inplane_supercell (tuple[int, int]) – Tuple defining the scaling factors for creating the supercell in the plane of the slab. Defaults to (1, 1).

  • slab_gen_kwargs (dict | None) – Optional dictionary of additional arguments to customize the slab generation process.

  • get_slabs_kwargs (dict | None) – Optional dictionary of additional arguments passed to the get_slabs method for further customization.

  • kwargs (dict) – Additional keyword arguments passed through to calc_many method.

Returns:

A dictionary containing the generated slab information, including the slab structure, bulk energy per atom, optimized bulk structure, and Miller index.

Return type:

dict[str, Any]