metropolis

Command-line usage

usage: cell metropolis [-h] [-task usage] [-plfp plat.json]
                       [-mofp model.pickle] [-sufp mc-setup.pickle]
                       [-mcrfp None] [-mcrfps None] [-scfp mc-scell.pickle]
                       [-trfp mc-trajectory.json] [-scsh 1] [-nsubs None]
                       [-ens canonical] [-sublat []] [-chem_pot None]
                       [-aux_models []] [-pred_swap True] [-reduce False]
                       [-n_steps None] [-n_clics 1] [-runs None] [-ef None]
                       [-temp None] [-k_B None] [-init_dec None]
                       [-acc_ratio None] [-rs None] [-fn None] [-resume None]
                       [-save_every 0] [-atoms metropolis.traj]
                       [-endpoints False] [-atoms_mode auto]
                       [-energy_key energy] [-sweeps None] [-batch 100000]
                       [-continue False] [-serialize True] [-metadata None]
                       [-start None]
                       [plotdata_filepath] [show_plot] [save_plot]
                       [keep_sigmas] [chemical_potential] [n_mc_eq]
                       [temperatures]

positional arguments:
  plotdata_filepath     [None]
  show_plot             [True]
  save_plot             [False]
  keep_sigmas           [1]
  chemical_potential    [0.0]
  n_mc_eq               [1]
  temperatures          [None]

options:
  -h, --help            show this help message and exit
  -task, --task usage   Task to perform.
  -plfp, --plat-filepath plat.json
                        Filepath of a serialized ParentLattice object.
  -mofp, --model-filepath model.pickle
                        Output Model file path.
  -sufp, --mcsetup-filepath mc-setup.pickle
                        MC setup file path.
  -mcrfp, --mcrun-filepath None
                        MC run file path.
  -mcrfps, --mcrun-filepaths None
                        MC run file path.
  -scfp, --mcscell-filepath mc-scell.pickle
                        MC scell file path.
  -trfp, --traj-filepath mc-trajectory.json
                        Filename for the output trajectory
  -scsh, --sc-shape 1   Supercell shape as a JSON integer, vector, or matrix.
  -nsubs, --n-substitutions None
                        Substitution counts as a JSON integer or dictionary
  -ens, --ensemble canonical
                        Thermodynamic ensemble
  -sublat, --sublattice-indices []
                        Sublattice indices as a JSON list
  -chem_pot, --chemical-potentials None
                        Chemical potentials for each sublattice
  -aux_models, --models-aux-filepaths []
                        Filepaths of auxiliary models to be used in sampling
  -pred_swap, --predict-swap True
                        Use predict_swap during energy prediction
  -reduce, --reduce-structure False
                        Use reduced structure, when supercell shape is
                        diagonal
  -n_steps, --n-mc-steps None
                        Number of metropolis steps to perform
  -n_clics, --n-clics 1
                        Number of clics (swaps in canonical, flips in grand-
                        canoncial)
  -runs, --runs None    Ordered temperature/length stages as a JSON list
  -ef, --energy-factor None
                        Required scalar multiplier: energy_factor * model
                        change must be TOTAL supercell energy in k_B*T units
  -temp, --temperature None
                        Required temperature in user-chosen units consistent
                        with k_B and the scaled supercell energy
  -k_B, --boltzmann-constant None
                        Required k_B in scaled energy per temperature unit; no
                        default units
  -init_dec, --initial-decoration None
                        Initial decoration of the supercell, list of integers
  -acc_ratio, --target-rate None
                        Real number between 0 and 1. Represents the rate of
                        accepted moves. If not ``None``, the initial
                        temperature will be adjusted to match the given
                        acceptance ratio. The acceptance ratio during the
                        simulation is computed using the last 1000 moves.
  -rs, --random-seed None
                        Random seed to produce reproducible results
  -fn, --filename None  Deprecated: use ``traf_filepath instead``
  -resume, --resume-from None
                        Resume the final complete XYZ frame with a new seeded
                        random stream
  -save_every, --save-atoms-every 0
                        Checkpoint interval in proposals; zero disables
                        periodic output
  -atoms, --atoms-filename metropolis.traj
                        XYZ/extxyz or ASE checkpoint output
  -endpoints, --save-atoms-endpoints False
                        Save initial configuration and each temperature
                        endpoint
  -atoms_mode, --atoms-mode auto
                        Checkpoint mode: x=new file, w=overwrite, a=append,
                        auto=legacy
  -energy_key, --energy-key energy
                        Energy property name for multi-output models
  -sweeps, --n-mc-sweeps None
                        Sweeps; one sweep is one proposal per substitutional
                        site
  -batch, --max-steps-per-batch 100000
                        Maximum temporary temperature array length
  -continue, --continue-chain False
                        Continue in memory; schedule stages always continue
  -serialize, --serialize True
                        Store accepted-move histories as JSON; use false for
                        large runs
  -metadata, --metadata None
                        Optional trajectory descriptions as a JSON dictionary
  -start, --start-from None
                        Initial XYZ source if output is absent; otherwise use
                        resume_from (default: output)

Arguments and behavior

clusterx.cli.metropolis.metropolis(task='usage', plat_filepath='plat.json', model_filepath='model.pickle', mcsetup_filepath='mc-setup.pickle', mcrun_filepath=None, mcrun_filepaths=None, plotdata_filepath=None, show_plot=True, save_plot=False, keep_sigmas=1, mcscell_filepath='mc-scell.pickle', traj_filepath='mc-trajectory.json', sc_shape=1, n_substitutions=None, ensemble='canonical', sublattice_indices=[], chemical_potential=0.0, chemical_potentials=None, models_aux_filepaths=[], predict_swap=True, reduce_structure=False, n_mc_steps=None, n_mc_eq=1, n_clics=1, runs=None, energy_factor=None, temperature=None, temperatures=None, boltzmann_constant=None, initial_decoration=None, target_rate=None, random_seed=None, filename=None, resume_from=None, save_atoms_every=0, atoms_filename='metropolis.traj', save_atoms_endpoints=False, atoms_mode='auto', energy_key='energy', n_mc_sweeps=None, max_steps_per_batch=100000, continue_chain=False, serialize=True, metadata=None, start_from=None)

Sample with an explicit TOTAL-supercell energy multiplier, k_B, and temperature.

Supply a linear CE energy model. The user is responsible for model normalization and units. For model energy eV/atom and T in K, use energy_factor=N_atoms and k_B in eV/K. For meV/atom and k_B in eV/K, use N_atoms/1000. A total-energy model still requires an explicit factor (1 when its energy unit matches k_B*T). CELL does not infer atom counts, unit conversions, or a default temperature/Boltzmann constant. Specify temperature directly or explicitly in every runs stage.

Notes

Checkpoint initialization for task=”runmc”

resume_from alone always loads that file’s final complete frame, even when atoms_filename does not exist. It never infers a temperature or run length. With start_from, the existence of atoms_filename selects the source, BEFORE opening or writing output:

  • Output absent: load the last complete frame of start_from.

  • Output present: load the last complete frame of resume_from.

When start_from is supplied, omitted resume_from defaults to atoms_filename. If resume_from names a different file, existence of atoms_filename still determines which source is selected. Missing, empty or incompatible selected checkpoints cause an error; they never silently fall back to the other file. The command prints the selected source and the output-existence decision. initial_decoration cannot be combined with either checkpoint option.

Loading restores cell/site/species/composition-compatible configurations. random_seed initializes a new random stream; checkpoint files do not restore the exact original proposal sequence. Selection happens once for the new MC object. Later schedule stages reuse the chain, random streams and caches without rechecking files.

Output and reuse

Use atoms_mode=”a” to create an absent output or append to an existing one. With the shorthand resume/output path, appending avoids duplicating the last loaded frame and removes an interrupted final XYZ tail before writing. A distinct start_from source is only read. atoms_mode=”w” explicitly replaces output AFTER loading the selected configuration; “x” refuses an existing output. Output existence is tested before either action. Enable save_atoms_every > 0 and/or save_atoms_endpoints=true to write frames; without checkpoints, output cannot mark completion of a previous invocation. These options specify another explicit number of proposals/sweeps each invocation, not a cumulative target or an inferred remaining run length.

Reusable named-step TOML example

Save as anneal-250K.toml and run cell --input_file anneal-250K.toml. This example assumes a one-atom binary parent cell, a 64-site supercell at half filling, and a model predicting eV/atom; adjust paths, geometry, counts and energy_factor for your model. The same input can be invoked repeatedly:

do = ["anneal_250K"]

[anneal_250K]
command = "metropolis"
task = "runmc"
model_filepath = "model.pickle"
plat_filepath = "plat.json"
sc_shape = [4, 4, 4]
n_substitutions = {"0" = [32]}
ensemble = "canonical"
temperature = 250.0
n_mc_sweeps = 10
energy_factor = 64.0
boltzmann_constant = 8.617330337217213e-5
predict_swap = true
reduce_structure = true
start_from = "300K.xyz"
# resume_from = "250K.xyz"  # Defaults to atoms_filename with start_from.
atoms_filename = "250K.xyz"
atoms_mode = "a"
save_atoms_endpoints = true
save_atoms_every = 64
serialize = false
random_seed = 43
max_steps_per_batch = 100000

First invocation reads 300K.xyz and creates 250K.xyz. Later invocations continue from 250K.xyz. To use another continuation source, set resume_from=”restart.xyz”; existence of 250K.xyz still selects that branch.

Equivalent direct CLI invocation (booleans take explicit true/false):

cell metropolis -task runmc -mofp model.pickle -plfp plat.json \
    -scsh '[4,4,4]' -nsubs '{"0":[32]}' -temp 250 -sweeps 10 \
    -ef 64 -k_B 8.617330337217213e-5 -pred_swap true -reduce true \
    -start 300K.xyz -atoms 250K.xyz -atoms_mode a \
    -endpoints true -save_every 64 -serialize false -rs 43

The Python API provides MonteCarlo(…, start_from=…) and mc.reset_chain(start_from=…, seed=…) with the same selection rule. mc.reset_chain(seed=…) clears file-based initialization for a fresh run.