# FCC argon with Lennard–Jones

Relax an FCC argon lattice with EZGA, then inspect its energy and lattice
constant. This walkthrough uses the
{repo}`FCC lattice example <examples/ezga/fcc_lattice/README.md>` 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](../install.md):

```bash
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](ezga-settings.md) before adapting the population or calculator.

## 2. Check and launch

From the run directory, check the inputs:

```bash
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:

```bash
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](parallel.md).

For Raven, copy the repository template:

```bash
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](monitoring.md) and
the [analysis page](ezga-analysis.md) for generation and completion queries.

## 4. Inspect the results and continue

After the run finishes, use the same activated environment:

```bash
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](ezga-analysis.md) to inspect populations,
generations, and rejected structures. For an independent longer search,
prepare a new directory and adjust the native YAML using
[EZGA settings](ezga-settings.md). See [Restarting a run](restart.md) for
continuing from a saved SODA database. Cite the
[EZGA work](ezga.md#references-and-project-links) and SODA when reporting
calculations based on this example.