gras 2.0.1

A Genetic Programming framework for Neural Architecture Search in Rust
Documentation
//! JSON round-trip representation of a [`Topology`].  [`Topology`] can't derive `Serialize` directly — it holds an RNG (`rng: fastrand::Rng`) that isn't serializable — so…

use fastrand::Rng;
use serde::de::Deserializer;
use serde::ser::Serializer;
use serde::{Deserialize, Serialize};

use crate::graph::node::Node;
use crate::graph::topology::{Connection, Topology, TopologyOptions};
/// JSON round-trip representation of a [`Topology`] — the blueprint minus
/// the RNG. `options.topology_seed` makes regeneration reproducible.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Spec {
    /// Topology id this blueprint was captured
    pub id: usize,
    /// The options the graph was built with (incl. `topology_seed`).
    pub options: TopologyOptions,
    /// Nodes in graph order.
    pub nodes: Vec<Node>,
    /// Names of the graph's input ports.
    pub graph_inputs: Vec<String>,
    /// Names of the graph's output ports.
    pub graph_outputs: Vec<String>,
    /// Finalized wiring between ports (no RNG state).
    pub connections: Vec<Connection>,
}

impl From<&Topology> for Spec {
    fn from(g: &Topology) -> Self {
        Spec {
            id: g.id,
            options: g.options,
            nodes: g.nodes.clone(),
            graph_inputs: g.graph_inputs.clone(),
            graph_outputs: g.graph_outputs.clone(),
            connections: g.connections.clone(),
        }
    }
}

impl Serialize for Topology {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        Spec::from(self).serialize(serializer)
    }
}

impl<'de> Deserialize<'de> for Topology {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let spec = Spec::deserialize(deserializer)?;
        let mut topology = Topology {
            id: spec.id,
            nodes: spec.nodes,
            options: spec.options,
            graph_inputs: spec.graph_inputs,
            graph_outputs: spec.graph_outputs,
            connections: spec.connections,
            // Reproducibility: the RNG is re-seeded from options.topology_seed,
            // a loaded graph regenerates wiring identically to a fresh one.
            rng: Rng::with_seed(spec.options.topology_seed as u64),
        };
        // Reading is the ONE place old wiring enters the process, and a run recorded before
        // one-wire-per-port refactor may stack wires on a port.
        topology.unstack_input_ports();
        Ok(topology)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::graph::topology::test_strategies::topology_strategy;
    use proptest::prelude::*;

    // ── serialization ───────────────────────────────────────────────────────

    #[test]
    fn test_topology_json_roundtrip() {
        let mut graph = Topology::new(7, None);
        graph.create_random_hidden_nodes(4);
        graph.refresh_labels();
        graph.finalize();
        let json = graph.to_json().unwrap();
        let loaded: Topology = Topology::from_json(&json).unwrap();
        assert_eq!(loaded.id, graph.id);
        assert_eq!(loaded.options, graph.options);
        assert_eq!(loaded.nodes, graph.nodes);
        assert_eq!(loaded.graph_inputs, graph.graph_inputs);
        assert_eq!(loaded.graph_outputs, graph.graph_outputs);
        assert_eq!(loaded.connections, graph.connections);
    }

    #[test]
    fn test_topology_json_rewiring_is_deterministic() {
        // The RNG is re-seeded from options.topology_seed on load, so a loaded graph
        // wires identically to a fresh graph with the same options.
        let mut original = Topology::new(3, None);
        original.nodes.push(Node::new_input(0, 2));
        original.nodes.push(Node::new_hidden(1, 3, 2));
        original.nodes.push(Node::new_output(2, 2, 1));

        let json = original.to_json().unwrap();
        let mut loaded = Topology::from_json(&json).unwrap();
        let mut fresh = Topology::new(3, None);
        fresh.nodes = original.nodes.clone();

        original.finalize();
        loaded.finalize();
        fresh.finalize();
        assert_eq!(loaded.connections, fresh.connections);
        assert_eq!(loaded.connections, original.connections);
    }

    #[test]
    fn test_topology_json_rebuilds_same_architecture() {
        // The blueprint is the single source of truth: saving/loading
        // re-building yields the same architecture (fresh random weights).
        use crate::graph::network::Network;
        use crate::graph::node::Activation;
        use flodl::nn::Module;
        use flodl::{Device, Tensor, TensorOptions, Variable};

        fn rand_input(batch: i64, input_dim: usize) -> Variable {
            Variable::new(
                Tensor::randn(
                    &[batch, input_dim as i64],
                    TensorOptions {
                        dtype: flodl::DType::Float32,
                        device: Device::CPU,
                    },
                )
                .unwrap(),
                false,
            )
        }

        let mut graph = Topology::new(0, None);
        graph.nodes.push(Node::new_input(0, 2));
        let mut wide = Node::new_hidden(1, 3, 2);
        wide.hidden_dim = Some(32);
        wide.activation = Activation::GeLU;
        graph.nodes.push(wide);
        graph.nodes.push(Node::new_output(2, 2, 1));
        graph.finalize();

        let module = Network::build(&graph, Device::CPU).unwrap();
        let json = graph.to_json().unwrap();
        let reloaded_graph = Topology::from_json(&json).unwrap();
        let rebuilt = Network::build(&reloaded_graph, Device::CPU).unwrap();

        // Same output node, same nodes + derived dims, same param count.
        assert_eq!(rebuilt.output_node, module.output_node);
        assert_eq!(rebuilt.nodes, module.nodes);
        assert_eq!(rebuilt.node_dims, module.node_dims);
        assert_eq!(rebuilt.parameters().len(), module.parameters().len());
        let input = rand_input(2, graph.options.input_dim.unwrap_or(1));
        assert_eq!(
            rebuilt.forward(&input).unwrap().shape(),
            module.forward(&input).unwrap().shape()
        );
    }

    // ── property tests (proptest) ───────────────────────────────────────────

    proptest! {
        /// Any random blueprint round-trips through JSON exactly: the loaded
        /// spec matches the original field-for-field.
        #[test]
        fn prop_topology_json_roundtrip(graph in topology_strategy()) {
            let json = graph.to_json().unwrap();
            let loaded: Topology = Topology::from_json(&json).unwrap();
            prop_assert_eq!(Spec::from(&loaded), Spec::from(&graph));                // Reproducibility: with both RNGs back at the seed, a reloaded
                // graph rewires identically to a fresh graph with the same options.
            let mut loaded = loaded;
            let mut fresh = graph;
            loaded.rng = fastrand::Rng::with_seed(loaded.options.topology_seed as u64);
            fresh.rng = fastrand::Rng::with_seed(fresh.options.topology_seed as u64);
            loaded.finalize();
            fresh.finalize();
            prop_assert_eq!(loaded.connections, fresh.connections);
        }
    }
}