FCC argon with Lennard–Jones¶

Relax an FCC argon lattice with EZGA, then inspect its energy and lattice constant. This walkthrough uses the FCC lattice example at examples/ezga/fcc_lattice/. An ASE Lennard–Jones calculator supplies the energies and forces; no external model, LAMMPS potential, or GPU is needed.

Use an EZGA-enabled build with ASE. The local launch below needs three available physical CPU cores and Open MPI. It evaluates the initial population and runs one evolutionary generation. This small example checks the setup and illustrates cell relaxation; it does not establish convergence of a general structure search.

1. Select your build and copy the inputs¶

Replace your-prefix with the name chosen in the installation guide:

export SODA_ROOT="$HOME/soda"
export SODA_BIN="$SODA_ROOT/build/your-prefix/soda"
source "$SODA_ROOT/build/your-prefix/modules.rc"

export SODA_EXAMPLE="$SODA_ROOT/examples/ezga/fcc_lattice"
export SODA_RUN="$HOME/soda-runs/ezga-fcc"
mkdir -p "$HOME/soda-runs"
mkdir "$SODA_RUN"
cp "$SODA_EXAMPLE/config.ini" "$SODA_EXAMPLE/native_ezga.yaml" \
  "$SODA_EXAMPLE/seed_structures.json" "$SODA_EXAMPLE/analyze.py" "$SODA_RUN/"
cd "$SODA_RUN"

Choose a new run-directory name if this one already exists. Keep the same SODA_ROOT and build selection in subsequent shells and batch jobs.

Input	Purpose
`config.ini`	Selects `job = ezga` and names the YAML and seed files.
`native_ezga.yaml`	Defines the energy objective, cell-strain mutation, and ASE/Lennard–Jones relaxation.
`seed_structures.json`	Ten identical 32-atom Ar cells, each a periodic 2 × 2 × 2 conventional FCC supercell with initial lattice constant 5.9 Å.
`analyze.py`	Exports the lowest-energy evaluated structure and a lattice summary.

The supplied YAML keeps ten selected individuals, disables duplicate filtering for these identical seeds, and sets max_generations: 1. Generation 0 evaluates the starting population; generation 1 applies cell-strain mutations and evaluates the resulting candidates. Hydrostatic cell relaxation allows the volume to change. Keep these settings for the first run; see EZGA settings before adapting the population or calculator.

2. Check and launch¶

From the run directory, check the inputs:

python "$SODA_ROOT/src/python/soda_analyzer.py" check-run-folder . \
  --soda-exe "$SODA_BIN" --check

Resolve blocking findings before launching. The checker does not evaluate energies or prove that the calculator can complete a relaxation.

For a local Open MPI run, use one combined head/master, one EZGA agent, and one CPU calculator worker, with one physical CPU core per rank:

export OMP_NUM_THREADS=1
export OMP_PLACES=cores
export OMP_PROC_BIND=close
export MKL_NUM_THREADS=1
export OPENBLAS_NUM_THREADS=1
mpirun -n 3 --map-by slot:PE=1 --bind-to core --report-bindings \
  "$SODA_BIN" --num-gpu-workers-per-node=0 --ezga_memory_cap_mb=0

The agent manages the evolutionary search; the calculator worker relaxes candidates. --ezga_memory_cap_mb=0 leaves the shared input/result payload capacity at its automatic setting; it is not a total process-memory limit. The thread settings keep numerical libraries within the one-core allocation. Run on allocated compute resources on an HPC system; see Parallel execution.

For Raven, copy the repository template:

cp "$SODA_EXAMPLE/submitjob.raven" "$SODA_RUN/"

It requests one node and 14 ranks: one head/master, one CPU agent, and 12 calculator workers, with one core per rank, 16000 MB, and one hour. These are allocation limits, not measured requirements. Ten candidates per batch leave some workers idle. Edit SODA_ROOT and BUILD_NAME in the copied script and review its resource requests before submitting with sbatch submitjob.raven. The template removes existing output/ data when starting a fresh run.

3. Follow progress¶

Watch the terminal or scheduler output and output/logs/. Look for initial-population evaluation, generation progress, and normal finalization at the configured generation limit. Results are collected in output/output.h5; temporary worker files are under workspace/.

The database can contain unevaluated seed records as well as relaxed structures. A stored row count alone does not tell you how many candidates have finished evaluation. See Monitoring and outputs and the analysis page for generation and completion queries.

4. Inspect the results and continue¶

After the run finishes, use the same activated environment:

python analyze.py

This writes best.xyz and summary.json, excluding non-finite energies and the unevaluated-seed placeholder 9999. For the supplied Lennard–Jones parameters and cutoff, the effective conventional lattice constant should relax toward approximately 5.35 Å, with a negative energy per atom. This value describes the example’s model, not an experimental comparison.

The script computes the lattice constant as the cube root of the cell volume divided by two, appropriate to the supplied supercell. Update its constants if you change the cell construction. Selecting the lowest total energy is appropriate here because every candidate has the same composition and atom count.

Use Analyzing EZGA output to inspect populations, generations, and rejected structures. For an independent longer search, prepare a new directory and adjust the native YAML using EZGA settings. See Restarting a run for continuing from a saved SODA database. Cite the EZGA work and SODA when reporting calculations based on this example.