gras 1.1.2

A Genetic Programming framework for Neural Architecture Search in Rust
Documentation
//! Initial population generation — shared by the `race` binary and any
//! embedding (e.g. the mnist `main.rs`).
//!
//! Determinism contract: individual `i` derives everything from
//! `derive_seed(run_seed, i)`. The duplicate gate re-rolls at ordinals past
//! the initial batch (`pop_size + attempt`), so a given `(run_seed, config)`
//! still produces a bit-identical population — duplicates included in the
//! draw order, replaced deterministically when they collide.

use super::config::RaceConfig;
use crate::graph::node::NodeKind;
use crate::graph::topology::Topology;
use crate::utils::seed::{derive_seed, topo_hash};

/// One deterministic topology draw from the run's config + pools, keyed by a
/// single ordinal. Shared by the initial loop and the duplicate re-roll so a
/// re-roll uses exactly the same pool/stride discipline as the original.
fn draw_topology(config: &RaceConfig, run_seed: u64, ordinal: usize) -> Topology {
    // Empty config pool ⇒ all known ops (resolved_* handles the fallback).
    let activation = config
        .resolved_activation_pool()
        .unwrap_or_else(|_| crate::evolution::pools::all_activations());
    let combine = config
        .resolved_combine_pool()
        .unwrap_or_else(|_| crate::evolution::pools::all_combine_ops());
    let standardize = config
        .resolved_standardize_pool()
        .unwrap_or_else(|_| crate::evolution::pools::all_standardize_ops());

    let seed = derive_seed(run_seed, ordinal) as usize;
    let mut rng = fastrand::Rng::with_seed(seed as u64);
    // Per-individual identity seed. `options.topology_seed` is the seed the
    // whole engine keys off: `Network::build` weights, `seed_step_randomness`,
    // and the anti-plateau challenge trigger. Leaving it at the template
    // default made every founder share ONE seed — identical initial weights,
    // and a challenge trigger that fired for the entire population at once
    // (or not at all) instead of ~`challenge_prob` of the nets per step.
    let mut opts = config.topology_options;
    opts.topology_seed = seed;
    let n_hidden = rng.usize(opts.min_hidden_num_nodes..=opts.max_hidden_num_nodes);
    let mut graph = Topology::new(seed, Some(opts));
    graph.create_random_hidden_nodes(n_hidden);
    let pool = config.hidden_dim_pool.clone().unwrap_or(4..=8);
    let stride = config.hidden_dim_stride.max(1);
    for node in &mut graph.nodes {
        if node.kind == NodeKind::Hidden {
            let n = ((pool.end() - pool.start()) / stride) + 1;
            node.hidden_dim = Some(pool.start() + rng.usize(0..n) * stride);
            node.activation = activation[rng.usize(0..activation.len())];
            node.combine_op = Some(combine[rng.usize(0..combine.len())]);
            node.standardize = Some(standardize[rng.usize(0..standardize.len())]);
        }
    }
    graph.refresh_labels();
    graph.finalize();
    graph
}

/// The initial population: `pop_size` deterministic draws, deduped by
/// topology hash. Dedupe matters because two identical topology JSONs hash
/// identically and `RaceState` would silently collapse them onto one key —
/// the pop would shrink below `pop_size` from step 0 (the gap this closes
/// was flagged as Tier-A follow-up when the duplicate gate landed for
/// children; this is the population-side twin of that gate).
pub fn initial_population(config: &RaceConfig, run_seed: u64) -> Vec<Topology> {
    let pop_size = config.pop_size;
    let mut topos: Vec<Topology> = (0..pop_size)
        .map(|i| draw_topology(config, run_seed, i))
        .collect();

    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut out = Vec::with_capacity(topos.len());
    for topo in topos.drain(..) {
        let hash = match topo.to_json() {
            Ok(json) => topo_hash(&json),
            Err(_) => {
                // Unserializable topology would fail later anyway; keep it
                // and let the engine's build path surface the error.
                out.push(topo);
                continue;
            }
        };
        if seen.insert(hash.clone()) {
            out.push(topo);
            continue;
        }
        tracing::info!(
            "initial population: duplicate topology {} → discarded, re-rolling a unique seed",
            &hash[..8]
        );
        // Duplicate — re-roll at ordinals past the initial batch, bounded.
        let mut replaced = false;
        for attempt in 0..8 {
            let candidate = draw_topology(config, run_seed, pop_size + attempt);
            let json = match candidate.to_json() {
                Ok(j) => j,
                Err(_) => continue,
            };
            if seen.insert(topo_hash(&json)) {
                out.push(candidate);
                replaced = true;
                break;
            }
        }
        if !replaced {
            tracing::warn!(
                "initial population: could not replace a duplicate topology after 8 attempts — \
                 keeping it (the engine's hash map will dedupe; pop runs one short)"
            );
        }
    }
    out
}

/// Same shape as [`initial_population`], seeded from the run header's
/// recorded split ratio so a resumed run's new entrants see the same
/// train/eval pools as the run that wrote the checkpoint.
pub fn initial_population_from_header(
    config: &RaceConfig,
    run_seed: u64,
    _train_eval_split_ratio: f32,
) -> Vec<Topology> {
    // The initial population topology draw does not depend on the split ratio
    // (that only affects the data stream), so delegate to the shared builder.
    initial_population(config, run_seed)
}

// ── Run topology (founding batch) loading ──────────────────────────────

/// Load a run topology from a saved artifact: a topology JSON file
/// (`Topology::to_json` output) or a `nets/<hash>.json` frontier state (its
/// `topology` field is parsed). Blueprint-ONLY — the topology gets fresh
/// weights and a fresh optimizer like every other net; weight import is a
/// separate, not-yet-landed path.
pub fn run_topology_from_json_file(path: &std::path::Path) -> Result<Topology, String> {
    let raw = std::fs::read_to_string(path)
        .map_err(|e| format!("run-topology {}: {e}", path.display()))?;
    // Try the two shapes: raw topology JSON first, then a NetState wrapper.
    if let Ok(topo) = Topology::from_json(&raw) {
        return Ok(topo);
    }
    let state: serde_json::Value =
        serde_json::from_str(&raw).map_err(|e| format!("run-topology {}: not topology or net-state JSON: {e}", path.display()))?;
    let topo_json = state
        .get("topology")
        .and_then(|t| t.as_str())
        .ok_or_else(|| format!("run-topology {}: no `topology` field", path.display()))?;
    Topology::from_json(topo_json).map_err(|e| format!("run-topology {}: bad topology: {e}", path.display()))
}

/// Load run topologies from a PRIOR RUN's directory: every
/// `nets/<hash>.json` frontier state, ranked by final smoothed fitness (the
/// champion first), up to `max` topologies. Dims and ops come from the saved
/// blueprints verbatim — the new run's topology pools don't constrain them
/// (the run topologies are proven architectures; re-rolling their nodes would
/// defeat the point). Fails only when NO state parses.
pub fn run_topologies_from_run_dir(dir: &std::path::Path, max: usize) -> Result<Vec<Topology>, String> {
    let nets_dir = dir.join("nets");
    let mut scored: Vec<(Option<f32>, Topology)> = Vec::new();
    let entries = std::fs::read_dir(&nets_dir)
        .map_err(|e| format!("{}: {e}", nets_dir.display()))?;
    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) != Some("json") {
            continue;
        }
        let Ok(raw) = std::fs::read_to_string(&path) else { continue };
        let Ok(state) = serde_json::from_str::<serde_json::Value>(&raw) else { continue };
        let Some(topo_json) = state.get("topology").and_then(|t| t.as_str()) else { continue };
        let Ok(topo) = Topology::from_json(topo_json) else { continue };
        let fitness = state
            .get("final_smoothed_fitness")
            .and_then(|f| f.as_f64())
            .map(|f| f as f32);
        scored.push((fitness, topo));
    }
    if scored.is_empty() {
        return Err(format!("{}: no parsable net states", nets_dir.display()));
    }
    // Ranked best-first when fitness exists; nets that never scored keep
    // their (deterministic) file order at the end.
    scored.sort_by(|a, b| match (b.0, a.0) {
        (Some(x), Some(y)) => x.partial_cmp(&y).unwrap_or(std::cmp::Ordering::Equal),
        (Some(_), None) => std::cmp::Ordering::Less,
        (None, Some(_)) => std::cmp::Ordering::Greater,
        (None, None) => std::cmp::Ordering::Equal,
    });
    Ok(scored.into_iter().take(max).map(|(_, t)| t).collect())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn tiny_config(pop: usize) -> RaceConfig {
        let opts = crate::graph::topology::TopologyOptions {
            // Deliberately tiny topology space: 1 hidden node, 1 dim ⇒ collisions
            // are guaranteed, which is exactly what the gate must handle.
            min_hidden_num_nodes: 1,
            max_hidden_num_nodes: 1,
            input_dim: Some(2),
            output_dim: Some(2),
            ..Default::default()
        };
        let mut cfg = RaceConfig::defaults();
        cfg.pop_size = pop;
        cfg.topology_options = opts;
        cfg.hidden_dim_pool = Some(4..=4);
        cfg
    }

    #[test]
    fn population_size_is_preserved_despite_duplicates() {
        let cfg = tiny_config(6);
        let topos = initial_population(&cfg, 42);
        assert_eq!(topos.len(), 6, "dedupe must not shrink the population");
    }

    #[test]
    fn population_has_no_duplicate_hashes() {
        let cfg = tiny_config(6);
        let topos = initial_population(&cfg, 42);
        let mut hashes: Vec<String> = topos
            .iter()
            .map(|t| topo_hash(&t.to_json().unwrap()))
            .collect();
        let total = hashes.len();
        hashes.sort();
        hashes.dedup();
        assert_eq!(hashes.len(), total, "no two topologies may share a hash");
    }

    #[test]
    fn population_is_deterministic_given_seed() {
        let cfg = tiny_config(6);
        let a: Vec<String> = initial_population(&cfg, 42)
            .iter()
            .map(|t| t.to_json().unwrap())
            .collect();
        let b: Vec<String> = initial_population(&cfg, 42)
            .iter()
            .map(|t| t.to_json().unwrap())
            .collect();
        assert_eq!(a, b, "same seed ⇒ bit-identical population");
    }

    #[test]
    fn forced_space_of_one_keeps_exactly_one_unique() {
        // A 1-hidden-node, fixed-dim space with no op variety can only
        // produce ONE distinct topology; the gate can't invent variety. It
        // must keep pop_size entries but only 1 unique hash — the warn path.
        let mut cfg = tiny_config(3);
        cfg.activation_pool = vec!["relu".into()];
        cfg.combine_op_pool = vec!["mean".into()];
        cfg.standardize_op_pool = vec!["identity".into()];
        let topos = initial_population(&cfg, 42);
        assert_eq!(topos.len(), 3, "pop size preserved even when trapped");
    }

    /// Every founder must carry its OWN `net_seed`. Sharing the template's
    /// seed gave the whole population identical initial weights and one
    /// challenge trigger — so `⚔` fired for every net at once (or none) on a
    /// given step instead of ~`challenge_prob` of them.
    #[test]
    fn founders_get_distinct_net_seeds() {
        let cfg = tiny_config(8);
        let topos = initial_population(&cfg, 42);
        let mut seeds: Vec<usize> = topos.iter().map(|t| t.options.topology_seed).collect();
        seeds.sort_unstable();
        seeds.dedup();
        assert_eq!(seeds.len(), 8, "each founder must carry a distinct net_seed");
    }
}