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 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.

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 for the extension points, input/output contracts, and YAML syntax. The EZGA configuration guide 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 native 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:

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 for custom factories, feature-name lookup, and the input/output contract, and Inspect rejected candidates for the saved records.

Unsupported and redirected settings

Check native inputs before reusing them

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 configuration support rules and the detailed EZGA guide when adapting an advanced native configuration.

Runtime controls

The FCC 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, and inspect complete generation commits before interpreting a partially finished run as a completed population.