Command paipai

Command: paipai

paipai is the main user command. It is a launcher script that starts Python workers and then runs the C++ Monte Carlo master mc_paipai.

Basic Usage

paipai [options]

Search mode:

paipai \
  --input struc.in \
  --mode search \
  --device cuda \
  --ngpu 4 \
  --fast 2 \
  --slow 2 \
  --steps 200000 \
  --temp 50

Finite-temperature mode:

paipai \
  --input struc.in \
  --mode finiteT \
  --device cuda \
  --ngpu 1 \
  --slow 1 \
  --steps 200000 \
  --temp 700

Basic Options

Option	Default	Meaning
-i, --input FILE	struc.in	Initial PAIPAI structure file. Not required with --resume-state.
--mode MODE	finiteT	Run mode: search or finiteT.
--model NAME	GRACE-2L-OMAT	MLIP model name passed to workers.
--device DEV	cpu	Worker device: cpu or cuda.
--ngpu N	0	Number of GPUs used for round-robin worker assignment. Must be at least 1 when --device cuda.
--root DIR	current directory	Root working directory.
--resume-state DIR	none	Resume finiteT from a state directory, or from the latest numbered child if DIR is mcprocess.
-h, --help	-	Show help.

If --resume-state is used without --root, the launcher defaults to finiteT_<temp>.

Worker Options

Option	Default	Meaning
--fast N	0	Number of fast workers. Ignored in finiteT because fast workers are skipped.
--slow N	1	Number of slow/refinement workers.
--pool-cap N	128	Maximum size of waiting_pool for screened candidates.
--fmax-screen X	0.10	Fast-worker relaxation force tolerance.
--max-steps-screen N	30	Fast-worker maximum relaxation steps.
--fmax-refine X	0.01	Slow-worker relaxation force tolerance.
--max-steps-refine N	400	Slow-worker maximum relaxation steps.

Monte Carlo Options

Option	Default	Meaning
--steps N	200000	Run budget. In search, this is fast-screened structures. In finiteT, this is processed MC proposals.
--temp T	700	Monte Carlo temperature used in Metropolis acceptance.
--p-swap-metal N	70	Weight for metal swap moves.
--p-swap-inter N	30	Weight for interstitial swap moves.
--p-hop-inter N	0	Weight for local interstitial hop moves.
--p-cluster-inter N	0	Weight for cluster interstitial swap moves.
--p-exch-metal N	0	Reserved weight for metal exchange moves.
--p-exch-inter N	0	Reserved weight for interstitial exchange moves.
--intsite-neighbor-cutoff X	3.5	Cutoff for interstitial-site metal-neighbor map.
--intsite-hop-cutoff X	3.0	Cutoff for local interstitial-hop graph.
--interstitial-site-cutoff X	1.5	Maximum relaxed interstitial distance to assigned reference site.

Move probabilities are proportional to nonnegative move weights. At least one move weight must be positive.

Prefast Options

These options are forwarded to mc_paipai. They are available on v2.1-dev.

Option	Default	Meaning
`--prefast on	off`	off
--prefast-candidates-per-slot N	6	Number of trial candidates ranked for each free fast-worker slot after warmup.
--prefast-warmup-steps N	1000	Valid MC proposals used for learning before multi-candidate prefast ranking starts.
--prefast-basis ref-dz	ref-dz	Reference-lattice double-zeta radial basis.
--prefast-nshells N	3	Number of detected shells per site-pair family.
--prefast-peak-scan-cutoff X	6.0	Maximum reference pair distance used in shell detection.
--prefast-peak-tol X	0.12	Distance tolerance for shell clustering.
--prefast-sigma-small X	0.10	Narrow Gaussian width in Angstrom.
--prefast-sigma-large X	0.30	Broad Gaussian width in Angstrom.
--prefast-cutoff-margin X	0.50	Margin added after the last shell center for cosine cutoff.
--prefast-learning-rate X	0.01	Normalized-LMS learning rate.
--prefast-lms-epsilon X	1e-12	Denominator stabilizer for normalized LMS.
--prefast-weight-decay X	0.0	Optional online weight decay.
`--prefast-diagnostics off	summary	updates

Other Behavior

Unknown launcher options are passed directly to mc_paipai.

Useful environment variables:

Variable	Meaning
PAIPAI_PYTHON	Python executable used for workers.
OMP_NUM_THREADS	Defaults to 1 if unset.
MKL_NUM_THREADS	Defaults to 1 if unset.
OPENBLAS_NUM_THREADS	Defaults to 1 if unset.
NUMEXPR_NUM_THREADS	Defaults to 1 if unset.