TransitionListener 2.0.0__py3-none-any.whl

transitionlistener/interface/__init__.py

@@ -0,0 +1,95 @@
+"""Interface entry points for TransitionListener scans.
+
+This module exposes the main functions and classes for performing
+scans and single-point evaluations using TransitionListener. It also
+manages global state variables such as debug mode, timeout settings,
+and logging configurations.
+
+Part of TransitionListener v2.0
+Documentation: https://tasillo.de/TransitionListener/
+
+Authors:
+    Jonas Matuszak <jonas.matuszak@kit.edu>
+    Carlo Tasillo <carlo.tasillo@ific.uv.es>
+"""
+
+import logging
+logging.getLogger("numexpr").setLevel(logging.WARNING)
+
+from . import state as _state
+from .logging_utils import Logger
+from .config_loader import ScanConfig
+from .pipeline import (
+    run_TL, _compute_single_point,
+    _build_result_from_context,
+    _handle_single_point_error)
+from .samplers import (
+    call_by_sampler,
+    sample_and_export_to_csv,
+    scanfunc,
+    extract_parameters,
+    log_likelihood,
+    prior_transform,
+    ultranest,
+)
+from .scans import (
+    create_grid,
+    line_scan,
+    grid_scan,
+    table,
+    random_scan,
+    save_results_1d,
+    save_results_2d,
+    plot_results_1d,
+    plot_results_2d,
+)
+from .single_point import single
+from .cli import main
+
+__all__ = [
+    "Logger",
+    "ScanConfig",
+    "run_TL",
+    "_compute_single_point",
+    "_build_result_from_context",
+    "_handle_single_point_error",
+    "call_by_sampler",
+    "sample_and_export_to_csv",
+    "scanfunc",
+    "extract_parameters",
+    "log_likelihood",
+    "prior_transform",
+    "ultranest",
+    "create_grid",
+    "line_scan",
+    "grid_scan",
+    "table",
+    "random_scan",
+    "save_results_1d",
+    "save_results_2d",
+    "plot_results_1d",
+    "plot_results_2d",
+    "single",
+    "main",
+    "DEBUGMODE",
+    "TIMEOUT",
+    "model",
+    "errorlogger",
+    "resultlogger",
+    "config",
+]
+
+
+def __getattr__(name):
+    """Proxy selected legacy module-level state to :mod:`transitionlistener.interface.state`."""
+    if name in {"DEBUGMODE", "TIMEOUT", "model", "errorlogger", "resultlogger", "config"}:
+        return getattr(_state, name)
+    raise AttributeError(f"module 'transitionlistener.interface' has no attribute '{name}'")
+
+
+def __setattr__(name, value):
+    """Mirror assignments to the shared interface state when applicable."""
+    if name in {"DEBUGMODE", "TIMEOUT", "model", "errorlogger", "resultlogger", "config"}:
+        setattr(_state, name, value)
+    else:
+        globals()[name] = value

transitionlistener/interface/check.py

@@ -0,0 +1,51 @@
+"""Entry point for ``tl --check``.
+
+All check logic lives in ``tests/check_installation.py`` in the repository.
+For pip installs, hatchling bundles that file as
+``transitionlistener/check_installation.py`` so it is always reachable.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+def _load_and_run(path: Path) -> int:
+    """Import the installation-check script at ``path`` and execute it."""
+    spec = importlib.util.spec_from_file_location("_tl_check_installation", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.run_checks()
+
+
+def run_checks() -> int:
+    """Locate and run the packaged installation checks.
+
+    The helper first prefers the repository-local ``tests/check_installation.py``
+    file and falls back to the copy bundled into wheel installs.
+    """
+    # Option 1: repo clone — tests/check_installation.py is at parents[3]/tests/
+    # (this file: src/transitionlistener/interface/check.py → parents[3] = repo root)
+    repo_path = Path(__file__).resolve().parents[3] / "tests" / "check_installation.py"
+    if repo_path.exists():
+        return _load_and_run(repo_path)
+
+    # Option 2: pip install — hatchling bundled it as transitionlistener/check_installation.py
+    try:
+        import importlib.resources as ir
+        import contextlib
+        ref = ir.files("transitionlistener") / "check_installation.py"
+        with contextlib.ExitStack() as stack:
+            bundled = stack.enter_context(ir.as_file(ref))
+            return _load_and_run(bundled)
+    except Exception:
+        pass
+
+    from transitionlistener import console
+    console.print(
+        "[bold red]ERROR[/bold red]  check_installation.py not found.\n"
+        "  Repo clone: expected at tests/check_installation.py\n"
+        "  pip install: rebuild the wheel with hatchling."
+    )
+    return 1

transitionlistener/interface/cli.py

@@ -0,0 +1,211 @@
+"""Command-line interface for TransitionListener.
+
+This module exposes the ``tl`` entry point which is used to launch scans and
+other analyses from the terminal.  The command line interface is intentionally
+minimal – most of the configuration is supplied through YAML files – but the
+help text should nonetheless offer a concise overview of what the tool does and
+how it can be used.  The updates in this module focus on surfacing that
+information so that ``tl -h`` is informative for new users.
+
+Part of TransitionListener v2.0
+Documentation: https://tasillo.de/TransitionListener/
+
+Authors:
+    Jonas Matuszak <jonas.matuszak@kit.edu>
+    Carlo Tasillo <carlo.tasillo@ific.uv.es>
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import textwrap
+import time
+
+from transitionlistener import console
+from rich.panel import Panel
+
+from . import state
+from .config_loader import ScanConfig
+from .scans import grid_scan, line_scan, random_scan, table
+from .single_point import single
+from .samplers import ultranest
+
+
+def main():
+    """Console entry point."""
+    t0 = time.time()
+
+    parser = argparse.ArgumentParser(
+        prog="tl",
+        description=textwrap.dedent(
+            """
+            TransitionListener performs parameter scans and single point
+            analyses for cosmological phase transition and gravitational
+            wave calculations.  Provide a YAML configuration file describing
+            the scan type, model inputs, and output location to launch a run.
+            """
+        ).strip(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent(
+            """
+            Common scan types include GridScan, LineScan, RandomScan, SinglePoint,
+            UltranestScan, and TableScan. The scan type is selected in the YAML
+            configuration file and determines which numerical routine is
+            executed.
+
+            Examples:
+              tl -c examples/example_point.yaml -v True
+              tl -c examples/example_grid.yaml -j 10
+              mpiexec -n 10 tl -c examples/example_ultranest.yaml
+
+            Documentation: https://www.tasillo.de/transitionlistener_development/
+            """
+        ).strip(),
+    )
+    parser.add_argument(
+        "-j",
+        "--jobs",
+        type=int,
+        default=1,
+        metavar="N",
+        help=(
+            "Number of parallel worker processes to use for supported scan "
+            "types (defaults to 1)."
+        ),
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=str,
+        metavar="FILE.yaml",
+        help=(
+            "Path to the YAML configuration file that defines the scan. The "
+            "file specifies the scan type, physics inputs, and output path."
+        ),
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable detailed logging to the console.",
+    )
+    parser.add_argument(
+        "-d",
+        "--debug",
+        action="store_true",
+        help="Enable debug mode (do not suppress runtime warnings).",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="store_true",
+        help="Show the TransitionListener version and exit.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Run a quick installation self-test and exit.",
+    )
+
+    args = parser.parse_args()
+
+    if args.check:
+        from .check import run_checks
+        raise SystemExit(run_checks())
+
+    if args.version:
+        from transitionlistener import __version__
+        console.print(Panel.fit(f"[bold green]TransitionListener version {__version__}[/bold green]", border_style="green"))
+        raise SystemExit(0)
+
+    if not args.config:
+        parser.error("a configuration file must be provided with -c/--config")
+
+    state.set_debugmode(args.debug)
+
+    config_path = os.path.expanduser(args.config)
+    if not os.path.exists(config_path):
+        parser.error(f"configuration file not found: {config_path}")
+
+    state.config = ScanConfig(config_path)
+    os.makedirs(state.config.output_path, exist_ok=True)
+
+    mpi_rank_env_vars = [
+        "OMPI_COMM_WORLD_RANK",
+        "PMI_RANK",
+        "PMIX_RANK",
+        "SLURM_PROCID",
+        "RANK",
+        "I_MPI_RANK",
+        "MPI_LOCALRANKID",
+    ]
+    mpi_size_env_vars = [
+        "OMPI_COMM_WORLD_SIZE",
+        "PMI_SIZE",
+        "PMIX_SIZE",
+        "SLURM_NPROCS",
+        "SLURM_NTASKS",
+        "WORLD_SIZE",
+        "MPIEXEC_TIMEOUT",
+    ]
+
+    rank_value = None
+    for env_var in mpi_rank_env_vars:
+        value = os.environ.get(env_var)
+        if value is not None:
+            rank_value = value
+            break
+
+    rank_from_env = rank_value is not None
+    if rank_value is None:
+        rank_value = "0"
+
+    try:
+        rank = int(rank_value)
+    except Exception:
+        rank = 0
+
+    is_mpi = rank_from_env or any(os.environ.get(env_var) is not None for env_var in mpi_size_env_vars)
+    if (not is_mpi) or (rank == 0):
+        message = "[green bold]Welcome to TransitionListener v2.0![/]"
+        console.print(Panel.fit(message, border_style="green"))
+        console.print()
+        state.config.display()
+        message = f"[green]Starting analysis of {state.config.description}[/]"
+        console.print(Panel.fit(message, border_style="green"))
+        console.print()
+
+    try:
+        if state.config.type == "GridScan":
+            grid_scan(state.config, n_jobs=args.jobs)
+        elif state.config.type == "LineScan":
+            line_scan(state.config, n_jobs=args.jobs)
+        elif state.config.type == "RandomScan":
+            random_scan(state.config, n_jobs=args.jobs)
+        elif state.config.type == "SinglePoint":
+            single(state.config, verbose=args.verbose)
+        elif state.config.type == "UltranestScan":
+            if args.jobs != 1:
+                msg = ("Error: Ultranest does not support parallelization through "
+                       "the -j option. We recommend parallelizing it using MPI. "
+                       "For this you need to execute: \n\n"
+                       "mpiexec -n <num_procs> tl -c <config.yaml>\n"
+                       "or, if `tl` is not installed,\n"
+                       "mpiexec -n <num_procs> env PYTHONPATH=src "
+                       "python -m transitionlistener.interface.cli -c <config.yaml>")
+                console.print(Panel.fit(f"[bold red]{msg}[/bold red]", border_style="red"))
+                raise SystemExit(1)
+            ultranest(state.config)
+        elif state.config.type == "TableScan":
+            table(state.config, n_jobs=args.jobs)
+        else:
+            raise ValueError("Unknown scan type.")
+    except ValueError as err:
+        console.print(Panel.fit(str(err), border_style="red"))
+        raise SystemExit(1) from err
+
+    tend = time.time()
+    if (not is_mpi) or (rank == 0):
+        msg = (f"Finished in {time.strftime('%H:%M:%S', time.gmtime(tend-t0))}")
+        console.print(Panel.fit(f"[bold green]{msg}[/bold green]", border_style="green"))

transitionlistener/interface/config_loader.py

@@ -0,0 +1,264 @@
+"""Configuration loader for TransitionListener scan YAML files.
+
+Part of TransitionListener v2.0
+Documentation: https://tasillo.de/TransitionListener/
+
+Authors:
+    Jonas Matuszak <jonas.matuszak@kit.edu>
+    Carlo Tasillo <carlo.tasillo@ific.uv.es>
+"""
+
+from __future__ import annotations
+
+import os
+import yaml
+
+from rich.panel import Panel
+from rich.table import Table
+
+from transitionlistener.config import all_observables
+from transitionlistener.helper_functions import import_file, load_potential
+from transitionlistener import console
+
+from . import state
+from ..observability import GW_Sensitivity_Data
+
+
+class ScanConfig:
+    """Read and store all settings required for a TransitionListener scan."""
+
+    def __init__(self, file: str):
+        """Parse the YAML configuration and expose the fields as attributes."""
+        with open(file, "r", encoding="utf-8") as cfile:
+            config = yaml.safe_load(cfile)
+
+        self.type = config["Scan"]
+
+        state.TIMEOUT = config.get("timeout", 300)
+        self.timeout = state.TIMEOUT
+
+        self.modelfile = config["Modelfile"]
+        self.potential_name = config["Potential"]
+        state.model = import_file(self.modelfile)
+        state.potential = load_potential(self.modelfile, self.potential_name)
+        self.model_params = self._resolve_model_parameters(state.potential)
+
+        self.derived_params = all_observables.copy()
+
+        self.output_path = config["output_path"]
+        if self.output_path[-1] != "/":
+            self.output_path += "/"
+
+        self.format = config["format"]
+        if self.format not in ["hdf5", "txt"]:
+            raise Exception("Output format must be either 'hdf5' or 'txt'")
+
+        self.description = config["description"]
+        self.plot_description = config["plot_description"]
+
+        if self.type == "SinglePoint":
+            self.params = config["Parameters"]
+            self.additional_plots = config.get("additional_plots", {})
+            self.plots = None
+
+        elif self.type == "TableScan":
+            self.params = config["Parameters"]
+            self.scan_params = config["Parameters"]["scan_params"]
+            self.other_params = config["Parameters"]["other_params"] or {}
+            try:
+                self.N = config["Parameters"]["N"]
+            except KeyError:
+                raise Exception("Number of random points N must be specified.")
+            if self.N < 1 or int(self.N) != self.N:
+                raise Exception("Number of random points N must be a positive integer.")
+            self.table_file = config["Tablefile"]
+            if not os.path.isfile(self.table_file):
+                raise Exception(f"Table file {self.table_file} does not exist.")
+
+        elif self.type == "RandomScan":
+            self.params = config["Parameters"]
+            self.scan_params = config["Parameters"]["scan_params"]
+            self.other_params = config["Parameters"]["other_params"] or {}
+            try:
+                self.N = config["Parameters"]["N"]
+            except KeyError:
+                raise Exception("Number of random points N must be specified.")
+            if self.N < 1 or int(self.N) != self.N:
+                raise Exception("Number of random points N must be a positive integer.")
+
+        elif self.type == "UltranestScan":
+            self.params = config["Parameters"]
+            self.scan_params = config["Parameters"]["scan_params"]
+            self.other_params = config["Parameters"]["other_params"]
+            self.transformation_file = config["Parameters"].get("transformation_file", None)
+            self.resume_mode = config.get("resume_mode", "resume")
+            valid_resume_modes = {True, "overwrite", "subfolder", "resume", "resume-similar"}
+            if self.resume_mode not in valid_resume_modes:
+                raise ValueError(
+                    "For UltranestScan, resume_mode must be one of "
+                    f"{sorted(repr(mode) for mode in valid_resume_modes)}; "
+                    f"got {self.resume_mode!r}."
+                )
+
+        elif self.type == "LineScan":
+            self.plots = config["plots"]
+            if len(list(config["Parameters"]["line_param"].keys())) != 1:
+                raise Exception("Line scan requires exactly one line parameter.")
+
+            self.line_param = list(config["Parameters"]["line_param"].keys())[0]
+            if self.line_param not in self.model_params.keys():
+                raise Exception(f"Line scan parameter {self.line_param} not found in model parameters.")
+
+            try:
+                self.scale = config["Parameters"]["line_param"][self.line_param]["scale"]
+                self.minmax = config["Parameters"]["line_param"][self.line_param]["range"]
+            except KeyError:
+                raise Exception("Line scan parameter must have 'range' and 'scale' specified.")
+
+            self.other_params = config["Parameters"]["other_params"] or {}
+            try:
+                self.N = config["Parameters"]["N"]
+            except KeyError:
+                raise Exception("Number of line points N must be specified.")
+            if self.N < 2 or int(self.N) != self.N:
+                raise Exception("Number of line points N must be an integer >= 2.")
+
+            self.overview_detector_name = config["overview_detector_name"]
+            self._validate_overview_detector(self.overview_detector_name)
+            self.overview_param_names = config["overview_param_names"]
+            self.show_scan_points = config.get("show_scan_points", True)
+
+        elif self.type == "GridScan":
+            self.plots = config["plots"]
+            grid_keys = list(config["Parameters"]["grid_params"].keys())
+            if set(grid_keys) != {"x", "y"} or len(grid_keys) != 2:
+                raise Exception("Grid scan requires exactly two grid parameters named 'x' and 'y'.")
+
+            try:
+                self.N = config["Parameters"]["N"]
+            except KeyError:
+                raise Exception("Number of grid points N must be specified.")
+            if self.N < 2 or int(self.N) != self.N:
+                raise Exception("Number of grid points N must be an integer >= 2.")
+
+            self.minmax = {}
+            self.scales = {}
+            self.grid_names = {}
+
+            try:
+                for key in grid_keys:
+                    entry = config["Parameters"]["grid_params"][key]
+                    self.minmax[key] = [float(val) for val in entry["range"]] # Support 1e-3
+                    self.scales[key] = entry["scale"]
+                    self.grid_names[key] = entry["name"]
+            except KeyError:
+                raise Exception("Grid parameters must have 'name', 'scale' and 'range' specified.")
+
+            self.other_params = config["Parameters"]["other_params"] or {}
+            self.overview_detector_name = config["overview_detector_name"]
+            self._validate_overview_detector(self.overview_detector_name)
+            self.overview_param_names = config["overview_param_names"]
+            self.show_scan_points = config.get("show_scan_points", True)
+
+        else:
+            raise Exception(f"Unknown scan type {self.type}")
+
+    def _validate_overview_detector(self, detector_name: str) -> None:
+        """Ensure the requested overview detector exists in the observability data."""
+        available = GW_Sensitivity_Data().det_names
+        if detector_name not in available:
+            raise ValueError(
+                "overview_detector_name must be one of "
+                + ", ".join(sorted(available))
+                + f"; got '{detector_name}'"
+            )
+
+    @staticmethod
+    def _resolve_model_parameters(potential):
+        """Return the parameter metadata defined by the imported model module."""
+        try:
+            params = potential.model_parameters
+        except Exception:
+            raise AttributeError(
+                "The provided model does not expose model_parameters either as a module-level "
+                "attribute or on the specific_potential class."
+            )
+
+        return {name: params[name].copy() for name in params}
+
+    def display(self):
+        """Pretty-print the loaded configuration to the console."""
+        try:
+            summary = Table(show_header=False, box=None, pad_edge=False)
+            summary.add_column("Setting", style="cyan")
+            summary.add_column("Value")
+            summary.add_row("Type", str(self.type))
+            summary.add_row("Model", str(self.modelfile))
+            summary.add_row("Output", str(self.output_path))
+            summary.add_row("Format", str(self.format))
+            plots_value = getattr(self, "plots", None)
+            if plots_value is not None:
+                summary.add_row("Plots", str(plots_value))
+            if getattr(self, "description", None):
+                summary.add_row("Description", str(self.description))
+            console.print(Panel(summary, title="Config", border_style="green"))
+
+            params_tbl = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
+            params_tbl.add_column("Parameter", style="cyan")
+            params_tbl.add_column("Value")
+
+            if self.type == "SinglePoint":
+                for k, v in self.params.items():
+                    try:
+                        val = f"{float(v):g}"
+                    except Exception:
+                        val = str(v)
+                    params_tbl.add_row(k, val)
+            elif self.type == "LineScan":
+                pname = self.line_param
+                rmin, rmax = self.minmax
+                params_tbl.add_row("mode", "Line")
+                params_tbl.add_row(pname, f"[{rmin:g}, {rmax:g}] ({self.scale})")
+                params_tbl.add_row("N", f"{self.N}")
+            elif self.type == "GridScan":
+                xname = self.grid_names.get("x", "x")
+                yname = self.grid_names.get("y", "y")
+                xmin, xmax = self.minmax["x"]
+                ymin, ymax = self.minmax["y"]
+                xscale = self.scales["x"]
+                yscale = self.scales["y"]
+                params_tbl.add_row("mode", "Grid")
+                params_tbl.add_row("x", f"{xname} [{xmin:g}, {xmax:g}] ({xscale})")
+                params_tbl.add_row("y", f"{yname} [{ymin:g}, {ymax:g}] ({yscale})")
+                params_tbl.add_row("N per axis", f"{self.N}")
+            else:
+                if hasattr(self, "scan_params") and isinstance(self.scan_params, dict):
+                    for k, spec in self.scan_params.items():
+                        try:
+                            rmin, rmax = spec.get("range", [None, None])
+                            scale = spec.get("scale", "")
+                            if rmin is not None and rmax is not None:
+                                spec_str = f"[{float(rmin):g}, {float(rmax):g}] ({scale})"
+                            else:
+                                spec_str = str(spec)
+                        except Exception:
+                            spec_str = str(spec)
+                        params_tbl.add_row(k, spec_str)
+                if hasattr(self, "N"):
+                    params_tbl.add_row("N", f"{self.N}")
+            console.print(Panel(params_tbl, title="Scan parameters", border_style="green"))
+
+            fixed = getattr(self, "other_params", None)
+            if fixed:
+                fixed_tbl = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
+                fixed_tbl.add_column("Fixed Parameter", style="cyan")
+                fixed_tbl.add_column("Value")
+                for k, v in fixed.items():
+                    try:
+                        val = f"{float(v):g}"
+                    except Exception:
+                        val = str(v)
+                    fixed_tbl.add_row(k, val)
+                console.print(Panel(fixed_tbl, title="Fixed Parameters", border_style="green"))
+        except Exception:
+            pass

transitionlistener/interface/logging_utils.py

@@ -0,0 +1,30 @@
+"""Small helpers for logging scan output to disk.
+
+Part of TransitionListener v2.0
+Documentation: https://tasillo.de/TransitionListener/
+
+Authors:
+    Jonas Matuszak <jonas.matuszak@kit.edu>
+    Carlo Tasillo <carlo.tasillo@ific.uv.es>
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class Logger:
+    """Very small helper that mirrors stdout logging to a file."""
+
+    def __init__(self, file_name: str | Path):
+        """Open `file_name` in append mode so logs persist across scans."""
+        self.file = open(file_name, "a")
+
+    def log(self, message: str):
+        """Write `message` to the backing file and flush immediately."""
+        self.file.write(message)
+        self.file.flush()
+
+    def close(self):
+        """Close the on-disk log file."""
+        self.file.close()