topasmoo 0.2.0__py3-none-any.whl

TopasMOO/__init__.py

@@ -0,0 +1,81 @@
+"""
+TopasMOO: Multi-Objective Optimization for TOPAS Monte Carlo Simulations
+
+TopasMOO extends the TopasOpt framework to handle multiple competing objectives
+using pymoo algorithms, particularly NSGA-II.
+
+Each optimization must import:
+``NSGAII_Optimizer``
+    The optimizer you construct and run (``.RunOptimization()``). This is the
+    main entry point for most users.
+``TopasMOOBaseClass``
+    Base class to subclass if you want to drive a different pymoo algorithm.
+
+The full visualization toolbox (Pareto fronts, petal diagrams, convergence plots,
+etc.) lives in the TopasMOO.plotting subpackage; only the style entry
+points are re-exported here for convenience. Pareto-analysis metrics live in
+TopasMOO.metrics and log helpers in TopasMOO.io.
+"""
+
+import importlib.metadata
+
+__author__ = "Mindy Harkness"
+try:
+    __version__ = importlib.metadata.version("topasmoo")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.2.0-dev"
+
+# Exceptions
+from .exceptions import (
+    InvalidParameterError,
+    MalformedOutputError,
+    ObjectiveFunctionError,
+    TopasExecutionError,
+    TopasMOOError,
+)
+
+# I/O utilities
+from .io import LogParetoFrontToFile, ReadInMultiObjectiveLogFile
+
+# Metrics
+from .metrics import (
+    calculate_crowding_distance,
+    calculate_dominance_rank,
+    calculate_knee_point,
+)
+
+# Core optimizer classes (TopasProblem is an internal pymoo adapter that stays
+# in TopasMOO.optimizers).
+from .optimizers import NSGAII_Optimizer, TopasMOOBaseClass
+
+# Plotting style entry points (the full plotting API lives in TopasMOO.plotting).
+from .plotting import (
+    apply_style,
+    available_publication_variants,
+    publication_style,
+    save_publication_figure,
+)
+
+__all__ = [
+    # Core classes
+    "NSGAII_Optimizer",
+    "TopasMOOBaseClass",
+    # Exceptions
+    "TopasMOOError",
+    "TopasExecutionError",
+    "InvalidParameterError",
+    "ObjectiveFunctionError",
+    "MalformedOutputError",
+    # Metrics
+    "calculate_knee_point",
+    "calculate_crowding_distance",
+    "calculate_dominance_rank",
+    # IO
+    "ReadInMultiObjectiveLogFile",
+    "LogParetoFrontToFile",
+    # Plotting style entry points (full plotting API under TopasMOO.plotting)
+    "apply_style",
+    "available_publication_variants",
+    "publication_style",
+    "save_publication_figure",
+]

TopasMOO/exceptions.py

@@ -0,0 +1,23 @@
+"""
+Custom exception classes for TopasMOO.
+"""
+
+
+class TopasMOOError(Exception):
+    """Base exception for all TopasMOO errors."""
+
+
+class TopasExecutionError(TopasMOOError):
+    """Raised when a TOPAS simulation fails to execute."""
+
+
+class InvalidParameterError(TopasMOOError):
+    """Raised when optimization parameters are invalid or inconsistent."""
+
+
+class ObjectiveFunctionError(TopasMOOError):
+    """Raised when the objective function returns unexpected results."""
+
+
+class MalformedOutputError(TopasMOOError):
+    """Raised when TOPAS output files are missing or malformed."""

TopasMOO/io.py

@@ -0,0 +1,118 @@
+"""
+I/O utilities for reading and writing TopasMOO optimization logs.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterable, Sequence
+from typing import TYPE_CHECKING, Union
+
+from .exceptions import MalformedOutputError
+
+if TYPE_CHECKING:
+    import numpy as np
+
+logger = logging.getLogger(__name__)
+
+PathLike = Union[str, os.PathLike]
+
+
+def ReadInMultiObjectiveLogFile(LogFilePath: PathLike) -> dict[str, list[float]]:
+    """Read a multi-objective optimization log file into a dictionary.
+
+    Parses the comma-separated log format produced by TopasMOO during
+    optimization, extracting iteration numbers, parameter values, and
+    objective function values.
+
+    :param LogFilePath: Path to the optimization log file
+        (typically ``logs/OptimizationLogs.txt``).
+
+    :returns: Dictionary mapping column names to lists of float values.
+        Keys include ``'Iteration'``, parameter names, and
+        ``'ObjectiveFunction_1'``, ``'ObjectiveFunction_2'``, etc.
+
+    :raises FileNotFoundError: If the log file does not exist.
+    :raises MalformedOutputError: If a data row contains a non-numeric value
+        after the ``key: value`` split.
+    """
+    log_path = os.fspath(LogFilePath)
+    if not os.path.isfile(log_path):
+        raise FileNotFoundError(f"Could not find log file at {log_path}")
+
+    results: dict[str, list[float]] = {}
+    with open(log_path, "r") as f:
+        lines = f.readlines()
+
+    if not lines:
+        return results
+
+    if not any("Iteration" in line for line in lines):
+        logger.warning("Log file format not recognized or empty: %s", log_path)
+        return results
+
+    for line_number, line in enumerate(lines, start=1):
+        if not line.startswith("Iteration"):
+            continue
+        for entry in line.split(","):
+            parts = entry.split(":")
+            if len(parts) < 2:
+                continue
+
+            key = parts[0].strip()
+            raw_value = parts[1].strip()
+            try:
+                value = float(raw_value)
+            except ValueError as exc:
+                raise MalformedOutputError(
+                    f"Could not parse value '{raw_value}' for key '{key}' "
+                    f"on line {line_number} of {log_path}"
+                ) from exc
+
+            results.setdefault(key, []).append(value)
+
+    return results
+
+
+def LogParetoFrontToFile(
+    LogFilePath: PathLike,
+    ParetoObjectives: np.ndarray | Iterable[Iterable[float]],
+    ParameterNames: Sequence[str],
+    n_objectives: int,
+    ParetoDecisionVars: np.ndarray | Iterable[Iterable[float]] | None = None,
+) -> None:
+    """Write the current Pareto front to a CSV-style log file.
+
+    :param LogFilePath: Output file path.
+    :param ParetoObjectives: Array of shape ``(n_solutions, n_objectives)``
+        containing objective values for all non-dominated solutions.
+    :param ParameterNames: Decision-variable names, used as the column headers for
+        the decision-variable values when ``ParetoDecisionVars`` is given.
+    :param n_objectives: Number of objective functions.
+    :param ParetoDecisionVars: Optional array of shape
+        ``(n_solutions, len(ParameterNames))`` aligned row-for-row with
+        ``ParetoObjectives``. When provided, each parameter is written as an
+        additional column so the file fully describes each solution. When
+        ``None``, only objective columns are written.
+    """
+    with open(os.fspath(LogFilePath), "w") as f:
+        header = "Solution_Index"
+        for i in range(n_objectives):
+            header += f",Objective_{i+1}"
+        if ParetoDecisionVars is not None:
+            for name in ParameterNames:
+                header += f",{name}"
+        header += "\n"
+        f.write(header)
+
+        decision_rows = list(ParetoDecisionVars) if ParetoDecisionVars is not None else None
+        for i, objectives in enumerate(ParetoObjectives):
+            line = f"{i}"
+            for obj_val in objectives:
+                line += f",{obj_val:.6f}"
+            if decision_rows is not None:
+                for var_val in decision_rows[i]:
+                    line += f",{var_val:.6f}"
+            line += "\n"
+            f.write(line)

TopasMOO/metrics.py

@@ -0,0 +1,141 @@
+"""
+Multi-objective optimization metrics for Pareto front analysis.
+
+All metrics assume minimization of objectives.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def normalize_objectives(
+    objectives: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Min-max normalize objectives per column to ``[0, 1]``.
+
+    Each objective (column) is scaled by its observed range across the given
+    solutions. Columns with zero range (a single distinct value) are left at
+    ``0`` rather than dividing by zero.
+
+    :param objectives: Array of shape ``(n_solutions, n_objectives)``.
+
+    :returns: Tuple ``(normalized, ideal, nadir)`` where ``ideal`` and ``nadir`` are
+        the per-objective minimum and maximum, and ``normalized`` has the same
+        shape as ``objectives``.
+    """
+    objectives = np.asarray(objectives, dtype=float)
+    ideal = objectives.min(axis=0)
+    nadir = objectives.max(axis=0)
+    obj_range = nadir - ideal
+    obj_range[obj_range == 0] = 1
+    normalized = (objectives - ideal) / obj_range
+    return normalized, ideal, nadir
+
+
+def calculate_knee_point(pareto_objectives: np.ndarray) -> int:
+    """Find the knee point (best trade-off) on a Pareto front.
+
+    Uses a trade-off method: the knee is the solution with the minimum
+    sum of min-max normalized objectives, representing the best balanced
+    compromise across all objectives.
+
+    :param pareto_objectives: Array of shape ``(n_solutions, n_objectives)``.
+        All objectives are assumed to be minimized.
+
+    :returns: Index (int) of the knee point solution in the input array.
+    """
+    normalized, _ideal, _nadir = normalize_objectives(pareto_objectives)
+
+    total_objectives = normalized.sum(axis=1)
+    return int(np.argmin(total_objectives))
+
+
+def calculate_crowding_distance(pareto_objectives: np.ndarray) -> np.ndarray:
+    """Calculate NSGA-II crowding distance for each solution.
+
+    Crowding distance measures how isolated a solution is in objective
+    space.  Higher values indicate solutions in less crowded regions,
+    which are preferred during selection to maintain diversity.
+
+    Boundary solutions (best/worst in any single objective) receive
+    infinite crowding distance.
+
+    :param pareto_objectives: Array of shape ``(n_solutions, n_objectives)``.
+
+    :returns: Array of crowding distances with shape ``(n_solutions,)``.
+    """
+    n_solutions, n_objectives = pareto_objectives.shape
+
+    if n_solutions <= 2:
+        return np.full(n_solutions, np.inf)
+
+    crowding = np.zeros(n_solutions)
+
+    for m in range(n_objectives):
+        sorted_indices = np.argsort(pareto_objectives[:, m])
+        obj_values = pareto_objectives[sorted_indices, m]
+
+        crowding[sorted_indices[0]] = np.inf
+        crowding[sorted_indices[-1]] = np.inf
+
+        obj_range = obj_values[-1] - obj_values[0]
+        if obj_range == 0:
+            continue
+
+        for i in range(1, n_solutions - 1):
+            crowding[sorted_indices[i]] += (
+                obj_values[i + 1] - obj_values[i - 1]
+            ) / obj_range
+
+    return crowding
+
+
+def calculate_dominance_rank(objectives: np.ndarray) -> np.ndarray:
+    """Assign dominance ranks using fast non-dominated sorting.
+
+    Rank 0 contains the Pareto front (non-dominated solutions).
+    Rank 1 contains solutions dominated only by rank-0 solutions,
+    and so on.
+
+    All objectives are assumed to be minimized.
+
+    :param objectives: Array of shape ``(n_solutions, n_objectives)``.
+
+    :returns: Integer array of dominance ranks with shape ``(n_solutions,)``.
+    """
+    n_solutions = len(objectives)
+    domination_count = np.zeros(n_solutions, dtype=int)
+    dominated_solutions = [[] for _ in range(n_solutions)]
+    ranks = np.zeros(n_solutions, dtype=int)
+
+    for i in range(n_solutions):
+        for j in range(i + 1, n_solutions):
+            if np.all(objectives[i] <= objectives[j]) and np.any(
+                objectives[i] < objectives[j]
+            ):
+                dominated_solutions[i].append(j)
+                domination_count[j] += 1
+            elif np.all(objectives[j] <= objectives[i]) and np.any(
+                objectives[j] < objectives[i]
+            ):
+                dominated_solutions[j].append(i)
+                domination_count[i] += 1
+
+    current_front = np.where(domination_count == 0)[0]
+    rank = 0
+
+    while len(current_front) > 0:
+        ranks[current_front] = rank
+        next_front = []
+
+        for i in current_front:
+            for j in dominated_solutions[i]:
+                domination_count[j] -= 1
+                if domination_count[j] == 0:
+                    next_front.append(j)
+
+        current_front = np.array(next_front)
+        rank += 1
+
+    return ranks