morphml 1.0.0__py3-none-any.whl

morphml/evaluation/heuristic.py

@@ -0,0 +1,237 @@
+"""Heuristic evaluators for fast architecture assessment.
+
+These evaluators estimate architecture quality without training,
+enabling rapid architecture search and development.
+
+Example:
+    >>> from morphml.evaluation import HeuristicEvaluator
+    >>>
+    >>> evaluator = HeuristicEvaluator()
+    >>> score = evaluator.combined_score(graph)
+"""
+
+from typing import Dict
+
+from morphml.core.graph import ModelGraph
+from morphml.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class HeuristicEvaluator:
+    """
+    Fast heuristic evaluation without training.
+
+    Provides multiple proxy metrics that correlate with actual
+    performance, enabling rapid architecture assessment.
+
+    Metrics:
+    - Parameter count
+    - FLOPs estimation
+    - Graph depth
+    - Graph width
+    - Connectivity ratio
+
+    Example:
+        >>> evaluator = HeuristicEvaluator(
+        ...     param_weight=0.3,
+        ...     depth_weight=0.3,
+        ...     width_weight=0.2
+        ... )
+        >>> score = evaluator(graph)
+    """
+
+    def __init__(
+        self,
+        param_weight: float = 0.3,
+        depth_weight: float = 0.3,
+        width_weight: float = 0.2,
+        connectivity_weight: float = 0.2,
+        target_params: int = 1000000,
+        target_depth: int = 20,
+    ):
+        """
+        Initialize heuristic evaluator.
+
+        Args:
+            param_weight: Weight for parameter penalty
+            depth_weight: Weight for depth score
+            width_weight: Weight for width score
+            connectivity_weight: Weight for connectivity
+            target_params: Target parameter count
+            target_depth: Target network depth
+        """
+        self.param_weight = param_weight
+        self.depth_weight = depth_weight
+        self.width_weight = width_weight
+        self.connectivity_weight = connectivity_weight
+        self.target_params = target_params
+        self.target_depth = target_depth
+
+    def __call__(self, graph: ModelGraph) -> float:
+        """Evaluate using combined score."""
+        return self.combined_score(graph)
+
+    def parameter_score(self, graph: ModelGraph) -> float:
+        """
+        Score based on parameter count.
+
+        Penalizes large models, rewards compact ones.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Score in [0, 1]
+        """
+        params = graph.estimate_parameters()
+
+        # Sigmoid-like scoring
+        ratio = params / self.target_params
+        if ratio < 0.5:
+            score = 1.0
+        elif ratio < 1.0:
+            score = 1.0 - 0.5 * (ratio - 0.5)
+        elif ratio < 2.0:
+            score = 0.75 - 0.5 * (ratio - 1.0)
+        else:
+            score = max(0.1, 0.25 - 0.1 * (ratio - 2.0))
+
+        return score
+
+    def depth_score(self, graph: ModelGraph) -> float:
+        """
+        Score based on network depth.
+
+        Moderate depth is preferred.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Score in [0, 1]
+        """
+        depth = graph.get_depth()
+
+        if depth < 5:
+            score = 0.5 + 0.1 * depth  # Too shallow
+        elif depth <= self.target_depth:
+            score = 0.8 + 0.01 * depth  # Good range
+        else:
+            score = max(0.3, 1.0 - 0.02 * (depth - self.target_depth))  # Too deep
+
+        return min(1.0, score)
+
+    def width_score(self, graph: ModelGraph) -> float:
+        """
+        Score based on network width.
+
+        Moderate width is preferred.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Score in [0, 1]
+        """
+        width = graph.get_max_width()
+
+        if width < 3:
+            score = 0.5 + 0.1 * width
+        elif width <= 10:
+            score = 0.8 + 0.02 * width
+        else:
+            score = max(0.5, 1.0 - 0.02 * (width - 10))
+
+        return min(1.0, score)
+
+    def connectivity_score(self, graph: ModelGraph) -> float:
+        """
+        Score based on connectivity ratio.
+
+        Measures how well-connected the graph is.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Score in [0, 1]
+        """
+        num_nodes = len(graph.nodes)
+        num_edges = len(graph.edges)
+
+        if num_nodes <= 1:
+            return 0.5
+
+        # Expected edges for DAG: between n-1 (linear) and n*(n-1)/2 (complete)
+        min_edges = num_nodes - 1
+        max_edges = num_nodes * (num_nodes - 1) / 2
+
+        if num_edges < min_edges:
+            return 0.0  # Disconnected
+
+        # Normalize
+        connectivity_ratio = (num_edges - min_edges) / (max_edges - min_edges + 1)
+
+        # Prefer moderate connectivity
+        if connectivity_ratio < 0.3:
+            score = 0.6 + connectivity_ratio
+        elif connectivity_ratio < 0.7:
+            score = 0.9
+        else:
+            score = 0.9 - 0.5 * (connectivity_ratio - 0.7)
+
+        return score
+
+    def combined_score(self, graph: ModelGraph) -> float:
+        """
+        Combined heuristic score.
+
+        Weighted combination of all metrics.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Combined score in [0, 1]
+        """
+        param_score = self.parameter_score(graph)
+        depth_score = self.depth_score(graph)
+        width_score = self.width_score(graph)
+        connectivity_score = self.connectivity_score(graph)
+
+        combined = (
+            self.param_weight * param_score
+            + self.depth_weight * depth_score
+            + self.width_weight * width_score
+            + self.connectivity_weight * connectivity_score
+        )
+
+        # Ensure in [0, 1]
+        combined = max(0.0, min(1.0, combined))
+
+        logger.debug(
+            f"Heuristic scores: param={param_score:.3f}, depth={depth_score:.3f}, "
+            f"width={width_score:.3f}, connectivity={connectivity_score:.3f}, "
+            f"combined={combined:.3f}"
+        )
+
+        return combined
+
+    def get_all_scores(self, graph: ModelGraph) -> Dict[str, float]:
+        """
+        Get all individual scores.
+
+        Args:
+            graph: Architecture to evaluate
+
+        Returns:
+            Dictionary of all scores
+        """
+        return {
+            "parameter": self.parameter_score(graph),
+            "depth": self.depth_score(graph),
+            "width": self.width_score(graph),
+            "connectivity": self.connectivity_score(graph),
+            "combined": self.combined_score(graph),
+        }

morphml/exceptions.py

@@ -0,0 +1,55 @@
+"""Custom exceptions for MorphML."""
+
+
+class MorphMLError(Exception):
+    """Base exception for all MorphML errors."""
+
+    pass
+
+
+class DSLError(MorphMLError):
+    """Raised when DSL parsing or compilation fails."""
+
+    pass
+
+
+class GraphError(MorphMLError):
+    """Raised when graph operations fail."""
+
+    pass
+
+
+class SearchSpaceError(MorphMLError):
+    """Raised when search space definition is invalid."""
+
+    pass
+
+
+class OptimizerError(MorphMLError):
+    """Raised when optimizer encounters an error."""
+
+    pass
+
+
+class EvaluationError(MorphMLError):
+    """Raised when architecture evaluation fails."""
+
+    pass
+
+
+class ConfigurationError(MorphMLError):
+    """Raised when configuration is invalid."""
+
+    pass
+
+
+class DistributedError(MorphMLError):
+    """Raised when distributed operations fail."""
+
+    pass
+
+
+class ValidationError(MorphMLError):
+    """Raised when validation fails."""
+
+    pass

morphml/execution/__init__.py

@@ -0,0 +1,5 @@
+"""Execution engine for running experiments."""
+
+from morphml.execution.local_executor import LocalExecutor, run_experiment
+
+__all__ = ["LocalExecutor", "run_experiment"]

morphml/execution/local_executor.py

@@ -0,0 +1,350 @@
+"""Local executor for running experiments on a single machine.
+
+Provides LocalExecutor class for orchestrating the complete
+experiment lifecycle on a single machine.
+
+Author: Eshan Roy <eshanized@proton.me>
+Organization: TONMOY INFRASTRUCTURE & VISION
+"""
+
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from morphml.config import get_config
+from morphml.core.dsl.search_space import SearchSpace
+from morphml.core.search.search_engine import SearchEngine
+from morphml.evaluation.heuristic import HeuristicEvaluator
+from morphml.logging_config import get_logger
+from morphml.utils.checkpoint import Checkpoint
+
+logger = get_logger(__name__)
+
+
+class LocalExecutor:
+    """
+    Executes experiments on local machine.
+
+    Manages the complete experiment lifecycle:
+    1. Initialize search from search space
+    2. Run optimizer for multiple generations
+    3. Evaluate candidates using evaluator
+    4. Track results and save checkpoints
+    5. Return best model
+
+    Example:
+        >>> executor = LocalExecutor()
+        >>> results = executor.run(
+        ...     search_space=space,
+        ...     optimizer=ga,
+        ...     evaluator=evaluator,
+        ...     max_evaluations=1000
+        ... )
+        >>> best_model = results['best_graph']
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """
+        Initialize local executor.
+
+        Args:
+            config: Configuration dictionary (uses global config if None)
+        """
+        self.config = config or get_config()
+        self.logger = logger
+        self.checkpoint_dir = Path(self.config.get("checkpoints_dir", "./checkpoints"))
+        self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
+
+    def run(
+        self,
+        search_space: SearchSpace,
+        optimizer: SearchEngine,
+        evaluator: Optional[Callable] = None,
+        max_evaluations: int = 1000,
+        checkpoint_interval: int = 100,
+        callbacks: Optional[list] = None,
+        verbose: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Run complete experiment.
+
+        Args:
+            search_space: Search space definition
+            optimizer: Optimizer instance (e.g., GeneticAlgorithm)
+            evaluator: Evaluator for fitness computation (defaults to HeuristicEvaluator)
+            max_evaluations: Budget in number of evaluations
+            checkpoint_interval: Save checkpoint every N evaluations
+            callbacks: Optional callbacks to call each generation
+            verbose: Print progress information
+
+        Returns:
+            Dictionary with results:
+                - best_graph: Best architecture found
+                - best_fitness: Best fitness value
+                - num_evaluations: Total evaluations performed
+                - elapsed_time: Total time in seconds
+                - final_generation: Final generation number
+                - statistics: Final statistics
+                - history: Complete history
+
+        Example:
+            >>> executor = LocalExecutor()
+            >>> results = executor.run(
+            ...     search_space=space,
+            ...     optimizer=GeneticAlgorithm(space, config),
+            ...     max_evaluations=500
+            ... )
+        """
+        if verbose:
+            self.logger.info("=" * 70)
+            self.logger.info("Starting Experiment")
+            self.logger.info("=" * 70)
+            self.logger.info(f"Search space: {search_space.name}")
+            self.logger.info(f"Optimizer: {optimizer.__class__.__name__}")
+            self.logger.info(f"Budget: {max_evaluations} evaluations")
+
+        # Use heuristic evaluator if none provided
+        if evaluator is None:
+            if verbose:
+                self.logger.info("No evaluator provided, using HeuristicEvaluator")
+            evaluator = HeuristicEvaluator()
+
+        # Configure optimizer
+        optimizer.config["max_evaluations"] = max_evaluations
+
+        # Track progress
+        start_time = time.time()
+        num_evaluations = 0
+        last_checkpoint = 0
+
+        # Initialize population
+        if verbose:
+            self.logger.info("Initializing population...")
+
+        population = optimizer.initialize_population(optimizer.config.get("population_size", 50))
+
+        if verbose:
+            self.logger.info(f"Population initialized with {len(population)} individuals")
+
+        # Evaluate initial population
+        for individual in population.individuals:
+            if individual.fitness is None:
+                individual.set_fitness(evaluator(individual.graph))
+                num_evaluations += 1
+
+        # Track best
+        optimizer._update_best(population)
+        optimizer._record_history(population)
+
+        if verbose:
+            self.logger.info(
+                f"Initial population evaluated. Best fitness: {population.best_fitness():.4f}"
+            )
+            self.logger.info("")
+            self.logger.info("Starting evolution...")
+
+        # Main evolution loop
+        generation = 0
+        callbacks = callbacks or []
+
+        while num_evaluations < max_evaluations and not optimizer.should_stop():
+            # Evolution step
+            population = optimizer.step(population, evaluator)
+
+            # Evaluate new individuals
+            for individual in population.individuals:
+                if individual.fitness is None and num_evaluations < max_evaluations:
+                    individual.set_fitness(evaluator(individual.graph))
+                    num_evaluations += 1
+
+            # Update tracking
+            optimizer._update_best(population)
+            optimizer._record_history(population)
+            optimizer.generation = generation
+            optimizer.num_evaluations = num_evaluations
+
+            # Call callbacks
+            for callback in callbacks:
+                callback(optimizer, population)
+
+            # Checkpoint
+            if num_evaluations - last_checkpoint >= checkpoint_interval:
+                self._save_checkpoint(optimizer, num_evaluations)
+                last_checkpoint = num_evaluations
+
+            # Log progress
+            if verbose and generation % 10 == 0:
+                stats = optimizer.get_statistics()
+                elapsed = time.time() - start_time
+                evals_per_sec = num_evaluations / elapsed if elapsed > 0 else 0
+
+                self.logger.info(
+                    f"Gen {generation:3d}: "
+                    f"best={stats['best_fitness']:.4f}, "
+                    f"mean={stats['mean_fitness']:.4f}, "
+                    f"evals={num_evaluations}/{max_evaluations}, "
+                    f"({evals_per_sec:.1f} eval/s)"
+                )
+
+            generation += 1
+
+        # Finalize
+        elapsed_time = time.time() - start_time
+        best_graph = optimizer.get_best()
+        final_stats = optimizer.get_statistics()
+
+        results = {
+            "best_graph": best_graph,
+            "best_fitness": final_stats["best_fitness"],
+            "num_evaluations": num_evaluations,
+            "elapsed_time": elapsed_time,
+            "final_generation": generation,
+            "statistics": final_stats,
+            "history": optimizer.get_history(),
+        }
+
+        if verbose:
+            self.logger.info("")
+            self.logger.info("=" * 70)
+            self.logger.info("Experiment Complete")
+            self.logger.info("=" * 70)
+            self.logger.info(f"Best fitness: {final_stats['best_fitness']:.4f}")
+            self.logger.info(f"Evaluations: {num_evaluations}")
+            self.logger.info(f"Time: {elapsed_time:.2f}s")
+            self.logger.info(f"Avg time per evaluation: {elapsed_time/num_evaluations*1000:.2f}ms")
+            self.logger.info("=" * 70)
+
+        return results
+
+    def _save_checkpoint(self, optimizer: SearchEngine, num_evals: int) -> None:
+        """
+        Save optimizer state to checkpoint.
+
+        Args:
+            optimizer: Optimizer to checkpoint
+            num_evals: Current number of evaluations
+        """
+        checkpoint_path = self.checkpoint_dir / f"checkpoint_{num_evals}.pkl"
+
+        try:
+            Checkpoint.save(optimizer, str(checkpoint_path))
+            self.logger.debug(f"Checkpoint saved: {checkpoint_path}")
+        except Exception as e:
+            self.logger.warning(f"Failed to save checkpoint: {e}")
+
+    def load_checkpoint(self, checkpoint_path: str) -> SearchEngine:
+        """
+        Load optimizer from checkpoint.
+
+        Args:
+            checkpoint_path: Path to checkpoint file
+
+        Returns:
+            Restored optimizer
+
+        Example:
+            >>> executor = LocalExecutor()
+            >>> optimizer = executor.load_checkpoint("checkpoint_500.pkl")
+        """
+        checkpoint_path = Path(checkpoint_path)
+
+        if not checkpoint_path.exists():
+            raise FileNotFoundError(f"Checkpoint not found: {checkpoint_path}")
+
+        self.logger.info(f"Loading checkpoint: {checkpoint_path}")
+        optimizer = Checkpoint.load(str(checkpoint_path))
+
+        self.logger.info(
+            f"Checkpoint loaded: generation {optimizer.generation}, "
+            f"{optimizer.num_evaluations} evaluations"
+        )
+
+        return optimizer
+
+    def resume(
+        self,
+        checkpoint_path: str,
+        search_space: SearchSpace,
+        evaluator: Optional[Callable] = None,
+        max_additional_evaluations: int = 500,
+        verbose: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Resume experiment from checkpoint.
+
+        Args:
+            checkpoint_path: Path to checkpoint file
+            search_space: Search space (must match checkpointed experiment)
+            evaluator: Evaluator for fitness computation
+            max_additional_evaluations: Additional evaluation budget
+            verbose: Print progress information
+
+        Returns:
+            Results dictionary
+
+        Example:
+            >>> executor = LocalExecutor()
+            >>> results = executor.resume(
+            ...     "checkpoint_500.pkl",
+            ...     search_space=space,
+            ...     max_additional_evaluations=500
+            ... )
+        """
+        # Load checkpoint
+        optimizer = self.load_checkpoint(checkpoint_path)
+
+        # Calculate remaining budget
+        prev_evals = optimizer.num_evaluations
+        total_budget = prev_evals + max_additional_evaluations
+
+        if verbose:
+            self.logger.info(f"Resuming from {prev_evals} evaluations")
+            self.logger.info(f"Additional budget: {max_additional_evaluations}")
+            self.logger.info(f"Total budget: {total_budget}")
+
+        # Continue execution
+        return self.run(
+            search_space=search_space,
+            optimizer=optimizer,
+            evaluator=evaluator,
+            max_evaluations=total_budget,
+            verbose=verbose,
+        )
+
+
+# Convenience function
+def run_experiment(
+    search_space: SearchSpace,
+    optimizer: SearchEngine,
+    evaluator: Optional[Callable] = None,
+    max_evaluations: int = 1000,
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    Convenience function to run experiment.
+
+    Args:
+        search_space: Search space definition
+        optimizer: Optimizer instance
+        evaluator: Evaluator function
+        max_evaluations: Evaluation budget
+        **kwargs: Additional arguments for LocalExecutor.run()
+
+    Returns:
+        Results dictionary
+
+    Example:
+        >>> results = run_experiment(
+        ...     search_space=space,
+        ...     optimizer=ga,
+        ...     max_evaluations=1000
+        ... )
+    """
+    executor = LocalExecutor()
+    return executor.run(
+        search_space=search_space,
+        optimizer=optimizer,
+        evaluator=evaluator,
+        max_evaluations=max_evaluations,
+        **kwargs,
+    )

morphml/integrations/__init__.py

@@ -0,0 +1,28 @@
+"""Framework integrations for MorphML.
+
+Provides adapters to convert ModelGraph architectures to various ML frameworks:
+- PyTorch (with training support)
+- TensorFlow/Keras
+- JAX/Flax
+- Scikit-learn
+
+Example:
+    >>> from morphml.integrations import PyTorchAdapter
+    >>> adapter = PyTorchAdapter()
+    >>> model = adapter.build_model(graph)
+    >>> trainer = adapter.get_trainer(model, config)
+    >>> results = trainer.train(train_loader, val_loader)
+"""
+
+from morphml.integrations.jax_adapter import JAXAdapter
+from morphml.integrations.pytorch_adapter import PyTorchAdapter, PyTorchTrainer
+from morphml.integrations.sklearn_adapter import SklearnAdapter
+from morphml.integrations.tensorflow_adapter import TensorFlowAdapter
+
+__all__ = [
+    "PyTorchAdapter",
+    "PyTorchTrainer",
+    "TensorFlowAdapter",
+    "JAXAdapter",
+    "SklearnAdapter",
+]