PyTracerLab 0.2.0__py3-none-any.whl

PyTracerLab/__init__.py

@@ -0,0 +1,8 @@
+"""PyTracerLab package initializer."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("PyTracerLab")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"

PyTracerLab/__main__.py

@@ -0,0 +1,7 @@
+"""Console entry point for launching the PyTracerLab GUI."""
+
+# from PyTracerLab.app import main
+from PyTracerLab.gui.app import main
+
+if __name__ == "__main__":
+    main()

PyTracerLab/gui/__init__.py

@@ -0,0 +1,10 @@
+"""
+PyTracerLab GUI subpackage.
+
+Contains the main PyQt5 application window, tabs, and controller/state logic.
+"""
+
+from .app import main
+from .main_window import MainWindow
+
+__all__ = ["main", "MainWindow"]

PyTracerLab/gui/app.py

@@ -0,0 +1,15 @@
+"""Application entry point for the PyTracerLab GUI."""
+
+import sys
+
+from PyQt5.QtWidgets import QApplication
+
+from .main_window import MainWindow
+
+
+def main():
+    """Launch the Qt application and show the main window."""
+    app = QApplication(sys.argv)
+    w = MainWindow()
+    w.show()
+    sys.exit(app.exec_())

PyTracerLab/gui/controller.py

@@ -0,0 +1,419 @@
+"""Qt controller that builds the model and runs simulations/solvers."""
+
+import matplotlib.pyplot as plt
+import numpy as np
+from PyQt5.QtCore import QObject, pyqtSignal
+
+from ..model import model as mm
+from ..model import solver as ms
+from ..model.registry import UNIT_REGISTRY
+from .database import Tracers
+
+
+class Controller(QObject):
+    """Bridge between GUI state and the computational model.
+
+    Orchestrates model construction from GUI state, runs simulations and
+    calibrations, and emits signals with results or errors.
+
+    Signals
+    -------
+    simulated : object
+        Emitted after a forward simulation; carries a NumPy array.
+    calibrated : object
+        Emitted after calibration; carries a payload ``dict`` with simulation
+        and optional envelopes/metadata.
+    status : str
+        Short user-facing status messages.
+    error : str
+        Error messages suitable for display.
+    """
+
+    # Use generic object payloads to support arrays or dicts from different solvers
+    simulated = pyqtSignal(object)
+    calibrated = pyqtSignal(object)
+    tracer_tracer_ready = pyqtSignal(object)
+    status = pyqtSignal(str)
+    error = pyqtSignal(str)
+
+    def __init__(self, state):
+        """Initialize the controller with a shared :class:`AppState`."""
+        super().__init__()
+        self.state = state
+        self.ml = None
+
+    def build_model(self):
+        """Construct a :class:`~PyTracerLab.model.model.Model` from current state.
+
+        Creates per-instance units (including bounds and fixed flags) based on
+        the detailed design in ``state.design_instances`` and the per-instance
+        parameters in ``state.params``.
+        """
+        try:
+            # We generally work in months (dt = 1.0); for yearly calculations
+            # we therefore have to use dt = 12.0
+            dt = 1.0 if self.state.is_monthly else 12.0
+            # Determine tracer set from state (dual-tracer aware)
+            tracer_names = []
+            t1 = getattr(self.state, "tracer1", None)
+            t2 = getattr(self.state, "tracer2", None)
+            if t1:
+                tracer_names.append(t1)
+            elif hasattr(self.state, "tracer") and getattr(self.state, "tracer"):
+                # single-tracer fallback
+                tracer_names.append(getattr(self.state, "tracer"))
+            if t2 and str(t2).lower() not in {"none", ""}:
+                tracer_names.append(t2)
+
+            # Determine the decay constants for the selected tracers
+            lam = []
+            for name, half_life in Tracers.tracer_data.items():
+                if name in tracer_names:
+                    lam.append(0.693 / (half_life * 12.0))  # convert to monthly
+            if len(lam) == 1:
+                lam = lam[0]
+
+            # Determine steady state input for the cases of one or two tracers
+            n_tracers = len(tracer_names) if tracer_names else 1
+            steady_state_input = getattr(self.state, "steady_state_input", None)
+            if steady_state_input is None:
+                ss_val = None
+            elif n_tracers == 1:
+                if isinstance(steady_state_input, (list, tuple)):
+                    ss_val = float(steady_state_input[0]) if steady_state_input else 0.0
+                else:
+                    ss_val = float(steady_state_input)
+            else:
+                if isinstance(steady_state_input, (list, tuple)):
+                    ss_seq = [float(v) for v in steady_state_input]
+                else:
+                    ss_seq = [float(steady_state_input)] * n_tracers
+                if len(ss_seq) != n_tracers:
+                    if len(ss_seq) == 1:
+                        ss_seq = ss_seq * n_tracers
+                    else:
+                        raise ValueError("steady_state_input must provide one value per tracer")
+                ss_val = ss_seq
+
+            steady_enabled = bool(getattr(self.state, "steady_state_enabled", False))
+            if not steady_enabled:
+                ss_val = None
+
+            # Set up the model
+            x = self.state.input_series
+            y = self.state.target_series
+            x = (x[0], x[1])
+
+            self.ml = mm.Model(
+                dt,
+                lam,
+                input_series=x[1] if x else None,
+                target_series=y[1] if y else None,
+                steady_state_input=ss_val,
+                n_warmup_half_lives=self.state.n_warmup_half_lives,
+                time_steps=x[0] if x else None,
+            )
+
+            # Build per-instance units based on the detailed design
+            instances = getattr(self.state, "design_instances", [])
+            for inst in instances:
+                unit_name: str = inst["name"]
+                prefix: str = inst["prefix"]
+                frac: float = float(inst.get("fraction", 0.0))
+
+                cls = UNIT_REGISTRY[unit_name]
+                spec = getattr(cls, "PARAMS", [])
+
+                # Parameter values with safe defaults
+                kwargs = {}
+                for p in spec:
+                    key = p["key"]
+                    default_val = p.get("default")
+                    rec = self.state.params.get(prefix, {}).get(key)
+
+                    # Handle parameters with time units
+                    # We always work in monthly resolution but always
+                    # get parameters with time units "years". We therefore
+                    # have to convert them to monthly values. The default
+                    # value is also given in years.
+                    param_value = rec["val"] if rec is not None else default_val
+                    param_name = p.get("key")
+
+                    if param_name == "mtt":
+                        param_value *= 12
+
+                    kwargs[key] = param_value
+
+                unit = cls(**kwargs)
+
+                # Bounds with safe defaults
+                bounds = []
+                for p in spec:
+                    key = p["key"]
+                    default_lb, default_ub = p.get("bounds", (None, None))
+                    rec = self.state.params.get(prefix, {}).get(key)
+                    lb = rec["lb"] if rec is not None else default_lb
+                    ub = rec["ub"] if rec is not None else default_ub
+
+                    # convert mtt bounds to monthly time units
+                    if key == "mtt":
+                        lb *= 12
+                        ub *= 12
+
+                    bounds.append((lb, ub))
+
+                self.ml.add_unit(
+                    unit=unit,
+                    fraction=frac,
+                    prefix=prefix,
+                    bounds=bounds,
+                )
+
+                # Fixed flags
+                for p in spec:
+                    key = p["key"]
+                    rec = self.state.params.get(prefix, {}).get(key)
+                    if rec is not None and rec.get("fixed", False):
+                        self.ml.set_fixed(f"{prefix}.{key}", True)
+
+        except Exception as e:
+            self.error.emit(str(e))
+            self.ml = None
+
+    def simulate(self):
+        """Run a forward simulation and emit the result via ``simulated``."""
+        try:
+            self.build_model()
+            if self.ml is None:
+                return
+            sim = self.ml.simulate()
+            self.state.last_simulation = sim
+            self.simulated.emit(sim)
+            self.status.emit("Simulation finished.")
+        except Exception as e:
+            self.error.emit(str(e))
+
+    def calibrate(self):
+        """Run the selected solver and emit a standardized payload.
+
+        The solver is chosen from ``state.solver_key`` and configured using
+        ``state.solver_params``.
+        """
+        try:
+            self.build_model()
+            if self.ml is None:
+                return
+            # Run selected solver via registry and emit standardized payload
+            key = getattr(self.state, "solver_key", "de")
+            params = getattr(self.state, "solver_params", {}).get(key, {})
+            payload = ms.run_solver(self.ml, key, params)
+            self.state.last_simulation = payload
+            self.calibrated.emit(payload)
+            self.status.emit("Calibration finished.")
+        except Exception as e:
+            self.error.emit(str(e))
+
+    def plot_age_distribution(self):
+        """Plot the age distribution and emit the figure."""
+        # at this point, the model is already built and has parameters assigned
+        # get age distributions
+        age_distributions = self.ml.get_age_distributions()
+
+        # get highest mean travel time of model parameters
+        mtts = []
+        for p in self.ml.params.items():
+            if p[1]["local_name"] == "mtt":
+                mtts.append(p[1]["value"])
+
+        mtt_max = max(mtts)
+        step_limit = int(mtt_max * 3)
+        dt = self.ml.dt / 12.0  # convert to years
+
+        step_limit = int(min(step_limit, len(age_distributions["distributions"][0])))
+        t_plot = [dt * i for i in range(step_limit)]
+
+        # prepare full distribution from fracions
+        dist_plot = np.zeros(len(age_distributions["distributions"][0][:step_limit]))
+        for i, frac in enumerate(age_distributions["fractions"]):
+            dist_plot += frac * age_distributions["distributions"][i][:step_limit]
+
+        fig, ax = plt.subplots(figsize=(6, 3))
+        ax.plot(t_plot, dist_plot, c="k", zorder=10000)
+        ax.set_xlim(0.0)
+        ax.set_ylim(0.0)
+        ax.grid(True, alpha=0.3, zorder=0)
+        ax.set_xlabel("Time [years]")
+        ax.set_ylabel("Fraction [-]")
+        ax.set_title("Age distribution")
+
+        plt.tight_layout()
+        plt.show()
+
+    def run_tracer_tracer(self, start: float, stop: float, count: int, param_key: str) -> None:
+        """Sweep mean travel time values and emit tracer-tracer results."""
+        try:
+            if count <= 1:
+                raise ValueError("Please choose at least two mean travel time points.")
+            if not np.isfinite(start) or not np.isfinite(stop):
+                raise ValueError("Start and stop values must be finite numbers.")
+            if float(stop) <= float(start):
+                raise ValueError("Stop value must be greater than start value.")
+
+            if not getattr(self.state, "tracer2", None):
+                raise ValueError("Tracer-tracer analysis requires two tracers.")
+
+            target = self.state.target_series
+            if target is None or target[1] is None:
+                raise ValueError("No observation series available.")
+            obs_times = np.asarray(target[0])
+            obs_vals = np.asarray(target[1], dtype=float)
+            if obs_vals.ndim == 1:
+                obs_vals = obs_vals.reshape(-1, 1)
+            if obs_vals.shape[1] < 2:
+                raise ValueError("Observation series must contain two tracer columns.")
+
+            self.build_model()
+            if self.ml is None:
+                raise RuntimeError(
+                    "Model is not available. \
+                        Configure the model before running a tracer-tracer sweep."
+                )
+            if param_key not in self.ml.params:
+                raise ValueError(f"Unknown parameter: {param_key}")
+
+            # Before we run the sweep, we need to convert the parameters with time units
+            # to match the internal monthly model resolution.
+            base_value = float(self.ml.params[param_key]["value"])
+
+            # We always get parameters with time units "years". We therefore
+            # need to convert them to months because we always work in months.
+            if "mtt" in param_key:
+                start *= 12
+                stop *= 12
+
+            grid = np.linspace(float(start), float(stop), int(count))
+            results = None
+
+            try:
+                for idx, val in enumerate(grid):
+                    self.ml.set_param(param_key, float(val))
+                    sim = self.ml.simulate()
+                    sim_arr = np.asarray(sim, dtype=float)
+                    if sim_arr.ndim == 1:
+                        sim_arr = sim_arr.reshape(-1, 1)
+                    if results is None:
+                        n_steps, n_tr = sim_arr.shape
+                        results = np.zeros((n_tr, grid.size, n_steps), dtype=float)
+                    elif sim_arr.shape[1] != results.shape[0]:
+                        raise ValueError("Simulation returned an unexpected number of tracers.")
+                    elif sim_arr.shape[0] != results.shape[2]:
+                        raise ValueError(
+                            "Simulation length changed across runs; cannot stack results."
+                        )
+                    for i in range(sim_arr.shape[1]):
+                        results[i, idx, :] = sim_arr[:, i]
+            finally:
+                self.ml.set_param(param_key, base_value)
+
+            if results is None:
+                raise ValueError("Failed to compute tracer-tracer results.")
+
+            if obs_vals.shape[0] != results.shape[2]:
+                raise ValueError("Observation length does not match simulation output.")
+
+            obs_mask = ~np.isnan(obs_vals[:, 0]) & ~np.isnan(obs_vals[:, 1])
+            obs_indices = np.nonzero(obs_mask)[0].astype(int)
+            if obs_indices.size == 0:
+                raise ValueError("No observation dates with values for both tracers.")
+
+            payload = {
+                "results": results,
+                "mtt_values": grid,
+                "param_key": param_key,
+                "obs_indices": obs_indices,
+                "timestamps": obs_times,
+                "observations": obs_vals,
+            }
+
+            self.state.tt_results = results
+            self.state.tt_mtt_values = grid
+            self.state.tt_obs_indices = obs_indices
+            self.state.tt_param_key = param_key
+
+            self.tracer_tracer_ready.emit(payload)
+            self.status.emit("Tracer-tracer sweep finished.")
+        except Exception as exc:
+            self.error.emit(str(exc))
+
+    def write_report(self, filename):
+        """Write a plain-text model report to ``filename`` using current state."""
+        if self.ml is None:
+            return
+        if self.state.is_monthly:
+            frequency = "1 month"
+        else:
+            frequency = "1 year"
+        tracer_names = []
+        if self.state.tracer1 is not None:
+            tracer_names.append(self.state.tracer1)
+        if self.state.tracer2 is not None:
+            tracer_names.append(self.state.tracer2)
+        # we always work in monthly frequency, so we always want to
+        # convert to years as units for mean travel time in the report
+        self.ml.write_report(
+            filename=filename, frequency=frequency, tracer=tracer_names, convert_mtt_to_years=True
+        )
+
+    def save_data(self, filename):
+        """Save simulation data to ``filename`` using current state."""
+        # Initialize lines
+        lines = []
+
+        # Get parameters
+        params = self.ml.params
+        # Get data and time stamps
+        data = np.asarray(self.state.last_simulation.get("sim"))
+        times = self.state.input_series[0]
+
+        # We have to prepare the data for the report
+        two_tracers = True
+        if data.ndim == 1:
+            two_tracers = False
+            data = data.reshape(-1, 1)
+
+        # Fill lines
+        # Parameters
+        lines.append("Parameters")
+        lines.append("----------")
+        for key, val in params.items():
+            lines.append(str(key) + ": " + str(val))
+        lines.append("")
+        lines.append("Simulation Data")
+        lines.append("---------------")
+        lines.append("")
+        headers = "Time, " + self.state.tracer1
+        if two_tracers:
+            headers += ", " + self.state.tracer2
+        lines.append(headers)
+
+        for i in range(len(data)):
+            if self.state.is_monthly:
+                if not two_tracers:
+                    lines.append(times[i].strftime("%Y-%m") + ", " + str(data[i, 0]))
+                else:
+                    lines.append(
+                        times[i].strftime("%Y-%m") + ", " + str(data[i, 0]) + ", " + str(data[i, 1])
+                    )
+            else:
+                if not two_tracers:
+                    lines.append(times[i].strftime("%Y") + ", " + str(data[i, 0]))
+                else:
+                    lines.append(
+                        times[i].strftime("%Y") + ", " + str(data[i, 0]) + ", " + str(data[i, 1])
+                    )
+
+        file_text = "\n".join(lines)
+        # Write lines
+        with open(filename, "w", encoding="utf-8") as f:
+            f.write(file_text)
+        return

PyTracerLab/gui/database.py

@@ -0,0 +1,16 @@
+"""Holds data of tracers supported in the PyTracerLab GUI."""
+
+from abc import ABC
+from dataclasses import dataclass
+
+
+@dataclass
+class Tracers(ABC):
+    """Database of all tracers supported by the PyTracerLab GUI."""
+
+    tracer_data = {
+        "Carbon-14": 5700.0,  # years
+        "Tritium": 12.32,  # years
+        "Krypton-85": 10.73,  # years
+        "Stable tracer (no decay)": 1e10,  # artificially large decay time
+    }

PyTracerLab/gui/main_window.py

@@ -0,0 +1,75 @@
+"""Main window for the PyTracerLab GUI, assembling all tabs."""
+
+from PyQt5.QtWidgets import QMessageBox, QTabWidget, QVBoxLayout, QWidget
+
+from ..model.registry import UNIT_REGISTRY
+from .controller import Controller
+from .state import AppState
+from .tabs.file_input import FileInputTab
+from .tabs.model_design import ModelDesignTab
+from .tabs.parameters import ParametersTab
+from .tabs.simulation import SimulationTab
+from .tabs.tracer_tracer import TracerTracerTab
+
+
+class MainWindow(QWidget):
+    """Top-level application window hosting the main tabs."""
+
+    def __init__(self):
+        """Create the main window and wire up tabs and controller."""
+        super().__init__()
+        # Initialize the window
+        self.setWindowTitle("PyTracerLab")
+        self.resize(800, 600)
+
+        self.state = AppState()
+        self.ctrl = Controller(self.state)
+
+        tabs = QTabWidget()
+        t1 = FileInputTab(self.state)
+        t2 = ModelDesignTab(self.state, UNIT_REGISTRY)
+        t3 = ParametersTab(self.state, UNIT_REGISTRY)
+        t4 = SimulationTab(self.state)
+        t5 = TracerTracerTab(self.state, UNIT_REGISTRY)
+
+        tabs.addTab(t1, "[1] Input")
+        tabs.addTab(t2, "[2] Model")
+        tabs.addTab(t3, "[3] Parameters")
+        tabs.addTab(t4, "[4] Simulation")
+        tabs.addTab(t5, "[5] Tracer-Tracer")
+
+        lay = QVBoxLayout(self)
+        lay.addWidget(tabs)
+
+        # wiring
+        t1.changed.connect(t2.refresh_tracer_inputs)
+        t1.changed.connect(t3.refresh)
+        t1.changed.connect(t5.reset_results)
+        t1.changed.connect(t5.refresh)
+        t2.selection_changed.connect(t3.refresh)
+        t2.selection_changed.connect(t5.refresh)
+        t2.selection_changed.connect(t5.reset_results)
+        t4.simulate_requested.connect(lambda: (t3.commit(), self.ctrl.simulate()))
+        t4.calibrate_requested.connect(lambda: (t3.commit(), self.ctrl.calibrate()))
+        t4.plot_age_distribution_requested.connect(
+            lambda: (t3.commit(), self.ctrl.plot_age_distribution())
+        )
+        t4.report_requested.connect(lambda fname: (t3.commit(), self.ctrl.write_report(fname)))
+        t4.savedata_requested.connect(lambda fname: (t3.commit(), self.ctrl.save_data(fname)))
+        t5.sweep_requested.connect(
+            lambda start, stop, count, key: (
+                t3.commit(),
+                self.ctrl.run_tracer_tracer(start, stop, count, key),
+            )
+        )
+
+        self.ctrl.simulated.connect(t4.show_results)
+        self.ctrl.calibrated.connect(t4.show_results)
+        self.ctrl.tracer_tracer_ready.connect(t5.handle_tracer_tracer_ready)
+        self.ctrl.status.connect(t4.show_status)
+
+        def _show_error(msg):
+            t5.sweep_failed()
+            QMessageBox.critical(self, "Error", msg)
+
+        self.ctrl.error.connect(_show_error)

PyTracerLab/gui/state.py

@@ -0,0 +1,122 @@
+"""Shared GUI state container used across tabs and controller."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+
+import numpy as np
+
+# Store the current state of the app in a centralized fashion
+
+ArrayLike = np.ndarray
+
+
+@dataclass
+class AppState:
+    """Central application state used by GUI components.
+
+    Attributes
+    ----------
+    is_monthly : bool
+        Whether input/target series are monthly (else yearly).
+    tracer : str
+        LEGACY: single-tracer selection kept for backward compatibility.
+    tracer1 : str
+        Primary tracer (e.g., ``"Tritium"``, ``"Carbon-14"``).
+    tracer2 : str | None
+        Optional second tracer; if ``None`` or ``"None"``, runs single-tracer mode.
+    solver_key : str
+        Selected solver registry key (``"de"``, ``"lsq"``, or ``"mcmc"``).
+    solver_params : dict
+        Per-solver configuration dictionary.
+    input_series : tuple(ndarray, ndarray) | None
+        Timestamps and input values.
+    target_series : tuple(ndarray, ndarray) | None
+        Timestamps and observation values (optional).
+    selected_units : list of str
+        Unique unit types (legacy support for parameters tab).
+    design_units : list of (str, float)
+        Flat list of chosen units and fractions (can repeat unit types).
+    unit_fractions : dict[str, float]
+        Per-instance fraction mapping keyed by unique instance prefix.
+    params : dict
+        Nested parameter values/bounds/fixed flags per instance prefix.
+    steady_state_input : float | list of float
+        Value(s) for optional steady-state warmup input. Provide a scalar for
+        single-tracer runs or one value per tracer for multi-tracer runs.
+    n_warmup_half_lives : int
+        Warmup length in half-lives of the tracer.
+    last_simulation : object | None
+        Last simulation result or solver payload for plotting.
+    last_times : ndarray | None
+        Cached timestamps for plotting (if needed).
+    """
+
+    is_monthly: bool = True
+    is_halfyearly: bool = False
+    tracer1: str = "Tritium"
+    tracer2: Optional[str] = None
+    # Selected solver (registry key); default to Differential Evolution
+    solver_key: str = "de"
+    # Per-solver parameters
+    solver_params: Dict[str, dict] = field(
+        default_factory=lambda: {
+            "de": {
+                "maxiter": 10000,
+                "popsize": 15,
+                "mutation": (0.5, 1.0),
+                "recombination": 0.7,
+                "tol": 0.01,
+                "sigma": None,
+            },
+            "lsq": {
+                "ftol": 1e-8,
+                "xtol": 1e-8,
+                "gtol": 1e-8,
+                "max_nfev": 10000,
+                "sigma": None,
+            },
+            "mcmc": {
+                "n_samples": 10000,
+                "burn_in": 2000,
+                "thin": 2,
+                "rw_scale": 0.05,
+                "sigma": None,
+            },
+            "dream": {
+                "n_samples": 2000,
+                "burn_in": 2000,
+                "thin": 1,
+                "n_chains": 3,
+                "n_diff_pairs": 2,
+                "n_cr": 4,
+                "sigma": None,
+            },
+        }
+    )
+    input_series: Optional[Tuple[ArrayLike, ArrayLike]] = None
+    target_series: Optional[Tuple[ArrayLike, ArrayLike]] = None
+    manual_observations: Dict[datetime, List[float]] = field(default_factory=dict)
+    selected_units: List[str] = field(default_factory=list)  # unique registry keys for params tab
+    # detailed design: list of (unit_name, fraction) allowing duplicates
+    design_units: List[Tuple[str, float]] = field(default_factory=list)
+    # aggregated by prefix for controller/model: {"epm": 0.5, ...}
+    unit_fractions: Dict[str, float] = field(default_factory=dict)
+    params: Dict[str, Dict[str, Dict[str, float]]] = field(default_factory=dict)
+    # params[prefix][key] = {"val":..., "lb":..., "ub":..., "fixed":0/1}
+    steady_state_input: Union[float, List[float]] = 0.0
+    n_warmup_half_lives: int = 10
+    tt_results: Optional[ArrayLike] = None
+    tt_mtt_values: Optional[np.ndarray] = None
+    tt_obs_indices: Optional[np.ndarray] = None
+    tt_param_key: Optional[str] = None
+    # Can be either a plain ndarray (legacy) or a payload dict from solver.run_solver
+    last_simulation: Optional[object] = None
+    last_times: Optional[ArrayLike] = None
+
+    def clear_tracer_tracer(self) -> None:
+        """Reset cached tracer-tracer sweep results."""
+        self.tt_results = None
+        self.tt_mtt_values = None
+        self.tt_obs_indices = None
+        self.tt_param_key = None