Cells

mcpy.cell defines the insertion region and estimates its free volume. Conceptual background, including the free-volume estimator and species_radii calibration, is in Cells and Calibrating species_radii.

Every non-trivial cell exposes calculate_volume(atoms) (refresh the cached free volume), get_volume(), get_random_point(), and get_atoms_specie_inside_cell(atoms, species).

BaseCell

BaseCell()

Abstract interface. Declares calculate_volume, get_random_point, and get_volume. Not instantiated directly.

Cell

Cell(atoms, species_radii=None, seed=None)

The full ASE simulation box as the active region. Random points are sampled uniformly in fractional coordinates. Its volume is the fixed box volume, so calculate_volume does no free-volume sampling.

  • species_radii (dict, optional): per-element exclusion radii.

  • seed (int, optional): cell-local RNG seed.

CustomCell

CustomCell(atoms, custom_height=None, bottom_z=None, species_radii=None,
           mc_sample_points=100_000, seed=None)

A rectangular sub-slab spanning the full x and y extent with finite thickness along z. Standard choice for surface slabs.

  • custom_height (float): thickness along z. Must not exceed the box height.

  • bottom_z (float): z of the lower face.

  • species_radii (dict): per-element exclusion radii.

  • mc_sample_points (int): random points for the free-volume estimate.

SphericalCell

SphericalCell(atoms, vacuum, species_radii, mc_sample_points=100_000,
              seed=None)

A sphere around an isolated cluster. On construction it translates the atoms so their center of mass sits at the origin, then sets the radius to the outermost atom distance plus vacuum.

  • vacuum (float): padding added to the bounding radius.

  • species_radii (dict): per-element exclusion radii.

  • mc_sample_points (int): random points for the free-volume estimate.

DomeCell

DomeCell(atoms, particle_species, bottom_z, vacuum, species_radii,
         mc_sample_points=100_000, seed=None)

A hemispherical region for a supported nanoparticle. Centers on the particle_species centroid and clips the ball at the support surface (z >= bottom_z). Unlike SphericalCell it does not translate the atoms.

  • particle_species (str | list[str]): symbol(s) identifying the particle. Raises ValueError if none are present.

  • bottom_z (float): z of the support surface.

  • vacuum (float): padding added to the particle bounding radius.

  • species_radii (dict): per-element exclusion radii.

  • mc_sample_points (int): random points for the free-volume estimate.

NullCell

NullCell()

A no-op cell. get_volume() returns 0 and it provides no insertion points. Use it as a placeholder where the API needs a cell but no insertion region exists, such as a pure-displacement canonical run.