Skip to content

XtalOpt

Jump to bottom
roeeasher edited this page Jun 18, 2026 · 2 revisions

🔮 XtalOpt: Evolutionary Crystal Structure Prediction

XtalOpt is an open-source evolutionary algorithm for crystal structure prediction that interfaces seamlessly with Avogadro and VASP. Unlike other tools that rely on discrete generational cutoffs, XtalOpt evaluates convergence continuously on a rolling, structure-by-structure basis.

While USPEX relies on strict generational steps, XtalOpt provides a flexible alternative that is highly integrated into graphical environments but can be efficiently run via the command line on high-performance clusters.

🛠️ Preparing Your Environment

To run XtalOpt via the command line on the Slurm cluster, you must first bypass a known SSH deadlock issue by setting up passwordless localhost access.

🧾 Step 1: Passwordless Localhost

Run these commands to generate an RSA key and authorize yourself so the background process can submit jobs silently.

Note: It is possible that an SSH key already exists for your account. If the first command asks to overwrite an existing key, there is no need to create a new one. Just type n and proceed to the next commands.

ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

🧾 Step 2: Force an RSA Host Key

Because XtalOpt's internal SSH library requires RSA, add the localhost key to your known hosts:

ssh-keyscan -t rsa localhost >> ~/.ssh/known_hosts

Verify the setup works silently without a password:

ssh localhost echo "Success"

🚀 Running XtalOpt for an Example

1️⃣ Open a tmux session

tmux new -s xtalopt_run

2️⃣ Make your working directories

Because of how XtalOpt copies files locally, you must create both a staging directory and an actual working directory.

mkdir XtalOpt_run
mkdir XtalOpt_run_staging
cd XtalOpt_run

⚙️ Editing Submission Settings

📄 xtalopt.in Configuration

Generate your initial xtalopt.in file from the XtalOpt GUI on your local machine and upload it to your working directory.

Here is the full configuration file with the key settings modified for the Slurm cluster.

Note that this displayed file is set up as an example for an NaCl supercell containing exactly 8 Sodium atoms and 8 Chlorine atoms (chemicalFormulas = Na8Cl8).

Ensure you update the paths to match your actual username and directories:

### Search Parameters ###
  chemicalFormulas = Na8Cl8
  vcSearch = false
  minAtoms = 1
  maxAtoms = 20
  numInitial = 30
  parentsPoolSize = 20
  limitRunningJobs = true
  maxNumStructures = 1000
  runningJobLimit = 20
  continuousStructures = 15

  optimizationType = basic
  tournamentSelection = true
  restrictedPool = false
  crowdingDistance = true
  objectivePrecision = -1

  objectivesReDo = false

  softExit = false
  saveHullSnapshots = false
  verboseOutput = false

### Cell Limits and Initialization ###
  minVolume = 1
  maxVolume = 100
  minVolumeScale = 0
  maxVolumeScale = 0

  aMin = 3
  bMin = 3
  cMin = 3
  aMax = 12
  bMax = 12
  cMax = 12
  alphaMin = 45
  betaMin  = 45
  gammaMin = 45
  alphaMax = 135
  betaMax  = 135
  gammaMax = 135

  usingRadiiInteratomicDistanceLimit = true
  radiiScalingFactor =  0.5
  minRadius = 0.25
  usingCustomIADs = false
  checkIADPostOptimization = false

  usingRandSpg = true

  usingMolecularUnits = false

### Genetic Operations ###
  weightStripple    = 25
  weightPermustrain = 25
  weightCrossover   = 35
  weightPermutomic  = 15
  weightPermucomp   = 5
  randomSuperCell   = 0

  crossoverMinContribution = 25
  crossoverCuts            = 1
  strippleAmplitudeMin     = 0.5
  strippleAmplitudeMax     = 1
  strippleNumWavesAxis1    = 1
  strippleNumWavesAxis2    = 1
  strippleStrainStdevMin   = 0.5
  strippleStrainStdevMax   = 0.5
  permustrainNumExchanges  = 4
  permustrainStrainStdevMax= 0.5

### Tolerances ###
  spglibTolerance        = 0.01
  xtalcompToleranceLength= 0.1
  xtalcompToleranceAngle = 2
  rdfTolerance           = 0
  rdfCutoff              = 6
  rdfSigma               = 0.008
  rdfNumBins             = 3000

### Job Handling ###
  jobFailLimit = 1
  jobFailAction = replaceWithRandom

### Optimizer ###
  numOptimizationSteps = 4
  optimizer = vasp
  templatesDirectory = path/to/templates/directory
  incarTemplates = INCAR_1, INCAR_2, INCAR_3, INCAR_4
  kpointsTemplates = KPOINTS_1, KPOINTS_2, KPOINTS_3, KPOINTS_4
  potcarFile Cl = path/to/POTCAR
  potcarFile Na = path/to/POTCAR

### Queue Interface ###
  queueInterface = slurm
  jobTemplates = job.1, job.2, job.3, job.4
  exeLocation = /powerapps/sources/rocky8/vasp.6.4.1/bin/vasp_std
  localWorkingDirectory = path/to/local/working/directory
  remoteWorkingDirectory = path/to/remote/working/directory
  localQueue = false

  logErrorDirectories   = false
  queueRefreshInterval = 10
  cleanRemoteDirs = false
  autoCancelJobAfterTime = false
  hoursForAutoCancelJob = 100
  host = localhost 
  port = 22
  user = username
  submitCommand = /usr/bin/sbatch
  cancelCommand = /usr/bin/scancel
  statusCommand = /usr/bin/squeue

Note: Remove any empty variables (like user1 = ) from your options file to prevent parser errors.

🌱 The Templates Directory

Create a templates/ folder inside your working directory. It must contain your SLURM scripts, INCARs, and KPOINTS files.

INCAR_1 to INCAR_4 could be found in Tutorial 14

📄 Job Submission (job.1 to job.4)

Since XtalOpt uses a non-interactive shell, you must manually source your bash profile to load the module command before executing VASP.

#!/bin/bash
#
# filename: slurm_script
#SBATCH -p leeburton-pool
#SBATCH --account=power-leeburton-users_v2
#SBATCH --job-name=XtalOpt
#SBATCH --time=72:00:00
#SBATCH --nodes=1
#SBATCH --ntasks=24
#SBATCH --mem=120GB

# Initialize the Linux environment
source /etc/profile
source ~/.bashrc

ulimit -s 81920

# Force the job to run in the current structure's directory
cd $SLURM_SUBMIT_DIR

# Load necessary modules
module load intel/rocky8-oneAPI-2023
module load vasp/rocky8-intel-6.4.1

# Execute VASP
mpirun -n $SLURM_NTASKS vasp_std > output

*Note: the continuousStructures line in xtalopt.in dictates the number of jobs that will run simultaneously at the queue.

📄 KPOINTS Configuration

XtalOpt scales the K-Point grid dynamically based on KPPRA (K-Points Per Reciprocal Atom). Instead of standard grids, you define the target KPPRA in the fourth line.

Example KPOINTS_1:

Automatic generation
0
Auto
15

🔁 Running the XtalOpt Loop

Once your xtalopt.in is configured and your templates/ directory is fully populated with all INCAR, KPOINTS, and job scripts:

xtalopt --cli

📋 Then detach safely from your tmux session with Ctrl+b, then d.

The algorithm will continuously generate new structures and submit VASP jobs asynchronously to the cluster queue.

🛑 Stopping Criteria Settings

XtalOpt stops based on the number of structural evaluations rather than hard generational cutoffs.

  maxNumStructures = 1000
  • continuousStructures: The search halts if 15 consecutive VASP jobs finish without discovering a structure with a lower energy than the current global minimum.
  • maxNumStructures: A computational safety limit to prevent the search from running indefinitely if it fails to converge.

🎉 Congratulations! You are ready to start running XtalOpt!

Clone this wiki locally