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.