# EZGA settings

EZGA defines the evolutionary search and its scientific settings. SODA reads
those settings through a native YAML file, distributes evaluations, and
collects results. Start with the [FCC example](ezga-fcc.md) before changing
the search or calculator.

## Where settings belong

| Location | What it controls |
| --- | --- |
| `[Main]` and `[EZGA]` in `config.ini` | Workflow selection, native YAML path, agents, and initial-structure inputs. |
| `native_ezga.yaml` | Population, objectives, variation, simulator, and supported native search settings. |
| MPI launcher and SODA command line | Rank allocation, GPU workers, memory cap, output, and restart. |

Keep `[Main] job = ezga`. Use `"$SODA_BIN" --help-config` to inspect INI
options and `"$SODA_BIN" --help` for runtime options in your build. Activate
its environment first, as described in [Preparing a run](preparing.md).

## SODA configuration: `[EZGA]`

These are SODA-specific integration options and defaults. The example sets
the YAML and seed paths explicitly.

| Option | Default | Purpose |
| --- | --- | --- |
| `config_yaml` | Empty | Native EZGA YAML path, resolved relative to `config.ini`. |
| `num_agents` | `1` | Agent count; more than one requires a matching list of agent INI files. |
| `agent_config_inis` | Empty | One INI path per agent, comma-separated; each child configuration declares one agent. |
| `seed_structures_json` | Empty | JSON seed-file path for a fresh run, relative to `config.ini`. |
| `generated_initial_population_json` | Empty | Generated-population specification; mutually exclusive with `seed_structures_json`. |
| `hdf5_output_path` | Empty | Optional HDF5 output-path override, resolved relative to `config.ini`. |
| `sage_structure_fields` | Empty | Optional SAGE fields to preserve; unrequested optional fields are not carried through SODA. |
| `sage_structure_missing_policy` | `strict` | Require the requested optional fields; only `strict` is supported. |
| `trusted_import_prefixes` | Empty | Additional Python module prefixes admitted for native factory imports. |
| `allow_filesystem_imports` | `false` | Explicitly allow filesystem-based factory imports when needed by a custom setup. |

The factory specifications in the supplied FCC YAML use installed EZGA
modules and need no additional import permissions. For custom functions,
see [Preparing custom factories for SODA–EZGA](ezga-factories.md) for the
extension points, input/output contracts, and YAML syntax. The
{repo}`EZGA configuration guide <docs/soda_analyzer_ezga.md>` also covers
converting an existing native run setup.

## Scientific settings in the FCC YAML

These are **example values**, not a list of EZGA's global defaults.
Edit them in the existing {repo}`native YAML <examples/ezga/fcc_lattice/native_ezga.yaml>`.

| Setting | Example value | Purpose |
| --- | --- | --- |
| `max_generations` | `1` | Generation limit after initial-population evaluation at generation 0. |
| `rng` | `0` | Native search seed. **Native difference:** a nonnegative `[Main] random_seed` overrides it for a fresh run. |
| `multiobjective.size` | `10` | Target number of selected individuals. |
| `multiobjective.selection_method` | `boltzmann` | Selects individuals using Boltzmann selection. |
| `population.filter_duplicates` | `false` | Allows the identical starting seeds in this demonstration. |
| `variation.initial_mutation_rate` | `1.0` | Initial mean number of mutations per candidate, not a probability. |
| `mutation_funcs` | `strain_cell`, `max_strain: 0.01` | Strains cell vectors and atomic positions; strain components are bounded by ±1%. |
| `evaluator.objectives_funcs` | `objective_energy` | Uses energy as the optimization objective. |
| `evaluator.features_funcs` | `feature_cell_volume` | Records cell volume as a feature. |
| `simulator.mode` | `sampling` | Uses the same sampling-temperature parameter for all candidates in a batch. |

Within `simulator.calculator.kwargs`, `nvt_steps: 0` skips molecular dynamics,
`fmax: 0.001` sets the relaxation force threshold in eV/Å, and
`steps_max: 100` limits optimizer steps. `constant_volume: false` and
`hydrostatic_strain: true` allow isotropic cell-volume relaxation.
The nested Lennard–Jones calculator uses Ar
`sigma: 3.405` Å, `epsilon: 0.0103` eV, `rc: 8.0` Å, and `shift: false`.
Changing these values changes the reference lattice and energy.

## Optional population constraints

Use `population.constraints` to filter candidates by the features computed by
`evaluator.features_funcs`. For example, this native factory accepts atom
counts from 1 through 100, including both bounds:

```yaml
evaluator:
  features_funcs:
    factory: ezga.evaluator.features:feature_total_atoms

population:
  constraints:
    - factory: ezga.DoE.constraint:ConstraintFactory.within_range
      args: [0, 1, 100]
```

This is an optional example, separate from the FCC settings above. Merge it
into your existing YAML while keeping the other evaluator and population
settings. Here `0` selects the atom-count feature column; update that index
if you combine or reorder features. The native factory needs no additional
`trusted_import_prefixes` entry.

All predicates must pass. SODA checks generated and supported injected/guided
candidates before dispatch, then checks each returned calculator product
using its updated features. A rejected candidate can also affect adaptive
mutation/crossover weights through native operator penalties.

Set `constraints: []` or `constraints: null` to disable these checks. An
explicit list, including a HiSE stage override, replaces the previous list.
Initial seed admission and inbound migrant admission are separate; these
predicates do not guarantee that every retained seed or migrant passes.
They also do not fix atoms during relaxation.

See [Population constraints](ezga-factories.md#population-constraints) for
custom factories, feature-name lookup, and the input/output contract, and
[Inspect rejected candidates](ezga-analysis.md#inspect-rejected-candidates)
for the saved records.

## Unsupported and redirected settings

:::{admonition} Check native inputs before reusing them
:class: tip

**Native difference** marks changed behavior; **unsupported** marks rejected
choices. These notes apply to the SODA integration.

| Native setting | Restriction or alternative when using SODA |
| --- | --- |
| `resume`, `resume_mode`, `initial_generation` | **Unsupported in YAML.** Use `--loadrun`; SODA resumes complete HDF5 generation commits, not native snapshots. |
| `output_path` | **Native difference:** keep `.`; results go to SODA's configured HDF5 output. |
| `save_logs`, `population.save_duplicates` | **Native difference:** native log/duplicate files are replaced by SODA logs and HDF5 records. |
| `simulator.execution` | **Native difference:** keep `async`, but SODA's MPI workers execute evaluations instead of the native executor. |
| `initial_population`, `population.dataset_path`, `population.template_path` | **Unsupported when nonempty.** Use `[EZGA] seed_structures_json` or `generated_initial_population_json`. |
| `population.db_path`, `population.db_ro_path` | **Native difference:** leave unset; population state is stored in SODA's HDF5 database. |
| `hashmap.method: descriptor` and descriptor-hash fields | **Unsupported.** Descriptor-hash provenance is not mapped by the integration. |
| `agentic.strategy` | **Native difference:** `deep`, `wide`, `exploitation`, and `exploration` share one adaptive coefficient mapping in SODA; they do not reproduce distinct native strategies. |
| `agentic.shared_dir`, `agentic.persist_seen: true` | **Unsupported.** MPI exchange and saved runtime state replace native mailboxes and `seen.json`. |
| `[EZGA] worker_groups`, `[EZGA] memory_cap_mb` | Retired INI options. Worker placement follows the MPI layout; use CLI `--ezga_memory_cap_mb` for the memory cap. |
| Optional SAGE `atomicConstraints` and `time` fields | Not admitted by `sage_structure_fields`; ordinary fixed-atom information is handled separately. |

`agentic.shard_width` and `agentic.poll_interval` must retain defaults `2`
and `2.0`; they do not control SODA's MPI exchange. See the
{repo}`configuration support rules <src/python/ezga_config_surface.py>` and
the {repo}`detailed EZGA guide <docs/soda_analyzer_ezga.md>` when adapting an
advanced native configuration.
:::

## Runtime controls

The [FCC launch](ezga-fcc.md#2-check-and-launch) uses one agent and one
calculator worker. Increasing MPI ranks does not itself increase
`num_agents`; additional worker capacity can evaluate candidates for the
existing agent. Keep CPU capacity for the agent when using GPU calculators.

`--num-gpu-workers-per-node=0` selects CPU workers for the FCC calculator.
`--ezga_memory_cap_mb=0` leaves shared input/result payload capacity at its
automatic setting. A positive value sets the explicit payload cap in MB
for all EZGA agents, not a total process-memory limit. Use SODA's `--loadrun` for
[restart](restart.md), and inspect complete generation commits before
interpreting a partially finished run as a completed population.