# `Jido.Evolve.State`
[🔗](https://github.com/agentjido/jido_evolve/blob/v1.0.0/lib/jido_evolve/state.ex#L1)

Represents the state of an evolutionary algorithm at a given generation.

This structure tracks the current population, their fitness scores,
and metadata about the evolution process.

# `t`

```elixir
@type t() :: %Jido.Evolve.State{
  average_score: number(),
  best_entity: nil | nil | any(),
  best_score: number(),
  config: %Jido.Evolve.Config{
    checkpoint_interval: nil | nil | integer(),
    crossover_rate: number(),
    crossover_strategy: atom(),
    elitism_rate: number(),
    evaluation_timeout: integer() | :infinity,
    generations: integer(),
    max_concurrency: integer(),
    metrics_enabled: boolean(),
    mutation_rate: number(),
    mutation_strategy: atom(),
    population_size: integer(),
    random_seed: nil | nil | integer(),
    selection_pressure: number(),
    selection_strategy: atom(),
    termination_criteria: [
      max_generations: integer(),
      target_fitness: number(),
      no_improvement: integer()
    ],
    tournament_size: integer()
  },
  diversity: number(),
  fitness_history: [number()],
  generation: integer(),
  metadata: map(),
  population: [any()],
  scores: map()
}
```

# `calculate_diversity`

```elixir
@spec calculate_diversity(t()) :: t()
```

Calculate diversity of the current population.

This is useful for monitoring convergence and maintaining diversity.

# `new`

```elixir
@spec new(map() | keyword()) :: {:ok, t()} | {:error, term()}
```

Create a new state from attributes.

# `new`

```elixir
@spec new([any()], Jido.Evolve.Config.t()) :: t()
```

Create a new initial state from a population and config.

## Examples

    iex> config = Jido.Evolve.Config.new!()
    iex> state = Jido.Evolve.State.new(["a", "b", "c"], config)
    iex> state.population
    ["a", "b", "c"]

# `new!`

```elixir
@spec new!(map() | keyword()) :: t()
```

Create a new state, raising on validation errors.

# `next_generation`

```elixir
@spec next_generation(t(), [any()]) :: t()
```

Update the population and advance the generation counter.

# `put_metadata`

```elixir
@spec put_metadata(t(), atom() | String.t(), term()) :: t()
```

Add metadata to the state.

# `terminated?`

```elixir
@spec terminated?(t()) :: boolean()
```

Check if termination criteria are met.

# `update_scores`

```elixir
@spec update_scores(t(), map()) :: t()
```

Update the state with new fitness scores.

This recalculates the best entity, best score, and average score.

---

*Consult [api-reference.md](api-reference.md) for complete listing*