Utilities

mcpy.utils holds the thermodynamic constants, the seeded RNG, logging setup, and phase-diagram post-processing.

SetUnits

SetUnits(unit_type, temperature, species)

Computes the constants the GCMC acceptance rules need. Built automatically by GrandCanonicalEnsemble from its units_type, temperature, and species. Conceptual background is in Ensembles (section “Setting a unit system”).

  • unit_type (str): 'metal' or 'LJ'. Any other value raises ValueError.

  • temperature (float): temperature in K.

  • species (list[str]): symbols to precompute masses and wavelengths for.

Attributes: beta, lambda_dbs (per-species thermal de Broglie wavelength), masses, BOLTZMANN_CONSTANT, PLANCK_CONSTANT.

Methods:

  • de_broglie_insertion(volume, n_atoms, specie): the insertion prefactor V / ((n_atoms + 1) Λ³). Raises ValueError if n_atoms < 0.

  • de_broglie_deletion(volume, n_atoms, specie): the deletion prefactor n_atoms Λ³ / V.

RandomNumberGenerator

RandomNumberGenerator(seed=None, warm_up=0)

Seeded wrapper over Python’s random.Random. Each move and the acceptance test carries its own instance, so the global random state is never touched.

  • seed (int, optional): seed for reproducibility.

  • warm_up (int): discarded draws after seeding. The default 0 is sufficient for the Mersenne Twister.

Methods: get_uniform(a=0.0, b=1.0), get_gaussian(mu=0.0, sigma=1.0).

configure

configure(level=logging.INFO, file=None, mpi_rank=None, stream=True)

Attaches handlers to the top-level mcpy logger. Importing mcpy attaches no handlers and mutates no global state; call this once at startup to opt in to log output. Importable from mcpy.utils.logging.

  • level (int): log level for the mcpy logger.

  • file (str, optional): log file path. Pass f"mcpy_rank_{rank}.log" for per-rank files.

  • mpi_rank (int, optional): included in the format string when set.

  • stream (bool): also emit to stderr.

Returns the configured mcpy logger. Re-calling is idempotent: it drops the handlers it previously attached.

plot_phase_diagram

plot_phase_diagram(frames, adsorbate='H', metal_symbols=('Pd', 'Ag'),
                   mu_ref=-3.05, kind='surface', T=300.0,
                   dmu_range=(-1.0, 0.0), n_bins=400, ...)

Builds a grand-canonical adsorbate phase diagram for one system configuration from a list of relaxed frames (or a list of trajectories). The lowest-energy adsorbate-free frame is the reference. Returns a dict of arrays and metadata and optionally saves the figure. A worked example is in Phase diagram analysis from relaxed trajectories.

Key parameters:

  • frames (list[ase.Atoms] | list[list]): frames for one configuration.

  • adsorbate (str): species whose count sets the stoichiometry.

  • kind (str): 'surface' normalizes by cell area (meV/Ų); 'nano' by metal-atom count (meV/atom). Any other value raises ValueError.

  • mu_ref (float): reference chemical potential of the adsorbate in eV.

  • adsorbate_count_fn (callable, optional): custom atoms -> int count for adsorbates that also occur in an inert sublattice.

See the function docstring for the full plotting and normalization parameters.

analyze_phase_diagram_results

analyze_phase_diagram_results(trajectory_path='relaxed_structures.xyz',
                              host_symbol='Ag', oxygen_symbol='O',
                              idx_ref=2400, ...)

Reads a relaxed-structure trajectory from disk and builds a surface oxidation phase diagram against the oxygen chemical potential, returning a dict of arrays and metadata. The module is also runnable as a script through main(). See the function docstring for the full set of thermodynamic-reference parameters.

compute_radii

scripts/compute_radii.py is a calibration script, not a library API. It automates the species_radii workflow for FCC(111) hosts. Configuration and usage are documented in Calibrating species_radii.