Typed config validation for Petri.run/2.

Uses Zoi to validate the config keyword list against a typed schema. Invalid configs return {:error, reasons}.

Config fields

Fields marked Required must always be present. The available fields depend on which :encoding you choose.

:binary encoding

• :population_size (integer/0) - Required. Number of individuals in each generation.

• :max_generations (integer/0) - Maximum number of generations before stopping.

• :fitness_threshold (float/0) - Stop when best fitness reaches or exceeds this value.

• :stagnation_generations (integer/0) - Stop if no improvement after this many generations.

• :time_budget_ms (integer/0) - Maximum wall-clock time in milliseconds.

• :max_evaluations (integer/0) - Maximum number of evaluations before stopping.

• :selection (:tournament | :roulette | :rank | :sus) - Selection strategy. The default value is :sus.

• :tournament_size (integer/0) - Number of individuals in each tournament (only for :tournament selection). The default value is 3.

• :elite_count (integer/0) - Number of top individuals preserved unchanged each generation. Ignored when replacement is :steady_state, where the best individuals survive naturally. The default value is 2.

• :crossover_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying crossover to a selected pair. Constant, function of the generation, or decay strategy tuple. The default value is 0.9.

• :mutation_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying mutation to an offspring. Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :parallel (boolean/0) - Whether to run evaluations in parallel. The default value is true.

• :parallel_timeout (integer/0) - Timeout in milliseconds. The default value is 5000.

• :parallel_max_concurrency (integer/0) - Maximum number of concurrent tasks when :parallel is enabled. Defaults to twice the number of schedulers at run time.

• :parallel_chunk_size (integer/0) - Number of chromosomes evaluated per task when :parallel is enabled. Defaults to ceil(population_size / max_concurrency), keeping the number of tasks within the concurrency limit.

• :constraint_penalty (function/0) - Takes a chromosome and returns a penalty value.

• :constraint (function/0) - Takes a chromosome and returns a boolean: true when the chromosome satisfies the constraint. Used by death_penalty_retries to decide whether an offspring is valid.

• :death_penalty_retries (integer/0) - Number of retries to create a valid individual offspring before the death penalty is applied. Requires constraint.

• :replacement (:generational | :steady_state) - Replacement strategy: :generational replaces the population with offspring each generation; :steady_state inserts offspring one pair at a time, replacing the worst individual. The default value is :generational.

• :seed (integer/0) - Random seed for reproducible runs.

• :encoding (:binary)

• :length (integer/0) - Required. Number of bits in the chromosome.

• :initialization (:random) - Initialization strategy. The default value is :random.

• :crossover (:single_point | :two_point | :uniform) - Crossover operator. The default value is :single_point.

• :mutation (:bit_flip) - Mutation operator. The default value is :bit_flip.

• :mutation_per_gene_rate (float/0) - Probability of flipping each individual bit.

:real encoding

• :population_size (integer/0) - Required. Number of individuals in each generation.

• :max_generations (integer/0) - Maximum number of generations before stopping.

• :fitness_threshold (float/0) - Stop when best fitness reaches or exceeds this value.

• :stagnation_generations (integer/0) - Stop if no improvement after this many generations.

• :time_budget_ms (integer/0) - Maximum wall-clock time in milliseconds.

• :max_evaluations (integer/0) - Maximum number of evaluations before stopping.

• :selection (:tournament | :roulette | :rank | :sus) - Selection strategy. The default value is :sus.

• :tournament_size (integer/0) - Number of individuals in each tournament (only for :tournament selection). The default value is 3.

• :elite_count (integer/0) - Number of top individuals preserved unchanged each generation. Ignored when replacement is :steady_state, where the best individuals survive naturally. The default value is 2.

• :crossover_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying crossover to a selected pair. Constant, function of the generation, or decay strategy tuple. The default value is 0.9.

• :mutation_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying mutation to an offspring. Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :parallel (boolean/0) - Whether to run evaluations in parallel. The default value is true.

• :parallel_timeout (integer/0) - Timeout in milliseconds. The default value is 5000.

• :parallel_max_concurrency (integer/0) - Maximum number of concurrent tasks when :parallel is enabled. Defaults to twice the number of schedulers at run time.

• :parallel_chunk_size (integer/0) - Number of chromosomes evaluated per task when :parallel is enabled. Defaults to ceil(population_size / max_concurrency), keeping the number of tasks within the concurrency limit.

• :constraint_penalty (function/0) - Takes a chromosome and returns a penalty value.

• :constraint (function/0) - Takes a chromosome and returns a boolean: true when the chromosome satisfies the constraint. Used by death_penalty_retries to decide whether an offspring is valid.

• :death_penalty_retries (integer/0) - Number of retries to create a valid individual offspring before the death penalty is applied. Requires constraint.

• :replacement (:generational | :steady_state) - Replacement strategy: :generational replaces the population with offspring each generation; :steady_state inserts offspring one pair at a time, replacing the worst individual. The default value is :generational.

• :seed (integer/0) - Random seed for reproducible runs.

• :encoding (:real)

• :bounds (list of {float/0, float/0}) - Required. List of {lo, hi} tuples, one per gene, defining the search space.

• :initialization (:random | :lhs) - Initialization strategy. The default value is :random.

• :crossover (:blx_alpha | :sbx) - Crossover operator. The default value is :blx_alpha.

• :blx_alpha_param (float/0) - Alpha parameter for BLX-α crossover (0.0 = average, 0.5 = midpoint). The default value is 0.5.

• :sbx_eta (float/0) - Distribution index for SBX crossover (higher = closer to parents). The default value is 2.0.

• :mutation (:gaussian | :uniform) - Mutation operator. The default value is :gaussian.

• :gaussian_sigma (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Standard deviation for Gaussian mutation (as fraction of bound width). Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :mutation_per_gene_rate (float/0) - Probability of mutating each individual gene. The default value is 1.0.

:permutation encoding

• :population_size (integer/0) - Required. Number of individuals in each generation.

• :max_generations (integer/0) - Maximum number of generations before stopping.

• :fitness_threshold (float/0) - Stop when best fitness reaches or exceeds this value.

• :stagnation_generations (integer/0) - Stop if no improvement after this many generations.

• :time_budget_ms (integer/0) - Maximum wall-clock time in milliseconds.

• :max_evaluations (integer/0) - Maximum number of evaluations before stopping.

• :selection (:tournament | :roulette | :rank | :sus) - Selection strategy. The default value is :sus.

• :tournament_size (integer/0) - Number of individuals in each tournament (only for :tournament selection). The default value is 3.

• :elite_count (integer/0) - Number of top individuals preserved unchanged each generation. Ignored when replacement is :steady_state, where the best individuals survive naturally. The default value is 2.

• :crossover_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying crossover to a selected pair. Constant, function of the generation, or decay strategy tuple. The default value is 0.9.

• :mutation_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying mutation to an offspring. Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :parallel (boolean/0) - Whether to run evaluations in parallel. The default value is true.

• :parallel_timeout (integer/0) - Timeout in milliseconds. The default value is 5000.

• :parallel_max_concurrency (integer/0) - Maximum number of concurrent tasks when :parallel is enabled. Defaults to twice the number of schedulers at run time.

• :parallel_chunk_size (integer/0) - Number of chromosomes evaluated per task when :parallel is enabled. Defaults to ceil(population_size / max_concurrency), keeping the number of tasks within the concurrency limit.

• :constraint_penalty (function/0) - Takes a chromosome and returns a penalty value.

• :constraint (function/0) - Takes a chromosome and returns a boolean: true when the chromosome satisfies the constraint. Used by death_penalty_retries to decide whether an offspring is valid.

• :death_penalty_retries (integer/0) - Number of retries to create a valid individual offspring before the death penalty is applied. Requires constraint.

• :replacement (:generational | :steady_state) - Replacement strategy: :generational replaces the population with offspring each generation; :steady_state inserts offspring one pair at a time, replacing the worst individual. The default value is :generational.

• :seed (integer/0) - Random seed for reproducible runs.

• :encoding (:permutation)

• :n (integer/0) - Required. Number of elements in the permutation.

• :initialization (:random) - Initialization strategy. The default value is :random.

• :crossover (:ox | :pmx | :cx) - Crossover operator. The default value is :pmx.

• :mutation (:swap | :insert | :inversion) - Mutation operator. The default value is :swap.

:integer encoding

• :population_size (integer/0) - Required. Number of individuals in each generation.

• :max_generations (integer/0) - Maximum number of generations before stopping.

• :fitness_threshold (float/0) - Stop when best fitness reaches or exceeds this value.

• :stagnation_generations (integer/0) - Stop if no improvement after this many generations.

• :time_budget_ms (integer/0) - Maximum wall-clock time in milliseconds.

• :max_evaluations (integer/0) - Maximum number of evaluations before stopping.

• :selection (:tournament | :roulette | :rank | :sus) - Selection strategy. The default value is :sus.

• :tournament_size (integer/0) - Number of individuals in each tournament (only for :tournament selection). The default value is 3.

• :elite_count (integer/0) - Number of top individuals preserved unchanged each generation. Ignored when replacement is :steady_state, where the best individuals survive naturally. The default value is 2.

• :crossover_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying crossover to a selected pair. Constant, function of the generation, or decay strategy tuple. The default value is 0.9.

• :mutation_rate (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Probability of applying mutation to an offspring. Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :parallel (boolean/0) - Whether to run evaluations in parallel. The default value is true.

• :parallel_timeout (integer/0) - Timeout in milliseconds. The default value is 5000.

• :parallel_max_concurrency (integer/0) - Maximum number of concurrent tasks when :parallel is enabled. Defaults to twice the number of schedulers at run time.

• :parallel_chunk_size (integer/0) - Number of chromosomes evaluated per task when :parallel is enabled. Defaults to ceil(population_size / max_concurrency), keeping the number of tasks within the concurrency limit.

• :constraint_penalty (function/0) - Takes a chromosome and returns a penalty value.

• :constraint (function/0) - Takes a chromosome and returns a boolean: true when the chromosome satisfies the constraint. Used by death_penalty_retries to decide whether an offspring is valid.

• :death_penalty_retries (integer/0) - Number of retries to create a valid individual offspring before the death penalty is applied. Requires constraint.

• :replacement (:generational | :steady_state) - Replacement strategy: :generational replaces the population with offspring each generation; :steady_state inserts offspring one pair at a time, replacing the worst individual. The default value is :generational.

• :seed (integer/0) - Random seed for reproducible runs.

• :encoding (:integer)

• :bounds (list of {integer/0, integer/0}) - Required. List of {lo, hi} tuples, one per gene, defining the integer search space.

• :initialization (:random) - Initialization strategy. The default value is :random.

• :crossover (:blx_alpha | :two_point | :sbx | :single_point) - Crossover operator. The default value is :blx_alpha.

• :blx_alpha_param (float/0) - Alpha parameter for BLX-α crossover. The default value is 0.5.

• :sbx_eta (float/0) - Distribution index for SBX crossover. The default value is 2.0.

• :mutation (:gaussian | :uniform) - Mutation operator. The default value is :gaussian.

• :gaussian_sigma (float/0 | function/0 | {:linear_decay, float/0, float/0, number/0} | {:exponential_decay, float/0, float/0, float/0}) - Standard deviation for Gaussian mutation (as fraction of bound width). Constant, function of the generation, or decay strategy tuple. The default value is 0.1.

• :mutation_per_gene_rate (float/0) - Probability of mutating each individual gene. The default value is 1.0.

Example

iex> {:ok, config} = Petri.Config.parse([
...>   encoding: :binary,
...>   length: 8,
...>   population_size: 20,
...>   max_generations: 10
...> ])
iex> config[:encoding]
:binary

iex> {:error, err} = Petri.Config.parse([
...>   encoding: :binary,
...>   length: 8,
...>   population_size: 0,
...>   max_generations: 10
...> ])
iex> is_list(err)
true