Add population-scale opinion dynamics with homophily-based network assignment

Implements Phase 3 enhancement for large-scale simulations (10-200+ nodes).

New Features:
=============

🌐 Population Network Module (src/influence/population_network.py):
- PopulationNetwork class for large-scale opinion dynamics
- Integrates Phase 2 variant generator with Phase 3 networks
- Homophily-based persona assignment to network nodes
- Supports 10-200+ node populations

Homophily Algorithm:
- Parameter range: 0.0 (random) to 1.0 (maximum clustering)
- Uses BFS traversal to assign personas based on similarity
- High homophily: similar personas become neighbors (echo chambers)
- Low homophily: diverse mixing across network
- Calculates similarity based on:
* Shared values (40%)
* Political alignment (30%)
* Age similarity (15%)
* Education similarity (15%)

Enhanced Influence Network (src/influence/network.py):
- Added homophily parameter to InfluenceNetwork class
- New method: calculate_persona_similarity() for homophily assignment
- New method: get_persona_base_type() to extract base persona from variants
- Supports persona variant tracking (e.g., "sarah_chen_v0", "sarah_chen_v1")

Population Generation:
- Distributes population_size across 6 base personas
- Uses Phase 2 VariantGenerator with configurable variation levels
- Creates realistic demographic variance within persona types
- Maintains core persona characteristics while adding diversity

Network Topology Options:
- Scale-Free (Barabási-Albert): Power-law distribution with hubs
- Small-World (Watts-Strogatz): Clustered communities with shortcuts
- Fully Connected: Complete graph (baseline)

Use Cases:
==========
1. Model echo chambers vs diverse neighborhoods
2. Study how homophily affects consensus formation
3. Compare network structure effects at population scale
4. Analyze opinion leader emergence in large networks

Example:
--------
# Create 100-node scale-free network with high homophily
pop_network = PopulationNetwork(
base_personas=base_personas,
population_size=100,
network_type="scale_free",
homophily=0.8, # High clustering
variation_level=VariationLevel.MODERATE
)

# Network stats
stats = pop_network.get_network_stats()
# Returns: nodes, edges, avg_degree, density, base_persona_distribution

Technical Details:
==================
- BFS-based assignment ensures connected clusters
- Similarity calculations reuse influence weight logic
- Node-to-persona mapping tracked for visualization
- Compatible with existing opinion dynamics engine
- Supports networkx graph operations

Next Steps:
- Update Phase 3 UI to add population mode
- Implement dual-color node visualization (persona + opinion cluster)
- Add population size and homophily sliders

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/influence/__init__.py

@@ -10,6 +10,7 @@ from .models import (
 from .network import InfluenceNetwork
 from .dynamics import OpinionDynamicsEngine
 from .equilibrium import EquilibriumDetector
+from .population_network import PopulationNetwork
 
 __all__ = [
     "OpinionPosition",
@@ -20,4 +21,5 @@ __all__ = [
     "InfluenceNetwork",
     "OpinionDynamicsEngine",
     "EquilibriumDetector",
+    "PopulationNetwork",
 ]

src/influence/network.py

@@ -33,6 +33,7 @@ class InfluenceNetwork:
         personas: List[Persona],
         network_type: NetworkType = "scale_free",
         random_seed: int = None,
+        homophily: float = 0.0,
     ):
         """
         Initialize influence network.
@@ -41,10 +42,13 @@ class InfluenceNetwork:
             personas: List of personas to include
             network_type: Network topology ("fully_connected", "scale_free", "small_world")
             random_seed: Random seed for reproducibility
+            homophily: Homophily parameter (0-1). Higher = similar personas cluster together
         """
         self.personas = {p.persona_id: p for p in personas}
         self.network_type = network_type
+        self.homophily = homophily
         self.influence_matrix: Dict[Tuple[str, str], InfluenceWeight] = {}
+        self.persona_assignment: Dict[int, str] = {}  # node_id -> persona_id mapping
 
         if random_seed is not None:
             random.seed(random_seed)
@@ -360,3 +364,45 @@ class InfluenceNetwork:
                     "factors": weight.factors,
                 })
         return edges
+
+    def calculate_persona_similarity(self, p1: Persona, p2: Persona) -> float:
+        """
+        Calculate overall similarity between two personas (0-1).
+
+        Used for homophily-based network assignment.
+        Higher values = more similar personas.
+        """
+        # Reuse existing similarity calculations
+        shared_values = self._calculate_shared_values(p1, p2)
+        political = self._calculate_political_alignment(p1, p2)
+
+        # Add demographic similarity
+        age_diff = abs(p1.demographics.age - p2.demographics.age) / 100.0
+        age_similarity = 1.0 - min(age_diff, 1.0)
+
+        # Education similarity (same level = 1.0, different = 0.5)
+        edu_similarity = 1.0 if p1.demographics.education == p2.demographics.education else 0.5
+
+        # Weighted combination
+        similarity = (
+            shared_values * 0.4 +
+            political * 0.3 +
+            age_similarity * 0.15 +
+            edu_similarity * 0.15
+        )
+
+        return similarity
+
+    @staticmethod
+    def get_persona_base_type(persona: Persona) -> str:
+        """
+        Extract base persona type from persona_id.
+
+        For variants, returns the base persona name.
+        E.g., "sarah_chen_v0" -> "sarah_chen"
+        """
+        persona_id = persona.persona_id
+        # Remove variant suffix if present
+        if "_v" in persona_id:
+            return persona_id.rsplit("_v", 1)[0]
+        return persona_id

src/influence/population_network.py

@@ -0,0 +1,250 @@
+"""Population-scale opinion dynamics with homophily-based network assignment"""
+
+from typing import List, Dict, Tuple
+import random
+import networkx as nx
+
+from ..personas.models import Persona
+from ..population.variant_generator import VariantGenerator, VariationLevel
+from .network import InfluenceNetwork, NetworkType
+
+
+class PopulationNetwork:
+    """
+    Creates population-scale networks with homophily-based persona assignment.
+
+    Combines Phase 2 (population variants) with Phase 3 (opinion networks).
+    """
+
+    def __init__(
+        self,
+        base_personas: List[Persona],
+        population_size: int,
+        network_type: NetworkType = "scale_free",
+        homophily: float = 0.5,
+        variation_level: VariationLevel = VariationLevel.MODERATE,
+        random_seed: int = None,
+    ):
+        """
+        Initialize population network.
+
+        Args:
+            base_personas: List of base personas to create variants from
+            population_size: Total number of nodes in network
+            network_type: Network topology
+            homophily: Homophily parameter (0-1, higher = more clustering)
+            variation_level: How much to vary persona characteristics
+            random_seed: Random seed for reproducibility
+        """
+        self.base_personas = base_personas
+        self.population_size = population_size
+        self.network_type = network_type
+        self.homophily = homophily
+        self.variation_level = variation_level
+
+        if random_seed is not None:
+            random.seed(random_seed)
+
+        # Generate population variants
+        self.variants = self._generate_population_variants()
+
+        # Create network topology
+        self.network_graph = self._create_network_topology()
+
+        # Assign personas to nodes with homophily
+        self.node_to_persona = self._assign_personas_with_homophily()
+
+        # Build influence network
+        self.influence_network = InfluenceNetwork(
+            personas=self.variants,
+            network_type=network_type,
+            homophily=homophily,
+        )
+
+    def _generate_population_variants(self) -> List[Persona]:
+        """Generate population variants from base personas"""
+        variants = []
+
+        # Distribute population across base personas
+        variants_per_base = self.population_size // len(self.base_personas)
+        remainder = self.population_size % len(self.base_personas)
+
+        for i, base_persona in enumerate(self.base_personas):
+            # Generate variants for this base persona
+            count = variants_per_base + (1 if i < remainder else 0)
+
+            generator = VariantGenerator(base_persona, self.variation_level)
+            persona_variants = [
+                generator.generate_variant(f"_v{len(variants) + j}")
+                for j in range(count)
+            ]
+            variants.extend(persona_variants)
+
+        return variants
+
+    def _create_network_topology(self) -> nx.Graph:
+        """Create network topology graph"""
+        n = self.population_size
+
+        if self.network_type == "fully_connected":
+            return nx.complete_graph(n)
+
+        elif self.network_type == "scale_free":
+            # Barabási-Albert
+            m = max(2, min(5, n // 10))  # Edges to attach per new node
+            return nx.barabasi_albert_graph(n, m)
+
+        elif self.network_type == "small_world":
+            # Watts-Strogatz
+            k = max(4, min(10, n // 5))  # Nearest neighbors
+            if k % 2 != 0:
+                k -= 1
+            p = 0.1  # Rewiring probability
+            return nx.watts_strogatz_graph(n, k, p)
+
+        else:
+            raise ValueError(f"Unknown network type: {self.network_type}")
+
+    def _assign_personas_with_homophily(self) -> Dict[int, str]:
+        """
+        Assign persona variants to network nodes using homophily.
+
+        Higher homophily = similar personas become neighbors.
+        """
+        node_to_persona = {}
+
+        if self.homophily <= 0.1:
+            # Random assignment (low homophily)
+            shuffled_variants = random.sample(self.variants, len(self.variants))
+            for node_id in self.network_graph.nodes():
+                node_to_persona[node_id] = shuffled_variants[node_id].persona_id
+            return node_to_persona
+
+        # High homophily: use similarity-based assignment
+        # Start with one random node
+        assigned_nodes = set()
+        unassigned_personas = {v.persona_id: v for v in self.variants}
+
+        # Pick random starting node and persona
+        start_node = random.choice(list(self.network_graph.nodes()))
+        start_persona = random.choice(list(unassigned_personas.values()))
+        node_to_persona[start_node] = start_persona.persona_id
+        assigned_nodes.add(start_node)
+        del unassigned_personas[start_persona.persona_id]
+
+        # Assign remaining nodes using BFS with similarity
+        while assigned_nodes and unassigned_personas:
+            # Pick a random assigned node
+            current_node = random.choice(list(assigned_nodes))
+            current_persona_id = node_to_persona[current_node]
+            current_persona = next(
+                v for v in self.variants if v.persona_id == current_persona_id
+            )
+
+            # Find unassigned neighbors
+            neighbors = [
+                n for n in self.network_graph.neighbors(current_node)
+                if n not in assigned_nodes
+            ]
+
+            if not neighbors:
+                assigned_nodes.remove(current_node)
+                continue
+
+            # Pick a random unassigned neighbor
+            neighbor = random.choice(neighbors)
+
+            # Assign persona based on homophily
+            if random.random() < self.homophily:
+                # High homophily: pick most similar persona
+                best_persona = self._find_most_similar_persona(
+                    current_persona, list(unassigned_personas.values())
+                )
+            else:
+                # Random choice (reduces homophily effect)
+                best_persona = random.choice(list(unassigned_personas.values()))
+
+            node_to_persona[neighbor] = best_persona.persona_id
+            assigned_nodes.add(neighbor)
+            del unassigned_personas[best_persona.persona_id]
+
+        # Assign any remaining unassigned nodes (shouldn't happen, but safety)
+        remaining_personas = list(unassigned_personas.values())
+        for node_id in self.network_graph.nodes():
+            if node_id not in node_to_persona and remaining_personas:
+                persona = remaining_personas.pop()
+                node_to_persona[node_id] = persona.persona_id
+
+        return node_to_persona
+
+    def _find_most_similar_persona(
+        self, reference: Persona, candidates: List[Persona]
+    ) -> Persona:
+        """Find the most similar persona from candidates"""
+        if not candidates:
+            return None
+
+        similarities = [
+            (
+                p,
+                self.influence_network.calculate_persona_similarity(reference, p)
+                if hasattr(self, 'influence_network')
+                else self._quick_similarity(reference, p)
+            )
+            for p in candidates
+        ]
+
+        return max(similarities, key=lambda x: x[1])[0]
+
+    def _quick_similarity(self, p1: Persona, p2: Persona) -> float:
+        """Quick similarity calculation (when influence network not yet built)"""
+        # Political alignment
+        scale = {
+            "very_progressive": -2,
+            "progressive": -1,
+            "moderate": 0,
+            "independent": 0,
+            "conservative": 1,
+            "very_conservative": 2,
+        }
+        pos1 = scale.get(p1.psychographics.political_leaning, 0)
+        pos2 = scale.get(p2.psychographics.political_leaning, 0)
+        political_sim = 1.0 - (abs(pos1 - pos2) / 4.0)
+
+        # Age similarity
+        age_sim = 1.0 - min(abs(p1.demographics.age - p2.demographics.age) / 100.0, 1.0)
+
+        return (political_sim * 0.6 + age_sim * 0.4)
+
+    def get_persona_for_node(self, node_id: int) -> Persona:
+        """Get the persona assigned to a specific node"""
+        persona_id = self.node_to_persona[node_id]
+        return next(v for v in self.variants if v.persona_id == persona_id)
+
+    def get_base_type_for_node(self, node_id: int) -> str:
+        """Get the base persona type for a node"""
+        persona = self.get_persona_for_node(node_id)
+        return InfluenceNetwork.get_persona_base_type(persona)
+
+    def get_neighbors(self, node_id: int) -> List[int]:
+        """Get neighboring nodes"""
+        return list(self.network_graph.neighbors(node_id))
+
+    def get_network_stats(self) -> Dict[str, any]:
+        """Get network statistics"""
+        return {
+            "nodes": self.network_graph.number_of_nodes(),
+            "edges": self.network_graph.number_of_edges(),
+            "avg_degree": sum(dict(self.network_graph.degree()).values()) / self.population_size,
+            "density": nx.density(self.network_graph),
+            "homophily": self.homophily,
+            "base_persona_distribution": self._calculate_base_distribution(),
+        }
+
+    def _calculate_base_distribution(self) -> Dict[str, int]:
+        """Calculate distribution of base persona types"""
+        distribution = {}
+        for node_id in self.network_graph.nodes():
+            base_type = self.get_base_type_for_node(node_id)
+            distribution[base_type] = distribution.get(base_type, 0) + 1
+        return distribution